Spring AI 1.1.6 来了！conversationId API大改，你的代码还能编译吗？

Spring AI 的更新速度越来越快，1.1.5 刚发布不到半月，1.1.6 就来了。这次有什么值得关注的变更？升级会踩什么坑？一篇讲清楚。

一、1.1.6 更新概览

Spring AI 1.1.6 属于 1.1.x 维护分支，定位是稳定性和安全性修复，不是大版本飞跃。具体包含：

类型	数量
新特性	2
Bug修复	5
文档改进	2
其他改进	5

相比 1.1.5 的"移除大模型"这种破坏性变更，1.1.6 的两个新特性更偏向工程规范化，但对现有代码有影响。

二、核心变更解读

变更1：移除聊天记忆默认会话 ID（⚠️ 破坏性变更）

这是本次最重要的变更，API变化很大。

之前的行为：聊天记忆 Advisor 可以不传会话 ID，系统会自动使用 "default" 作为默认值：

public interface ChatMemory {
    String DEFAULT_CONVERSATION_ID = "default";
    String CONVERSATION_ID = "chat_memory_conversation_id";
    // ...
}

所有没传 ID 的记忆都归到 default 分组里。看着方便，实际是个隐患——多用户场景下会串记忆。

1.1.6 的行为：必须显式传递会话 ID，不再有默认值。API变化包括：

1. 移除 DEFAULT_CONVERSATION_ID 常量（不再提供默认值）
2. 移除 conversationId(String) 构建器方法（整个方法删掉了）
3. 会话ID改为通过 advisors的param 传递

如果不传会话 ID：直接抛出 IllegalArgumentException: conversationId cannot be null。

升级代码示例：

import org.springframework.ai.chat.memory.ChatMemory;

// ❌ 1.1.5 及之前：构建时设置ID
var advisor = MessageChatMemoryAdvisor.builder(chatMemory)
    .conversationId("user-123")  // 这个方法在1.1.6中不存在了！
    .build();
chatClient.prompt().user("你好").advisors(advisor).call();

// ❌ 错误写法（.context()方法也不存在）
chatClient.prompt()
    .user("你好")
    .context(Map.of(ChatMemory.CONVERSATION_ID, "user-123"))  // 编译报错
    .call();

// ✅ 1.1.6 正确写法：通过advisors的param传ID
var advisor = MessageChatMemoryAdvisor.builder(chatMemory).build();
chatClient.prompt()
    .user("你好")
    .advisors(spec -> spec
        .advisors(advisor)  // 添加advisor
        .param(ChatMemory.CONVERSATION_ID, "user-123"))  // 传会话ID
    .call()
    .content();

如果ChatClient已配置默认advisor：

// 在Builder中配置默认advisor
var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
    .build();

// 调用时只需传param
chatClient.prompt()
    .user("你好")
    .advisors(spec -> spec.param(ChatMemory.CONVERSATION_ID, "user-123"))
    .call()
    .content();

核心变化：会话ID从"构建时设置"改为"调用时通过advisor param传递"。同一个Advisor实例可以被不同会话复用。

如果之前依赖了默认 ID，升级后一定要逐个检查所有 ChatMemory Advisor 的调用点，确保都通过 .advisors(spec -> spec.param(ChatMemory.CONVERSATION_ID, "xxx")) 传入了会话ID。

变更2：MCP 自动配置支持自定义 Bean 定义

之前 MCP 相关的 SSE 客户端连接配置 Bean 没有 @ConditionalOnMissingBean 注解，导致你无法用自己的实现覆盖自动配置。

1.1.6 补上了：

@Bean
@ConditionalOnMissingBean(McpSseClientConnectionDetails.class)
PropertiesMcpSseClientConnectionDetails mcpSseClientConnectionDetails(
        McpSseClientProperties sseProperties) {
    return new PropertiesMcpSseClientConnectionDetails(sseProperties);
}

这意味着什么？ 你现在可以自定义 MCP 连接逻辑，比如：

@Configuration
public class CustomMcpConfig {
    
    @Bean
    public McpSseClientConnectionDetails customMcpConnection() {
        // 自定义连接逻辑：负载均衡、认证、重试策略等
        return new McpSseClientConnectionDetails() {
            @Override
            public String getConnectionUrl() {
                return "https://your-mcp-server.com/sse";
            }
        };
    }
}

三、2.0.0-M6 预览：大版本在即

1.1.6 是维护分支，真正的大招在 2.0.0。目前 2.0.0 已到 M6 里程碑，预期本月 GA。

2.0.0 的核心变化方向：

• 架构重构：Agent Skills 原生支持，Agentic Patterns 系列正式纳入
• 版本要求提升：Spring Boot 4.x + JDK 21+
• 模块化：更细粒度的 starter 拆分

如果你在做新项目，建议关注 2.0.0 GA；老项目先升 1.1.6 保稳定。

四、升级实战：踩坑记录

坑1：conversationId方法不存在，编译报错

报错：

error: cannot find symbol
symbol:   method conversationId(String)
location: class Builder

场景：代码中使用了 builder().conversationId("xxx")，升级后编译失败。

解决：删除构建器中的 conversationId() 调用，改为在调用 ChatClient 时通过 advisors 的 param 传入。

// 改造前（1.1.5）
var advisor = MessageChatMemoryAdvisor.builder(chatMemory)
    .conversationId("user-123")
    .build();
chatClient.prompt().user("你好").advisors(advisor).call();

// 改造后（1.1.6）
var advisor = MessageChatMemoryAdvisor.builder(chatMemory).build();
chatClient.prompt()
    .user("你好")
    .advisors(spec -> spec
        .advisors(advisor)
        .param(ChatMemory.CONVERSATION_ID, "user-123"))
    .call();

坑2：DEFAULT_CONVERSATION_ID 常量不存在

报错：

error: cannot find symbol
symbol:   variable DEFAULT_CONVERSATION_ID
location: interface ChatMemory

解决：全局搜索 DEFAULT_CONVERSATION_ID，删除相关代码，改用显式传递会话ID。

坑3：不传会话ID运行时报错

报错：

java.lang.IllegalArgumentException: conversationId cannot be null

场景：创建 Advisor 时没设置 ID，调用时也没通过 advisors param 传入。

解决：确保每次调用 ChatClient 时都通过 .advisors(spec -> spec.param(ChatMemory.CONVERSATION_ID, "xxx")) 传入会话ID。

// ❌ 缺少会话ID
chatClient.prompt().user("你好").advisors(advisor).call();

// ✅ 正确传入
chatClient.prompt()
    .user("你好")
    .advisors(spec -> spec
        .advisors(advisor)
        .param(ChatMemory.CONVERSATION_ID, "user-123"))
    .call();

坑4：PromptChatMemoryAdvisor 已废弃

PromptChatMemoryAdvisor is now deprecated，建议使用 MessageChatMemoryAdvisor 替代。

坑5：Spring Boot 版本不匹配

现象：升级 Spring AI 到 1.1.6 后，某些 Spring Boot 自动配置不生效。

原因：Spring AI 1.1.6 依赖 Spring Boot 3.5.x，如果你的项目还在 3.3.x 或 3.4.x，可能出现 Bean 定义冲突。

五、依赖兼容性清单

组件	1.1.5	1.1.6	2.0.0-M6
Spring Boot	3.5.14	3.5.x	4.0.1
JDK 最低	17	17	21
Spring AI Alibaba	1.0.0-M6.1	1.0.0-M6.1+	待适配
MCP 支持	✅	✅（可自定义Bean）	✅
Agent Skills	❌	❌	✅

升级建议：

1. 1.1.4 → 1.1.6：直接升，处理 ChatMemory API 变化
2. 1.1.5 → 1.1.6：变化很小，主要处理 conversationId API 变化
3. 1.0.x → 1.1.6：跨度大，建议先升到 1.1.5，再升到 1.1.6

<!-- Maven 依赖（示例：OpenAI 模型，其他模型替换为对应 starter） -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>1.1.6</version>
</dependency>

⚠️ Spring AI 没有通用的 spring-ai-starter，starter 都是按模型分的，如 spring-ai-starter-model-openai、spring-ai-starter-model-deepseek 等。使用时请选择对应模型的 starter。

// Gradle 依赖（同样需要指定具体模型 starter）
implementation 'org.springframework.ai:spring-ai-starter-model-openai:1.1.6'

写在最后

Spring AI 1.1.6 看似小版本，但 ChatMemory API 的变化是设计理念转变：从"构建时静态配置"改为"调用时通过advisor param动态传递"。这让 Advisor 实例可以复用，更符合 Spring 的单例理念。

关键变化总结：

1. conversationId(String) 方法被完全移除
2. 会话ID改为通过 .advisors(spec -> spec.param(ChatMemory.CONVERSATION_ID, "xxx")) 传递
3. PromptChatMemoryAdvisor 已废弃，建议迁移到 MessageChatMemoryAdvisor

2.0.0 GA 在即，1.1.x 分支的维护期不会太长。建议在 2.0.0 正式发布前，先升到 1.1.6 把 API 变化处理好，后续迁移 2.0 会顺畅很多。

---

本文基于 Spring AI 1.1.6 官方 Release Notes、源码分析和实测整理。如有关注的具体变更点，欢迎评论区交流。