1. 项目背景与核心痛点

Spring Boot 3.x版本最重大的变更之一就是全面转向Jakarta EE 9+的命名空间。这个改动源于Oracle将Java EE捐赠给Eclipse基金会后的品牌重塑，所有原javax.包名统一变更为jakarta.。对于正在使用Spring Boot 2.x的企业来说，这直接导致：

• 超过80%的Java EE相关API调用需要修改导入语句
• 所有依赖的第三方库必须同时支持Jakarta命名空间
• 配置文件中的javax.*属性需要同步更新
• 测试用例中的Mock对象需要适配新包路径

我在实际迁移过程中发现，单纯使用IDE的全局替换会导致以下典型问题：

1. 部分库同时存在javax和jakarta版本（如JPA实现）
2. 某些框架的SPI扩展点需要特殊处理（如Hibernate的UserType）
3. 测试环境与运行时环境的包扫描差异

2. 迁移前准备

2.1 环境清单检查

建议先建立完整的依赖树报告：

mvn dependency:tree -Dincludes=javax.* > dep-tree.txt

重点关注这些易出问题的依赖组：

• 持久层：javax.persistence, javax.transaction
• Web服务：javax.servlet, javax.ws.rs
• 验证框架：javax.validation
• 其他工具类：javax.annotation, javax.xml.bind

2.2 兼容性矩阵构建

制作类似下表的版本对照表：

关键提示：不要尝试混合使用javax和jakarta的依赖，这会导致类加载冲突

3. 分步迁移实战

3.1 基础包名替换

使用IDE的结构化替换（非纯文本替换）：

1. IntelliJ IDEA中按Ctrl+Shift+R
2. 勾选"Preserve case"和"Whole words only"
3. 使用正则表达式：javax\.(persistence|servlet|ws|transaction)\..*

对于Maven项目，需要同步修改：

<!-- 错误示例 --> <dependency> <groupId>javax.servlet</groupId> <artifactId>javax.servlet-api</artifactId> <version>4.0.1</version> </dependency> <!-- 正确示例 --> <dependency> <groupId>jakarta.servlet</groupId> <artifactId>jakarta.servlet-api</artifactId> <version>6.0.0</version> </dependency>

3.2 特殊场景处理

3.2.1 JPA实体类转换

对于使用@Converter的场景：

// 旧版 import javax.persistence.Convert; import javax.persistence.Converter; // 新版 import jakarta.persistence.Convert; import jakarta.persistence.Converter;

注意Embeddable对象中的关联注解也需要更新：

@Embeddable public class Address { // 旧版 @ManyToOne(fetch = FetchType.LAZY) @JoinColumn(name = "city_id") private City city; // 新版保持相同结构，仅改包名 }

3.2.2 Spring Security配置

WebSecurityConfigurerAdapter已被废弃，新的Lambda DSL风格配置示例：

@Configuration @EnableWebSecurity public class SecurityConfig { @Bean SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth -> auth .requestMatchers("/public/**").permitAll() .anyRequest().authenticated() ) .formLogin(form -> form .loginPage("/login") .permitAll() ); return http.build(); } }

3.3 测试代码适配

JUnit 5的测试类需要特别注意：

// 旧版 import javax.servlet.ServletContext; // 新版 import jakarta.servlet.ServletContext; @SpringBootTest class MyControllerTest { @Autowired private ServletContext servletContext; // 现在来自jakarta包 @Test void contextLoads() { assertNotNull(servletContext); } }

Mock测试的调整示例：

// 旧版 import static org.mockito.Mockito.*; import javax.servlet.http.HttpServletRequest; // 新版 import static org.mockito.Mockito.*; import jakarta.servlet.http.HttpServletRequest; @Test void testRequestHandler() { HttpServletRequest request = mock(HttpServletRequest.class); when(request.getParameter("name")).thenReturn("test"); // ... 测试逻辑 }

4. 疑难问题解决方案

4.1 混合依赖冲突

典型错误现象：

java.lang.LinkageError: loader constraint violation

解决方案步骤：

1. 执行mvn dependency:tree找出冲突依赖
2. 对每个冲突依赖执行：

   <dependency> <groupId>problematic.group</groupId> <artifactId>problematic-artifact</artifactId> <exclusions> <exclusion> <groupId>javax.*</groupId> <artifactId>*</artifactId> </exclusion> </exclusions> </dependency>

3. 添加对应的jakarta版本依赖

4.2 序列化兼容问题

当遇到JSON序列化异常时，检查是否使用了JAXB注解：

// 旧版 import javax.xml.bind.annotation.XmlElement; // 新版 import jakarta.xml.bind.annotation.XmlElement; @Getter @Setter public class UserDTO { @XmlElement(name = "user_name") private String username; }

Jackson的兼容配置：

@Configuration public class JacksonConfig { @Bean public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() { return builder -> { // 处理jakarta包下的JAXB注解 builder.annotationIntrospector(new JaxbAnnotationIntrospector(TypeFactory.defaultInstance())); }; } }

5. 迁移后验证清单

5.1 编译时检查

确保项目中不存在任何javax.*的导入：

grep -r "import javax." src/

5.2 运行时验证

创建健康检查端点：

@RestController @RequestMapping("/migration") public class MigrationCheckController { @GetMapping("/check") public Map<String, String> checkEnvironment() { return Map.of( "servletContext", ServletContext.class.getPackage().getName(), "persistence", EntityManager.class.getPackage().getName() ); } }

预期输出：

{ "servletContext": "jakarta.servlet", "persistence": "jakarta.persistence" }

5.3 性能基准测试

使用JMeter对比关键指标：

6. 进阶优化建议

6.1 构建时处理

使用Maven Rewrite插件实现自动化迁移：

<plugin> <groupId>org.openrewrite.maven</groupId> <artifactId>rewrite-maven-plugin</artifactId> <version>5.8.1</version> <configuration> <activeRecipes> <recipe>org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta</recipe> </activeRecipes> </configuration> <dependencies> <dependency> <groupId>org.openrewrite.recipe</groupId> <artifactId>rewrite-migrate-java</artifactId> <version>2.1.0</version> </dependency> </dependencies> </plugin>

执行命令：

mvn rewrite:run

6.2 模块化迁移策略

对于大型项目建议采用分层迁移：

1. 先迁移基础设施层（DAO、Util等）
2. 再迁移业务逻辑层（Service）
3. 最后迁移表现层（Controller）

使用接口隔离：

// 通用接口保持javax-free public interface OrderService { Order createOrder(OrderDTO dto); } // 实现类处理jakarta依赖 @Repository public class JpaOrderRepository implements OrderRepository { @PersistenceContext private EntityManager em; // jakarta.persistence }

7. 回滚方案设计

尽管迁移过程经过充分测试，仍需准备回滚方案：

1. 代码版本控制：

   git checkout -b spring-boot-3-migration # 进行所有修改后 git commit -m "Migrate to Spring Boot 3.x"

2. 依赖回滚配置：

   <!-- 在父POM中定义属性 --> <properties> <spring-boot.version>3.1.5</spring-boot.version> <fallback.spring-boot.version>2.7.12</fallback.spring-boot.version> </properties> <!-- 子模块可快速切换版本 --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>${spring-boot.version}</version> </parent>

3. 数据库兼容层：

   public class HibernateCompatSettings { @Bean public Properties jpaProperties() { Properties props = new Properties(); if (isSpringBoot2()) { props.put("hibernate.jpa.compliance.query", "false"); } return props; } private boolean isSpringBoot2() { return SpringBootVersion.getVersion().startsWith("2."); } }

迁移过程中我们团队总结的经验是：先在一个非核心模块上完成全流程验证，记录所有遇到的问题和解决方案，形成内部迁移手册后再推广到全项目。对于特别复杂的遗留系统，可以考虑引入Jakarta转换层进行渐进式迁移