企业官网建设流程全解析

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

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

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 的默认形态。

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

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

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

// ❌ 迁移前（Boot 3.x）：javaximportjavax.validation.Valid;importjavax.persistence.Entity;// ✅ 迁移后（Boot 4.x）：jakartaimportjakarta.validation.Valid;importjakarta.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 默认）importcom.fasterxml.jackson.databind.ObjectMapper;// ✅ Jackson 3（Boot 4.1 默认）importtools.jackson.databind.ObjectMapper;

提醒两点：第一，你代码里直接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 不一样，在前面 11 篇的验证工程里都踩过、也都在测试里锁死了：

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

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

五、迁移六步路线图

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

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 个用例跑绿，再小流量灰度，监控降级率。

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

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

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

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

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

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

// ❌ 迁移前（Boot 3.x + Spring AI 1.x）@RestController@RequestMapping("/api/legacy")publicclassLegacyOrderController{@PostMappingpublicStringcreate(@javax.validation.Valid@RequestBodyOrderDtodto){// 1.x 直接塞字符串，2.x 要包 AssistantMessageChatResponser=client.call(newPrompt(dto.sku()));returnr.getResult().getOutput().getContent();}}// ✅ 迁移后（Boot 4.1 + Spring AI 2.0）@RestController@RequestMapping("/api/new")publicclassNewOrderController{privatefinalChatClientchatClient;publicNewOrderController(ChatModelmodel){this.chatClient=ChatClient.create(model);}@PostMappingpublicStringcreate(@jakarta.validation.Valid@RequestBodyOrderDtodto){// 2.0 的 ChatClient 流式 API，output 直接用 content()returnchatClient.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 容器用虚拟线程处理请求，吞吐明显上去：

@BeanpublicTomcatProtocolHandlerCustomizer<?>virtualThreads(){returnhandler->handler.setExecutor(Executors.newVirtualThreadPerTaskExecutor());}

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

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

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

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