Spring AI 1.1.0-SNAPSHOT实战：5分钟搞定Streamable HTTP协议升级（含Maven配置避坑指南）

Spring AI 1.1.0-SNAPSHOT实战：5分钟搞定Streamable HTTP协议升级（含Maven配置避坑指南）

最近在折腾一个基于Spring AI的智能体项目，原本用SSE（Server-Sent Events）做消息推送，开发测试阶段感觉还行，但一上预发布环境，各种幺蛾子就来了。负载均衡器时不时把长连接掐断，客户端重连后会话状态全丢，用户正在进行的复杂对话直接归零，体验相当糟糕。正头疼怎么重构这块的时候，瞄到Spring AI社区放出了1.1.0-SNAPSHOT版本，里面赫然增加了对Streamable HTTP协议的支持。我花了一个下午研究文档和源码，把现有服务从SSE迁移了过去，整个过程比预想的要顺畅不少。这篇文章，我就把自己踩过的坑、配置的细节和实际测试的心得整理出来，如果你也在为SSE的稳定性发愁，或者想给AI应用找个更靠谱的通信层，那接下来的内容应该能帮你省下不少时间。

1. 为什么是Streamable HTTP？从SSE的痛点说起

我们团队最初选择SSE，看中的是它的简单。一个/events端点，text/event-stream的Content-Type，服务端就能源源不断地向客户端推送数据，对于需要实时反馈的AI对话场景，似乎是个天然的选择。但在实际的生产部署中，SSE架构的局限性逐渐暴露无遗。

首先最让人头疼的是连接管理的脆弱性。SSE基于HTTP长连接，这意味着服务端必须为每个在线客户端维持一个打开的TCP连接。在云原生环境下，这带来了几个棘手的问题：

• 基础设施不友好：很多云服务商的负载均衡器（如AWS ALB、Nginx的默认配置）都有连接超时限制，通常在60秒到几分钟不等。超过这个时间，连接会被主动切断。虽然SSE协议本身有心跳机制，但并非所有负载均衡器都“认识”SSE，它们可能将其视为普通的HTTP长连接并强行中断。
• 服务器资源压力：每个连接都占用一个线程或一个非阻塞IO资源。当并发用户数上升到几千时，服务器需要维护的活跃连接数也随之暴涨，对内存和文件描述符都是不小的考验。我们曾遇到过因为连接数过多导致服务器ulimit限制被触发，新用户完全无法建立连接的情况。
• 会话状态丢失：这是最影响用户体验的一点。SSE连接一旦断开（比如用户网络波动、移动设备切换Wi-Fi），整个会话上下文就没了。客户端重连后，服务端无法识别这是同一个用户之前的会话，用户不得不从头开始。想象一下，用户花了十分钟描述一个复杂的报表需求，刚说到一半，网络闪断，一切重来，这种体验足以让用户放弃你的产品。

其次，SSE的单向通信模型在复杂的AI交互中显得力不从心。在MCP（Model Context Protocol）或类似的AI工具调用协议中，客户端和服务端需要双向、多轮的交互。SSE只能由服务端向客户端推送，客户端发起请求仍需走传统的HTTP POST。这就导致了逻辑上的割裂：一部分消息走SSE流，另一部分走普通HTTP，增加了客户端状态同步的复杂度。

那么，Streamable HTTP带来了什么改变？它本质上是一种混合协议，巧妙地将HTTP请求/响应与按需触发的SSE流结合在了一起。它的核心设计哲学是“统一端点，按需流式化”。所有客户端与服务端的通信，无论是简单的工具调用查询，还是需要持续流式输出的AI生成，都通过同一个端点（例如/api/mcp）完成。服务端根据请求的具体内容和上下文，动态决定本次响应是立即返回一个完整的HTTP响应，还是将连接升级为SSE流进行分块输出。这种设计带来了几个立竿见影的好处：

• 连接按需创建，资源高效：只有真正需要流式输出的请求（如“生成一篇长文章”）才会建立SSE长连接。对于大量简单的请求（如“查询天气”、“执行计算”），则使用普通的HTTP短连接快速处理并关闭，极大减轻了服务端的连接维护压力。
• 内置会话管理：协议层面支持会话ID（Session ID）。客户端首次连接时可以获取一个ID，并在后续请求中携带。这样，即使SSE流因网络问题中断，客户端也能凭此ID重新连接，服务端可以恢复之前的会话状态，实现断线重连。
• 更好的基础设施兼容性：由于大部分交互是短连接的HTTP，只有少数长任务才启用长连接，这使得整个服务对负载均衡器、API网关、CDN等中间件更加友好，降低了被误杀连接的概率。

下面这个表格直观对比了SSE与Streamable HTTP在几个关键维度上的差异：

注意：Streamable HTTP并不是要完全取代SSE，而是对SSE使用模式的一种优化和封装。它让开发者无需关心底层是长连接还是短连接，只需关注业务逻辑，由框架根据交互的“流式”需求自动选择最合适的传输方式。

2. 环境准备：Maven快照仓库配置详解

Spring AI 1.1.0-SNAPSHOT目前还处于快照阶段，这意味着它没有发布到Maven中央仓库（Central Repository）。如果你直接使用默认的仓库配置，mvn clean install时会找不到相关的jar包。因此，第一步也是最容易踩坑的一步，就是正确配置Maven以拉取Spring的快照依赖。

很多团队内部可能配置了统一的Maven镜像仓库（比如Nexus或Artifactory）来加速构建。问题在于，这些镜像仓库通常不会同步快照版本，或者同步策略比较保守。如果你在s