Maven Helper-lry — VS Code 扩展

在 pom.xml 里悬停就能看依赖的完整信息：JDK 兼容性、版本冲突、最新稳定版、版本列表（含 Java 版本标注）

✨ 鸣谢

首先，衷心感谢所有为 VS Code 插件生态做出贡献的开发者们。作为新进入程序员行列的大学生，本插件的诞生，离不开对以下开源项目和前辈们优秀作品的学习与借鉴：

• 感谢Maven Helper等此类知名插件开发者，他们的高质量作品为我展示了插件开发的可能性与最佳实践。
• 感谢所有撰写 VS Code 插件开发教程、分享踩坑经验的博主和社区成员，你们的文章为我提供了宝贵的入门指引。
• 感谢整个 VS Code 开源社区，正是这个充满活力的生态系统，让学习和创造变得如此便捷。

本插件在开发过程中，在功能和实现思路上受以上前辈的启发良多。在此，向所有无私分享知识与代码的开源贡献者们致以最诚挚的谢意。

✨ 为什么做这个插件

在日常使用上，Maven-helper这个插件已经很厉害了，但对个人从0搭建项目，Maven 依赖管理有四个日常痛点：

全部在编辑器里完成，不用切终端跑 mvn 命令，不用开浏览器查版本。

📦 安装

前置要求

• Node.js 18+（含 npm）
• VS Code 或 Cursor 1.85+

从源码构建

# 1. 克隆仓库
git clone https://github.com/lll/maven-helper.git
cd maven-helper

# 2. 安装依赖
npm install

# 3. 编译 TypeScript
npm run compile

# 4. 打包成 VSIX
npx vsce package

打包完成后会在项目根目录生成 maven-helper-1.0.0.vsix。

安装到 VS Code / Cursor

# 命令行安装
code --install-extension maven-helper-1.0.0.vsix

或者在编辑器里安装：

1. Ctrl+Shift+X 打开扩展面板
2. 点右上角 ··· → 从 VSIX 安装
3. 选择生成的 .vsix 文件

安装后重启编辑器，打开任意项目的 pom.xml 即可使用。

开发调试

如果想直接在源码上调试（不需要打包）：

# 用 VS Code 打开本项目
code maven-helper

# 按 F5 启动 Extension Development Host
# 在新窗口里打开任意项目的 pom.xml 即可测试

使用方式

功能 1：悬停查看完整分析

鼠标悬停在 <dependency> 块内的 <version> 标签上，弹出完整面板：

• JDK 兼容性检查 — 当前版本要求 JDK 几，项目配置了 JDK 几，兼容 ✅ 还是不兼容 ❌
• 版本冲突检测 — 该依赖是否在 pom.xml 中被声明了多个不同版本
• 最新稳定版 — Maven Central 上的最新 stable 版本，对比你当前用的版本
• 版本列表 — 最近 20 个版本，每行标注类型（稳定版/快照版/预发布）+ 要求的 Java 版本 + 是否兼容

鼠标悬停在 <artifactId> 或 <groupId> 上，弹出轻量摘要：

• 当前版本 + 要求 JDK + 兼容性 + 最新版对比 + Maven Central 链接

功能 2：右键代码操作

在 <version> 行上右键或点灯泡图标，出现三个操作：

功能 3：命令面板

按 Ctrl+Shift+P 输入 Maven Helper：

📋 悬停面板示例

悬停在 <version>3.3.0</version> 上（项目 JDK 为 8）：

📦 org.springframework.boot:spring-boot-starter-web

当前版本：3.3.0
项目 JDK：8

─── 🔧 JDK 兼容性检查 ───

❌ 不兼容

当前版本 3.3.0 要求 JDK 17+，你的项目配置是 JDK 8。

运行时可能抛出 UnsupportedClassVersionError，或使用了项目 JDK 不支持的语法特性。

解决方案：
1. 将项目 JDK 升级到 17+（修改 <java.version> 或 maven.compiler.source）
2. 或换用该依赖的旧版本（要求 JDK 8 以下的版本）

─── 🔗 版本冲突检测 ───

✅ 无冲突

该依赖在 pom.xml 中只出现了一次，不存在版本冲突。

─── 🆕 最新稳定版 ───

最新稳定版：3.3.0，你已在使用最新稳定版 ✅

─── 📋 Maven Central 版本列表 ───

共找到 45 个版本，以下为最近发布的版本：

- 3.3.0      ✅ 稳定版    要求 JDK 17+   ❌ 不兼容
- 3.2.7      ✅ 稳定版    要求 JDK 17+   ❌ 不兼容
- 3.1.12     ✅ 稳定版    要求 JDK 17+   ❌ 不兼容
- 2.7.18     ✅ 稳定版    要求 JDK 8+    ✅ 兼容
- 2.7.17     ✅ 稳定版    要求 JDK 8+    ✅ 兼容
...

说明：「要求 Java」是根据该依赖所属生态（Spring Boot、Jakarta EE 等）和版本号推断的估计值。
兼容性以你项目当前配置的 JDK 8 为基准。

🛠️ 技术架构

技术栈

• TypeScript + VS Code Extension API
• Node.js https 模块 调用 Maven Central Search REST API
• 正则解析 pom.xml（轻量，无第三方 XML 库依赖）

项目结构

maven-helper/
├── package.json              # 扩展元数据 + 命令注册
├── tsconfig.json             # TypeScript 编译配置
├── src/
│   ├── extension.ts          # 入口：命令注册 + 各功能实现
│   ├── mavenCentralClient.ts # Maven Central API 客户端
│   ├── dependencyParser.ts   # pom.xml 解析器
│   ├── hoverProvider.ts      # 悬停提示（核心功能）
│   ├── diagnostics.ts        # 诊断（当前为空，按需启用）
│   └── codeActions.ts        # 右键代码操作
└── out/                      # 编译产物

核心流程

pom.xml 悬停 → dependencyParser 解析依赖
                → mavenCentralClient 查 Maven Central API
                → estimateRequiredJdk() 判断 JDK 兼容性
                → 组装 Markdown 面板 → 返回 Hover

⚠️ 已知不足 & 后续计划

这个插件是业余时间快速迭代的产物，以下已知不足，后续逐步补齐：

JDK 兼容性判断不够精确

现状： 维护了一份硬编码的兼容矩阵，覆盖 Spring Boot、Spring Framework、Jakarta、Guava、Mockito、Jackson 等知名库。未知库走启发式推断（版本号 ≥30 → JDK 17）。

问题： 冷门库、新出的库不在矩阵里，推断可能不准。

后续计划： 改成从本地 Maven 仓库 ``.m2读取 jar 包的 class 文件 major version，100% 精确判断。或解析 POM 中的maven.compiler.source`。

只支持 pom.xml，不支持 build.gradle

现状： 只解析 Maven 的 pom.xml。

后续计划： 增加 Gradle (build.gradle) 支持，覆盖更广的 JVM 生态。

依赖冲突检测只看直接声明

现状： 只检测同一个依赖在 pom.xml 中被直接声明多次的情况，检测不到传递依赖引起的冲突（这个需要解析 mvn dependency:tree 输出）。

后续计划： 集成 Maven 调用解析传递依赖冲突。

中文用 Unicode 转义

现状： 为绕过 PowerShell 管道编码问题，所有中文用 \uXXXX 转义写进源码，可读性差。

后续计划： 改用 JSON 资源文件管理多语言文案，支持中英文切换。