最近在做一个订单状态实时推送的功能。需求本身不复杂用户下单之后后台经过审核、出库、发货、签收这些环节前端页面要实时显示最新状态不能让用户手动刷新才知道进度。我的第一反应是上WebSocket这个词这几年太火了一聊到实时就想到它。可真把方案摊开对比之后我最后选了SSEServer-Sent EventsSpring Boot里用SseEmitter实现代码量比WebSocket少一个数量级效果却完全够用。这篇文章把选型决策、SSE协议机制、Spring Boot落地代码、以及生产环境里那些连接莫名断开的坑全部写透。适合正在做通知推送、任务进度反馈、实时看板刷新这类服务端单方向推给浏览器场景的后端同学前端同学也能从中搞清楚EventSource该怎么和后端配合。1. 实时推送选型轮询、WebSocket、SSE我为什么选了最轻的那个1.1 三种方案的定位差异在做实时推送之前很多人的第一反应是直接用轮询不就行了。轮询确实是成本最低的方案前端每隔几秒发一个Ajax请求后端返回最新数据。但它有两个硬伤——延迟受轮询间隔限制间隔设小了流量浪费严重间隔设大了体验又差。长轮询Long Polling改良了一下让服务端把请求挂住一段时间有数据再返回但本质上还是在模拟推送连接频繁建立销毁代码复杂度还不低。WebSocket走的是另一条路它通过HTTP Upgrade把协议切换成TCP长连接实现真正的全双工通信。服务端能推客户端也能推适合聊天、协同编辑这类两端交互频繁的场景。但选择WebSocket意味着你要处理协议升级流程、二进制帧、心跳保活、消息重连这些底层细节。虽然后端框架帮我们隐藏了不少但整套体系依然是重量级的。SSE是个折中方案它没有新协议就是普通的HTTP GET请求只是服务端拿到请求后不急着返回而是把响应头设置成text/event-stream然后持续把数据写进响应体里。浏览器端的EventSource对象会自动解析这个流有数据就触发回调连接断了还会自动重试。下面这张对比表是我当时做选型时列的维度轮询WebSocketSSE通信方向客户端拉取双向服务端单向推送协议基础HTTP独立协议UpgradeHTTP自动重连无需自己实现EventSource内置服务端实现成本低高低浏览器兼容性全兼容主流浏览器支持IE不兼容其余主流可用典型场景低频数据查询聊天、双向协作通知、进度、实时看板1.2 适合用SSE的场景清单我把SSE适用的场景大致归成几类第一类是服务端状态变更通知比如订单状态流转、支付结果回调、消息中心红点第二类是任务进度推送比如文件处理、数据导入导出、视频转码前端要展示百分比第三类是实时数据广播比如股票行情、竞拍价格、监控大屏、运维日志流。这些场景的共同点是数据流向都是服务端到客户端单向的客户端几乎不发消息偶尔发也只是订阅或取消订阅。当然SSE也有明显的短板。它只能服务端吐数据无法替代WebSocket做双向通信浏览器对HTTP/1.1下同一域名连接数有限制一般是6个如果页面开了太多长连接会出问题而且中间任何一层代理如果缓冲了响应推送就会卡住。这些短板在选型的时候心里得有数。我当时的需求是订单状态单向推送SSE完美匹配于是当天就开工了。2. SSE协议详解一次完整的text/event-stream消息流是怎么诞生的2.1 本质就是一个不会被关闭的GET响应很多人第一次接触SSE会以为这是一种全新的网络协议其实不是。SSE的全称是Server-Sent Events它建立在普通HTTP之上只是借用了Content-Type: text/event-stream这个MIME类型让浏览器知道这个响应是一个事件流。整个通信过程是这样的客户端用EventSource对象发一个GET请求服务端收到请求后在响应头上标明Content-Type: text/event-stream然后连接保持打开。之后服务端想推数据就往这个响应体里写一段符合SSE格式的文本浏览器解析到了就触发事件。连接可以在Push之后继续保持也可以由服务端主动关闭。协议层面SSE消息是纯文本所以调试极其方便。后端一条命令就能看原始流curl -N http://localhost:8080/sse/news-N参数是关键它告诉curl禁止缓冲服务端每写一段数据终端就立即显示一段。如果你在浏览器里直接访问SSE接口的URL同样会看到源源不断的文本往外冒。2.2 消息格式data、event、id、retry各干什么SSE的在线数据格式很简单人为规定了一套键值对行。一条完整的消息由若干个字段行组成以空行结束。最核心的字段是data代表真正传给前端的数据data: 这是一条普通消息如果我需要传递结构化数据一般让data携带JSON字符串这样前端拿到后直接JSON.parse。还有几个字段虽然不像data那样必须但业务上非常有用event: orderStatus data: {orderId:20241101,status:SHIPPED,timestamp:1710000000000} id: 88 retry: 5000event字段声明事件类型相当于给这条消息打了个标签。前端默认监听onmessage处理所有消息但如果你用addEventListener(orderStatus, handler)就能针对性地只处理特定类型的事件。id字段是消息编号它的真正威力在断线重连环节浏览器重连时会把最后收到的id放到Last-Event-ID请求头里带给服务端服务端借此知道客户端缺了哪些数据就可以从断点继续推送。retry字段则告诉浏览器下一次重连前等待多少毫秒不传的话浏览器默认用3秒左右的机制。另外有一种特殊行以冒号开头的行是注释不算事件数据但能证明连接还活着。这类行我们一般用来做心跳包后面专门展开讲。2.3 浏览器端EventSource最小可运行代码服务端的坑先不聊先看客户端长什么样。EventSource是浏览器内置对象不需要引入任何依赖const es new EventSource(/sse/order/1001); es.onopen () { console.log(连接建立); }; es.onmessage (event) { const data JSON.parse(event.data); console.log(收到订单状态, data.status); }; es.addEventListener(orderStatus, (event) { // 只处理服务端 event: orderStatus 的消息 const data JSON.parse(event.data); updateOrderUI(data); }); es.onerror () { // 连接断开浏览器会自动重连 console.log(连接异常等待重连); };这里有个容易忽略的点EventSource默认只支持GET请求没法自定义请求头。如果你需要在订阅时带认证信息要么用Cookie要么把token放到URL的query参数里比如new EventSource(/sse/order/1001?tokenxxx)。这点很像img标签的防盗链逻辑所有信息都在地址上。3. Spring Boot里用SseEmitter跑通第一个推送接口3.1 依赖与前置其实你什么都不用加Spring Boot项目接入SSE最大的优点就是零额外依赖。SseEmitter是spring-webmvc自带的类凡是引入了spring-boot-starter-web的项目都能直接用不需要引入任何Reactor、Netty或额外消息中间件。我当时用的是Spring Boot 2.7Spring Boot 3.x也完全一样这个类在org.springframework.web.servlet.mvc.method.annotation包下。SseEmitter本质上是Spring MVC对Servlet 3.1异步请求的一种封装专门用来生成text/event-stream响应。你只要在Controller方法里返回一个SseEmitter实例Spring容器会自动完成异步请求的注册屏蔽掉底层Servlet API的细节。对业务代码来说你的任务只有一个在合适的时机调用emitter.send(...)把数据推出去。3.2 最简实现一个持续推送的新闻接口先写一个最直观的例子接口每两秒推送一条新闻推完5条后正常关闭连接。这样你能立刻看到SSE的完整生命周期RestController public class NewsSseController { GetMapping(path /sse/news, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter streamNews() { // 0L 表示连接永不超时 SseEmitter emitter new SseEmitter(0L); new Thread(() - { try { for (int i 1; i 5; i) { SseEmitter.SseEventBuilder event SseEmitter.event() .id(String.valueOf(i)) .name(news) .data(新闻 # i 已发布); emitter.send(event); Thread.sleep(2000); } emitter.complete(); } catch (Exception ex) { emitter.completeWithError(ex); } }).start(); return emitter; } }拆解一下关键点。produces MediaType.TEXT_EVENT_STREAM_VALUE让Spring在响应头里写入正确的MIME类型这是SSE能工作的基础。new SseEmitter(0L)传0表示不设超时原因后面细说。业务线程用SseEmitter.SseEventBuilder构造完整事件可以同时带上id、name和data。推送完最后一条后调用complete()等于告诉Spring和浏览器流结束了如果过程中出了异常用completeWithError(ex)把异常信息回传给客户端。3.3 用SseEventBuilder组装丰富事件上面例子里的.id()、.name()、.data()这三个方法是用的最多的。我再补几个实际会碰到的用法// 1. 推送JSON对象Spring会用Jackson自动序列化 OrderStatus status new OrderStatus(1001, SHIPPED, Instant.now()); emitter.send(SseEmitter.event() .name(orderStatus) .data(status, MediaType.APPLICATION_JSON)); // 2. 设置重连时间告诉浏览器断线后等5秒再连 emitter.send(SseEmitter.event() .reconnectTime(5000) .data(暂时的失败稍后重试)); // 3. 推送纯注释行用于心跳 emitter.send(SseEmitter.event().comment(heartbeat));这里提一下.comment()它生成的就是前面说的以冒号开头的注释行。注释行不会被前端当事件触发但会让数据在连接上流动那些闲置超时的判定就会被重置。3.4 快捷自测curl和EventSource的配合写完接口怎么快速验证我的习惯是三步走。第一步用curl看原始协议流curl -N http://localhost:8080/sse/news如果接口通终端上会每隔两秒出现一段id:、event:、data:组成的文本。第二步写一个50行以内的HTML文件用EventSource订阅并把消息显示到页面上这一步验证的是前端能不能正确解析。第三步才考虑用户维度、鉴权、心跳这些生产问题。先把这三步跑通说明SSE链路基本没问题了。4. 连接生命周期里的三个鬼门关超时、心跳、断线重连4.1 SseEmitter的超时参数没设置好连接悄悄被回收SSE连接是长连接但底层的Servlet容器都有异步请求超时机制。SseEmitter无参构造会采用一个默认超时值在Spring Boot默认内嵌容器下通常就是30秒左右。这意味着如果你建了连接之后30秒内什么都没推容器会认为这个请求超时了直接把异步上下文回收掉连接被断开。前端EventSource会以为网络异常进入重连流程。所以这个接口能推一次数据和这个接口能长期保持推送完全是两件事。我的做法是如果这个连接预期长期存在比如用户挂在订单页面一小时用new SseEmitter(0L)明确告诉容器永不超时如果连接只是短任务用的比如一次文件导入进度那就设一个合理的超时时间比如new SseEmitter(120_000L)超时后自动断开再由客户端重连。超时时长可以在SseEmitter上注册回调emitter.onTimeout(() - { System.out.println(连接超时等待清理); emitter.complete(); });无论设了多长的超时我都建议定期发心跳因为网络链路不止容器一层代理、网关、负载均衡设备都可能有自己的空闲回收策略。4.2 心跳包解决stream disconnected before completion: idle timeout waiting for sse在把这个SSE接口部署到网关后面时我遇到了一个非常典型的报错stream disconnected before completion: idle timeout waiting for sse这段话的意思是连接尚未完整结束但因为等待SSE数据时闲置超时连接被强行断开了。常见于后端服务通过Spring Cloud Gateway这类反应式网关代理SSE的场景底层Netty对长时间没有数据交互的连接会做闲置回收。Tomcat、Nginx也同样存在类似机制。解决方案是双管齐下。第一从源头避免闲置服务端定期发送心跳注释行。第二在网关或代理层把相关的空闲超时调大。服务端心跳的代码很简单我一般直接丢一个定时任务进去GetMapping(path /sse/task/{taskId}, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter taskProgress(PathVariable String taskId) { SseEmitter emitter new SseEmitter(0L); ScheduledExecutorService scheduler Executors.newSingleThreadScheduledExecutor(); TaskProgress progress TaskManager.get(taskId); // 每15秒发送一个注释行当心跳 scheduler.scheduleAtFixedRate(() - { try { emitter.send(SseEmitter.event().comment(heartbeat)); } catch (IOException e) { // 客户端已断开 scheduler.shutdown(); } }, 0, 15, TimeUnit.SECONDS); // 真正推送业务数据的线程 pushProgressLoop(emitter, progress, scheduler); return emitter; }心跳间隔我建议设在10秒到30秒之间。间隔太短会平白增加网络流量太长则可能被某些代理层的空闲阈值掐掉。如果确定整条链路只有一个Tomcat没有其他代理心跳可以放宽到30秒如果链路里还有Nginx、云负载均衡、各种网关建议保守一点用10秒。4.3 断线重连与Last-Event-ID续传EventSource最让我省心的地方是自动重连。连接断了浏览器会根据retry字段或者自己的默认策略自动重新发起请求不需要前端写任何重试逻辑。但重连了不代表数据不丢。比如服务端推送了1到10条消息客户端收到第5条后Wi-Fi闪断重连成功后的第一次请求服务端如果又从第1条开始推那客户端就要重复处理一堆旧数据。解决思路是把id字段用起来。浏览器重连时会在请求头里带上Last-Event-ID值是它最后收到的那条消息的id。服务端读取这个请求头就能确定客户端消费到哪了。实现方式是这样的GetMapping(path /sse/orders/{orderId}, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter orderStream(PathVariable String orderId, RequestHeader(value Last-Event-ID, required false) String lastEventId) { SseEmitter emitter new SseEmitter(0L); // 从lastEventId之后开始补发 ListOrderStatusEvent pendingEvents eventStore.findAfter(orderId, lastEventId); pendingEvents.forEach(event - { try { emitter.send(SseEmitter.event() .id(event.seq()) .name(orderStatus) .data(event, MediaType.APPLICATION_JSON)); } catch (IOException e) { // 客户端断开停止发送 } }); return emitter; }实现续传的前提是服务端自己得存一份每个用户/每条连接发过哪些消息的凭证。简单的做法是内存里存最近N条稳妥一点丢Redis。对大多数业务来说SSE本来就是实时通知客户端重连后能看到当前最新状态基本就满足需求了不一定非要逐条补齐历史。要不要做断点续传取决于业务对消息完整性的要求。比如订单状态推送重连后把当前状态推一次就够了但如果是审计日志流那缺一条都不行。5. 多用户并发推送从注册表设计到订单状态推送完整案例5.1 用ConcurrentHashMap自己维护连接池上面这些示例都是单连接独立演示实际系统里肯定是很多用户同时挂着SSE连接后台某个时刻发生了某个事件要把对应事件推给对应用户。所以必须有一个地方把所有活的连接管起来。我的做法很朴素一个ConcurrentHashMapkey是用户IDvalue是用户的SseEmitter。封装成一个注册表组件Component public class SseClientRegistry { private final MapString, SseEmitter clients new ConcurrentHashMap(); public SseEmitter register(String userId) { SseEmitter emitter new SseEmitter(0L); clients.put(userId, emitter); emitter.onCompletion(() - clients.remove(userId, emitter)); emitter.onTimeout(() - clients.remove(userId, emitter)); emitter.onError(e - clients.remove(userId, emitter)); return emitter; } public OptionalSseEmitter get(String userId) { return Optional.ofNullable(clients.get(userId)); } public void remove(String userId) { clients.remove(userId); } public int onlineCount() { return clients.size(); } }注册表这个想法很土但真的很可靠。onCompletion、onTimeout、onError这三个回调必须都写上否则连接断开后Map里会残留一堆垃圾Emitter时间一长就是内存泄漏。remove(userId, emitter)这种重载比直接把remove(userId)更安全它只会删除当前这个Emitter对象对应的条目防止并发下误删了用户重新建立的新连接。5.2 完整实战用户下单后订单状态实时刷新用一个具体场景把注册表串起来。用户在商城下单订单状态从待支付变成已支付再到已发货前端页面要实时刷新。核心流程分三步用户订阅、业务事件推送、前端接收。第一步用户打开订单详情页时订阅SSERestController RequestMapping(/api/sse) public class SseController { private final SseClientRegistry registry; public SseController(SseClientRegistry registry) { this.registry registry; } GetMapping(value /subscribe, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter subscribe(RequestParam String userId) { return registry.register(userId); } }第二步订单服务里订单状态一变就调用推送服务Service public class OrderPushService { private final SseClientRegistry registry; public OrderPushService(SseClientRegistry registry) { this.registry registry; } public void pushOrderStatus(Order order) { String userId order.getUserId(); registry.get(userId).ifPresentOrElse(emitter - { try { MapString, Object payload new HashMap(); payload.put(orderId, order.getId()); payload.put(status, order.getStatus().name()); payload.put(updatedAt, System.currentTimeMillis()); emitter.send(SseEmitter.event() .name(orderStatus) .data(payload, MediaType.APPLICATION_JSON)); } catch (IOException e) { registry.remove(userId); } }, () - { // 用户当前不在线可考虑存离线消息等下次订阅时再补发 log.info(用户{}离线暂不推送, userId); }); } }第三步前端订阅这个接口并监听orderStatus事件。之前那段EventSource代码直接能用。5.3 连接清理的细节别等OOM才想起来连接池这东西注册容易清理难。我在生产环境里踩过的具体坑有两个。第一个坑是线程泄漏。每个SSE连接如果都有一个自己的new Thread()或者ScheduledExecutorService当用户量上来时线程数会暴涨。后来我统一用一个共享的ScheduledExecutorService做心跳和定时推送连接本身仅仅是一个异步响应对象挂在线程池上这样线程资源是可控的。第二个坑是send方法抛IOException的时机。客户端断网时服务端不是立刻感知到的要等下一次send写数据时才会抛异常。如果心跳停了、业务数据又稀一个僵尸连接可能要在Map里驻留很久。所以心跳任务里catch到IOException后要顺手清理掉对应的连接别只shutdown自己的调度器。6. 生产环境避坑代理、集群与连接数这三个话题绕不开6.1 Nginx和网关的SSE专项配置开发环境里直接连Spring Boot端口SSE很欢快。一上生产前面挡了Nginx问题就来了Nginx默认开启了响应缓冲它会攒满一段数据才往后端转发。SSE是边产生边推送的Nginx一缓冲浏览器端就像断流一样半天收不到数据然后触发重连重连又缓冲形成恶性循环。Nginx反向代理SSE时至少需要这三条配置location /api/sse/ { proxy_pass http://backend-server; proxy_http_version 1.1; proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s; proxy_set_header Host $host; }proxy_http_version 1.1是保证长连接能撑住proxy_buffering off关掉缓冲让数据即收即转proxy_read_timeout 3600s把代理层的读超时拉到足够长。如果用了Spring Cloud Gateway这类响应式网关同样关注底层Netty的idleTimeout配置把它调大再配合服务端心跳包基本上stream disconnected before completion这类报错就能压下去。6.2 单机连接数的极限与HTTP/2SSE本质是长连接每一个用户都会占用一个连接。单机受两个限制一个是操作系统文件描述符上限另一个是Tomcat最大连接数配置。Tomcat默认的max-connections默认值是8192如果每个用户一条SSE连接再算上其他普通HTTP请求单机撑几千活跃用户已经是比较紧张的状态了。浏览器端的连接限制也要算进去。HTTP/1.1协议下每个域名最多同时开6个TCP连接如果一个页面既有SSE订阅、又有轮询请求、还要加载静态资源6个连接很容易被占满。这也是为什么老浏览器下SSE会被吐槽开多了不工作。解决方案之一是上HTTP/2。HTTP/2在同一TCP连接里多路复用SSE连接不再独占一个物理连接浏览器端的6连接限制对SSE的约束就小很多。Spring Boot开启HTTP/2比较简单内嵌Tomcat从9.0.x开始就支持配合server.http2.enabledtrue配置即可前提是使用了HTTPS。6.3 集群环境下推送指令如何到达正确的实例前面的ConcurrentHashMap方案有个前提用户订阅的连接和订单状态变更的事件落在同一台应用实例上。单机没问题一上集群就露馅——用户在A实例挂了SSE连接订单状态变更被负载均衡分到了B实例B实例手里的注册表里根本没有这个用户推送就静默丢失了。集群下的常规做法是把推送目标从应用内存挪到共享的中间件上。简单可靠的方案是这样所有实例订阅同一个Redis频道或消息队列的topic业务方要推送时往频道里发一条消息消息内容包含目标用户ID和事件数据。所有实例都收到这条广播然后各自查自己本地的注册表——用户连接在哪个实例上哪个实例就执行真正的emitter.send。用Redis的Pub/Sub就能实现Service public class ClusterOrderPushService { private final StringRedisTemplate redisTemplate; private final SseClientRegistry registry; // 业务推送入口发布到Redis频道 public void pushOrderStatus(Order order) { MapString, Object payload new HashMap(); payload.put(userId, order.getUserId()); payload.put(orderId, order.getId()); payload.put(status, order.getStatus().name()); redisTemplate.convertAndSend(order-status-topic, payload); } // 每个实例启动时注册Redis订阅收到消息后查本地注册表 PostConstruct public void subscribeOrderChannel() { redisTemplate.getConnectionFactory().getConnection().subscribe( (message, pattern) - { // 反序列化payload查本地注册表并发推送 MapString, Object payload deserialize(new String(message.getBody())); String userId (String) payload.get(userId); registry.get(userId).ifPresent(emitter - { try { emitter.send(SseEmitter.event() .name(orderStatus) .data(payload, MediaType.APPLICATION_JSON)); } catch (IOException e) { registry.remove(userId); } }); }, order-status-topic.getBytes() ); } }注意事项是Redis Pub/Sub的消息不持久化实例重启期间发布的消息会丢。如果推送场景不允许丢消息就把消息落到Stream或普通消息队列里让每个实例都消费到一个完整的推送指令流再结合本地注册表做幂等推送。这套方案持久化、扩展性都强很多代价是引入一个消息中间件。绝大多数订单通知、告警推送场景Redis Pub/Sub已经够用。我做了几年后端实时推送的坑基本上都踩过一遍。如果让我给一个通用建议先把业务里是不是真的需要双向通信这个问题想清楚。如果只是服务端往浏览器推数据SSE就是性价比最高的那个方案没有之一。它的调试体验、开发效率、运维成本都比WebSocket友好得多。真的遇到单向推送满足不了的场景再上WebSocket也不迟。最后再分享一个小技巧如果你也遇到SSE连接飘忽不定先别急着改代码花十分钟把从浏览器到服务端整条链路捋一遍看看哪一层有缓冲、哪一层有闲置超时十有八九问题就在那里。
最近在做一个订单状态实时推送的功能。需求本身不复杂用户下单之后后台经过审核、出库、发货、签收这些环节前端页面要实时显示最新状态不能让用户手动刷新才知道进度。我的第一反应是上WebSocket这个词这几年太火了一聊到实时就想到它。可真把方案摊开对比之后我最后选了SSEServer-Sent EventsSpring Boot里用SseEmitter实现代码量比WebSocket少一个数量级效果却完全够用。这篇文章把选型决策、SSE协议机制、Spring Boot落地代码、以及生产环境里那些连接莫名断开的坑全部写透。适合正在做通知推送、任务进度反馈、实时看板刷新这类服务端单方向推给浏览器场景的后端同学前端同学也能从中搞清楚EventSource该怎么和后端配合。1. 实时推送选型轮询、WebSocket、SSE我为什么选了最轻的那个1.1 三种方案的定位差异在做实时推送之前很多人的第一反应是直接用轮询不就行了。轮询确实是成本最低的方案前端每隔几秒发一个Ajax请求后端返回最新数据。但它有两个硬伤——延迟受轮询间隔限制间隔设小了流量浪费严重间隔设大了体验又差。长轮询Long Polling改良了一下让服务端把请求挂住一段时间有数据再返回但本质上还是在模拟推送连接频繁建立销毁代码复杂度还不低。WebSocket走的是另一条路它通过HTTP Upgrade把协议切换成TCP长连接实现真正的全双工通信。服务端能推客户端也能推适合聊天、协同编辑这类两端交互频繁的场景。但选择WebSocket意味着你要处理协议升级流程、二进制帧、心跳保活、消息重连这些底层细节。虽然后端框架帮我们隐藏了不少但整套体系依然是重量级的。SSE是个折中方案它没有新协议就是普通的HTTP GET请求只是服务端拿到请求后不急着返回而是把响应头设置成text/event-stream然后持续把数据写进响应体里。浏览器端的EventSource对象会自动解析这个流有数据就触发回调连接断了还会自动重试。下面这张对比表是我当时做选型时列的维度轮询WebSocketSSE通信方向客户端拉取双向服务端单向推送协议基础HTTP独立协议UpgradeHTTP自动重连无需自己实现EventSource内置服务端实现成本低高低浏览器兼容性全兼容主流浏览器支持IE不兼容其余主流可用典型场景低频数据查询聊天、双向协作通知、进度、实时看板1.2 适合用SSE的场景清单我把SSE适用的场景大致归成几类第一类是服务端状态变更通知比如订单状态流转、支付结果回调、消息中心红点第二类是任务进度推送比如文件处理、数据导入导出、视频转码前端要展示百分比第三类是实时数据广播比如股票行情、竞拍价格、监控大屏、运维日志流。这些场景的共同点是数据流向都是服务端到客户端单向的客户端几乎不发消息偶尔发也只是订阅或取消订阅。当然SSE也有明显的短板。它只能服务端吐数据无法替代WebSocket做双向通信浏览器对HTTP/1.1下同一域名连接数有限制一般是6个如果页面开了太多长连接会出问题而且中间任何一层代理如果缓冲了响应推送就会卡住。这些短板在选型的时候心里得有数。我当时的需求是订单状态单向推送SSE完美匹配于是当天就开工了。2. SSE协议详解一次完整的text/event-stream消息流是怎么诞生的2.1 本质就是一个不会被关闭的GET响应很多人第一次接触SSE会以为这是一种全新的网络协议其实不是。SSE的全称是Server-Sent Events它建立在普通HTTP之上只是借用了Content-Type: text/event-stream这个MIME类型让浏览器知道这个响应是一个事件流。整个通信过程是这样的客户端用EventSource对象发一个GET请求服务端收到请求后在响应头上标明Content-Type: text/event-stream然后连接保持打开。之后服务端想推数据就往这个响应体里写一段符合SSE格式的文本浏览器解析到了就触发事件。连接可以在Push之后继续保持也可以由服务端主动关闭。协议层面SSE消息是纯文本所以调试极其方便。后端一条命令就能看原始流curl -N http://localhost:8080/sse/news-N参数是关键它告诉curl禁止缓冲服务端每写一段数据终端就立即显示一段。如果你在浏览器里直接访问SSE接口的URL同样会看到源源不断的文本往外冒。2.2 消息格式data、event、id、retry各干什么SSE的在线数据格式很简单人为规定了一套键值对行。一条完整的消息由若干个字段行组成以空行结束。最核心的字段是data代表真正传给前端的数据data: 这是一条普通消息如果我需要传递结构化数据一般让data携带JSON字符串这样前端拿到后直接JSON.parse。还有几个字段虽然不像data那样必须但业务上非常有用event: orderStatus data: {orderId:20241101,status:SHIPPED,timestamp:1710000000000} id: 88 retry: 5000event字段声明事件类型相当于给这条消息打了个标签。前端默认监听onmessage处理所有消息但如果你用addEventListener(orderStatus, handler)就能针对性地只处理特定类型的事件。id字段是消息编号它的真正威力在断线重连环节浏览器重连时会把最后收到的id放到Last-Event-ID请求头里带给服务端服务端借此知道客户端缺了哪些数据就可以从断点继续推送。retry字段则告诉浏览器下一次重连前等待多少毫秒不传的话浏览器默认用3秒左右的机制。另外有一种特殊行以冒号开头的行是注释不算事件数据但能证明连接还活着。这类行我们一般用来做心跳包后面专门展开讲。2.3 浏览器端EventSource最小可运行代码服务端的坑先不聊先看客户端长什么样。EventSource是浏览器内置对象不需要引入任何依赖const es new EventSource(/sse/order/1001); es.onopen () { console.log(连接建立); }; es.onmessage (event) { const data JSON.parse(event.data); console.log(收到订单状态, data.status); }; es.addEventListener(orderStatus, (event) { // 只处理服务端 event: orderStatus 的消息 const data JSON.parse(event.data); updateOrderUI(data); }); es.onerror () { // 连接断开浏览器会自动重连 console.log(连接异常等待重连); };这里有个容易忽略的点EventSource默认只支持GET请求没法自定义请求头。如果你需要在订阅时带认证信息要么用Cookie要么把token放到URL的query参数里比如new EventSource(/sse/order/1001?tokenxxx)。这点很像img标签的防盗链逻辑所有信息都在地址上。3. Spring Boot里用SseEmitter跑通第一个推送接口3.1 依赖与前置其实你什么都不用加Spring Boot项目接入SSE最大的优点就是零额外依赖。SseEmitter是spring-webmvc自带的类凡是引入了spring-boot-starter-web的项目都能直接用不需要引入任何Reactor、Netty或额外消息中间件。我当时用的是Spring Boot 2.7Spring Boot 3.x也完全一样这个类在org.springframework.web.servlet.mvc.method.annotation包下。SseEmitter本质上是Spring MVC对Servlet 3.1异步请求的一种封装专门用来生成text/event-stream响应。你只要在Controller方法里返回一个SseEmitter实例Spring容器会自动完成异步请求的注册屏蔽掉底层Servlet API的细节。对业务代码来说你的任务只有一个在合适的时机调用emitter.send(...)把数据推出去。3.2 最简实现一个持续推送的新闻接口先写一个最直观的例子接口每两秒推送一条新闻推完5条后正常关闭连接。这样你能立刻看到SSE的完整生命周期RestController public class NewsSseController { GetMapping(path /sse/news, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter streamNews() { // 0L 表示连接永不超时 SseEmitter emitter new SseEmitter(0L); new Thread(() - { try { for (int i 1; i 5; i) { SseEmitter.SseEventBuilder event SseEmitter.event() .id(String.valueOf(i)) .name(news) .data(新闻 # i 已发布); emitter.send(event); Thread.sleep(2000); } emitter.complete(); } catch (Exception ex) { emitter.completeWithError(ex); } }).start(); return emitter; } }拆解一下关键点。produces MediaType.TEXT_EVENT_STREAM_VALUE让Spring在响应头里写入正确的MIME类型这是SSE能工作的基础。new SseEmitter(0L)传0表示不设超时原因后面细说。业务线程用SseEmitter.SseEventBuilder构造完整事件可以同时带上id、name和data。推送完最后一条后调用complete()等于告诉Spring和浏览器流结束了如果过程中出了异常用completeWithError(ex)把异常信息回传给客户端。3.3 用SseEventBuilder组装丰富事件上面例子里的.id()、.name()、.data()这三个方法是用的最多的。我再补几个实际会碰到的用法// 1. 推送JSON对象Spring会用Jackson自动序列化 OrderStatus status new OrderStatus(1001, SHIPPED, Instant.now()); emitter.send(SseEmitter.event() .name(orderStatus) .data(status, MediaType.APPLICATION_JSON)); // 2. 设置重连时间告诉浏览器断线后等5秒再连 emitter.send(SseEmitter.event() .reconnectTime(5000) .data(暂时的失败稍后重试)); // 3. 推送纯注释行用于心跳 emitter.send(SseEmitter.event().comment(heartbeat));这里提一下.comment()它生成的就是前面说的以冒号开头的注释行。注释行不会被前端当事件触发但会让数据在连接上流动那些闲置超时的判定就会被重置。3.4 快捷自测curl和EventSource的配合写完接口怎么快速验证我的习惯是三步走。第一步用curl看原始协议流curl -N http://localhost:8080/sse/news如果接口通终端上会每隔两秒出现一段id:、event:、data:组成的文本。第二步写一个50行以内的HTML文件用EventSource订阅并把消息显示到页面上这一步验证的是前端能不能正确解析。第三步才考虑用户维度、鉴权、心跳这些生产问题。先把这三步跑通说明SSE链路基本没问题了。4. 连接生命周期里的三个鬼门关超时、心跳、断线重连4.1 SseEmitter的超时参数没设置好连接悄悄被回收SSE连接是长连接但底层的Servlet容器都有异步请求超时机制。SseEmitter无参构造会采用一个默认超时值在Spring Boot默认内嵌容器下通常就是30秒左右。这意味着如果你建了连接之后30秒内什么都没推容器会认为这个请求超时了直接把异步上下文回收掉连接被断开。前端EventSource会以为网络异常进入重连流程。所以这个接口能推一次数据和这个接口能长期保持推送完全是两件事。我的做法是如果这个连接预期长期存在比如用户挂在订单页面一小时用new SseEmitter(0L)明确告诉容器永不超时如果连接只是短任务用的比如一次文件导入进度那就设一个合理的超时时间比如new SseEmitter(120_000L)超时后自动断开再由客户端重连。超时时长可以在SseEmitter上注册回调emitter.onTimeout(() - { System.out.println(连接超时等待清理); emitter.complete(); });无论设了多长的超时我都建议定期发心跳因为网络链路不止容器一层代理、网关、负载均衡设备都可能有自己的空闲回收策略。4.2 心跳包解决stream disconnected before completion: idle timeout waiting for sse在把这个SSE接口部署到网关后面时我遇到了一个非常典型的报错stream disconnected before completion: idle timeout waiting for sse这段话的意思是连接尚未完整结束但因为等待SSE数据时闲置超时连接被强行断开了。常见于后端服务通过Spring Cloud Gateway这类反应式网关代理SSE的场景底层Netty对长时间没有数据交互的连接会做闲置回收。Tomcat、Nginx也同样存在类似机制。解决方案是双管齐下。第一从源头避免闲置服务端定期发送心跳注释行。第二在网关或代理层把相关的空闲超时调大。服务端心跳的代码很简单我一般直接丢一个定时任务进去GetMapping(path /sse/task/{taskId}, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter taskProgress(PathVariable String taskId) { SseEmitter emitter new SseEmitter(0L); ScheduledExecutorService scheduler Executors.newSingleThreadScheduledExecutor(); TaskProgress progress TaskManager.get(taskId); // 每15秒发送一个注释行当心跳 scheduler.scheduleAtFixedRate(() - { try { emitter.send(SseEmitter.event().comment(heartbeat)); } catch (IOException e) { // 客户端已断开 scheduler.shutdown(); } }, 0, 15, TimeUnit.SECONDS); // 真正推送业务数据的线程 pushProgressLoop(emitter, progress, scheduler); return emitter; }心跳间隔我建议设在10秒到30秒之间。间隔太短会平白增加网络流量太长则可能被某些代理层的空闲阈值掐掉。如果确定整条链路只有一个Tomcat没有其他代理心跳可以放宽到30秒如果链路里还有Nginx、云负载均衡、各种网关建议保守一点用10秒。4.3 断线重连与Last-Event-ID续传EventSource最让我省心的地方是自动重连。连接断了浏览器会根据retry字段或者自己的默认策略自动重新发起请求不需要前端写任何重试逻辑。但重连了不代表数据不丢。比如服务端推送了1到10条消息客户端收到第5条后Wi-Fi闪断重连成功后的第一次请求服务端如果又从第1条开始推那客户端就要重复处理一堆旧数据。解决思路是把id字段用起来。浏览器重连时会在请求头里带上Last-Event-ID值是它最后收到的那条消息的id。服务端读取这个请求头就能确定客户端消费到哪了。实现方式是这样的GetMapping(path /sse/orders/{orderId}, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter orderStream(PathVariable String orderId, RequestHeader(value Last-Event-ID, required false) String lastEventId) { SseEmitter emitter new SseEmitter(0L); // 从lastEventId之后开始补发 ListOrderStatusEvent pendingEvents eventStore.findAfter(orderId, lastEventId); pendingEvents.forEach(event - { try { emitter.send(SseEmitter.event() .id(event.seq()) .name(orderStatus) .data(event, MediaType.APPLICATION_JSON)); } catch (IOException e) { // 客户端断开停止发送 } }); return emitter; }实现续传的前提是服务端自己得存一份每个用户/每条连接发过哪些消息的凭证。简单的做法是内存里存最近N条稳妥一点丢Redis。对大多数业务来说SSE本来就是实时通知客户端重连后能看到当前最新状态基本就满足需求了不一定非要逐条补齐历史。要不要做断点续传取决于业务对消息完整性的要求。比如订单状态推送重连后把当前状态推一次就够了但如果是审计日志流那缺一条都不行。5. 多用户并发推送从注册表设计到订单状态推送完整案例5.1 用ConcurrentHashMap自己维护连接池上面这些示例都是单连接独立演示实际系统里肯定是很多用户同时挂着SSE连接后台某个时刻发生了某个事件要把对应事件推给对应用户。所以必须有一个地方把所有活的连接管起来。我的做法很朴素一个ConcurrentHashMapkey是用户IDvalue是用户的SseEmitter。封装成一个注册表组件Component public class SseClientRegistry { private final MapString, SseEmitter clients new ConcurrentHashMap(); public SseEmitter register(String userId) { SseEmitter emitter new SseEmitter(0L); clients.put(userId, emitter); emitter.onCompletion(() - clients.remove(userId, emitter)); emitter.onTimeout(() - clients.remove(userId, emitter)); emitter.onError(e - clients.remove(userId, emitter)); return emitter; } public OptionalSseEmitter get(String userId) { return Optional.ofNullable(clients.get(userId)); } public void remove(String userId) { clients.remove(userId); } public int onlineCount() { return clients.size(); } }注册表这个想法很土但真的很可靠。onCompletion、onTimeout、onError这三个回调必须都写上否则连接断开后Map里会残留一堆垃圾Emitter时间一长就是内存泄漏。remove(userId, emitter)这种重载比直接把remove(userId)更安全它只会删除当前这个Emitter对象对应的条目防止并发下误删了用户重新建立的新连接。5.2 完整实战用户下单后订单状态实时刷新用一个具体场景把注册表串起来。用户在商城下单订单状态从待支付变成已支付再到已发货前端页面要实时刷新。核心流程分三步用户订阅、业务事件推送、前端接收。第一步用户打开订单详情页时订阅SSERestController RequestMapping(/api/sse) public class SseController { private final SseClientRegistry registry; public SseController(SseClientRegistry registry) { this.registry registry; } GetMapping(value /subscribe, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter subscribe(RequestParam String userId) { return registry.register(userId); } }第二步订单服务里订单状态一变就调用推送服务Service public class OrderPushService { private final SseClientRegistry registry; public OrderPushService(SseClientRegistry registry) { this.registry registry; } public void pushOrderStatus(Order order) { String userId order.getUserId(); registry.get(userId).ifPresentOrElse(emitter - { try { MapString, Object payload new HashMap(); payload.put(orderId, order.getId()); payload.put(status, order.getStatus().name()); payload.put(updatedAt, System.currentTimeMillis()); emitter.send(SseEmitter.event() .name(orderStatus) .data(payload, MediaType.APPLICATION_JSON)); } catch (IOException e) { registry.remove(userId); } }, () - { // 用户当前不在线可考虑存离线消息等下次订阅时再补发 log.info(用户{}离线暂不推送, userId); }); } }第三步前端订阅这个接口并监听orderStatus事件。之前那段EventSource代码直接能用。5.3 连接清理的细节别等OOM才想起来连接池这东西注册容易清理难。我在生产环境里踩过的具体坑有两个。第一个坑是线程泄漏。每个SSE连接如果都有一个自己的new Thread()或者ScheduledExecutorService当用户量上来时线程数会暴涨。后来我统一用一个共享的ScheduledExecutorService做心跳和定时推送连接本身仅仅是一个异步响应对象挂在线程池上这样线程资源是可控的。第二个坑是send方法抛IOException的时机。客户端断网时服务端不是立刻感知到的要等下一次send写数据时才会抛异常。如果心跳停了、业务数据又稀一个僵尸连接可能要在Map里驻留很久。所以心跳任务里catch到IOException后要顺手清理掉对应的连接别只shutdown自己的调度器。6. 生产环境避坑代理、集群与连接数这三个话题绕不开6.1 Nginx和网关的SSE专项配置开发环境里直接连Spring Boot端口SSE很欢快。一上生产前面挡了Nginx问题就来了Nginx默认开启了响应缓冲它会攒满一段数据才往后端转发。SSE是边产生边推送的Nginx一缓冲浏览器端就像断流一样半天收不到数据然后触发重连重连又缓冲形成恶性循环。Nginx反向代理SSE时至少需要这三条配置location /api/sse/ { proxy_pass http://backend-server; proxy_http_version 1.1; proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s; proxy_set_header Host $host; }proxy_http_version 1.1是保证长连接能撑住proxy_buffering off关掉缓冲让数据即收即转proxy_read_timeout 3600s把代理层的读超时拉到足够长。如果用了Spring Cloud Gateway这类响应式网关同样关注底层Netty的idleTimeout配置把它调大再配合服务端心跳包基本上stream disconnected before completion这类报错就能压下去。6.2 单机连接数的极限与HTTP/2SSE本质是长连接每一个用户都会占用一个连接。单机受两个限制一个是操作系统文件描述符上限另一个是Tomcat最大连接数配置。Tomcat默认的max-connections默认值是8192如果每个用户一条SSE连接再算上其他普通HTTP请求单机撑几千活跃用户已经是比较紧张的状态了。浏览器端的连接限制也要算进去。HTTP/1.1协议下每个域名最多同时开6个TCP连接如果一个页面既有SSE订阅、又有轮询请求、还要加载静态资源6个连接很容易被占满。这也是为什么老浏览器下SSE会被吐槽开多了不工作。解决方案之一是上HTTP/2。HTTP/2在同一TCP连接里多路复用SSE连接不再独占一个物理连接浏览器端的6连接限制对SSE的约束就小很多。Spring Boot开启HTTP/2比较简单内嵌Tomcat从9.0.x开始就支持配合server.http2.enabledtrue配置即可前提是使用了HTTPS。6.3 集群环境下推送指令如何到达正确的实例前面的ConcurrentHashMap方案有个前提用户订阅的连接和订单状态变更的事件落在同一台应用实例上。单机没问题一上集群就露馅——用户在A实例挂了SSE连接订单状态变更被负载均衡分到了B实例B实例手里的注册表里根本没有这个用户推送就静默丢失了。集群下的常规做法是把推送目标从应用内存挪到共享的中间件上。简单可靠的方案是这样所有实例订阅同一个Redis频道或消息队列的topic业务方要推送时往频道里发一条消息消息内容包含目标用户ID和事件数据。所有实例都收到这条广播然后各自查自己本地的注册表——用户连接在哪个实例上哪个实例就执行真正的emitter.send。用Redis的Pub/Sub就能实现Service public class ClusterOrderPushService { private final StringRedisTemplate redisTemplate; private final SseClientRegistry registry; // 业务推送入口发布到Redis频道 public void pushOrderStatus(Order order) { MapString, Object payload new HashMap(); payload.put(userId, order.getUserId()); payload.put(orderId, order.getId()); payload.put(status, order.getStatus().name()); redisTemplate.convertAndSend(order-status-topic, payload); } // 每个实例启动时注册Redis订阅收到消息后查本地注册表 PostConstruct public void subscribeOrderChannel() { redisTemplate.getConnectionFactory().getConnection().subscribe( (message, pattern) - { // 反序列化payload查本地注册表并发推送 MapString, Object payload deserialize(new String(message.getBody())); String userId (String) payload.get(userId); registry.get(userId).ifPresent(emitter - { try { emitter.send(SseEmitter.event() .name(orderStatus) .data(payload, MediaType.APPLICATION_JSON)); } catch (IOException e) { registry.remove(userId); } }); }, order-status-topic.getBytes() ); } }注意事项是Redis Pub/Sub的消息不持久化实例重启期间发布的消息会丢。如果推送场景不允许丢消息就把消息落到Stream或普通消息队列里让每个实例都消费到一个完整的推送指令流再结合本地注册表做幂等推送。这套方案持久化、扩展性都强很多代价是引入一个消息中间件。绝大多数订单通知、告警推送场景Redis Pub/Sub已经够用。我做了几年后端实时推送的坑基本上都踩过一遍。如果让我给一个通用建议先把业务里是不是真的需要双向通信这个问题想清楚。如果只是服务端往浏览器推数据SSE就是性价比最高的那个方案没有之一。它的调试体验、开发效率、运维成本都比WebSocket友好得多。真的遇到单向推送满足不了的场景再上WebSocket也不迟。最后再分享一个小技巧如果你也遇到SSE连接飘忽不定先别急着改代码花十分钟把从浏览器到服务端整条链路捋一遍看看哪一层有缓冲、哪一层有闲置超时十有八九问题就在那里。
