★ FEATURED ARTICLE “流式对话接口”这几个字第一次让我熬夜的原因不是协议本身而是一个看起来无关的现象前端光标停在输入框上等了七八秒页面一动不动用户以为卡死了连续点了几次发送后端队列里堆了四五个重复请求。后来把“等一整段”改成“逐字吐”这个体验问题当场消失。标题里讲的“一个 Java 项目里用 SSE 构造流式对话接口”落到工程上就是这一件事把上游模型逐块吐出来的文本稳定、低延迟、可控地送到浏览器中间不能缓冲、不能积压、不能把线程池挂死。SSEServer-Sent Events是浏览器原生支持的服务端推送协议基于普通 HTTP 长连接服务端以text/event-stream格式持续写出数据帧客户端用EventSource或fetch的流式读取接收。它天生适合“一问一答、服务端单向持续输出”的对话场景比 WebSocket 轻比轮询省。这篇内容面向已经会写 Spring Boot 接口、但对流式输出、异步写出、网关配合还没跑通的开发者也适合需要评估方案选型的技术负责人。下面我按选型、协议细节、服务端实现、工程细节、联调、排错六个部分展开代码骨架和参数都能直接拿去改。1. 先搞清楚一次流式对话在链路上到底发生了什么很多人一上手就写SseEmitter写完之后发现“本地能出字、测试环境卡住不动”然后开始怀疑框架。真正的问题往往在链路认知上一次流式对话不是“一个接口返回数据”而是“一条跨越浏览器、网关、Java 应用、上游模型服务的长连接在这条连接上持续搬运文本增量”。这条链路上任何一环做了缓冲流式就退化成一次性返回。1.1 从“等一整段”到“逐字吐”的差别非流式的对话接口很好理解请求进来服务端调上游模型等完整结果返回序列化成 JSON一次性响应。它的优点是实现简单、错误处理清晰缺点是首字节时间等于整个生成时间用户感知的等待被放大到极限而且长文本生成很容易触发浏览器或网关的超时。流式对话的本质是把“生成”和“传输”重叠起来。上游每产生一个片段通常是一个 token 或者几个 token 组成的 chunk服务端就立刻往下游写一帧浏览器收到就渲染。整条连接的生命周期内HTTP 状态码早已在响应头阶段确定后面的内容全部是“同一响应体里的增量数据”。这意味着两件事一是错误一旦发生你没法再改状态码只能通过事件内容告知前端二是任何一个中间环节只要攒着不发送前端就只能干等。我在项目里做过一个对比测试同样一段 800 字左右的回答非流式接口的首字节时间是 6.8 秒流式接口的首字节时间是 0.9 秒虽然总耗时只差不到一秒但用户的主观感受完全是两回事。对话类产品的体验门槛就在首字节这个数字比总时长重要得多。1.2 SSE、WebSocket、长轮询的横向对比选型的时候别只看“能不能用”要看“代价是什么”。我整理了一张表是这几年在不同项目里反复验证过的结论维度SSEWebSocket长轮询传输层普通 HTTP/1.1 或 HTTP/2独立协议需 Upgrade 握手普通 HTTP方向服务端到客户端单向双向客户端发起服务端挂起浏览器支持原生 EventSource自动重连原生支持全支持鉴权方式沿用 HTTP 头或 Cookie握手阶段处理略麻烦同普通请求中间件友好度好本质是 HTTP部分网关需额外放行好适合场景单向增量输出、通知双向实时互动、协同编辑兼容性兜底对话场景的流量方向非常明确客户端发一次请求服务端持续往客户端推文本。这种“单向下行 一次上行”的形态用 WebSocket 是杀鸡用牛刀你还得额外维护连接状态、心跳、重连、鉴权透传。SSE 用的是标准 HTTP天然复用现有的鉴权、限流、日志体系出问题的时候抓包也简单——它就是一段格式特殊的文本响应。真正需要警惕的是 HTTP/1.1 下同域名的连接数限制。浏览器对同一域名的并发连接通常限制在 6 个左右SSE 连接会长期占用一个。如果一个页面同时开多个流式连接很容易把配额吃满导致其他请求排队。常规做法是把对话流放在独立子域或者直接上 HTTP/2多路复用下这个问题基本消失。1.3 标题里那个“接口”的职责边界我见过不少实现把职责搅在一起Controller 里直接拼上游请求、解析响应、写 SSE 帧一个方法两百行。这种写法能跑但没法维护。我的习惯是把一条流拆成四段职责接收与校验参数、组装上游请求、解析上游流、写出下游帧。前三段是纯逻辑可单测最后一段才涉及线程和 IO。还有一层容易忽略的边界会话上下文。对话接口通常要带历史消息历史消息的裁剪、系统提示词的拼接、参数透传这些都应该在“组装上游请求”这一段完成而不是散落在流式循环里。流式循环只做一件事——把上游的字节流翻译成下游的文本帧。职责越单一出问题的时候定位越快。注意不要在流式循环里做数据库写入、日志落盘这类阻塞操作。一个 chunk 一次数据库调用高并发下会直接把连接池打满。2. 把 SSE 规范拆成能直接写进代码的几条规则SSE 的协议文本很短但真正写代码时踩坑的地方集中在几个细节上响应头的字符集、帧的分隔符、注释行的心跳、事件 ID 的重连语义。这几条搞清楚了剩下的都是工程问题。2.1 响应头与报文格式三个不能错的点服务端返回 SSE 时响应头必须包含Content-Type: text/event-stream通常还要显式带charsetUTF-8否则某些容器或网关会按 ISO-8859-1 处理中文直接变乱码。另外两个头也建议加上Cache-Control: no-cache防止中间层缓存X-Accel-Buffering: no是给 Nginx 看的告诉它这条响应不要缓冲。报文格式的规则很简单但严格每一帧由若干行组成行与行之间用换行分隔帧与帧之间用一个空行分隔。字段有四种data:数据内容可以出现多次客户端会按换行拼接event:事件名客户端可以按名字分别监听id:事件 ID断线重连时浏览器会通过Last-Event-ID头带回来retry:重连间隔毫秒数最容易错的是分隔符。帧结束必须是两个换行也就是一个空行。我见过把\n写成\r\n然后在某些客户端上不生效的也见过只发一个\n导致所有数据被当成一帧的。稳妥的做法是行内用\n帧尾固定发\n\n。data: {delta:你好} data: {delta:我在}还有一个隐藏细节如果data的内容本身包含换行必须拆成多个data:行浏览器会把它们用\n拼起来。对话场景里模型输出经常带换行尤其是代码块这里处理不好前端渲染的 Markdown 就会错位。2.2 心跳、断线与事件 ID 的实战用法长连接最怕的是“看起来还连着实际上已经死了”。中间设备负载均衡、代理、防火墙通常有闲置超时30 秒到 5 分钟不等连接上长时间没有字节流动就会被掐断而客户端可能毫无感知一直等下去。解决办法是发心跳。SSE 支持以冒号开头的注释行客户端会忽略内容但连接上产生了流量: ping我一般设 15 秒一次心跳比大多数中间设备的闲置超时都短。心跳不要和数据帧抢同一个写入口否则并发写会把帧切碎直接导致客户端解析失败。id字段和自动重连是一对。浏览器在连接断开后会自动重连默认 3 秒可以用retry:调整并把最后收到的事件 ID 通过Last-Event-ID请求头带回来。对话场景里这条机制可以做得很有价值把已经发出的文本片段编号重连时服务端读取这个头从断点继续推。不过说实话模型生成是一次性的流服务端很难“续传”所以大多数项目里我选择不让浏览器自动重连而是在前端捕获onerror后决定是重试整个请求还是提示用户。提示如果业务上不需要断点续传建议在前端手动close()连接避免浏览器无脑重连造成服务端压力。2.3 中文、编码与多行数据的处理坑中文问题的根源几乎都在字符集上。响应头没有声明charsetUTF-8或者输出流用的不是 UTF-8 编码或者网关做了转码三种情况表现都是乱码但排查路径完全不同。我的排查顺序是先用 curl 直接打服务端看原始字节如果 curl 正常、浏览器乱码那是响应头或网关如果 curl 也乱码那是服务端输出流编码。多行数据是另一个高频坑。模型输出的内容里带\n是常态如果直接把原始字符串塞进data:后面客户端只会收到第一行后面的内容要么被当成新字段解析失败要么被丢弃。正确做法是先把内容里的换行替换成\n字面量或者拆成多个data:行。我通常选择前者在 JSON 序列化时自然就转义了——把增量包成 JSON 再发是最省心的做法{id:c12,delta:第一行\n第二行}这样前端拿到的是一个合法的 JSON 字符串JSON.parse之后换行原样保留不需要在前端再做任何拆分逻辑。3. Java 服务端落地三种实现的取舍与核心代码Java 侧做 SSE 有三条主流路线Spring MVC 的SseEmitter、WebFlux 的FluxServerSentEvent、以及原生 Servlet 3 的异步输出。选哪条不是看哪条新而是看你的项目底子和团队熟悉度。3.1 SseEmitter 还是 WebFlux先看项目底子如果项目是典型的 Spring Boot MVC 阻塞式数据库访问我强烈建议用SseEmitter。它建立在 Servlet 3 的异步请求之上不引入响应式栈团队不需要理解背压、事件循环这些概念出问题也好排查。如果项目本来就是 WebFlux或者需要同时支撑大量长连接几千以上那FluxServerSentEvent更合适。响应式栈的优势在于用少量线程扛住大量空闲连接但代价是调试成本高一个阻塞调用混进去就会拖垮整个事件循环。原生 Servlet 的方式我不太推荐除非你有特殊需求。SseEmitter本身就是对它的封装把超时、完成回调、异常回调都处理好了没必要重造。方案适用场景线程模型上手成本SseEmitter常规 MVC 项目一连接一异步任务低WebFlux Flux高并发长连接事件循环少量线程中高Servlet 异步特殊定制手动管理高3.2 SseEmitter 版本的完整骨架下面这个骨架是我在多个项目里反复改出来的去掉了业务细节保留了所有关键结构。核心思路是Controller 立刻返回SseEmitter把实际的流式处理丢给独立线程池处理过程中随时检查连接是否还有效。RestController RequestMapping(/api/chat) public class ChatStreamController { private final ChatStreamService chatStreamService; private final ThreadPoolExecutor streamExecutor; public ChatStreamController(ChatStreamService chatStreamService, ThreadPoolExecutor streamExecutor) { this.chatStreamService chatStreamService; this.streamExecutor streamExecutor; } PostMapping(value /stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter stream(RequestBody ChatRequest request) { // 0 表示不设超时实际项目里建议设一个上限比如 5 分钟 SseEmitter emitter new SseEmitter(5 * 60 * 1000L); AtomicBoolean closed new AtomicBoolean(false); emitter.onCompletion(() - closed.set(true)); emitter.onTimeout(() - { closed.set(true); emitter.complete(); }); emitter.onError(e - closed.set(true)); streamExecutor.execute(() - { try { chatStreamService.streamChat(request, delta - { if (closed.get()) { throw new StreamAbortedException(client gone); } try { emitter.send(SseEmitter.event() .name(delta) .data(ChatChunk.of(delta), MediaType.APPLICATION_JSON)); } catch (IOException e) { throw new StreamAbortedException(write failed, e); } }); emitter.send(SseEmitter.event().name(done).data({})); emitter.complete(); } catch (StreamAbortedException e) { emitter.completeWithError(e); } catch (Exception e) { try { emitter.send(SseEmitter.event().name(error) .data(ErrorPayload.of(生成中断))); } catch (IOException ignored) { // 连接已断忽略 } emitter.complete(); } }); return emitter; } }几个地方值得单独说。produces必须声明为text/event-stream否则 Spring 可能按 JSON 处理。onCompletion、onTimeout、onError三个回调一定要注册它们是判断“客户端还在不在”的唯一可靠信号。emitter.send是同步写出在多线程并发调用时会出现帧交错所以必须保证同一条连接只有一个线程在写——这也是我把整个流处理放在单个任务里的原因。MediaType.APPLICATION_JSON这个参数也建议带上。不带的话Spring 会按默认转换器写中文转义行为可能不符合预期带上之后序列化器明确前端解析也稳定。3.3 WebFlux 版本响应式栈的写法如果走 WebFlux代码会短很多但理解成本在别处。核心是把上游的流式响应包装成FluxString再映射成ServerSentEventGetMapping(value /stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public FluxServerSentEventString stream(RequestParam String q) { return chatClient.stream(q) .map(delta - ServerSentEvent.Stringbuilder() .event(delta) .data(delta) .build()) .concatWith(Flux.just(ServerSentEvent.Stringbuilder() .event(done).data({}).build())) .onErrorResume(e - Flux.just(ServerSentEvent.Stringbuilder() .event(error).data({\msg\:\生成中断\}).build())); }关键在于chatClient.stream必须返回真正的响应式流也就是基于WebClient的bodyToFlux或者支持响应式的 HTTP 客户端。如果底层用的是阻塞式客户端整个事件循环会被卡住几千连接的优势瞬间归零。这一点我在评审时必查只要看到响应式方法里出现block()直接打回。3.4 上游流式读取的解析器怎么写不管用哪条路线都要面对“解析上游流”这件事。上游模型服务的流式响应通常也是 SSE 格式或者按行分隔的 JSON你需要自己写解析器。这部分看似简单实际坑最多。核心原则是按行读取、按帧聚合。HTTP 响应体是一个字节流BufferedReader.readLine()能帮你处理行边界但不能假设“一次 read 就是一行”网络包会被任意切分。用readLine循环是最稳的try (BufferedReader reader new BufferedReader( new InputStreamReader(response.body().byteStream(), StandardCharsets.UTF_8))) { String line; while ((line reader.readLine()) ! null) { if (line.isEmpty()) { continue; } if (line.startsWith(data:)) { String payload line.substring(5).trim(); if ([DONE].equals(payload)) { break; } String delta extractDelta(payload); if (delta ! null !delta.isEmpty()) { consumer.accept(delta); } } } }这里有两个细节。第一data:后面可能有一个空格也可能没有trim()能兼容。第二结束标记各家不一样有的是[DONE]有的是一个特定的字段必须明确判断否则循环会一直等到连接超时。第三extractDelta里解析 JSON 时要注意字段可能不存在尤其是第一个 chunk 通常只带角色信息不带内容直接取内容字段会抛空指针。4. 工程细节线程池、超时、取消与资源回收流式接口和普通接口最大的区别是“生命周期长”。普通接口几百毫秒就结束流式接口可能持续一分钟。这一分钟里线程、连接、内存都在被占用任何一个维度失控都会放大成线上故障。4.1 线程池怎么配才不会被一次对话拖垮SseEmitter的实现里每个活跃连接都要占一个工作线程。这个线程从开始处理到流结束都不会释放因为它要持续写数据。这意味着线程池大小直接决定了并发对话数上限。我的做法是给流式接口单独的线程池和业务线程池隔离。核心线程数按“平均并发对话数 × 1.2”估最大线程数按峰值估队列不要设太大——队列积压意味着用户已经在等了排在队里没有任何意义不如快速失败让前端提示稍后重试。Bean(streamExecutor) public ThreadPoolExecutor streamExecutor() { return new ThreadPoolExecutor( 16, 64, 60L, TimeUnit.SECONDS, new LinkedBlockingQueue(128), new ThreadFactoryBuilder().setNameFormat(chat-stream-%d).build(), new ThreadPoolExecutor.AbortPolicy()); }拒绝策略用AbortPolicy在处理入口捕获RejectedExecutionException返回一个明确的“当前排队较多”事件。这种做法比无限排队诚实得多。另外线程名一定要带业务前缀出问题的时候jstack一眼就能看出流式线程占了多少。4.2 超时链路的三层对齐流式接口的超时不是一个值而是三个值必须对齐否则会出现“前端还在等、服务端已经断”的诡异现象层级配置项建议值SseEmitter构造参数 timeout5 分钟Spring MVC 异步spring.mvc.async.request-timeout略大于上者网关/代理proxy_read_timeout略大于上者上游 HTTP 客户端readTimeout按模型最长生成时间估顺序上越靠外的超时必须越大。我见过把网关超时设成 60 秒、应用设成 5 分钟的配置结果第 61 秒网关先断应用侧还在傻乎乎地写日志里一片Broken pipe。统一原则应用层最先感知并主动收尾网关层兜底。心跳机制在这里也有价值它能让网关的闲置超时计时器不断重置避免长回答被误杀。4.3 客户端断开的检测与资源回收用户关掉页面、切换标签、网络抖动都会导致连接断开。服务端如果不感知就会继续调上游、继续生成、继续占线程白白烧钱。SseEmitter的onCompletion、onError是主要信号但它们不是实时的有时要等到下一次写失败才触发。所以我在每次写之前都检查一个AtomicBoolean标志写失败也立刻置位两层保险。上游那边的 HTTP 连接也要主动关闭InputStream要放在 try-with-resources 里否则连接池里的连接会一直挂着。还有一个容易忽略的点用户主动点“停止生成”时前端调用close()服务端感知到写失败后要记得把上游请求也取消掉。如果用的是支持取消的 HTTP 客户端直接cancel()如果是阻塞式客户端就得靠关闭输入流让读取循环抛异常退出。这一步不做一个用户点停止后端还在跑完整段生成成本是实打实的。5. 联调现场前端、网关、压缩这三道坎代码写完只是开始真正让人抓狂的是联调阶段。我统计过自己遇到的流式问题八成集中在三个地方前端接收方式、网关缓冲、响应压缩。这三块任何一个没配好表现都是“本地好的环境上不出来”。5.1 前端怎么接EventSource 与 fetch 流的选择EventSource是最省事的浏览器帮你处理解析、重连代码几行就够const es new EventSource(/api/chat/stream?q encodeURIComponent(question)); es.addEventListener(delta, e { appendText(JSON.parse(e.data).delta); }); es.addEventListener(done, () es.close()); es.addEventListener(error, () es.close());但它有两个硬限制只支持 GET不能自定义请求头。这意味着你没法在 Header 里放 Authorization也没法传复杂的请求体。绕法有两种把参数和令牌放 query string或者用 Cookie 鉴权。前者要注意令牌泄露到日志里后者要处理跨域 Cookie 的问题。所以我更常用fetch加流式读取自由度更高const resp await fetch(/api/chat/stream, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer token }, body: JSON.stringify({ q: question }) }); const reader resp.body.getReader(); const decoder new TextDecoder(utf-8); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const frames buffer.split(\n\n); buffer frames.pop(); for (const frame of frames) handleFrame(frame); }这段代码里有两个关键点。decoder.decode的stream: true参数必须加否则一个中文字符被网络包切成两半时会解出乱码。buffer的作用是处理帧被切断的情况——网络不保证一次 read 就是一个完整帧必须自己攒到\n\n再解析。5.2 反向代理与压缩两个默认开启的“杀手”Nginx 默认会对响应做缓冲它会把上游发来的数据攒在自己的缓冲区里攒够一定大小或者连接结束才往下发。对流式接口来说这是灾难。必须显式关掉location /api/chat/stream { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_cache off; chunked_transfer_encoding on; proxy_read_timeout 300s; }proxy_buffering off是核心其他几项是配套。proxy_set_header Connection 是为了保持长连接避免每个请求都重新握手。压缩是第二个杀手。gzip 为了压缩率会攒一批数据再压天然和流式冲突。如果全局开了 gzipSSE 响应会被攒住前端看到的还是“一次性返回”。解决办法是在 Nginx 里对这条路径关掉压缩或者后端在响应头里明确声明不压缩。有些团队用Content-Encoding: identity兜底也能起作用。注意应用层的日志过滤器、链路追踪组件如果包装了 Response也可能引入缓冲。我遇到过某个日志组件把响应体全部缓存下来做审计导致流式彻底失效排查了大半天。5.3 鉴权怎么带上以及跨域的两个细节鉴权这块POST fetch 的方案最直接Authorization 头照常带。用 EventSource 的话就只能靠 Cookie 或者 query 参数。query 参数的问题在于会进访问日志、会进浏览器历史如果是长期有效的令牌风险不小。折中方案是用短时效的一次性票据前端先调一个普通接口换票再拿票去建流。跨域时要注意withCredentials。用 Cookie 鉴权必须带上这个标志同时服务端的 CORS 配置里allowCredentials要为 true而且allowedOrigins不能是通配符*必须是具体域名。这个限制很多人第一次遇到会懵其实规范就是这么定的。还有一个坑某些网关或 CDN 会对text/event-stream响应做特殊处理比如强制加上Content-Length或者把 chunked 编码转成固定长度。一旦响应带上Content-Length流式就不可能了。联调时用curl -N -v看响应头如果没有Transfer-Encoding: chunked而是Content-Length那问题就在中间层。6. 问题排查速查表与几个反直觉的坑流式接口的问题有个特点现象都差不多“不出来”或者“一下全出来”但根因可能在任何一层。这时候靠猜是没用的得按链路分段定位。6.1 常见现象与根因对照现象最可能的根因快速验证方式本地正常环境一次性返回网关或压缩缓冲curl -N看是否逐块输出首帧正常之后长时间无数据上游解析卡住或心跳缺失看服务端日志时间戳中文乱码响应头缺 charset检查 Content-Type前端报解析错误帧分隔符不对或多行 data 未处理抓包看原始报文第 60 秒整断开某层超时设置过小对齐三层超时配置并发上去后大量超时流式线程池耗尽jstack看线程数用户关闭页面后仍在计费未检测断开检查写失败的异常处理用这张表的时候有个技巧先用curl -N直接打应用端口绕过网关。如果这一步是流式的问题就在网关如果这一步就不是问题在应用。这一步能把排查范围砍掉一半。6.2 三个反直觉的坑第一个坑SseEmitter的send调用如果抛异常不代表连接一定断了。有时候是序列化失败有时候是临时写阻塞。我的处理是捕获后先检查onError标志再决定是重试一次还是直接收尾。无脑当成断开会丢数据无脑重试又可能死循环。第二个坑Spring 的ResponseBody和SseEmitter混用会出问题。有些同学在同一个 Controller 里既返回SseEmitter又配置了全局的消息转换器结果流式响应的内容被 JSON 转换器二次处理前端收到的是转义过的字符串。检查方法很简单看原始响应里是不是\满天飞。第三个坑HTTP/2 下某些网关对流的处理行为和 HTTP/1.1 不同。我遇到过一次HTTP/1.1 下正常的流切到 HTTP/2 后第一帧之后就没数据了最后定位到是网关对 HTTP/2 流的窗口更新有问题临时降级协议解决。这类问题没有通用答案只能靠分段验证锁定层级。6.3 上线前的自检清单我在每次上线流式接口前都会走一遍这个清单基本能挡掉九成问题响应头是否包含text/event-stream;charsetUTF-8、no-cache、X-Accel-Buffering: no帧尾是否固定为两个换行数据中的换行是否做了转义心跳是否开启间隔是否小于所有中间层的闲置超时三层超时是否从内到外递增流式线程池是否独立、是否有拒绝策略、线程名是否可辨识客户端断开后上游请求是否被取消网关是否关闭了缓冲和压缩异常情况下是否还能给前端发一条error事件最后分享一个我在联调时常用的小手段在服务端每个 chunk 写出时打一行带毫秒时间戳的日志同时在浏览器控制台打印收到时间。两边一对比就能立刻看出延迟发生在哪一段——是上游吐得慢还是服务端写出去被堵住。这个办法比任何抓包工具都快尤其是当你面对的是“用户说卡但你本地复现不了”这类问题时。我个人的习惯是把这个日志开关做成配置项只在联调期打开线上关掉既不影响性能又能在出问题时临时开启定位。
阅读完成 · 觉得有帮助？
