【AI全栈12-12】Spring Boot 3.x → 4.x 迁移实操：Jakarta 11、Jackson 3 与 AI 2.0

本文是「Spring Boot + AI 全栈后端」系列第 12 篇，也是收官篇。前 11 篇把能力铺完了，最后这一篇聊一个每个老项目都绕不开的硬活：从 Spring Boot 3.x 迁到 4.x + AI 2.0。示例基于 Spring AI 2.0 / Boot 4.1，验证工程本身就是这个版本，跑绿即证据。

Spring Boot 3.x → 4.x 迁移实操：Jakarta 11、Jackson 3 与 AI 2.0

一、先说清楚：为什么要迁

V哥先把动机摆正。两个理由：

1. AI 2.0 要 Boot 4.x 底座。Spring AI 2.0 的很多 API 是跟着 Boot 4 / Jakarta 11 走的，老 3.x 项目想用最新 Spring AI，基本绕不开这一迁。
2. 新特性只在 4.x。虚拟线程默认、Jackson 3、Jakarta 11 命名空间------这些不是"可选项"，是 4.x 的默认形态。

但迁移最怕的是"破坏性变更藏在编译过了、一跑就炸"的地方。V哥把踩过的三个大坑和一套验证法一次性讲透。

二、最显眼的坑：javax → jakarta，import 全改

这是第一道坎，也是最容易低估的一道。所有 javax.* 的注解、类型，在 Boot 4.1 里一律是 jakarta.*：

// ❌ 迁移前（Boot 3.x）：javax
import javax.validation.Valid;
import javax.persistence.Entity;

// ✅ 迁移后（Boot 4.x）：jakarta
import jakarta.validation.Valid;
import jakarta.persistence.Entity;

别以为只是改个包名------很多老项目里 javax.validation、javax.annotation、javax.persistence 散在上百个文件 。V哥的建议是：用 IDE 的全项目替换（Rename / Find-Replace）一次性改，改完先编译，让编译器把漏网的 javax.* 全揪出来。我们验证工程迁完后，专门写了断言：javax.validation.Valid 已经 ClassNotFoundException，而 jakarta.validation.Valid 能正常加载------这才说明命名空间真正清干净了。

三、第二道坑：Jackson 3，包名从 com.fasterxml.jackson 变 tools.jackson

很多人不知道：Boot 4.1 把 JSON 引擎换成了 Jackson 3，包名直接变了：

// ❌ Jackson 2（Boot 3.x 默认）
import com.fasterxml.jackson.databind.ObjectMapper;

// ✅ Jackson 3（Boot 4.1 默认）
import tools.jackson.databind.ObjectMapper;

V哥提醒两点：第一 ，你代码里直接 new com.fasterxml.jackson.databind.ObjectMapper() 在 4.x 下不是不行（2.x 作为传递依赖还在），但新代码应该换 tools.jackson；第二 ，Jackson 3 的 API 有零星不兼容，比如部分旧的 ObjectMapper 配置方法签名变了。最稳的做法是先把 ObjectMapper 换成 3.x 的包，逐个跑序列化测试。我们验证工程里就有一句：用 tools.jackson.databind.ObjectMapper 把一个 record 序列化再反序列化，对象要原样回来------record 在 Jackson 3 里是一等公民，不用再挂参数名模块。

四、第三道坑：Spring AI 2.0 的 API 漂移

如果你顺带把 Spring AI 升到 2.0，几个 API 和 1.x 不一样，V哥在前面 11 篇的验证工程里都踩过、也都在测试里锁死了：

• ChatResponse 的构造要用 new Generation(new AssistantMessage(text)) 包一层，不能直接塞字符串；
• ChatClient 的 .options() 收的是 ChatOptions.Builder<?>，不是 build() 后的对象；
• entity(Class) 直接把模型 JSON 落 POJO，但要给字段加 @JsonPropertyDescription 让 schema 对齐。

这些不是"记住就行"，是写进测试、跑绿才算数。V哥的原则：凡是 API 漂移点，都配一个离线桩把行为锁住，下次升级一跑测试就知道哪里裂了。

五、V哥的迁移六步路线图

别一上来就 mvn spring-boot:upgrade。V哥按这个顺序走，每一步都能回滚、能验证：

1. 升 JDK 到 21 ：Boot 4.1 最低 Java 17，但 V哥建议直接 21，虚拟线程才用得爽。先改构建文件里的 java.version，确保本地和 CI 都换。
2. 升 Boot 父版本到 4.1.1 ：改 spring-boot-starter-parent 版本，处理 BOM 变化。
3. 全项目改 jakarta：上面说的 import 替换，编译过一遍。
4. 改 Jackson 包名 ：com.fasterxml.jackson 换成 tools.jackson，跑序列化测试。
5. 升 Spring AI 到 2.0.1：处理 API 漂移，复用前面各篇的桩和测试。
6. 全量测试 + 灰度：先在测试环境把 74 个用例跑绿，再小流量灰度，监控降级率。

六、怎么判断迁移"真的成了"，而不是"编译过了"

V哥最反对"编译过就等于迁完"。我们验证工程迁到 Boot 4.1 后，专门落了四个断言，全过才算迁移验收通过：

• Jakarta 校验还在 ：一个带 @Valid 的 record DTO，非法请求返 400，合法返 200；
• Jackson 3 能序列化 record：写出去再读回来，对象不变；
• javax 命名空间确实没了 ：javax.validation.Valid 加载不了，jakarta.validation.Valid 能加载；
• AI 栈完好 ：ChatClient 照样能调，回答非空。

这四个断言，把"命名空间、JSON 引擎、校验框架、AI 能力"四个迁移高发雷区一次性验掉。编译通过只是门票，这四个绿灯才是验收。

七、破坏性变更一张图记牢 + 老代码前后对比

光讲概念容易忘，V哥把四件大事压成一张图，迁移前对着勾一遍。再给一段最典型的"老 Controller"前后对比，你照着改就行：

// ❌ 迁移前（Boot 3.x + Spring AI 1.x）
@RestController
@RequestMapping("/api/legacy")
public class LegacyOrderController {
    @PostMapping
    public String create(@javax.validation.Valid @RequestBody OrderDto dto) {
        // 1.x 直接塞字符串，2.x 要包 AssistantMessage
        ChatResponse r = client.call(new Prompt(dto.sku()));
        return r.getResult().getOutput().getContent();
    }
}

// ✅ 迁移后（Boot 4.1 + Spring AI 2.0）
@RestController
@RequestMapping("/api/new")
public class NewOrderController {
    private final ChatClient chatClient;
    public NewOrderController(ChatModel model) { this.chatClient = ChatClient.create(model); }

    @PostMapping
    public String create(@jakarta.validation.Valid @RequestBody OrderDto dto) {
        // 2.0 的 ChatClient 流式 API，output 直接用 content()
        return chatClient.prompt().user(dto.sku()).call().content();
    }
}

注意三处同时变：javax → jakarta、老的 ChatClient.call(Prompt) → 新的 builder 链式 prompt().user().call().content()、ChatResponse 取内容的方式也变了。这三处往往在同一文件里连着炸，所以 V哥才说"AI 升级和 Boot 升级要一起做、一起验"。

顺带一句 Java 21 的红利：迁到 4.1 后可以把高并发 IO 换成虚拟线程，一行配置就能让 Web 容器用虚拟线程处理请求，吞吐明显上去：

@Bean
public TomcatProtocolHandlerCustomizer<?> virtualThreads() {
    return handler -> handler.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
}

这行在 Boot 3.x 也能写，但 V哥建议和迁移一起做------反正都要动构建，顺手把虚拟线程红利拿了。

八、V哥的迁移铁律（收官清单）

1. 先改能编译的，再查运行期的：jakarta、Jackson 包名是编译期就能暴露的；AI API 漂移、序列化差异要在测试里抓。
2. 每个破坏性变更配一个测试：javax 没了、Jackson 3 往返、AI 调通------都是可断言的，别靠肉眼。
3. 别一次性大爆炸：六步走，每步可回滚、可验证；JDK 和 Boot 先动，业务代码最后动。
4. 灰度 + 监控兜底：小流量先上，盯降级率和错误率，异常立刻回退。

到这里，V哥的「Spring Boot + AI 全栈后端」12 篇就收官了：从"为什么选 Spring Boot 做 AI 后端"，到对话、成本、结构化、实时、私有知识、Agent、MCP、流式、多模态、上线扛量，最后落到"老项目怎么稳迁"。AI 全栈后端不是把模型接进来就完事，是一整套工程能力------希望这 12 篇能帮你把这条路走顺。