javax-to-jakarta-migration

javax → jakarta 迁移技能

适用场景

• 用户明确要求迁移到 jakarta 命名空间、Tomcat 10+/11 或 Jakarta EE
• java-upgrade 或 spring-boot-4-migration 委托执行命名空间迁移

仅检测到 javax.* 导入并不代表获准执行此迁移；应改为报告这些导入。

在 Spring Boot 项目中，Boot BOM 会管理 Jakarta 版本：不要固定以下版本，并由 Boot 版本决定 Jakarta EE 级别（Boot 4 = Jakarta EE 11，Servlet 6.1）。以下示例针对非 Boot 项目中的 Jakarta EE 10（Servlet 6.0、Tomcat 10.1+）。

流程

步骤 0 — 基线

先运行 ./mvnw verify 或 ./gradlew build 并记录结果；如果基线未通过，不要迁移。将更改放在单独的提交/步骤中。

步骤 1 — 扫描 javax 用法

在代码库中搜索所有需要迁移的 javax.* 导入：

javax.servlet.*      → jakarta.servlet.*
javax.persistence.*  → jakarta.persistence.*
javax.validation.*   → jakarta.validation.*
javax.annotation.*   → jakarta.annotation.*
javax.inject.*       → jakarta.inject.*
javax.enterprise.*   → jakarta.enterprise.*
javax.faces.*        → jakarta.faces.*
javax.ws.rs.*        → jakarta.ws.rs.*
javax.el.*           → jakarta.el.*
javax.json.*         → jakarta.json.*
javax.mail.*         → jakarta.mail.*
javax.websocket.*    → jakarta.websocket.*

不要迁移以下内容（它们仍属于 javax.*）：

• javax.sql.* — 属于 JDK
• javax.naming.* — 属于 JDK（JNDI）
• javax.crypto.* — 属于 JDK
• javax.net.* — 属于 JDK
• javax.security.auth.* — 属于 JDK
• javax.swing.*、javax.xml.parsers.* — JDK 包

步骤 2 — 更新 pom.xml

替换依赖坐标。选择与目标运行时匹配的 API 版本；下表针对 Jakarta EE 10（Tomcat 10.1+、Servlet 6.0）：

目标运行时	Jakarta EE	Servlet	Persistence	Validation	Annotations
Tomcat 10.0	9	5.0	3.0	3.0	2.0
Tomcat 10.1	10	6.0	3.1	3.0	2.1
Tomcat 11	11	6.1	3.2	3.1	3.0

旧版	新版
javax.servlet:javax.servlet-api	jakarta.servlet:jakarta.servlet-api:6.0.0
javax.persistence:javax.persistence-api	jakarta.persistence:jakarta.persistence-api:3.1.0
javax.validation:validation-api	jakarta.validation:jakarta.validation-api:3.0.2
javax.annotation:javax.annotation-api	jakarta.annotation:jakarta.annotation-api:2.1.1

步骤 3 — 更新 web.xml（如果存在）

version 必须与目标 Servlet 级别一致（Tomcat 10.0 为 5.0，Tomcat 10.1 为 6.0，Tomcat 11 为 6.1）；以下示例适用于 Servlet 6.0：

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="4.0">


<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" version="6.0">

步骤 4 — 更新 Java 源文件

仅将步骤 1 中识别出的 Jakarta EE javax. 导入替换为 .java 文件中对应的 jakarta. 导入；保留 JDK 包（例如 javax.sql、javax.crypto）不变。同时检查非 Java 引用：persistence.xml（javax.persistence.* 属性）、META-INF/services、beans.xml、属性文件/YAML、字符串类名和反射。

步骤 5 — 验证

1. 运行 mvn clean compile 或 gradlew build — 修复所有编译错误
2. 运行 mvn test 或 gradlew test — 确保所有测试通过
3. 搜索剩余的 javax.* 导入（排除 JDK 包）

上游资料（迁移前阅读）

获取目标版本对应的页面；如与本技能冲突，优先遵循上游资料。

• Jakarta EE 规范：https://jakarta.ee/specifications/
• Eclipse Transformer（二进制/字节码转换）：https://github.com/eclipse-transformer/transformer
• OpenRewrite org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta：https://docs.openrewrite.org/recipes/java/migrate/jakarta/javaxmigrationtojakarta
• Tomcat 9 到 10 的迁移：https://tomcat.apache.org/migration-10.html
• Hibernate 迁移指南：https://hibernate.org/orm/documentation/migrate/
• Spring Boot 3 升级（Jakarta EE 9+ 基线）：https://docs.spring.io/spring-boot/upgrading.html

输出

提供迁移摘要，列出所有已更改的文件、已替换的导入，以及任何所需的手动步骤。