![](https://developer.qcloudimg.com/http-save/yehe-7353521/28d924c468f4796506d19089313ad2ff.jpg)

> 一年多前，我在另一个迁移项目里尝试过 OpenRewrite，做了可行性验证，最终评估下来方案不合适，那个项目转而采用了 AI 的方式。顺着那次探索写了个系列，然后就搁置了。最近真正的迁移计划提上日程，翻出来一看——当时踩过的坑、记下来的东西，全都用上了。
> 
> 任何学习和痛苦都不会白费，只是兑现的时间不一定。

## 为什么迁移这么痛

Spring Boot 2 的 EOL 早已过去，但很多团队的升级计划还停在 Jira 的某个角落吃灰。不是不想升，是真的怕。

怕什么？怕的不是技术本身，而是规模。`javax.*` 全部变成 `jakarta.*`，Spring Security 配置 API 重写，WebMVC 和异步配置的适配器类被移除，JUnit 4 注解也换了一套。任何一个变化单独处理都不难，但加在一起，乘以整个代码库的文件数量，就成了一个让人望而却步的工程量——而且还是那种高度重复、极易出错、回归验证代价极高的工作。

这类变更有一个共同特征：**规则清晰，但执行枯燥，且不能出错**。每一处 `javax.persistence.Entity` 都应该改成 `jakarta.persistence.Entity`，没有例外。这种工作本质上不需要人来做判断，它需要的是一种可以精确、批量、可审计地修改代码的机制。

[OpenRewrite](https://docs.openrewrite.org) 就是为此而生的。

## OpenRewrite 是什么

OpenRewrite 是一个专为大规模代码变更设计的自动化重构引擎，最初由 Netflix 内部孵化，现在由 [Moderne](https://moderne.io) 维护。它的核心思想是：把代码解析成一棵**无损语义树（Lossless Semantic Tree，LST）**，在树上做精确变换，再把结果写回代码——全程保留原有的格式、注释和空白。

这是一个关键细节。普通的文本替换工具不理解代码语义，正则表达式不知道 `import javax.persistence.Entity` 和字符串里写的 `"javax.persistence.Entity"` 有什么区别。OpenRewrite 的 LST 是类型感知的，它知道每个标识符解析到哪个类、哪个方法，所以它的变更是精确的。

变更逻辑封装在 **Recipe** 里。Recipe 可以是声明式的（YAML 配置），也可以是命令式的（Java 实现），它通过 **Visitor 模式**遍历 LST，找到匹配的节点，施加变换。官方提供了数百个开箱即用的 Recipe，覆盖 Spring、JUnit、Lombok、Mockito 等主流框架的迁移场景。你也可以写自己的。

如果你想深入了解这套机制，我此前写过一个系列：

- OpenRewrite 基础与原理
- 无损语义树（LST）详解
- Recipe 与 Visitor 实现
- 用 JavaTemplate 创建复杂 LST

这篇文章不会重复这些内容，而是聚焦在一个实际问题上：**拿它来做 Spring Boot 迁移，体验如何**。

但在开始之前，有个问题值得先回答。

## 既然有 AI，为什么还需要 OpenRewrite

这是个合理的质疑。现在的 AI coding assistant 能读懂代码、理解迁移规则，你把文件丢给它，告诉它 " 把所有 `javax.persistence` 换成 `jakarta.persistence`"，它能做到。那为什么还需要专门的工具？

问题在于，AI 的输出是**概率性**的，而代码迁移需要的是**确定性**。

你把 20 个文件交给 AI 处理，它改对了 18 个，第 19 个它觉得这里的 import 顺序也可以顺手调整一下，第 20 个它误判了某个同名类的包路径。这些都是真实会发生的情况。更麻烦的是，你很难事先知道它在哪里 " 发挥了创意 "——你必须逐文件做 diff 审查，工作量不比手动改少多少。

还有一个问题是**规模**。一个中等规模的 Spring Boot 项目可能有几百个 Java 文件，涉及 `javax.*` 的 import 可能分布在其中的大半。让 AI 一次处理完整个代码库，超出上下文窗口；分批处理，需要人工协调，还面临批次间不一致的风险。

OpenRewrite 在这两点上恰好是 AI 的对立面：**同一个 Recipe，在任意规模的代码库上运行，结果完全一致、完全可预测**。它不会 " 顺手 " 做额外修改，不会跳过某个文件，不会因为代码风格不统一而行为不同。每次运行产生的 diff 可以被审查、被 code review、被版本控制追踪。

这不是说 AI 没有用武之地。恰恰相反——在这次迁移里，有两处问题是 OpenRewrite 处理不了的，最终还是靠 AI 辅助解决的。后面会讲到。

AI 擅长处理**语义复杂、需要判断**的变更；OpenRewrite 擅长处理**规则明确、需要精确执行**的变更。迁移工作里两类都有，用对工具才是关键。

## Recipe-First 是什么

Recipe-First 不是一个官方概念，而是一种做事方式的选择：**当你发现代码需要变更时，第一反应不是打开编辑器，而是问「能不能写成 Recipe」**。

这个区别听起来微妙，但影响很深远。

手动改代码，改完就结束了。这次迁移积累的知识——哪些 API 变了、怎么替换、有哪些坑——存在于开发者的记忆里，不可转移，下次换一个项目还得重来。而把这些知识写成 Recipe，它就变成了可执行的文档：不仅记录了「应该怎么改」，还能直接帮你改。

这次迁移里，我们把 `httpclient5` 与 `httpcore5` 的版本对齐问题写成了一个自定义 Recipe：

```yaml
type: specs.openrewrite.org/v1beta/recipe
name: com.example.FixHttpComponents5VersionMismatch
displayName: Fix HttpComponents 5 version mismatch
recipeList:
  - org.openrewrite.maven.ChangePropertyValue:
      key: httpcore5.version
      newValue: 5.3.4
      addIfMissing: true
```

这个 Recipe 解决的问题很具体：`httpclient5 5.4.x` 依赖 `httpcore5 5.3.x`，但很多项目里 `httpcore5.version` 被锁定在了旧版本，导致运行时 `NoSuchMethodError`。如果靠手动排查，每次遇到这个问题都要重新走一遍诊断流程。而有了这个 Recipe，下一个遇到同样问题的项目，一条命令解决。

内部公共库的 API 迁移也是同样的思路。`ApiResponse.success()` 改名为 `ApiResult.ok()`，`@RequireLogin` 换成 `@Authenticated`——这些变更写成 Recipe 之后，不再需要有人去记「内部库 v2 的变更清单」，Recipe 本身就是那份清单，而且是可运行的。

Recipe-First 的本质是把**迁移知识资产化**。

## 一次完整迁移过程

迁移的起点是一个标准的 Spring Boot 2.7.18 项目，包含 REST API、Spring Security 配置、异步处理、HttpClient 封装，以及一批 JUnit 4 测试。目标是升级到 Spring Boot 3.5.0。

整个过程分两步。

**第一步：跑官方 Recipe**

OpenRewrite 的 `rewrite-spring` 模块提供了 `UpgradeSpringBoot_3_5` Recipe，它是一个组合 Recipe，内部编排了数十个子 Recipe，覆盖了绝大多数迁移场景。一条命令：

```bash
mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:LATEST \
  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_5 \
  -pl web-app
```

运行完成后，13 个文件被修改。主要变更包括：

`javax.*` 全面换成 `jakarta.*`——`javax.persistence`、`javax.validation`、`javax.servlet` 里的每一处 import，一个不漏。`WebSecurityConfigurerAdapter` 被移除，Security 配置改为直接注入 `SecurityFilterChain` Bean。`WebMvcConfigurerAdapter`、`HandlerInterceptorAdapter`、`AsyncConfigurerSupport` 这些废弃的适配器类全部替换为对应的接口实现。JUnit 4 的 `@RunWith(SpringRunner.class)` 换成 `@ExtendWith(SpringExtension.class)`，`org.junit.Test` 换成 `org.junit.jupiter.api.Test`，断言类也一并迁移到 JUnit 5 的 `Assertions`。HttpClient 4 的 API 迁移到 HttpClient 5。`ResponseStatusException.getStatus()` 换成 `getStatusCode()`。

**第二步：跑自定义 Recipe**

官方 Recipe 处理不了项目特有的问题。先构建自定义 Recipe 模块，再运行：

```bash
mvn install -pl migration-recipes -q
mvn org.openrewrite.maven:rewrite-maven-plugin:6.12.0:run -pl web-app
```

这一步完成了两件事：`httpcore5` 版本对齐（避免运行时 `NoSuchMethodError`），以及内部公共库 v1 到 v2 的 API 迁移。

两步跑完，`mvn clean install`，BUILD SUCCESS，测试全部通过，`/actuator/health` 返回 `{"status":"UP"}`。

当然，这中间还有两处需要手动处理的问题。

## Recipe 搞不定的地方

两处手动修复，都有一个共同原因：**变更涉及的不是语法替换，而是 API 行为的根本改变**，没有机械化的对应规则可以套用。

**第一处：HttpClient 5 移除了超时配置方法**

`RestTemplateConfig` 里原本有这样的代码：

```java
httpClient.setConnectTimeout(5000);
httpClient.setReadTimeout(30000);
```

HttpClient 5 把这些方法彻底移除了，不是改名，是消失了。超时配置的方式变成了通过 `RequestConfig` 对象统一管理：

```java
RequestConfig requestConfig = RequestConfig.custom()
    .setConnectTimeout(Timeout.ofSeconds(5))
    .setResponseTimeout(Timeout.ofSeconds(30))
    .setConnectionRequestTimeout(Timeout.ofSeconds(10))
    .build();

CloseableHttpClient httpClient = HttpClients.custom()
    .setDefaultRequestConfig(requestConfig)
    .build();
```

这种变更 Recipe 处理不了——它需要理解旧代码的意图，然后用完全不同的结构重新表达。这是 AI 擅长的事，给它看旧代码和新 API 文档，它能正确完成这个转换。

**第二处：`@Override` 不再成立**

OpenRewrite 迁移完成后，`SecurityConfig` 里的 `userDetailsService()` 方法上出现了一个编译错误：`@Override` 无效，因为 Spring Boot 3 里这个方法不再来自任何父类，它已经是一个普通的 `@Bean` 方法。删掉那个 `@Override` 即可。

这个问题理论上可以写成 Recipe，但它边界模糊——不是所有 `@Override` 都该删，只有这个特定的方法在特定的迁移上下文里需要删。OpenRewrite 可以精确操作 LST，但告诉它「只删这种情况下的 `@Override`」，Recipe 本身就变得比直接删更复杂了。

这两处加在一起，不到 10 分钟。放在整个迁移工程量的比例里，是噪音级别的。

这也说明了一个问题：Recipe 的边界不是工具的缺陷，而是合理的分工。规则明确的变更，交给 Recipe；需要语义判断的，交给人或 AI。迁移工作里两类都有，但比例差异悬殊——Recipe 处理了 95%，手动处理了剩下的 5%。

## Recipe 是资产，不是脚本

脚本是一次性的。它解决了眼前的问题，跑完就归档，下次遇到类似的问题，你得重新写或者重新找。Recipe 不一样——它是**可复用的迁移知识**，随着时间积累，会成为团队真正有价值的工程资产。

这次整理出来的 Recipe 放在 [spring-boot-migration-toolkit](https://github.com/addozhang/spring-boot-migration-toolkit) 的 `v2` 分支里。任何项目需要做同样的迁移，把这个模块引入、跑两条命令就够了。它不需要懂 OpenRewrite 内部机制，不需要查迁移文档，不需要团队里有人曾经踩过那些坑——因为踩坑的经验已经固化在 Recipe 里了。

更重要的是，Recipe 有一个脚本和 AI 都做不到的特性：**可验证性**。你可以先用 `rewrite:dryRun` 看它会改什么，再决定要不要真的执行。执行之后产生的是干净的 git diff，可以被 code review，可以被 CI 门禁拦截，可以被回滚。整个变更链路是透明的、可审计的。

顺便一提：[之前写过一篇](https://atbug.com/one-command-to-convert-legacy-spring-rest-services-to-mcp-services/) 用 OpenRewrite 把传统 Spring REST 服务一键转换成 MCP Server 的文章，Recipe-First 的思路在那里也同样适用——只要变更规则是确定的，就可以被 Recipe 化，就可以被重复使用。

这个逻辑不局限于 Spring Boot 升级。任何规模化的代码变更——内部框架升级、API 废弃替换、安全规范落地——都可以用这个方式来做。**把变更知识写成 Recipe，把 Recipe 当作代码一样管理**，这才是 OpenRewrite 想让你做的事。

## 现在升到哪个版本合适

既然要升，就升到一个值得的版本。Spring Boot 各版本的社区支持周期如下（数据来自 [endoflife.date](https://endoflife.date/spring-boot)）：

| 版本 | 发布日期 | 社区支持截止 |
|------|----------|--------------|
| 3.3 | 2024-05 | 2025-06 ⚠️ 已过期 |
| 3.4 | 2024-11 | 2025-12 ⚠️ 已过期 |
| **3.5** | **2025-05** | **2026-06 ← 推荐** |
| 4.0 | 2025-11 | 2026-12 |

> 注：各版本均有 Broadcom 商业付费的扩展支持（Extended Support），到期后可继续获得安全补丁，但需购买 Spring 商业许可证，不在本文讨论范围内。

结论：**先升到 3.5，4.0 留作下一步**。

- 3.3 / 3.4 社区支持已过期，跳过
- 3.5 是 3.x 系列最新稳定版，社区支持到 2026-06，迁移成本低
- 4.0 虽然社区支持到 2026-12，但引入了更多 breaking changes，从 2.x 直接跳风险更高——先落地 3.5，再升 4.0 是更稳的两步走策略

本文所有示例均已基于 Spring Boot 3.5.0 验证，直接使用即可。

## 结语

Spring Boot 2 → 3 的迁移，本质上是一个规模化变更问题，而不是一个技术难题。大多数变更的规则是明确的，只是数量多、分布散、人工处理容易出错。

OpenRewrite 解决的正是这个问题。官方 Recipe 处理框架层面的变更，自定义 Recipe 处理项目特有的问题，少数需要语义判断的地方留给人或 AI。这次迁移里，两步命令完成了 95% 的工作，剩下的不到 10 分钟手动处理。

如果你还没开始迁移，现在是个好时机。如果你已经在手动改代码，可以停下来想想：这个改法，能不能写成 Recipe。




一年多前，我在另一个迁移项目里尝试过 OpenRewrite，做了可行性验证，最终评估下来方案不合适，那个项目转而采用了 AI 的方式。顺着那次探索写了个系列，然后就搁置了。最近真正的迁移计划提上日程，翻出来一看——当时踩过的坑、记下来的东西，全都用上了。  任何学习和痛苦都不会白费，只是兑现的时间不一定。

Spring Boot 2 升 3：两条命令搞定 95%，AI 收尾

后端

编程语言

开发工具

OpenRewrite是专为大规模代码迁移设计的自动化重构工具，可将SpringBoot 2升级到3.5.0的90%工作自动化处理。它通过无损语义树精确修改代码，保留格式和注释，避免AI工具的不确定性。官方Recipe处理框架变更，自定义Recipe解决项目特有问题，仅5%需手动调整。建议先升级到社区支持到2026年的SpringBoot 3.5版本，再考虑后续升级。

安全补丁

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenRewrite是专为大规模代码迁移设计的自动化重构工具，可将SpringBoot 2升级到3.5.0的90%工作自动化处理。它通过无损语义树精确修改代码，保留格式和注释，避免AI工具的不确定性。官方Recipe处理框架变更，自定义Recipe解决项目特有问题，仅5%需手动调整。建议先升级到社区支持到2026年的...

Spring Boot 2 升 3：两条命令搞定 95%，AI 收尾-腾讯云开发者社区-腾讯云

Spring Boot 2 升 3：两条命令搞定 95%，AI 收尾

Spring Boot 2 升 3：两条命令搞定 95%，AI 收尾

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐