1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | javax-to-jakarta-migration-github-awesome-copilot |
| 作者/维护者 | GitHub(github/awesome-copilot 合集);技能由社区贡献者 vinod kumar 于 2026-04 提交,Julien Dubois 于 2026-10 修订并补充安全约束 |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/javax-to-jakarta-migration |
| 许可证 | MIT(合集仓库,GitHub API) |
| GitHub Stars / Forks | 合集整体 40,177 / 5,158(GitHub API);该数字属整个合集,不代表本技能自身热度 |
| 技能自身热度 | 第三方技能榜(skills.sh)显示约 90 次安装 |
| 最新版本 | 无独立版本号;最近一次提交 2026-10-15 |
| 安装方式 | npx skills add https://github.com/github/awesome-copilot --skill javax-to-jakarta-migration,或手动复制目录 |
2. 功能介绍与亮点
这是一份让 AI 编程助手把 Java 项目从 javax.* 迁到 jakarta.* 命名空间的操作手册,单个 SKILL.md(约 5 KB),无脚本。
- 明确触发条件:只在用户明确要求迁移(升级 Tomcat 10+/11、Jakarta EE),或由 java-upgrade、spring-boot-4-migration 委托时才执行;单纯发现
javax导入只汇报、不动手。 - 分步流程:先跑
./mvnw verify或./gradlew build记录基线,红灯不迁移;再扫描导入、改 pom 依赖坐标、改web.xml命名空间与版本、替换源码导入,最后编译、测试并复查残留。 - 映射与例外清单:给出 servlet、persistence、validation、inject、ws.rs 等十余个包的对照,并列出必须保留
javax的 JDK 自带包(javax.sql、javax.naming、javax.crypto、javax.net、javax.security.auth、javax.swing、javax.xml.parsers)。 - 版本矩阵:Tomcat 10.0 / 10.1 / 11 对应 Jakarta EE 9 / 10 / 11,以及各规范版本,避免版本错配。
- Spring Boot 提示:Boot 项目由 BOM 决定 Jakarta 版本,不手工钉版本(Boot 4 对应 Jakarta EE 11)。
- 非 Java 文件提醒:同步检查
persistence.xml属性、META-INF/services、beans.xml、配置文件与反射字符串。
3. 适用场景
分类:工程效率与代码质量。
- 把 Spring Boot 2.x、Tomcat 9 及更早的老项目升到 Tomcat 10+ / Jakarta EE,让助手批量改导入与依赖。
- 作为大版本升级(Java 或 Spring Boot)中的命名空间迁移子步骤。
- 受益人群:维护存量 Java Web 项目的初中级后端开发者。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 标准 SKILL.md(front matter + 正文),复制到 ~/.claude/skills/ 即可 |
| Codex | 需适配 | 同为 SKILL.md 格式,但不自动发现 ~/.codex/skills,需手动引用 |
| OpenClaw | 未验证 | 未取得实际加载证据 |
| Hermes Agent | 原生支持(按路径) | 按路径扫描子目录探测 SKILL.md;未实机安装 |
5. 推荐理由
迁移本身机械,真正的坑在边界:哪些 javax 包不能动、版本矩阵怎么对、非 Java 文件里的引用别漏。该技能把这几处写成硬规则,并要求先有绿色基线、独立提交,出错时容易回滚。比起让助手“全局替换 javax”,范围更可控。纯文档,无脚本、无外联。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 个人贡献者提交进合集,第三方榜约 90 次安装,暂无具名用户评价;合集的 40,177 stars 不计入本技能 |
| 可用性 | 8 | 复制即用、流程清晰、近一周仍在修订;但示例较少,需自备 Maven/Gradle 构建环境 |
| 安全性 | 9 | 见下方检查清单 |
综合 = 三项均值 = 7.33。
安全检查清单:
- 执行 shell:技能本身不含脚本;仅指示 agent 在用户项目里运行
mvnw verify、gradlew build、mvn test等构建命令,用途明确。通过。 - 联网外发:无外发;仅列出规范与迁移指南的文档链接。通过。
- 凭据:不涉及。通过。
- 可疑指令:通读全文,无提示注入迹象;反而要求“未被明确要求不得迁移”。通过。
- 作者/组织信誉:GitHub 官方合集。通过。
- License:MIT。通过。
- 维护:2026-10-15 仍在提交;skills.sh 上 Gen Agent Trust Hub、Socket、Snyk 三项审计均为通过。通过。
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 差异 |
|---|---|---|
| 本技能 | 给 AI 助手的 javax→jakarta 迁移流程 | 带触发约束、JDK 包例外清单、版本矩阵与基线要求 |
OpenRewrite JavaxMigrationToJakarta 配方 |
自动化重写工具 | 确定性更强、覆盖更广,但需配置构建插件并学习 recipe,不含对话式判断 |
| Eclipse Transformer | 字节码/二进制层转换 | 适合第三方 jar 与无源码场景,不处理源码与配置文件 |
| Tomcat 官方迁移工具与指南 | 运行时迁移 | 针对 Tomcat 部署,不改应用源码 |
核心差异:不替代 OpenRewrite 等工具,而是让助手在改代码时遵守边界与版本对应关系,也可与这些工具配合使用。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
同合集的 java-upgrade 技能会把命名空间迁移委托给本技能;该技能的 2026-10 修订由 Julien Dubois 在评审意见下完成,增加了“未明确要求不得迁移”的约束与版本矩阵。
10. 安装使用方式
# 方式一:npx skills
npx skills add https://github.com/github/awesome-copilot --skill javax-to-jakarta-migration
# 方式二:手动复制
git clone https://github.com/github/awesome-copilot
cp -r awesome-copilot/skills/javax-to-jakarta-migration ~/.claude/skills/
安装后在 Java 项目目录里明确提出“把这个模块迁到 jakarta 命名空间 / 升级到 Tomcat 10.1”之类的请求即会触发;一般无需重启,必要时新开会话。
11. 注意事项
- 只迁移源码与配置;第三方依赖若仍依赖
javax,需自行升级版本或借助 OpenRewrite、Eclipse Transformer 处理二进制。 - 文中示例依赖版本针对 Jakarta EE 10(Servlet 6.0、Tomcat 10.1+);目标运行时不同须按矩阵调整。
- 迁移前务必在干净分支上执行并保证基线构建通过,改动后跑完整测试。
- 技能不含自动化脚本,大型项目的替换量取决于 agent 的执行范围。