Spring AI 2.0 升级即编译报错？9 个破坏性变更逐个拆解，附完整迁移代码

2026 年 6 月 12 日 Spring AI 2.0.0 GA 发布，基线从 Boot 3.5 一路跳到 Boot 4 + Framework 7 + Jackson 3。昨天（8 月 20 日），CSDN 一篇深度迁移指南刷屏技术圈，同日 JeecgBoot v3.9.3 宣布全面适配 Spring Boot 4。Java AI 生态正在经历一次"换底子"式大升级——你的项目升得上去吗？

一、为什么这次升级值得你高度关注

先交代热点背景。2026 年 8 月 20 日，两件事同时发生：

5CSDN 发布《Spring AI 2.0 升级实战：9 个破坏性变更逐条迁移》，基于官方 Upgrade Notes，将三十多条变更归纳为 9 个破坏性变更，引发技术社区大量转发讨论

6JeecgBoot v3.9.3 正式发布，后端全面适配 Spring Boot 4，AI 低代码迈入 2.0 阶段，前端一步到位切到 Vite 8

这不是普通的版本迭代。Spring AI 官方的原话是：

Spring AI 2.0 embraces using ChatClient as the most common user-facing API while ChatModel is more of a lower-level building block.

翻译过来：ChatClient 是唯一推荐入口，ChatModel 降级为底层构建块。 如果你还把它当成 1.x → 1.y 的次版本升级，编译报错会教你做人。

据 Azul《2026 State of Java Survey》报告，62% 的企业已使用 Java 开发 AI 功能，较去年的 50% 显著提升。Spring AI 2.0 正是这波浪潮的基础设施。

二、9 个破坏性变更全景速查表

先上一张总览表，升级前对着检查，心里有数：

| 编号

变更名称

影响面

痛感级别

基线大跳版 Boot 4 / Framework 7 / Jackson 3

全局

极高

| |

Options 体系重构：Builder 创建、不可变

所有调用链

高

| |

ChatModel 降级，ChatClient 成唯一入口

业务代码

高

| |

模型提供商精简：OpenAI 3→1、Anthropic 2→1

POM 依赖

中

| |

工具注册方式变更：@Bean + @Description 移除

Agent 代码

极高

| |

ToolCallingAdvisor 自动注册

Advisor 链

中

| |

配置扁平化

YAML 配置

中

| |

MCP 生态换血：SDK 2.0、Streamable HTTP

MCP 对接

高

| |

对话记忆重构 + 温度 / maxTokens 默认值变化

会话管理

中

下面挑出影响最大、踩坑最痛的 4 个，逐个用代码拆解。

三、变更一：基线大跳版——Jackson 3 包名全改

这是最"硬"的一个变更。Spring AI 2.0 底座从 Spring Boot 3.5 跳到 Boot 4.0/4.1 + Framework 7.0，连 JSON 库都从 Jackson 2 换成了 Jackson 3。

核心变化：Jackson 3 的包名从 com.fasterxml.jackson.* 改成了 tools.jackson.*

新旧基线对比：

| 项目

1.x

2.0

Spring Boot

3.2 ~ 3.5

4.0 / 4.1

| |

Spring Framework

6.x

7.0

| |

Jackson

2（com.fasterxml）

3（tools.jackson）

| |

空安全

无统一标注

JSpecify 全面标注

| |

JDK

17+

17+（建议 21+）

如果你在项目里写了 ObjectMapper 定制代码，import 就得批量改：

CODE

// 1.x 写法

import com.fasterxml.jackson.databind.ObjectMapper;

import com.fasterxml.jackson.databind.JsonNode;

// 2.0 写法

import tools.jackson.databind.ObjectMapper;

import tools.jackson.databind.JsonNode;

Spring AI 2.0 新增了 JsonHelper 工具类统一 JSON 编解码，Jackson 3 已内置 java.time 支持，无需再注册 JavaTimeModule：

CODE

// 2.0 推荐用法

JsonHelper jsonHelper = new JsonHelper();

MyType obj = jsonHelper.fromJson(json, MyType.class);

String out = jsonHelper.toJson(obj);

踩坑提示：所有显式声明的 Jackson 2 依赖要删掉，统一走 Boot 4 BOM。老版本 MyBatis、ShardingSphere 等第三方库，升级前先查它们的 Boot 4 适配版本。

四、变更五：工具注册方式变了（影响最大）

Agent 开发者最关心的一个。1.x 时代用 @Bean + @Description 注册 Function 的方式，在 2.0 里被直接移除。

CODE

// ❌ 1.x 写法，2.0 不再工作

@Bean

@Description(“获取指定城市的当前天气”)

Function currentWeather() {

return weatherService::getWeather;

}

// ✅ 2.0 写法

@Bean

ToolCallback currentWeather() {

return FunctionToolCallback.builder(“currentWeather”, weatherService::getWeather)

.description(“获取指定城市的当前天气”)

.inputType(WeatherRequest.class)

.build();

}

变化要点：

◆返回类型从 Function 改为 ToolCallback

◆必须用 FunctionToolCallback.builder() 链式构建

◆必须显式指定 inputType（1.x 靠反射推断，2.0 要求显式声明）

◆SpringBeanToolCallbackResolver 和 toolNames() 都被移除

好消息是 2.0 新增了 @Tool 注解，定义工具更简洁：

CODE

class WeatherTools {

@Tool(description = “获取指定城市的当前天气”)

public String getWeather(String city) {

return weatherService.fetch(city);

}

@Tool(description = “预订航班”)

public BookingConfirmation bookFlight(

String origin, String destination,

@ToolParam(description = “日期，格式 YYYY-MM-DD”) String date) {

return flightService.book(origin, destination, date);

}

Spring AI 自动生成 JSON Schema 作为工具定义传递给大模型，不需要你手写 Schema 了。

五、变更三：ChatModel 降级，ChatClient 成唯一入口

1.x 时代你可以直接 new OpenAiChatModel(...) 并手写调用循环。2.0 官方明确表态：

ChatClient 是面向业务的 API，ChatModel 是给框架作者用的底层构建块。

一个关键变化：.options() 现在接收的是 ChatOptions.Builder 而不是构建好的实例：

CODE

// 1.x 写法

ChatOptions opts = AnthropicChatOptions.builder()

.maxTokens(100).temperature(0.7).build();

String response = chatClient.prompt(“讲个笑话”)

.options(opts) // 传入实例

.call().content();

// 2.0 写法

String response = chatClient.prompt(“讲个笑话”)

.options(AnthropicChatOptions.builder() // 传入 Builder

.maxTokens(100).temperature(0.7))

.call().content();

另外，ChatModel.call(Prompt) 的隐式 Options 合并逻辑被去掉了——prompt 里的 options 非 null 直接用，null 就用模型默认。所有 internalCall / internalStream 方法改为 private，想绕过公开 API 驱动循环的路径被堵死。

六、变更四：模型提供商精简——POM 依赖大扫除

2.0 对模型接入做了一次合并大扫除：

| 提供商

1.x 变体

2.0 保留

OpenAI

HTTP / SDK / Azure 三套

仅 spring-ai-openai，底层换官方 SDK

| |

Anthropic

HTTP / SDK 两套

仅 SDK 变体

| |

Google

GenAI SDK + Vertex AI

移除 Vertex，仅保留 GenAI SDK

| |

MiniMax

专用支持

移除，改用 Anthropic 兼容端点

典型 POM 迁移：

CODE

org.springframework.ai

spring-ai-starter-model-azure-openai

org.springframework.ai

spring-ai-starter-model-openai

代码侧：AzureOpenAiChatModel → OpenAiChatModel（去掉 Azure 前缀）。

被低估的变化：Anthropic 的 maxTokens 默认值从 500 跳到 4096。如果你的应用依赖"默认短回复"做了截断或超时假设，行为会变。

七、JeecgBoot 已率先适配——生态迁移信号

昨天发布的 JeecgBoot v3.9.3 是一个强烈的生态信号：主流框架正在快速跟进 Spring Boot 4。

JeecgBoot v3.9.3 的核心升级：

| 组件

升级前

升级后

Spring Boot

3.x

4.x

| |

前端构建

Vite 5/6

Vite 8

| |

Shiro

2.x

3.0

| |

MyBatis-Plus

3.5.x

3.5.16

| |

Nacos

2.x

3.2.2

| |

XXL-JOB

2.x

3.4.2

同时发布了 AI Skills 自然语言编程、对话式 BI 产品 JimuChatBI 1.0。这说明 Spring Boot 4 + AI 的组合已经从"实验性"走向"生产可用"。

八、升级前检查清单

根据以上分析，整理一份升级前必做清单：

56确认 JDK 版本：本地和 CI 环境必须是 Java 17+，建议 21+

57确认 Spring Boot 版本：还在 Boot 3.x 的项目走 Spring AI 1.1.x 维护线，不要硬升 2.0

58批量替换 Jackson import：全局搜索 com.fasterxml.jackson → tools.jackson

59工具注册代码：全局搜索 @Bean + @Description + Function，改为 ToolCallback / @Tool

60Options 代码：全局搜索 .copy() → 重写为 .mutate().build()；setXxx( → builder 链式调用

61POM 依赖：Azure OpenAI 依赖改为统一 spring-ai-openai；删掉显式 Jackson 2 声明

62第三方库兼容性：MyBatis、ShardingSphere 等查 Boot 4 适配版本

63回归测试：尤其注意 Anthropic maxTokens 默认值变化、Options 集合字段不可变

选型建议：如果你的项目还在 Spring Boot 3.x 上，别急着升 2.0。先用 Spring AI 1.1.x 稳住，等 Boot 4 生态完全铺开再迁移。LangChain4j 1.19.0 对 Boot 版本没有强绑定，是一个灵活的过渡方案。

你正在用 Spring AI 还是 LangChain4j？升级过程中踩了哪些坑？评论区聊聊，一起避坑。

（本文基于 2026-08-20 CSDN/腾讯云公开技术资料整理，Spring AI 版本以 2.0.0 GA 为准，JeecgBoot 版本以 v3.9.3 为准）

文章目录

Spring AI 2.0 升级即编译报错？9 个破坏性变更逐个拆解，附完整迁移代码