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

一、版本概览

1.1 发布信息

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核心。

包名变更：

迁移示例：

// 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依赖变更：

<!-- 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配置，需要更新导入

迁移示例：

// 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:

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

After (2.0.0-M3):

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

2.4 多个ChatOptions统一Builder模式

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

三、Breaking Changes（破坏性变更）

3.1 Claude 3.x 模型移除

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

模型映射：

代码迁移：

// 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() 重命名

方法名更加语义化：

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

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

3.3 MCP Transport 模块迁移

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

3.4 McpClientCustomizer 接口合并

两个接口合并为一个：

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

// After: 统一接口
McpClientCustomizer

四、新特性详解

4.1 MCP注解完整示例

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

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：

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

@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模式：

// 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配方，可以自动完成大部分迁移工作：

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run 
  -Drewrite.configLocation= 
  -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配置示例

<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></url>
    </repository>
</repositories>

六、兼容性矩阵

七、总结

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

升级建议：

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

参考资料

• Spring AI 2.0.0-M3 Release Notes
• Spring AI 2.0 升级指南
• Spring Boot 4.0 文档