1、简述Spring AI 2.0 构建在Spring Boot 4.0和Spring Framework 7.0之上底层 Jakarta EE 规范升级到Jakarta EE 11。这意味着Spring Boot 3.x → 4.0 是硬性门槛迁移前必须先升级 Boot 版本Jackson 2 → Jackson 3JSON 处理全面升级包名从com.fasterxml.jackson变为tools.jackson对结构化输出、工具参数序列化影响较大JSpecify 空安全注解全面覆盖代码库中必填/可选参数边界更清晰Kotlin 用户尤其受益⚠️ 老项目建议先评估迁移成本新项目可以直接从 2.0 起步。2、架构重构ChatClient 成为主角这是 2.0 最核心的设计决策。在 1.x 中ChatClient和ChatModel边界模糊很多人直接Autowired ChatModel工具调用、重试、内存管理统统往里塞。2.0 明确了分工组件定位适用场景ChatClient面向业务开发者的高层 API内置 Advisor 链日常开发、工具调用、Agent 场景ChatModel底层模型抽象直接对接厂商 SDK框架扩展、底层集成简单说写业务代码就用 ChatClient。// 2.0 推荐写法ChatClientchatClientChatClient.builder(chatModel).build();StringresponsechatClient.prompt().user(今天北京天气怎么样).call().content();3、Tool Calling 彻底重构这是 breaking changes 最集中的领域也是 2.0 最大的亮点。3.1 核心变化工具执行循环移入 Advisor1.x 中工具调用的循环逻辑内嵌在各个ChatModel实现里——OpenAI 有一套Ollama 有一套行为不一致且 bug 各异。2.0 将这些全部移除统一由ToolCallingAdvisor在ChatClient层面接管。3.2 API 重命名速查表1.x2.0FunctionCallbackToolCallbackFunctionToolCallback.builder()同上接口名变builder 逻辑调整ChatClient.functions()ChatClient.tools()defaultFunctions()defaultTools()FunctionCallingOptionsToolCallingChatOptionsToolCallAdvisor(已废弃)ToolCallingAdvisor详细的迁移对照可参考 Spring AI 官方迁移指南。3.3 工具注册新写法1.x 方式已废弃BeanpublicFunctionCallbackweatherFunction(){returnFunctionCallback.builder().function(getWeather,newWeatherService()).description(查询天气).inputType(WeatherRequest.class).build();}2.0 推荐方式一使用 Tool 注解ComponentpublicclassWeatherTools{Tool(description查询指定城市的实时天气信息)publicWeatherResponsegetWeather(WeatherRequestrequest){// 实现天气查询逻辑returnnewWeatherResponse(request.city(),晴,25,东南风3级);}}// 使用时直接注册AutowiredprivateWeatherToolsweatherTools;StringresponsechatClient.prompt().user(北京今天天气怎么样).tools(weatherTools)// 直接传入 bean.call().content();2.0 推荐方式二MethodToolCallback 显式构建.tools(MethodToolCallback.builder().toolObject(weatherTools).toolMethod(ReflectionUtils.findMethod(WeatherTools.class,getWeather,WeatherRequest.class)).build())关键变化method()配置被替换为更明确的MethodToolCallback非静态方法需要同时提供 method 和 targetObject。4、结构化输出自纠正机制2.0 在结构化输出方面引入了自纠正重试循环解决了模型输出不符合 Schema 的痛点。// 方式一响应端校验 自动重试默认最多3次ActorsFilmsfilmschatClient.prompt().user(随机生成一个演员的电影作品列表).call().entity(ActorsFilms.class,spec-spec.validateSchema());// 方式二Provider 原生结构化输出更精准但兼容性有限.entity(ActorsFilms.class,spec-spec.useProviderStructuredOutput());validateSchema()会自动检测 JSON 是否符合 Schema不符合则把校验错误追加到 prompt 中重试模型能看到具体的错误信息并修正。该能力由StructuredOutputValidationAdvisor驱动调用时自动注册。支持 Provider 原生结构化输出的模型OpenAI、Anthropic、Google GenAI、Mistral AI、Ollama特定模型。5、MCP 2.0 集成2.0 对 MCP 支持做了大幅重构传输层移入 Spring AI 核心WebMVC 和 WebFlux 的 MCP 传输实现从 MCP Java SDK 迁移到 Spring AI 框架版本对齐。Streamable HTTP 成为默认传输取代已废弃的 SSE支持无状态变体便于横向扩展。注解包迁移org.springaicommunity.mcp→org.springframework.ai.mcp.annotation。将 Spring Bean 暴露为 MCP Server 工具只需将Tool替换为McpToolComponentpublicclassWeatherTools{McpTool(description查询天气)publicWeatherResponsegetWeather(WeatherRequestrequest){// ...}}本地Tool和远程 MCP 工具共享同一ToolCallback接口可以混用chatClient.prompt().tools(localWeatherTool,mcpToolFromRemoteServer).user(查询天气并保存记录).call();6、升级实操建议6.1 使用 OpenRewrite 自动化迁移Spring AI 官方提供了 OpenRewrite 迁移配方可以自动完成大部分代码更新mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run\-Drewrite.configLocationhttps://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml\-Drewrite.activeRecipesorg.springframework.ai.migration.MigrateToSpringAI200M36.2 需要手动处理的重点Boot 版本升级先升级到 Spring Boot 4.0Tool注解迁移将FunctionCallbackBean 改为Tool注解方法ChatClient替换ChatModel业务层改用ChatClientJackson 3 兼容注意包名变化检查自定义序列化逻辑Options 配置默认值现在由 Options 层管理不再会静默覆盖模型提供方的默认值6.3 示例项目参考社区已有基于 Spring AI 2.0 的示例工程可供参考包含基础教程提示词、结构化输出、Tool Calling、MCP、Advisor和进阶内容多轮对话、RAG、Agent。7、总结Spring AI 2.0 的核心升级思路可概括为将 AI 应用开发从“调用模型”提升到“构建 Agent”的工程化水平。ChatClient Advisor 链的架构使工具调用、结构化输出、记忆管理等能力变得可组合、可扩展同时通过底层框架升级Spring Boot 4、Jackson 3、JSpecify提升了生产环境的健壮性。如果你正在规划新项目直接上 2.0 是最佳选择如果是 1.x 存量项目建议按上述清单逐步迁移可以先用 OpenRewrite 处理机械性变更再手动处理架构层面的调整。