Spring AI 2.0 正式发布：Java AI 开发的分水岭来了

Spring AI 2.0.0 GA 正式发布了。我第一眼看到这个消息，脑子里第一个念头是：终于！

从 1.0 GA（2025 年 5 月）到 2.0 GA，不过一年时间，Spring AI 的 API 就经历了一次大手术。如果你正在用 Spring AI 1.x 做 AI 应用，看完这篇文章你可能会有点痛苦——因为有不少 breaking changes；但如果你现在才准备入场，恭喜你，直接上 2.0，踩的坑会少很多。

今天我来拆解 Spring AI 2.0 最核心的机制变化，不讲 PPT，只讲能让你看完就想动手的干货。

先把底座说清楚：Spring Boot 4 + Jakarta EE 11

Spring AI 2.0 是建在 Spring Boot 4.0 和 Spring Framework 7.0 之上的，底层 Java EE 规范升级到了 Jakarta EE 11。

这意味着什么？意味着如果你的项目还在用 Spring Boot 2.x 或者 3.x，想迁移到 Spring AI 2.0，你得先把 Spring Boot 升到 4.0——这不是小事。

好消息是，Spring Boot 4.0 目前和 Spring AI 2.0 节奏基本同步，算是一个"全家桶升级"。坏消息是，Jakarta EE 的包名从 javax. 改成了 jakarta.，这对于有历史包袱的老项目来说，是一个不小的迁移成本。

所以第一个建议：新项目直接上，老项目先评估迁移成本。

最大的架构变化：ChatClient 才是主角

这是 Spring AI 2.0 里我觉得最值得单独讲的一个设计决策。

在 Spring AI 1.x 里，大家（包括很多官方示例）其实混用 ChatClient 和 ChatModel，两者边界模糊，很多人直接 @Autowired ChatModel 来用，工具调用、重试、内存管理统统往里塞。

Spring AI 2.0 把这个边界明确了：

你写业务代码，就用 ChatClient。

一个最简单的工具调用例子，2.0 的写法是这样的：

String response = ChatClient.create(chatModel)
    .prompt("明天是星期几？")
    .tools(new DateTimeTools())
    .call()
    .content();

干净，简洁，工具调用、执行循环全部自动处理。

以前 1.x 里工具调用的循环逻辑是各个 ChatModel 实现自己内嵌的，OpenAI 有一套，Ollama 有一套，Anthropic 有一套，代码重复，行为不一致，bug 还各不相同。2.0 把这些统统干掉了——工具执行循环提升到 Advisor 链里，统一处理。

Advisor 链：工具调用的新归宿

这是 Spring AI 2.0 架构里我最喜欢的部分。

ChatClient 有一个 Advisor 链，每次请求都会经过这条链处理。2.0 新增的 ToolCallingAdvisor 被 ChatClient **自动注册**，不需要你手动配置，它接管了完整的工具调用循环：

请求 → Advisor链 → [ToolCallingAdvisor] → 模型
                              ↑                  ↓
                           工具执行 ←── 模型返回工具调用请求

这个设计有一个很优雅的地方：循环是可组合的。Advisor 链支持循环重入——工具调用 Advisor 可以重新进入下游链，同一套机制还可以用来做结构化输出的重试循环、评估循环等等。

你想自定义工具调用行为？继承 ToolCallingAdvisor，重写关键方法，然后注册到链里就行。不需要改模型层代码。

如果某次请求你不想走自动工具调用，也可以临时关掉：

ChatClient.create(chatModel)
    .prompt(...)
    .advisors(AdvisorParams.toolCallingAdvisorAutoRegister(false))
    .call()
    .content();

MCP 2.0：协议规范全面对齐

Model Context Protocol（MCP）是目前 AI 生态里增长最快的集成协议，Spring AI 2.0 对 MCP 的支持做了大幅重构。

两个关键变化：

1. 传输层移入 Spring AI

原来 WebMVC 和 WebFlux 的 MCP 传输实现是在 MCP Java SDK 里的，现在被整体挪进了 Spring AI 框架本身。好处是发布节奏对齐，版本不再撕裂。

2. Streamable HTTP 成为默认

原来默认的 SSE 传输被标记为 deprecated，新的默认传输是 Streamable HTTP。Streamable HTTP 有个无状态变体，可以实现远程部署的横向扩展——这对生产环境很重要，因为 SSE 是有状态的长连接，扩容麻烦。

当然，本地进程集成还是可以用 STDIO。

MCP Server 端的注解写法也更简洁了，一个统一的 McpSyncRequestContext 参数搞定日志、进度上报、采样、提示等所有功能：

@McpTool
public String searchDocs(String query, McpSyncRequestContext ctx) {
    ctx.reportProgress("正在搜索：" + query, 0.3);
    // ... 业务逻辑
    return result;
}

Agent Skills：像插件一样扩展 Agent 能力

这个功能是 Spring AI 生态里我觉得最有想象力的一个。

Agent Skills 的核心思想是：把 Agent 的能力定义为一个模块化的文件夹，里面包含指令、脚本、资源，Agent 可以按需发现和加载。

内置的 Skill 包括：

• file：文件读写能力
• shell：执行 Shell 命令
• web-fetch：抓取网页内容
• task：任务管理
• auto-memory：自动记忆（持久化上下文）

更重要的是，Skill 是跨模型可移植的。你写一次 Skill，用 OpenAI、Anthropic、Google Gemini 都能跑，不用为每个模型单独适配。

这让 Agent 的能力扩展变得像装 npm 包一样简单。

省 Token 神器：动态工具发现

这个功能非常实用，我要重点介绍一下。

你有没有遇到过这种情况：你的 Agent 要用到几十个甚至上百个工具，但每次请求你都把所有工具定义全部塞进 context，Token 哗哗地烧，成本蹭蹭地涨？

Spring AI 2.0 引入了 ToolSearchToolCallingAdvisor，实现了渐进式工具披露：

• 模型每次请求只收到一个「搜索工具」，Token 消耗极小
• 当模型需要某个能力时，用自然语言查询触发搜索
• 搜索结果动态注入上下文
• 模型再调用发现的工具

// 启用动态工具发现（只需一行配置）
spring.ai.chat.client.tool-search-advisor.enabled=true

搜索策略支持三种：

• regex：正则匹配，默认，零依赖
• lucene：Lucene 全文索引，starter 内置
• vector：向量语义搜索，需要 VectorStore Bean

根据官方数据，动态工具发现可以实现 34%~64% 的 Token 节省。对于工具多的场景，这个数字相当可观。

Null-safe API：终于不用猜哪里会 NPE 了

Spring AI 2.0 和 Spring Boot 4.0 一起，全面拥抱了 JSpecify 注解，实现了 API 级别的 Null 安全检查，并且在编译时强制校验。

这意味着什么？之前你调 Spring AI 的 API，经常需要自己猜哪个返回值可能是 null，写一堆防御性的 if != null。现在，方法签名上直接标注 @NonNull 和 @Nullable，IDE 和编译器帮你在写代码的时候就揪出问题，不用等到运行时踩坑。

对 Kotlin 开发者来说，这意味着可以少用 !! 操作符了，因为框架层面的 null 契约更清晰了。

升级前必看：Breaking Changes 速查

如果你已经在用 Spring AI 1.x，这部分最重要。

最容易踩的坑是工具调用方式变了。以前可以这样传：

// 1.x 写法（2.0 已不支持）
chatOptions.setToolNames(List.of("searchTool", "calcTool")); // ❌

2.0 必须显式传 ToolCallback 对象：

// 2.0 写法
ChatClient.create(chatModel)
    .prompt(...)
    .tools(new SearchTool(), new CalcTool()) // ✅
    .call()
    .content();

另一个常见坑：如果你的代码里有 chatModel.call(prompt) 并且依赖模型自己处理工具调用，2.0 里这个调用不会执行工具了，必须走 ChatClient。

总结

Spring AI 2.0 是 Java AI 生态一次实质性的成熟。核心思路很清晰：

1. ChatClient 统一入口把工具调用、Advisor、记忆管理统一在一条可组合的链上
2. MCP 深度集成跟上协议规范，Streamable HTTP 解决生产级扩展问题
3. Agent Skills 插件化让 Agent 能力的扩展变得标准化
4. Token 成本优化动态工具发现在工具多的场景省下 34%~64%
5. Null 安全把一类运行时问题提前到编译期解决

Breaking changes 不少，但方向是对的。如果你是新项目，现在入场，Spring AI 2.0 配 Spring Boot 4.0，这是目前 Java 生态里 AI 应用开发体验最好的组合。

你现在在用 Spring AI 吗？有没有从 1.x 迁移 2.0 的踩坑经历？评论区聊聊。

— 完 —