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

张涛酱107456
36 阅读3分钟

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.*

迁移示例：

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

类名变更
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-opusclaude-opus-4-6
claude-3-sonnetclaude-sonnet-4-6
claude-3-haikuclaude-haiku-4-5

代码迁移：

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

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

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=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配置示例

<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 Boot3.4.x / 3.5.x4.0.x
Spring Framework6.x7.0
Java17+21+
Jackson2.x3.x
MCP SDK0.18.x1.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自动迁移

参考资料

avatar
文章
阅读
粉丝