Spring AI 2.0.0-M3 新特性解析：MCP核心集成与重大升级

Spring AI 2.0.0-M3 于2026年3月17日发布，带来了23个新特性和45个bug修复。这是Spring AI 2.0的第三个里程碑版本，为与Spring Boot 4.0配合做好了准备。

一、版本概览

1.1 发布信息

项目	内容
版本号	2.0.0-M3
发布日期	2026-03-17
新特性	23个
Bug修复	45个
文档改进	16个
其他改进	67个

1.2 与Spring Boot 4.0的关系

Spring AI 2.0.0-M3 与 Spring Boot 4.0 配套：

使用 Jackson 3（Spring Boot 4默认）
支持 Java 21+
适配 Spring Framework 7.0

二、核心变化

2.1 MCP Annotations 迁移到核心

这是最重要的变化：MCP（Model Context Protocol）相关注解从社区包迁移到Spring AI核心。

包名变更：

变更前	变更后
`org.springaicommunity.mcp.annotation.*`	`org.springframework.ai.mcp.annotation.*`

迁移示例：

java 复制代码

// Before (1.x)
import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpPrompt;

// After (2.0.0-M3)
import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpPrompt;

Maven依赖变更：

xml 复制代码

<!-- Before: 需要单独引入 -->
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>mcp-annotations</artifactId>
</dependency>

<!-- After: 已包含在Spring AI核心中，无需单独引入 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>

2.2 Jackson 2 → Jackson 3 迁移

Spring AI 2.0 使用 Jackson 3（tools.jackson 包），适配 Spring Boot 4。

影响：

包名从 com.fasterxml.jackson 变为 tools.jackson
如果项目中有自定义Jackson配置，需要更新导入

迁移示例：

java 复制代码

// Before (Jackson 2)
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.annotation.JsonProperty;

// After (Jackson 3)
import tools.jackson.databind.ObjectMapper;
import tools.jackson.annotation.JsonProperty;

2.3 OpenAI SDK Builder API 改进

OpenAI集成现在使用新的Builder模式，API更流畅。

Before:

java 复制代码

OpenAiChatOptions options = new OpenAiChatOptions();
options.setModel("gpt-4");
options.setTemperature(0.7);
options.setMaxTokens(1000);

After (2.0.0-M3):

java 复制代码

OpenAiChatOptions options = OpenAiChatOptions.builder()
    .model("gpt-4")
    .temperature(0.7)
    .maxTokens(1000)
    .build();

2.4 多个ChatOptions统一Builder模式

以下模型选项类都统一使用Builder模式：

类名	变更
`AnthropicChatOptions`	构造函数 → Builder
`AzureOpenAiChatOptions`	构造函数 → Builder
`MistralAiChatOptions`	构造函数 → Builder
`BedrockChatOptions`	构造函数 → Builder
`DeepSeekChatOptions`	构造函数 → Builder

三、Breaking Changes（破坏性变更）

3.1 Claude 3.x 模型移除

Claude 3 Opus、Sonnet、Haiku 已被移除，必须迁移到 Claude 4.x。

模型映射：

旧模型	新模型
`claude-3-opus`	`claude-opus-4-6`
`claude-3-sonnet`	`claude-sonnet-4-6`
`claude-3-haiku`	`claude-haiku-4-5`

代码迁移：

java 复制代码

// Before
AnthropicChatOptions options = new AnthropicChatOptions();
options.setModel("claude-3-opus-20240229");

// After
AnthropicChatOptions options = AnthropicChatOptions.builder()
    .model("claude-opus-4-6")
    .build();

3.2 disableMemory() 重命名

方法名更加语义化：

java 复制代码

// Before (已废弃但保留兼容)
chatClient.disableMemory()

// After (推荐)
chatClient.disableInternalConversationHistory()

3.3 MCP Transport 模块迁移

MCP Spring Transport 模块从 MCP Java SDK 迁移到 Spring AI：

变更前	变更后
`io.modelcontextprotocol.sdk:mcp-spring-webflux`	`org.springframework.ai:mcp-spring-webflux`
`io.modelcontextprotocol.sdk:mcp-spring-webmvc`	`org.springframework.ai:mcp-spring-webmvc`

3.4 McpClientCustomizer 接口合并

两个接口合并为一个：

java 复制代码

// Before: 两个独立接口
McpAsyncClientCustomizer
McpSyncClientCustomizer

// After: 统一接口
McpClientCustomizer

四、新特性详解

4.1 MCP注解完整示例

使用新的MCP注解定义工具：

java 复制代码

import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpPrompt;
import org.springframework.stereotype.Component;

@Component
public class WeatherTools {
    
    @McpTool(description = "获取指定城市的天气信息")
    public String getWeather(String city) {
        // 实现天气查询逻辑
        return city + " 今天晴，温度25°C";
    }
    
    @McpPrompt(description = "生成天气报告模板")
    public String weatherReportPrompt(String city) {
        return "请为" + city + "生成详细的天气报告";
    }
}

4.2 Anthropic官方SDK集成

Anthropic集成从RestClient改为官方Java SDK：

xml 复制代码

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-anthropic</artifactId>
</dependency>

java 复制代码

@Service
public class ClaudeService {
    
    private final ChatClient chatClient;
    
    public ClaudeService(ChatClient.Builder builder) {
        this.chatClient = builder
            .defaultSystem("你是一个有帮助的助手")
            .build();
    }
    
    public String chat(String userMessage) {
        return chatClient.prompt()
            .user(userMessage)
            .call()
            .content();
    }
}

4.3 Builder模式统一

所有ChatOptions都支持Builder模式：

java 复制代码

// Anthropic
AnthropicChatOptions anthropicOptions = AnthropicChatOptions.builder()
    .model("claude-sonnet-4-6")
    .temperature(0.7)
    .maxTokens(2000)
    .build();

// Azure OpenAI
AzureOpenAiChatOptions azureOptions = AzureOpenAiChatOptions.builder()
    .model("gpt-4")
    .temperature(0.5)
    .build();

// Mistral
MistralAiChatOptions mistralOptions = MistralAiChatOptions.builder()
    .model("mistral-large")
    .temperature(0.3)
    .build();

五、升级指南

5.1 使用OpenRewrite自动迁移

Spring AI提供了OpenRewrite配方，可以自动完成大部分迁移工作：

bash 复制代码

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
  -Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
  -Drewrite.activeRecipes=org.springframework.ai.migration.M3MigrateMcpAnnotations \
  -Dmaven.compiler.failOnError=false

5.2 手动迁移检查清单

更新Spring AI版本到2.0.0-M3
更新Spring Boot版本到4.0.x
更新MCP注解包名导入
移除org.springaicommunity:mcp-annotations依赖
更新MCP Transport依赖groupId
更新Jackson相关导入（如使用）
迁移Claude 3.x模型到4.x
更新ChatOptions使用Builder模式
替换disableMemory()为disableInternalConversationHistory()

5.3 Maven配置示例

xml 复制代码

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.4</version>
</parent>

<properties>
    <spring-ai.version>2.0.0-M3</spring-ai.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

六、兼容性矩阵

组件	1.x版本	2.0.0-M3
Spring Boot	3.4.x / 3.5.x	4.0.x
Spring Framework	6.x	7.0
Java	17+	21+
Jackson	2.x	3.x
MCP SDK	0.18.x	1.0.x

七、总结

Spring AI 2.0.0-M3 是一个重要的里程碑版本：

变化类型	影响
MCP核心集成	降级使用门槛，官方支持
Jackson 3迁移	与Spring Boot 4保持一致
Builder模式统一	API更一致、更流畅
Claude 4.x支持	使用最新模型能力

升级建议：

新项目：直接使用2.0.0-M3
现有项目：等待2.0.0 GA版本，或使用OpenRewrite自动迁移

Spring AI 2.0.0-M3 新特性解析：MCP核心集成与重大升级

一、版本概览

1.1 发布信息

1.2 与Spring Boot 4.0的关系

二、核心变化

2.1 MCP Annotations 迁移到核心

2.2 Jackson 2 → Jackson 3 迁移

2.3 OpenAI SDK Builder API 改进

2.4 多个ChatOptions统一Builder模式

三、Breaking Changes（破坏性变更）

3.1 Claude 3.x 模型移除

3.2 disableMemory() 重命名

3.3 MCP Transport 模块迁移

3.4 McpClientCustomizer 接口合并

四、新特性详解

4.1 MCP注解完整示例

4.2 Anthropic官方SDK集成

4.3 Builder模式统一

五、升级指南

5.1 使用OpenRewrite自动迁移

5.2 手动迁移检查清单

5.3 Maven配置示例

六、兼容性矩阵

七、总结

参考资料