戰(zhàn)：從SSE到服務(wù)端消息推送完整指南)
1. 內(nèi)容整體設(shè)計(jì)與思路拆解1.1 為什么會(huì)有 “后端主動(dòng)推送” 這種需求先從一個(gè)最常見的場(chǎng)景說起用戶在網(wǎng)頁上點(diǎn)了“導(dǎo)出報(bào)表”后端開始跑任務(wù)跑完要通知前端下載文件。如果只用傳統(tǒng)的 HTTP 請(qǐng)求-響應(yīng)模型前端要么在發(fā)起請(qǐng)求后一直卡住等結(jié)果要么讓用戶“過一會(huì)兒手動(dòng)刷新”體驗(yàn)都很糟糕。真正理想的效果是后端任務(wù)一完成網(wǎng)頁立刻彈出“報(bào)表已生成點(diǎn)擊下載”。這種“后端主動(dòng)往瀏覽器推送狀態(tài)或數(shù)據(jù)”的需求絕不只是導(dǎo)出報(bào)表會(huì)用到。掃碼登錄、訂單狀態(tài)流轉(zhuǎn)、部署日志實(shí)時(shí)滾動(dòng)、在線告警通知、大屏數(shù)據(jù)刷新都屬于這個(gè)范疇。而實(shí)現(xiàn)這類需求業(yè)界常見的方案無非四種前端輪詢、WebSocket、SSEServer-Sent Events以及在某些場(chǎng)景下用的MQ WebSocket 網(wǎng)關(guān)組合。SSE 在這四個(gè)方案里往往是被低估的那一個(gè)。很多人一聊到實(shí)時(shí)通信腦子里第一反應(yīng)就是 WebSocket但實(shí)際上 SSE 在很多業(yè)務(wù)場(chǎng)景下更合適而且實(shí)現(xiàn)起來簡(jiǎn)單得多。1.2 SSE 是什么憑什么能往后端發(fā)消息SSE 全稱 Server-Sent Events是 HTML5 規(guī)范里定義的一種服務(wù)端推送技術(shù)。它不需要引入額外的協(xié)議也不需要像 WebSocket 那樣先做一次 HTTP 升級(jí)握手它就是一次普通的 HTTP 請(qǐng)求只不過服務(wù)端收到請(qǐng)求后不馬上結(jié)束響應(yīng)而是把響應(yīng)頭里的Content-Type設(shè)成text/event-stream然后持續(xù)地往響應(yīng)流里寫數(shù)據(jù)。用大白話講瀏覽器往后端發(fā)了一個(gè)普通 GET 請(qǐng)求后端說“你先別走我這邊有數(shù)據(jù)了就一段一段發(fā)給你”于是連接就保持打開狀態(tài)數(shù)據(jù)分多次從服務(wù)端流到前端。瀏覽器端的EventSource對(duì)象是原生支持的不需要任何第三方庫斷線后還會(huì)自動(dòng)重連這是 SSE 最大的一個(gè)隱藏優(yōu)勢(shì)。那什么東西能通過這條流發(fā)過去純文本?？梢允?JSON 字符串、字符串本身、也可以是事件類型加數(shù)據(jù)的組合。后端發(fā)的每一條消息瀏覽器都能通過onmessage或自定義事件監(jiān)聽器收到。也就是說SSE 本質(zhì)上是一條服務(wù)端到客戶端的單向數(shù)據(jù)通道如果前端需要給后端發(fā)消息走普通 HTTP 請(qǐng)求即可完全不影響。1.3 為什么 Spring Boot 里首選 SseEmitter在 Spring Boot 里沒有直接暴露底層的 HttpServletResponse 流讓你手寫 SSE而是提供了更高級(jí)的抽象類SseEmitter。這個(gè)類是 Spring Framework 4.2 引入的專門用來在 Spring MVC 里實(shí)現(xiàn)服務(wù)端推送底層依然基于 Servlet 的異步處理能力只是把“異步響應(yīng) 定時(shí)發(fā)送 連接完成/超時(shí)/異?；卣{(diào)”這些雜活全部封裝好了。SseEmitter 帶來的最直接好處有三個(gè)第一它天然兼容 Spring MVC 的 Controller 寫法你不需要懂 Servlet 異步編程細(xì)節(jié)一個(gè)方法返回SseEmitter即可。第二它提供了send()方法、complete()方法、onCompletion()/onTimeout()/onError()回調(diào)能覆蓋連接生命周期內(nèi)的所有關(guān)鍵節(jié)點(diǎn)。第三它支持按text/event-stream標(biāo)準(zhǔn)格式來組織消息包括事件名、事件 ID、數(shù)據(jù)多行內(nèi)容和瀏覽器的EventSource能完美對(duì)接。說白了如果你已經(jīng)在用 Spring Boot想在 Java 后端給前端做消息推送SseEmitter 就是最貼近“開箱即用”的那個(gè)方案不用引入 Netty、不用自己寫協(xié)議解析一個(gè) Controller 加一個(gè)線程池就足夠了。1.4 這篇內(nèi)容適合誰看能解決什么問題如果你在學(xué) Spring Boot或者正在做前后端分離項(xiàng)目、需要做站內(nèi)信/通知/進(jìn)度播報(bào)這類功能這篇內(nèi)容可以幫你繞開很多我當(dāng)年踩過的坑。我會(huì)把 SseEmitter 從環(huán)境準(zhǔn)備、核心代碼、前端連接到斷線重連、常見報(bào)錯(cuò)都過一遍尤其是高頻出現(xiàn)的stream disconnected before completion這類問題會(huì)重點(diǎn)分析根因和解決辦法。我接下來會(huì)按自己的實(shí)踐路線來寫先搭建一個(gè)最小可運(yùn)行的 SseEmitter Demo再講怎么把前端 EventSource 接上然后重點(diǎn)講生產(chǎn)環(huán)境里一定會(huì)遇到的超時(shí)、斷線、多客戶端管理問題最后附上一個(gè)常見問題排查表。整個(gè)節(jié)奏跟著真實(shí)項(xiàng)目走不是照抄官方文檔。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 環(huán)境準(zhǔn)備Spring Boot 版本與依賴問題先說一個(gè)很多人剛上手會(huì)懵的點(diǎn)SseEmitter 到底需要哪些依賴答案是只需要 spring-boot-starter-web不需要額外引入任何東西。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency只要項(xiàng)目里已經(jīng)引入了它SseEmitter 就在org.springframework.web.servlet.mvc.method.annotation包下面躺著直接用就行。Spring Boot 2.x 和 3.x 都支持不過需要注意一個(gè)細(xì)節(jié)Spring Boot 3.x 基于 Spring Framework 6Servlet API 從javax.servlet遷移到了jakarta.servlet如果你之前項(xiàng)目里直接寫過HttpServletResponse、AsyncContext這類底層對(duì)象升級(jí)到 Spring Boot 3.x 后依賴坐標(biāo)要同步調(diào)整。SseEmitter 本身被封裝在 Spring MVC 里對(duì)使用者來說影響不大但如果你要在底層做擴(kuò)展、寫 Filter 或攔截器還是要留個(gè)心眼看下你用的依賴包版本對(duì)應(yīng)的是哪套 Servlet API。還有一點(diǎn)經(jīng)常被忽略Spring Boot 版本迭代后異步請(qǐng)求默認(rèn)行為有變化。比如對(duì)接 SSE 時(shí)會(huì)涉及spring.mvc.async.request-timeout這個(gè)配置它控制的是 Spring MVC 異步請(qǐng)求的超時(shí)時(shí)間SseEmitter 連接也受它管。在高版本里如果某些默認(rèn)配置沒有顯式設(shè)置可能會(huì)導(dǎo)致連接比預(yù)期更早被釋放。我一般會(huì)在配置文件里顯式寫清楚超時(shí)時(shí)間而不是依賴默認(rèn)值。2.2 SseEmitter 核心 API 逐個(gè)拆解SseEmitter 的 API 不算多但每個(gè)都很關(guān)鍵。我按照使用頻率從高到低列一下new SseEmitter(Long timeout)構(gòu)造一個(gè)連接實(shí)例timeout是超時(shí)時(shí)間單位毫秒。傳0L表示永不超時(shí)但生產(chǎn)環(huán)境不建議這么干很容易造成連接泄漏。send(Object object)往連接里寫數(shù)據(jù)?？梢詡髯址?、對(duì)象Spring 會(huì)序列化成 SSE 格式。如果想發(fā)送自定義事件名和數(shù)據(jù)可以用SseEventBuilder。complete()正常關(guān)閉連接通知瀏覽器流結(jié)束了。completeWithError(Throwable ex)發(fā)生異常時(shí)關(guān)閉連接瀏覽器端會(huì)觸發(fā) error 事件。onCompletion(Runnable callback)連接正常完成時(shí)回調(diào)通常是客戶端斷開或服務(wù)端主動(dòng)complete()。onTimeout(Runnable callback)連接超時(shí)前觸發(fā)在回調(diào)里可以做清理或重連處理。onError(ConsumerThrowable callback)連接異常時(shí)觸發(fā)。實(shí)際使用中send()和complete()是最常用的而onCompletion()和onTimeout()往往是容易被人忽略、但排查問題時(shí)最關(guān)鍵的回調(diào)。2.3 SSE 消息格式與 SseEventBuilderSSE 的協(xié)議格式其實(shí)非常簡(jiǎn)單每條消息由若干字段組成每個(gè)字段一行行與行之間用空行分隔。字段名主要有data、event、id和retry。瀏覽器端的 EventSource 會(huì)按這個(gè)格式自動(dòng)解析。如果只是用emitter.send(obj)Spring 會(huì)把它序列化成data: obj這樣一條消息。但如果你想做更精細(xì)的控制比如指定事件類型就得用SseEventBuilderSseEmitter emitter new SseEmitter(); // 指定事件名稱和數(shù)據(jù) emitter.send(SseEmitter.event().name(orderStatus).data(jsonString)); // 帶上事件ID用于斷線重連時(shí)的 Last-Event-ID emitter.send(SseEmitter.event().id(1001).name(orderStatus).data(jsonString));這里event().name(orderStatus)對(duì)應(yīng)瀏覽器的addEventListener(orderStatus, ...)監(jiān)聽器id()則對(duì)應(yīng) SSE 協(xié)議里的id字段瀏覽器斷線重連時(shí)會(huì)自動(dòng)把Last-Event-ID請(qǐng)求頭發(fā)給服務(wù)端方便做斷點(diǎn)續(xù)傳。不過說實(shí)話大多數(shù)業(yè)務(wù)場(chǎng)景用默認(rèn)的data消息加上一個(gè) JSON 結(jié)構(gòu)體就夠用了比如{ type: orderStatus, data: { ... } }。自定義事件主要是為了前端多個(gè)監(jiān)聽器解耦需要的時(shí)候再用。2.4 連接生命周期與回調(diào)的坑SseEmitter 的生命周期其實(shí)和一把鎖的解鎖過程很像創(chuàng)建連接 → 保持連接 → 正常關(guān)閉/異常關(guān)閉/超時(shí)關(guān)閉。關(guān)鍵坑在于onCompletion()和onTimeout()在部分并發(fā)場(chǎng)景下可能觸發(fā)多個(gè)回調(diào)如果你在回調(diào)里寫入了共享資源容易造成重復(fù)釋放或者臟數(shù)據(jù)。比如連接超時(shí)后onTimeout()觸發(fā)一次但如果還有地方在調(diào)emitter.send()可能又拋出異常。我的習(xí)慣是持有一個(gè)MapString, SseEmitter在回調(diào)里把該客戶端 ID 從 Map 中移除同時(shí)加一個(gè)局部原子標(biāo)記確保釋放操作只執(zhí)行一次。emitter.onCompletion(() - { clientMap.remove(clientId); System.out.println(SSE連接已關(guān)閉: clientId); }); emitter.onTimeout(() - { clientMap.remove(clientId); emitter.complete(); });這種寫法雖然簡(jiǎn)單但能避免大量“僵尸連接”堆積在服務(wù)端。你如果不清理客戶端刷新頁面后舊的連接還掛在服務(wù)端連接數(shù)會(huì)越來越難看。3. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 最簡(jiǎn) Demo一個(gè) Controller 搞定推送我先寫個(gè)最直接的 Demo。假設(shè)場(chǎng)景是前端頁面打開后連上 SSE 接口后端每秒推送一次服務(wù)器當(dāng)前時(shí)間前端實(shí)時(shí)顯示。RestController RequestMapping(/api/sse) public class SseController { private final MapString, SseEmitter emitterMap new ConcurrentHashMap(); GetMapping(value /clock, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter clock() { String clientId UUID.randomUUID().toString(); SseEmitter emitter new SseEmitter(60_000L); // 60秒超時(shí) emitterMap.put(clientId, emitter); emitter.onCompletion(() - emitterMap.remove(clientId)); emitter.onTimeout(() - { emitter.complete(); emitterMap.remove(clientId); }); // 用一個(gè)線程池定時(shí)推送 Executors.newSingleThreadExecutor().submit(() - { try { while (true) { String timeJson {\time\:\ LocalTime.now() \}; emitter.send(timeJson); Thread.sleep(1000); } } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; } }這里有個(gè)很重要的點(diǎn)produces MediaType.TEXT_EVENT_STREAM_VALUE也就是text/event-stream。如果不設(shè)置這個(gè) Content-Type瀏覽器端 EventSource 會(huì)直接報(bào)錯(cuò)不把它當(dāng) SSE 流處理。這個(gè)細(xì)節(jié)很多新手會(huì)漏掉一漏就是大問題。另外還要注意我在這個(gè) Demo 里用的是Executors.newSingleThreadExecutor()每次來一個(gè)連接就開一個(gè)線程這在生產(chǎn)環(huán)境是不合適的后面會(huì)講正確的線程池做法。3.2 更符合實(shí)戰(zhàn)的寫法線程池 通用連接管理器真實(shí)項(xiàng)目里不能每個(gè)客戶端都開一個(gè)單線程否則高并發(fā)下線程數(shù)直接爆炸。更合理的做法是準(zhǔn)備一個(gè)應(yīng)用級(jí)線程池或者直接使用容器自帶的異步線程池控制器只負(fù)責(zé)創(chuàng)建 SseEmitter 并把它放進(jìn)連接管理器。我項(xiàng)目里的一個(gè)通用寫法是這樣的Service public class SseService { private final MapString, SseEmitter clients new ConcurrentHashMap(); private final ScheduledExecutorService scheduler Executors.newScheduledThreadPool(4); public SseEmitter connect(String clientId) { SseEmitter emitter new SseEmitter(300_000L); // 5分鐘超時(shí) clients.put(clientId, emitter); emitter.onCompletion(() - clients.remove(clientId)); emitter.onTimeout(() - { clients.remove(clientId); emitter.complete(); }); emitter.onError(e - clients.remove(clientId)); return emitter; } public void sendToClient(String clientId, Object data) { SseEmitter emitter clients.get(clientId); if (emitter ! null) { try { emitter.send(data); } catch (IOException e) { clients.remove(clientId); } } } public void sendToAll(Object data) { clients.forEach((id, emitter) - { try { emitter.send(data); } catch (IOException e) { clients.remove(id); } }); } public void heartbeat() { scheduler.scheduleAtFixedRate(() - { clients.forEach((id, emitter) - { try { emitter.send(SseEmitter.event().comment(heartbeat)); } catch (IOException e) { clients.remove(id); } }); }, 10, 30, TimeUnit.SECONDS); } }這個(gè)類三個(gè)職責(zé)管連接、發(fā)消息、?；?。connect()方法返回的SseEmitter直接給 Controller 用Controller 不需要關(guān)心連接生命周期。這里我引入了心跳機(jī)制這是生產(chǎn)環(huán)境必備的手段。瀏覽器端 EventSource 如果長時(shí)間收不到任何數(shù)據(jù)有些代理服務(wù)器或負(fù)載均衡器會(huì)認(rèn)為連接空閑從而把它斷開這也直接關(guān)聯(lián)到后面會(huì)講到的idle timeout問題。通過定時(shí)發(fā)送一條comment類型的空消息既能?；罘?wù)端連接又不會(huì)讓前端收到實(shí)際業(yè)務(wù)數(shù)據(jù)。3.3 實(shí)戰(zhàn)案例掃碼登錄的進(jìn)度推送光有 Demo 還不過癮我來分享一個(gè)我在實(shí)際項(xiàng)目中做過、且很適合用 SSE 的場(chǎng)景掃碼登錄。用戶打開網(wǎng)站前端調(diào)接口獲取一個(gè)二維碼和登錄憑證ticket二維碼上帶了ticket手機(jī)端掃碼確認(rèn)后后端在某個(gè)接口里更新了登錄狀態(tài)此時(shí)網(wǎng)頁需要立刻感知到“確認(rèn)成功”并跳轉(zhuǎn)。用傳統(tǒng)輪詢的方式要么延遲高要么請(qǐng)求量大用 SSE 就很順。實(shí)現(xiàn)思路用戶打開登錄頁前端生成ticket或者后端生成。前端以ticket為參數(shù)發(fā)起 SSE 連接/api/sse/login/{ticket}。后端把這個(gè)連接存入連接管理器。用戶在手機(jī)端確認(rèn)后后端業(yè)務(wù)邏輯調(diào)用sseService.sendToClient(ticket, LOGIN_SUCCESS)。前端收到消息跳轉(zhuǎn)主頁同時(shí)關(guān)閉 EventSource。關(guān)鍵代碼里有個(gè)細(xì)節(jié)ticket必須是連接的唯一標(biāo)識(shí)我用ConcurrentHashMap管理key 就是ticketvalue 是SseEmitter。注意在用戶取消登錄或掃碼頁面關(guān)閉時(shí)前端要主動(dòng)調(diào)一個(gè)“斷開連接”的接口或者直接關(guān)閉 EventSource服務(wù)端通過onCompletion()回調(diào)清理掉過期連接。如果不做清理這些連接會(huì)一直掛到超時(shí)時(shí)間才被回收。3.4 前端怎么接EventSource 使用要點(diǎn)服務(wù)端寫好了前端要用EventSource來接。原生寫法是最簡(jiǎn)單也最穩(wěn)的const source new EventSource(/api/sse/clock); source.onopen () { console.log(SSE 連接已建立); }; source.onmessage (event) { const data JSON.parse(event.data); console.log(收到消息:, data); document.getElementById(time).innerText data.time; }; source.onerror (event) { console.error(連接異常); // EventSource 會(huì)自動(dòng)重連但這里可以根據(jù)業(yè)務(wù)邏輯決定是否要手動(dòng) close };如果服務(wù)端用了SseEventBuilder.event().name(orderStatus)這種自定義事件名前端要用addEventListener來監(jiān)聽source.addEventListener(orderStatus, (event) { const data JSON.parse(event.data); console.log(訂單狀態(tài)變化:, data); });關(guān)于自動(dòng)重連這是 SSE 相對(duì) WebSocket 的一個(gè)天然優(yōu)勢(shì)。EventSource 在連接斷開后默認(rèn)會(huì)自動(dòng)重連重連間隔可以通過服務(wù)端發(fā)送retry: 5000字段來調(diào)整。而且連接異常時(shí)瀏覽器會(huì)把上次收到的id作為Last-Event-ID請(qǐng)求頭發(fā)給服務(wù)端服務(wù)端如果做了斷點(diǎn)續(xù)傳邏輯就能實(shí)現(xiàn)“斷開后接著推送而不是重頭推送”。不過自動(dòng)重連也有坑如果服務(wù)端因?yàn)闃I(yè)務(wù)原因主動(dòng)complete()關(guān)閉了連接比如用戶已經(jīng)登錄成功但前端沒有調(diào)close()EventSource 會(huì)自動(dòng)重連并產(chǎn)生大量無效連接。解決辦法是當(dāng)前端收到業(yè)務(wù)結(jié)束信號(hào)時(shí)必須手動(dòng)執(zhí)行source.close()不能再依賴服務(wù)端關(guān)閉。3.5 參數(shù)選擇與計(jì)算過程超時(shí)時(shí)間、線程池規(guī)格、心跳間隔聊參數(shù)之前先強(qiáng)調(diào)一個(gè)原則SSE 連接數(shù)等于“計(jì)數(shù)線程 連接對(duì)象”的資源組合不能不加約束。這里我把幾個(gè)關(guān)鍵參數(shù)總結(jié)一下并解釋為什么這么選單連接超時(shí)時(shí)間我一般設(shè) 300 秒5 分鐘。純前端頁面如果超過 5 分鐘沒有業(yè)務(wù)消息說明用戶大概率已經(jīng)離開或者頁面進(jìn)入后臺(tái)了。如果業(yè)務(wù)要求長時(shí)間在線可以配合心跳把超時(shí)時(shí)間設(shè)長比如 30 分鐘。心跳間隔核心目的是防止中間代理空閑超時(shí)。常見的 Nginx 代理配置里proxy_read_timeout默認(rèn)是 60 秒也就是說代理 60 秒沒讀到后端數(shù)據(jù)就會(huì)掐掉連接。我習(xí)慣把心跳間隔設(shè)為 30 秒給代理超時(shí)留足夠余量。這里有個(gè)常見誤區(qū)只有同時(shí)把 Nginx 的proxy_read_timeout調(diào)大如 300 秒并把服務(wù)端超時(shí)時(shí)間對(duì)齊三層才能協(xié)同工作。推送線程池規(guī)格Executors.newScheduledThreadPool(4)還是newCachedThreadPool()取決于你的推送任務(wù)類型。如果是大量低頻消息推送用固定線程池如果每個(gè)連接的消息會(huì)阻塞而你又需要嚴(yán)格隔離得用更大的線程池或消息隊(duì)列方案但代價(jià)是復(fù)雜度上升。個(gè)人建議從 4 個(gè)調(diào)度線程開始?jí)簻y(cè)后看 CPU 和線程池隊(duì)列積壓情況再調(diào)整不要一上來就配 200。這些參數(shù)沒有絕對(duì)標(biāo)準(zhǔn)核心原則是“三層對(duì)齊”服務(wù)端超時(shí)時(shí)間、心跳間隔、中間代理的 read timeout 三者必須滿足“服務(wù)端超時(shí) 心跳間隔 代理超時(shí)”否則連接就會(huì)在某個(gè)環(huán)節(jié)被誤殺。4. 常見問題與排查技巧實(shí)錄4.1 高頻報(bào)錯(cuò)stream disconnected before completion很多人在用 SseEmitter 時(shí)會(huì)遇到這種報(bào)錯(cuò)報(bào)錯(cuò)信息類似org.springframework.web.context.request.async.AsyncRequestNotUsableException: The async request timed out after [...] stream disconnected before completion: idle timeout waiting for sse我記得最早看到這個(gè)報(bào)錯(cuò)時(shí)反復(fù)查了好幾天最后才把根因定位清楚。這個(gè)報(bào)錯(cuò)的直接原因是服務(wù)端在創(chuàng)建 SseEmitter 后沒有再往流里寫任何數(shù)據(jù)連接空閑時(shí)間達(dá)到了超時(shí)閾值被容器或代理強(qiáng)制關(guān)掉了。這個(gè)報(bào)錯(cuò)有兩個(gè)層面第一連接空閑超時(shí)。創(chuàng)建了new SseEmitter(30000)后30 秒內(nèi)沒有調(diào)用send()Spring 容器會(huì)判定異步請(qǐng)求超時(shí)觸發(fā)onTimeout()回調(diào)并斷開連接。所以如果你要“先建立連接過一段時(shí)間再發(fā)消息”的業(yè)務(wù)光設(shè)一個(gè)超時(shí)時(shí)間沒用必須配合心跳機(jī)制讓連接在空閑期間也有數(shù)據(jù)流動(dòng)。我上面的heartbeat()方法就是這個(gè)作用。第二瀏覽器事件中的stream disconnected before completion字樣。這個(gè)更像是對(duì)狀態(tài)的描述連接已經(jīng)斷開了。斷開的原因從服務(wù)端日志里查可能是容器超時(shí)、代理超時(shí)也可能是 Nginx 返回了 504/502。排查思路是先在本地直連后端繞開 Nginx 看是否正常再通過帶重試的 curl 模擬 SSE 連接確認(rèn)大概多久會(huì)斷然后對(duì)照服務(wù)端日志和 Nginx 日志找具體超時(shí)配置。4.2 Nginx 對(duì) SSE 的攔路行為不管在測(cè)試環(huán)境還是生產(chǎn)環(huán)境只要前面掛了 NginxSSE 幾乎都會(huì)遇到一個(gè)同樣的問題連接建立后很快就斷了。大多數(shù)情況是因?yàn)?Nginx 對(duì) HTTP 有緩沖和超時(shí)機(jī)制。需要在 Nginx 配置里為 SSE 接口做三件事location /api/sse/ { proxy_pass http://backend; proxy_set_header Connection ; proxy_http_version 1.1; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; }proxy_buffering off關(guān)閉緩沖。默認(rèn)情況下 Nginx 會(huì)緩沖上游響應(yīng)等攢夠一定量再一次性返回給客戶端這對(duì) SSE 是致命打擊。proxy_http_version 1.1和清空Connection頭避免連接頭引起兼容問題。proxy_read_timeout 300s跟服務(wù)端超時(shí)對(duì)齊確保代理層不會(huì)因?yàn)殚L時(shí)間無數(shù)據(jù)而提前斷開。改完配置記得nginx -t nginx -s reload。我在生產(chǎn)上排查過無數(shù)次“SSE 連上幾秒就斷開”的工單最后 90% 都倒在 Nginx 緩沖和讀超時(shí)這兩個(gè)配置上這塊一定要優(yōu)先排查。4.3 多個(gè)客戶端并發(fā)與線程安全問題SseEmitter 實(shí)例本身有狀態(tài)的同一個(gè)SseEmitter不能在多線程里并發(fā)調(diào)用send()而不加鎖。如果同一個(gè)連接有多個(gè)線程同時(shí)往流里寫數(shù)據(jù)會(huì)發(fā)生數(shù)據(jù)交錯(cuò)或者IOException導(dǎo)致連接被關(guān)閉。實(shí)際業(yè)務(wù)里常見的觸發(fā)場(chǎng)景是一個(gè)客戶端訂閱了多個(gè)事件源比如同時(shí)訂閱“訂單狀態(tài)變化”和“系統(tǒng)公告”兩個(gè)服務(wù)方法在不同的線程里對(duì)同一個(gè)SseEmitter調(diào)send()。解決辦法我一般采取兩個(gè)方向加鎖把send()方法用synchronized或ReentrantLock保護(hù)起來保證同一時(shí)間只有一個(gè)線程在寫。串行化把所有推送任務(wù)丟到一個(gè)單線程隊(duì)列里如BlockingQueue 一個(gè)消費(fèi)者線程按順序發(fā)送。這種方式對(duì)消息量大的場(chǎng)景更安全。另外ConcurrentHashMap在多線程環(huán)境下對(duì) Map 操作是安全的但“判斷連接是否存在 → 發(fā)送消息”這個(gè)復(fù)合動(dòng)作不是原子的需要同步校驗(yàn)或者干脆在send()方法里直接捕獲IOException并從 Map 刪除。不要試圖先containsKey()再get()這兩個(gè)操作之間連接可能已經(jīng)斷了省略檢查直接 send 并捕獲異常是最省心的寫法。4.4 Spring Boot 版本太高/太低帶來的差異有人反饋過這樣一個(gè)場(chǎng)景同一個(gè)SseEmitter代碼在 Spring Boot 2.3 上正常升級(jí)到 Spring Boot 3.2 后就出現(xiàn)連接閃斷。這不是錯(cuò)覺是 Spring Boot 3.x 和 Spring Framework 6 在異步請(qǐng)求處理、線程池配置、默認(rèn)超時(shí)機(jī)制上發(fā)生了變化。幾個(gè)我在實(shí)踐中摸出來的版本差異點(diǎn)Spring Boot 3.x 默認(rèn)使用 Jakarta Servlet API如果你在項(xiàng)目里同時(shí)引入了老版javax.servlet依賴會(huì)導(dǎo)致異步請(qǐng)求行為異常。Spring Boot 3.x 對(duì) Spring MVC 異步請(qǐng)求超時(shí)時(shí)間的默認(rèn)值發(fā)生了變化如果你沒有顯式配置spring.mvc.async.request-timeout建議在升級(jí)后加上并逐步壓測(cè)驗(yàn)證。Spring Boot 3.x 的自動(dòng)配置更嚴(yán)格某些第三方攔截器或過濾器如果在新版本里注冊(cè)順序不對(duì)可能會(huì)提前消費(fèi)掉 SSE 響應(yīng)體或者給響應(yīng)頭增加不必要的內(nèi)容。我建議如果你的核心業(yè)務(wù)重度依賴 SseEmitter升級(jí) Spring Boot 大版本時(shí)把這個(gè)功能單獨(dú)拎出來做一次回歸測(cè)試不要隨大流一起升級(jí)。我踩過一回整個(gè)版本的異步連接數(shù)在壓測(cè)里直接掉了一半排查了很久才發(fā)現(xiàn)是新版默認(rèn)線程配置導(dǎo)致的。4.5 排查速查表這里整理了一張表把我在 SseEmitter 使用中遇到的高頻問題、現(xiàn)象、根因和解決方案匯總起來方便排查時(shí)直接對(duì)照現(xiàn)象可能原因解決辦法連接建立后幾秒內(nèi)斷開服務(wù)端超時(shí)時(shí)間太短且無心跳增加超時(shí)時(shí)間加入定時(shí)心跳前端報(bào) net::ERR_INCOMPLETE_CHUNKED_ENCODINGNginx 緩沖或代理超時(shí)關(guān)掉 Nginx 的 proxy_buffering設(shè)置 proxy_read_timeout后端日志報(bào) AsyncRequestNotUsableException連接被容器回收線程被釋放配置異步線程池設(shè)置合理超時(shí)心跳?；顂end() 拋 IllegalStateException連接已經(jīng) complete 或客戶端已斷開捕獲 IOException從 Map 清理連接多個(gè)線程同時(shí) send 導(dǎo)致數(shù)據(jù)錯(cuò)亂未對(duì) SseEmitter 實(shí)例加鎖加同步鎖或改為單線程隊(duì)列消費(fèi)EventSource 一直重連但收不到數(shù)據(jù)服務(wù)端返回的不是 text/event-stream或接口報(bào)錯(cuò)檢查 Content-Type、HTTP 狀態(tài)碼和網(wǎng)關(guān)日志升級(jí) Spring Boot 版本后連接閃斷異步配置或 Servlet API 版本變化顯式配置 long 超時(shí)和異步線程池回歸壓測(cè)4.6 后端主動(dòng)斷開與客戶端異常斷開這里再單獨(dú)說一個(gè)很容易搞混的場(chǎng)景后端主動(dòng)斷開和客戶端異常斷開代碼處理和前端表現(xiàn)是不一樣的。如果后端要主動(dòng)斷開比如推送完最后一條消息、業(yè)務(wù)結(jié)束應(yīng)該調(diào)用complete()此時(shí)瀏覽器端觸發(fā)onclose或onerror。但注意EventSource 的 onerror 默認(rèn)會(huì)觸發(fā)自動(dòng)重連因此服務(wù)端主動(dòng)關(guān)閉前最好先在消息體里告訴前端“連接即將關(guān)閉”讓前端在收到該消息后手動(dòng)close()從而避免無意義的自動(dòng)重連。如果是客戶端異常斷開比如用戶關(guān)了瀏覽器、斷了網(wǎng)服務(wù)端不會(huì)立刻感知到。這時(shí)send()方法會(huì)在下一次嘗試寫入時(shí)拋出 IOExceptiononCompletion()回調(diào)才可能觸發(fā)。這就是為什么發(fā)送時(shí)一定要捕獲異常并清理連接否則這些“半死不活”的連接會(huì)一直占用服務(wù)端資源。我在生產(chǎn)中還碰到過一種情況客戶端把 EventSource 關(guān)閉了但服務(wù)端的 SseEmitter 連接沒有被回收因?yàn)榈讓泳W(wǎng)絡(luò)沒有任何數(shù)據(jù)流動(dòng)服務(wù)端也不知道對(duì)端已經(jīng)走了。如果沒有設(shè)置超時(shí)時(shí)間這個(gè)連接可能一直掛著。所以我的建議是每個(gè)連接都必須設(shè)置超時(shí)時(shí)間超時(shí)時(shí)間到后服務(wù)端主動(dòng) complete釋放資源。5. 稍微拓展一點(diǎn)SSE 和 WebSocket 的取舍5.1 二者的適用場(chǎng)景對(duì)比很多人會(huì)問既然 WebSocket 能做到雙向通信為什么還要用 SSE其實(shí)這兩個(gè)東西不是替代關(guān)系是“各司其職”。WebSocket 是全雙工通信客戶端和服務(wù)端都能隨時(shí)發(fā)消息適合聊天、實(shí)時(shí)協(xié)作、在線游戲這類場(chǎng)景。SSE 是半雙工只能服務(wù)端主動(dòng)推客戶端要發(fā)消息得另外走普通 HTTP這種設(shè)計(jì)反而讓它比 WebSocket 更輕量、更容易做權(quán)限校驗(yàn)、更容易做斷線重連。我自己的判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果只需要服務(wù)端推送比如狀態(tài)提醒、進(jìn)度播報(bào)用 SSE如果需要雙向高頻交互、多人實(shí)時(shí)協(xié)作用 WebSocket。不要一上來就把架構(gòu)復(fù)雜度拉滿能用 SSE 解決的就先別上 WebSocket。尤其是在 Java 生態(tài)里WebSocket 雖然 Spring 也支持但它涉及到握手會(huì)話管理、心跳檢測(cè)、消息分發(fā)代碼量和排查難度都上一個(gè)臺(tái)階。5.2 什么時(shí)候不該用 SSESSE 也不是銀彈。我有一次在設(shè)計(jì)一個(gè)項(xiàng)目時(shí)業(yè)務(wù)要求“服務(wù)端推消息給前端前端處理完要立刻返回結(jié)果”這種模式下 SSE 就顯得別扭了因?yàn)?SSE 是單向的前端返回結(jié)果只能再發(fā) HTTP 請(qǐng)求來回一多就沒有“實(shí)時(shí)”的感覺了。這種場(chǎng)景還是應(yīng)該用 WebSocket 或者把交互改造成請(qǐng)求-響應(yīng)模式。還有一個(gè)場(chǎng)景不建議用 SSE消息量極其密集、每條消息都很小、實(shí)時(shí)性要求近乎硬實(shí)時(shí)的金融行情推送。SSE 基于 HTTP 長連接每條消息都有 HTTP 層開銷雖然也能撐住但吞吐量和高并發(fā)能力比不上專門做協(xié)議優(yōu)化的方案。這種場(chǎng)景下WebSocket 甚至自研 TCP 協(xié)議都比 SSE 合適。結(jié)尾的話最后分享一點(diǎn)個(gè)人體會(huì)我在項(xiàng)目里第一次用 SseEmitter 時(shí)也是抱著“這玩意能行嗎”的心態(tài)。踩過幾次坑之后慢慢摸索出幾條經(jīng)驗(yàn)比如一定要配心跳、一定要管理好連接 Map、一定要關(guān) Nginx 緩沖做到這三點(diǎn)SSE 在 Spring Boot 里基本就是一條穩(wěn)定的一對(duì)多推送通道了。如果你現(xiàn)在正準(zhǔn)備實(shí)現(xiàn)掃碼登錄、任務(wù)進(jìn)度播報(bào)、實(shí)時(shí)告警這些功能可以先從 SseEmitter 這種低成本方案開始推等到確認(rèn)確實(shí)需要雙向通信時(shí)再上 WebSocket往往能省掉很多不必要的復(fù)雜度。 Spring Boot SseEmitter實(shí)戰(zhàn)：從SSE到服務(wù)端消息推送完整指南
1. 內(nèi)容整體設(shè)計(jì)與思路拆解1.1 為什么會(huì)有 “后端主動(dòng)推送” 這種需求先從一個(gè)最常見的場(chǎng)景說起用戶在網(wǎng)頁上點(diǎn)了“導(dǎo)出報(bào)表”后端開始跑任務(wù)跑完要通知前端下載文件。如果只用傳統(tǒng)的 HTTP 請(qǐng)求-響應(yīng)模型前端要么在發(fā)起請(qǐng)求后一直卡住等結(jié)果要么讓用戶“過一會(huì)兒手動(dòng)刷新”體驗(yàn)都很糟糕。真正理想的效果是后端任務(wù)一完成網(wǎng)頁立刻彈出“報(bào)表已生成點(diǎn)擊下載”。這種“后端主動(dòng)往瀏覽器推送狀態(tài)或數(shù)據(jù)”的需求絕不只是導(dǎo)出報(bào)表會(huì)用到。掃碼登錄、訂單狀態(tài)流轉(zhuǎn)、部署日志實(shí)時(shí)滾動(dòng)、在線告警通知、大屏數(shù)據(jù)刷新都屬于這個(gè)范疇。而實(shí)現(xiàn)這類需求業(yè)界常見的方案無非四種前端輪詢、WebSocket、SSEServer-Sent Events以及在某些場(chǎng)景下用的MQ WebSocket 網(wǎng)關(guān)組合。SSE 在這四個(gè)方案里往往是被低估的那一個(gè)。很多人一聊到實(shí)時(shí)通信腦子里第一反應(yīng)就是 WebSocket但實(shí)際上 SSE 在很多業(yè)務(wù)場(chǎng)景下更合適而且實(shí)現(xiàn)起來簡(jiǎn)單得多。1.2 SSE 是什么憑什么能往后端發(fā)消息SSE 全稱 Server-Sent Events是 HTML5 規(guī)范里定義的一種服務(wù)端推送技術(shù)。它不需要引入額外的協(xié)議也不需要像 WebSocket 那樣先做一次 HTTP 升級(jí)握手它就是一次普通的 HTTP 請(qǐng)求只不過服務(wù)端收到請(qǐng)求后不馬上結(jié)束響應(yīng)而是把響應(yīng)頭里的Content-Type設(shè)成text/event-stream然后持續(xù)地往響應(yīng)流里寫數(shù)據(jù)。用大白話講瀏覽器往后端發(fā)了一個(gè)普通 GET 請(qǐng)求后端說“你先別走我這邊有數(shù)據(jù)了就一段一段發(fā)給你”于是連接就保持打開狀態(tài)數(shù)據(jù)分多次從服務(wù)端流到前端。瀏覽器端的EventSource對(duì)象是原生支持的不需要任何第三方庫斷線后還會(huì)自動(dòng)重連這是 SSE 最大的一個(gè)隱藏優(yōu)勢(shì)。那什么東西能通過這條流發(fā)過去純文本?？梢允?JSON 字符串、字符串本身、也可以是事件類型加數(shù)據(jù)的組合。后端發(fā)的每一條消息瀏覽器都能通過onmessage或自定義事件監(jiān)聽器收到。也就是說SSE 本質(zhì)上是一條服務(wù)端到客戶端的單向數(shù)據(jù)通道如果前端需要給后端發(fā)消息走普通 HTTP 請(qǐng)求即可完全不影響。1.3 為什么 Spring Boot 里首選 SseEmitter在 Spring Boot 里沒有直接暴露底層的 HttpServletResponse 流讓你手寫 SSE而是提供了更高級(jí)的抽象類SseEmitter。這個(gè)類是 Spring Framework 4.2 引入的專門用來在 Spring MVC 里實(shí)現(xiàn)服務(wù)端推送底層依然基于 Servlet 的異步處理能力只是把“異步響應(yīng) 定時(shí)發(fā)送 連接完成/超時(shí)/異?；卣{(diào)”這些雜活全部封裝好了。SseEmitter 帶來的最直接好處有三個(gè)第一它天然兼容 Spring MVC 的 Controller 寫法你不需要懂 Servlet 異步編程細(xì)節(jié)一個(gè)方法返回SseEmitter即可。第二它提供了send()方法、complete()方法、onCompletion()/onTimeout()/onError()回調(diào)能覆蓋連接生命周期內(nèi)的所有關(guān)鍵節(jié)點(diǎn)。第三它支持按text/event-stream標(biāo)準(zhǔn)格式來組織消息包括事件名、事件 ID、數(shù)據(jù)多行內(nèi)容和瀏覽器的EventSource能完美對(duì)接。說白了如果你已經(jīng)在用 Spring Boot想在 Java 后端給前端做消息推送SseEmitter 就是最貼近“開箱即用”的那個(gè)方案不用引入 Netty、不用自己寫協(xié)議解析一個(gè) Controller 加一個(gè)線程池就足夠了。1.4 這篇內(nèi)容適合誰看能解決什么問題如果你在學(xué) Spring Boot或者正在做前后端分離項(xiàng)目、需要做站內(nèi)信/通知/進(jìn)度播報(bào)這類功能這篇內(nèi)容可以幫你繞開很多我當(dāng)年踩過的坑。我會(huì)把 SseEmitter 從環(huán)境準(zhǔn)備、核心代碼、前端連接到斷線重連、常見報(bào)錯(cuò)都過一遍尤其是高頻出現(xiàn)的stream disconnected before completion這類問題會(huì)重點(diǎn)分析根因和解決辦法。我接下來會(huì)按自己的實(shí)踐路線來寫先搭建一個(gè)最小可運(yùn)行的 SseEmitter Demo再講怎么把前端 EventSource 接上然后重點(diǎn)講生產(chǎn)環(huán)境里一定會(huì)遇到的超時(shí)、斷線、多客戶端管理問題最后附上一個(gè)常見問題排查表。整個(gè)節(jié)奏跟著真實(shí)項(xiàng)目走不是照抄官方文檔。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 環(huán)境準(zhǔn)備Spring Boot 版本與依賴問題先說一個(gè)很多人剛上手會(huì)懵的點(diǎn)SseEmitter 到底需要哪些依賴答案是只需要 spring-boot-starter-web不需要額外引入任何東西。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency只要項(xiàng)目里已經(jīng)引入了它SseEmitter 就在org.springframework.web.servlet.mvc.method.annotation包下面躺著直接用就行。Spring Boot 2.x 和 3.x 都支持不過需要注意一個(gè)細(xì)節(jié)Spring Boot 3.x 基于 Spring Framework 6Servlet API 從javax.servlet遷移到了jakarta.servlet如果你之前項(xiàng)目里直接寫過HttpServletResponse、AsyncContext這類底層對(duì)象升級(jí)到 Spring Boot 3.x 后依賴坐標(biāo)要同步調(diào)整。SseEmitter 本身被封裝在 Spring MVC 里對(duì)使用者來說影響不大但如果你要在底層做擴(kuò)展、寫 Filter 或攔截器還是要留個(gè)心眼看下你用的依賴包版本對(duì)應(yīng)的是哪套 Servlet API。還有一點(diǎn)經(jīng)常被忽略Spring Boot 版本迭代后異步請(qǐng)求默認(rèn)行為有變化。比如對(duì)接 SSE 時(shí)會(huì)涉及spring.mvc.async.request-timeout這個(gè)配置它控制的是 Spring MVC 異步請(qǐng)求的超時(shí)時(shí)間SseEmitter 連接也受它管。在高版本里如果某些默認(rèn)配置沒有顯式設(shè)置可能會(huì)導(dǎo)致連接比預(yù)期更早被釋放。我一般會(huì)在配置文件里顯式寫清楚超時(shí)時(shí)間而不是依賴默認(rèn)值。2.2 SseEmitter 核心 API 逐個(gè)拆解SseEmitter 的 API 不算多但每個(gè)都很關(guān)鍵。我按照使用頻率從高到低列一下new SseEmitter(Long timeout)構(gòu)造一個(gè)連接實(shí)例timeout是超時(shí)時(shí)間單位毫秒。傳0L表示永不超時(shí)但生產(chǎn)環(huán)境不建議這么干很容易造成連接泄漏。send(Object object)往連接里寫數(shù)據(jù)?？梢詡髯址?、對(duì)象Spring 會(huì)序列化成 SSE 格式。如果想發(fā)送自定義事件名和數(shù)據(jù)可以用SseEventBuilder。complete()正常關(guān)閉連接通知瀏覽器流結(jié)束了。completeWithError(Throwable ex)發(fā)生異常時(shí)關(guān)閉連接瀏覽器端會(huì)觸發(fā) error 事件。onCompletion(Runnable callback)連接正常完成時(shí)回調(diào)通常是客戶端斷開或服務(wù)端主動(dòng)complete()。onTimeout(Runnable callback)連接超時(shí)前觸發(fā)在回調(diào)里可以做清理或重連處理。onError(ConsumerThrowable callback)連接異常時(shí)觸發(fā)。實(shí)際使用中send()和complete()是最常用的而onCompletion()和onTimeout()往往是容易被人忽略、但排查問題時(shí)最關(guān)鍵的回調(diào)。2.3 SSE 消息格式與 SseEventBuilderSSE 的協(xié)議格式其實(shí)非常簡(jiǎn)單每條消息由若干字段組成每個(gè)字段一行行與行之間用空行分隔。字段名主要有data、event、id和retry。瀏覽器端的 EventSource 會(huì)按這個(gè)格式自動(dòng)解析。如果只是用emitter.send(obj)Spring 會(huì)把它序列化成data: obj這樣一條消息。但如果你想做更精細(xì)的控制比如指定事件類型就得用SseEventBuilderSseEmitter emitter new SseEmitter(); // 指定事件名稱和數(shù)據(jù) emitter.send(SseEmitter.event().name(orderStatus).data(jsonString)); // 帶上事件ID用于斷線重連時(shí)的 Last-Event-ID emitter.send(SseEmitter.event().id(1001).name(orderStatus).data(jsonString));這里event().name(orderStatus)對(duì)應(yīng)瀏覽器的addEventListener(orderStatus, ...)監(jiān)聽器id()則對(duì)應(yīng) SSE 協(xié)議里的id字段瀏覽器斷線重連時(shí)會(huì)自動(dòng)把Last-Event-ID請(qǐng)求頭發(fā)給服務(wù)端方便做斷點(diǎn)續(xù)傳。不過說實(shí)話大多數(shù)業(yè)務(wù)場(chǎng)景用默認(rèn)的data消息加上一個(gè) JSON 結(jié)構(gòu)體就夠用了比如{ type: orderStatus, data: { ... } }。自定義事件主要是為了前端多個(gè)監(jiān)聽器解耦需要的時(shí)候再用。2.4 連接生命周期與回調(diào)的坑SseEmitter 的生命周期其實(shí)和一把鎖的解鎖過程很像創(chuàng)建連接 → 保持連接 → 正常關(guān)閉/異常關(guān)閉/超時(shí)關(guān)閉。關(guān)鍵坑在于onCompletion()和onTimeout()在部分并發(fā)場(chǎng)景下可能觸發(fā)多個(gè)回調(diào)如果你在回調(diào)里寫入了共享資源容易造成重復(fù)釋放或者臟數(shù)據(jù)。比如連接超時(shí)后onTimeout()觸發(fā)一次但如果還有地方在調(diào)emitter.send()可能又拋出異常。我的習(xí)慣是持有一個(gè)MapString, SseEmitter在回調(diào)里把該客戶端 ID 從 Map 中移除同時(shí)加一個(gè)局部原子標(biāo)記確保釋放操作只執(zhí)行一次。emitter.onCompletion(() - { clientMap.remove(clientId); System.out.println(SSE連接已關(guān)閉: clientId); }); emitter.onTimeout(() - { clientMap.remove(clientId); emitter.complete(); });這種寫法雖然簡(jiǎn)單但能避免大量“僵尸連接”堆積在服務(wù)端。你如果不清理客戶端刷新頁面后舊的連接還掛在服務(wù)端連接數(shù)會(huì)越來越難看。3. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 最簡(jiǎn) Demo一個(gè) Controller 搞定推送我先寫個(gè)最直接的 Demo。假設(shè)場(chǎng)景是前端頁面打開后連上 SSE 接口后端每秒推送一次服務(wù)器當(dāng)前時(shí)間前端實(shí)時(shí)顯示。RestController RequestMapping(/api/sse) public class SseController { private final MapString, SseEmitter emitterMap new ConcurrentHashMap(); GetMapping(value /clock, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter clock() { String clientId UUID.randomUUID().toString(); SseEmitter emitter new SseEmitter(60_000L); // 60秒超時(shí) emitterMap.put(clientId, emitter); emitter.onCompletion(() - emitterMap.remove(clientId)); emitter.onTimeout(() - { emitter.complete(); emitterMap.remove(clientId); }); // 用一個(gè)線程池定時(shí)推送 Executors.newSingleThreadExecutor().submit(() - { try { while (true) { String timeJson {\time\:\ LocalTime.now() \}; emitter.send(timeJson); Thread.sleep(1000); } } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; } }這里有個(gè)很重要的點(diǎn)produces MediaType.TEXT_EVENT_STREAM_VALUE也就是text/event-stream。如果不設(shè)置這個(gè) Content-Type瀏覽器端 EventSource 會(huì)直接報(bào)錯(cuò)不把它當(dāng) SSE 流處理。這個(gè)細(xì)節(jié)很多新手會(huì)漏掉一漏就是大問題。另外還要注意我在這個(gè) Demo 里用的是Executors.newSingleThreadExecutor()每次來一個(gè)連接就開一個(gè)線程這在生產(chǎn)環(huán)境是不合適的后面會(huì)講正確的線程池做法。3.2 更符合實(shí)戰(zhàn)的寫法線程池 通用連接管理器真實(shí)項(xiàng)目里不能每個(gè)客戶端都開一個(gè)單線程否則高并發(fā)下線程數(shù)直接爆炸。更合理的做法是準(zhǔn)備一個(gè)應(yīng)用級(jí)線程池或者直接使用容器自帶的異步線程池控制器只負(fù)責(zé)創(chuàng)建 SseEmitter 并把它放進(jìn)連接管理器。我項(xiàng)目里的一個(gè)通用寫法是這樣的Service public class SseService { private final MapString, SseEmitter clients new ConcurrentHashMap(); private final ScheduledExecutorService scheduler Executors.newScheduledThreadPool(4); public SseEmitter connect(String clientId) { SseEmitter emitter new SseEmitter(300_000L); // 5分鐘超時(shí) clients.put(clientId, emitter); emitter.onCompletion(() - clients.remove(clientId)); emitter.onTimeout(() - { clients.remove(clientId); emitter.complete(); }); emitter.onError(e - clients.remove(clientId)); return emitter; } public void sendToClient(String clientId, Object data) { SseEmitter emitter clients.get(clientId); if (emitter ! null) { try { emitter.send(data); } catch (IOException e) { clients.remove(clientId); } } } public void sendToAll(Object data) { clients.forEach((id, emitter) - { try { emitter.send(data); } catch (IOException e) { clients.remove(id); } }); } public void heartbeat() { scheduler.scheduleAtFixedRate(() - { clients.forEach((id, emitter) - { try { emitter.send(SseEmitter.event().comment(heartbeat)); } catch (IOException e) { clients.remove(id); } }); }, 10, 30, TimeUnit.SECONDS); } }這個(gè)類三個(gè)職責(zé)管連接、發(fā)消息、?；?。connect()方法返回的SseEmitter直接給 Controller 用Controller 不需要關(guān)心連接生命周期。這里我引入了心跳機(jī)制這是生產(chǎn)環(huán)境必備的手段。瀏覽器端 EventSource 如果長時(shí)間收不到任何數(shù)據(jù)有些代理服務(wù)器或負(fù)載均衡器會(huì)認(rèn)為連接空閑從而把它斷開這也直接關(guān)聯(lián)到后面會(huì)講到的idle timeout問題。通過定時(shí)發(fā)送一條comment類型的空消息既能?；罘?wù)端連接又不會(huì)讓前端收到實(shí)際業(yè)務(wù)數(shù)據(jù)。3.3 實(shí)戰(zhàn)案例掃碼登錄的進(jìn)度推送光有 Demo 還不過癮我來分享一個(gè)我在實(shí)際項(xiàng)目中做過、且很適合用 SSE 的場(chǎng)景掃碼登錄。用戶打開網(wǎng)站前端調(diào)接口獲取一個(gè)二維碼和登錄憑證ticket二維碼上帶了ticket手機(jī)端掃碼確認(rèn)后后端在某個(gè)接口里更新了登錄狀態(tài)此時(shí)網(wǎng)頁需要立刻感知到“確認(rèn)成功”并跳轉(zhuǎn)。用傳統(tǒng)輪詢的方式要么延遲高要么請(qǐng)求量大用 SSE 就很順。實(shí)現(xiàn)思路用戶打開登錄頁前端生成ticket或者后端生成。前端以ticket為參數(shù)發(fā)起 SSE 連接/api/sse/login/{ticket}。后端把這個(gè)連接存入連接管理器。用戶在手機(jī)端確認(rèn)后后端業(yè)務(wù)邏輯調(diào)用sseService.sendToClient(ticket, LOGIN_SUCCESS)。前端收到消息跳轉(zhuǎn)主頁同時(shí)關(guān)閉 EventSource。關(guān)鍵代碼里有個(gè)細(xì)節(jié)ticket必須是連接的唯一標(biāo)識(shí)我用ConcurrentHashMap管理key 就是ticketvalue 是SseEmitter。注意在用戶取消登錄或掃碼頁面關(guān)閉時(shí)前端要主動(dòng)調(diào)一個(gè)“斷開連接”的接口或者直接關(guān)閉 EventSource服務(wù)端通過onCompletion()回調(diào)清理掉過期連接。如果不做清理這些連接會(huì)一直掛到超時(shí)時(shí)間才被回收。3.4 前端怎么接EventSource 使用要點(diǎn)服務(wù)端寫好了前端要用EventSource來接。原生寫法是最簡(jiǎn)單也最穩(wěn)的const source new EventSource(/api/sse/clock); source.onopen () { console.log(SSE 連接已建立); }; source.onmessage (event) { const data JSON.parse(event.data); console.log(收到消息:, data); document.getElementById(time).innerText data.time; }; source.onerror (event) { console.error(連接異常); // EventSource 會(huì)自動(dòng)重連但這里可以根據(jù)業(yè)務(wù)邏輯決定是否要手動(dòng) close };如果服務(wù)端用了SseEventBuilder.event().name(orderStatus)這種自定義事件名前端要用addEventListener來監(jiān)聽source.addEventListener(orderStatus, (event) { const data JSON.parse(event.data); console.log(訂單狀態(tài)變化:, data); });關(guān)于自動(dòng)重連這是 SSE 相對(duì) WebSocket 的一個(gè)天然優(yōu)勢(shì)。EventSource 在連接斷開后默認(rèn)會(huì)自動(dòng)重連重連間隔可以通過服務(wù)端發(fā)送retry: 5000字段來調(diào)整。而且連接異常時(shí)瀏覽器會(huì)把上次收到的id作為Last-Event-ID請(qǐng)求頭發(fā)給服務(wù)端服務(wù)端如果做了斷點(diǎn)續(xù)傳邏輯就能實(shí)現(xiàn)“斷開后接著推送而不是重頭推送”。不過自動(dòng)重連也有坑如果服務(wù)端因?yàn)闃I(yè)務(wù)原因主動(dòng)complete()關(guān)閉了連接比如用戶已經(jīng)登錄成功但前端沒有調(diào)close()EventSource 會(huì)自動(dòng)重連并產(chǎn)生大量無效連接。解決辦法是當(dāng)前端收到業(yè)務(wù)結(jié)束信號(hào)時(shí)必須手動(dòng)執(zhí)行source.close()不能再依賴服務(wù)端關(guān)閉。3.5 參數(shù)選擇與計(jì)算過程超時(shí)時(shí)間、線程池規(guī)格、心跳間隔聊參數(shù)之前先強(qiáng)調(diào)一個(gè)原則SSE 連接數(shù)等于“計(jì)數(shù)線程 連接對(duì)象”的資源組合不能不加約束。這里我把幾個(gè)關(guān)鍵參數(shù)總結(jié)一下并解釋為什么這么選單連接超時(shí)時(shí)間我一般設(shè) 300 秒5 分鐘。純前端頁面如果超過 5 分鐘沒有業(yè)務(wù)消息說明用戶大概率已經(jīng)離開或者頁面進(jìn)入后臺(tái)了。如果業(yè)務(wù)要求長時(shí)間在線可以配合心跳把超時(shí)時(shí)間設(shè)長比如 30 分鐘。心跳間隔核心目的是防止中間代理空閑超時(shí)。常見的 Nginx 代理配置里proxy_read_timeout默認(rèn)是 60 秒也就是說代理 60 秒沒讀到后端數(shù)據(jù)就會(huì)掐掉連接。我習(xí)慣把心跳間隔設(shè)為 30 秒給代理超時(shí)留足夠余量。這里有個(gè)常見誤區(qū)只有同時(shí)把 Nginx 的proxy_read_timeout調(diào)大如 300 秒并把服務(wù)端超時(shí)時(shí)間對(duì)齊三層才能協(xié)同工作。推送線程池規(guī)格Executors.newScheduledThreadPool(4)還是newCachedThreadPool()取決于你的推送任務(wù)類型。如果是大量低頻消息推送用固定線程池如果每個(gè)連接的消息會(huì)阻塞而你又需要嚴(yán)格隔離得用更大的線程池或消息隊(duì)列方案但代價(jià)是復(fù)雜度上升。個(gè)人建議從 4 個(gè)調(diào)度線程開始?jí)簻y(cè)后看 CPU 和線程池隊(duì)列積壓情況再調(diào)整不要一上來就配 200。這些參數(shù)沒有絕對(duì)標(biāo)準(zhǔn)核心原則是“三層對(duì)齊”服務(wù)端超時(shí)時(shí)間、心跳間隔、中間代理的 read timeout 三者必須滿足“服務(wù)端超時(shí) 心跳間隔 代理超時(shí)”否則連接就會(huì)在某個(gè)環(huán)節(jié)被誤殺。4. 常見問題與排查技巧實(shí)錄4.1 高頻報(bào)錯(cuò)stream disconnected before completion很多人在用 SseEmitter 時(shí)會(huì)遇到這種報(bào)錯(cuò)報(bào)錯(cuò)信息類似org.springframework.web.context.request.async.AsyncRequestNotUsableException: The async request timed out after [...] stream disconnected before completion: idle timeout waiting for sse我記得最早看到這個(gè)報(bào)錯(cuò)時(shí)反復(fù)查了好幾天最后才把根因定位清楚。這個(gè)報(bào)錯(cuò)的直接原因是服務(wù)端在創(chuàng)建 SseEmitter 后沒有再往流里寫任何數(shù)據(jù)連接空閑時(shí)間達(dá)到了超時(shí)閾值被容器或代理強(qiáng)制關(guān)掉了。這個(gè)報(bào)錯(cuò)有兩個(gè)層面第一連接空閑超時(shí)。創(chuàng)建了new SseEmitter(30000)后30 秒內(nèi)沒有調(diào)用send()Spring 容器會(huì)判定異步請(qǐng)求超時(shí)觸發(fā)onTimeout()回調(diào)并斷開連接。所以如果你要“先建立連接過一段時(shí)間再發(fā)消息”的業(yè)務(wù)光設(shè)一個(gè)超時(shí)時(shí)間沒用必須配合心跳機(jī)制讓連接在空閑期間也有數(shù)據(jù)流動(dòng)。我上面的heartbeat()方法就是這個(gè)作用。第二瀏覽器事件中的stream disconnected before completion字樣。這個(gè)更像是對(duì)狀態(tài)的描述連接已經(jīng)斷開了。斷開的原因從服務(wù)端日志里查可能是容器超時(shí)、代理超時(shí)也可能是 Nginx 返回了 504/502。排查思路是先在本地直連后端繞開 Nginx 看是否正常再通過帶重試的 curl 模擬 SSE 連接確認(rèn)大概多久會(huì)斷然后對(duì)照服務(wù)端日志和 Nginx 日志找具體超時(shí)配置。4.2 Nginx 對(duì) SSE 的攔路行為不管在測(cè)試環(huán)境還是生產(chǎn)環(huán)境只要前面掛了 NginxSSE 幾乎都會(huì)遇到一個(gè)同樣的問題連接建立后很快就斷了。大多數(shù)情況是因?yàn)?Nginx 對(duì) HTTP 有緩沖和超時(shí)機(jī)制。需要在 Nginx 配置里為 SSE 接口做三件事location /api/sse/ { proxy_pass http://backend; proxy_set_header Connection ; proxy_http_version 1.1; proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; }proxy_buffering off關(guān)閉緩沖。默認(rèn)情況下 Nginx 會(huì)緩沖上游響應(yīng)等攢夠一定量再一次性返回給客戶端這對(duì) SSE 是致命打擊。proxy_http_version 1.1和清空Connection頭避免連接頭引起兼容問題。proxy_read_timeout 300s跟服務(wù)端超時(shí)對(duì)齊確保代理層不會(huì)因?yàn)殚L時(shí)間無數(shù)據(jù)而提前斷開。改完配置記得nginx -t nginx -s reload。我在生產(chǎn)上排查過無數(shù)次“SSE 連上幾秒就斷開”的工單最后 90% 都倒在 Nginx 緩沖和讀超時(shí)這兩個(gè)配置上這塊一定要優(yōu)先排查。4.3 多個(gè)客戶端并發(fā)與線程安全問題SseEmitter 實(shí)例本身有狀態(tài)的同一個(gè)SseEmitter不能在多線程里并發(fā)調(diào)用send()而不加鎖。如果同一個(gè)連接有多個(gè)線程同時(shí)往流里寫數(shù)據(jù)會(huì)發(fā)生數(shù)據(jù)交錯(cuò)或者IOException導(dǎo)致連接被關(guān)閉。實(shí)際業(yè)務(wù)里常見的觸發(fā)場(chǎng)景是一個(gè)客戶端訂閱了多個(gè)事件源比如同時(shí)訂閱“訂單狀態(tài)變化”和“系統(tǒng)公告”兩個(gè)服務(wù)方法在不同的線程里對(duì)同一個(gè)SseEmitter調(diào)send()。解決辦法我一般采取兩個(gè)方向加鎖把send()方法用synchronized或ReentrantLock保護(hù)起來保證同一時(shí)間只有一個(gè)線程在寫。串行化把所有推送任務(wù)丟到一個(gè)單線程隊(duì)列里如BlockingQueue 一個(gè)消費(fèi)者線程按順序發(fā)送。這種方式對(duì)消息量大的場(chǎng)景更安全。另外ConcurrentHashMap在多線程環(huán)境下對(duì) Map 操作是安全的但“判斷連接是否存在 → 發(fā)送消息”這個(gè)復(fù)合動(dòng)作不是原子的需要同步校驗(yàn)或者干脆在send()方法里直接捕獲IOException并從 Map 刪除。不要試圖先containsKey()再get()這兩個(gè)操作之間連接可能已經(jīng)斷了省略檢查直接 send 并捕獲異常是最省心的寫法。4.4 Spring Boot 版本太高/太低帶來的差異有人反饋過這樣一個(gè)場(chǎng)景同一個(gè)SseEmitter代碼在 Spring Boot 2.3 上正常升級(jí)到 Spring Boot 3.2 后就出現(xiàn)連接閃斷。這不是錯(cuò)覺是 Spring Boot 3.x 和 Spring Framework 6 在異步請(qǐng)求處理、線程池配置、默認(rèn)超時(shí)機(jī)制上發(fā)生了變化。幾個(gè)我在實(shí)踐中摸出來的版本差異點(diǎn)Spring Boot 3.x 默認(rèn)使用 Jakarta Servlet API如果你在項(xiàng)目里同時(shí)引入了老版javax.servlet依賴會(huì)導(dǎo)致異步請(qǐng)求行為異常。Spring Boot 3.x 對(duì) Spring MVC 異步請(qǐng)求超時(shí)時(shí)間的默認(rèn)值發(fā)生了變化如果你沒有顯式配置spring.mvc.async.request-timeout建議在升級(jí)后加上并逐步壓測(cè)驗(yàn)證。Spring Boot 3.x 的自動(dòng)配置更嚴(yán)格某些第三方攔截器或過濾器如果在新版本里注冊(cè)順序不對(duì)可能會(huì)提前消費(fèi)掉 SSE 響應(yīng)體或者給響應(yīng)頭增加不必要的內(nèi)容。我建議如果你的核心業(yè)務(wù)重度依賴 SseEmitter升級(jí) Spring Boot 大版本時(shí)把這個(gè)功能單獨(dú)拎出來做一次回歸測(cè)試不要隨大流一起升級(jí)。我踩過一回整個(gè)版本的異步連接數(shù)在壓測(cè)里直接掉了一半排查了很久才發(fā)現(xiàn)是新版默認(rèn)線程配置導(dǎo)致的。4.5 排查速查表這里整理了一張表把我在 SseEmitter 使用中遇到的高頻問題、現(xiàn)象、根因和解決方案匯總起來方便排查時(shí)直接對(duì)照現(xiàn)象可能原因解決辦法連接建立后幾秒內(nèi)斷開服務(wù)端超時(shí)時(shí)間太短且無心跳增加超時(shí)時(shí)間加入定時(shí)心跳前端報(bào) net::ERR_INCOMPLETE_CHUNKED_ENCODINGNginx 緩沖或代理超時(shí)關(guān)掉 Nginx 的 proxy_buffering設(shè)置 proxy_read_timeout后端日志報(bào) AsyncRequestNotUsableException連接被容器回收線程被釋放配置異步線程池設(shè)置合理超時(shí)心跳?；顂end() 拋 IllegalStateException連接已經(jīng) complete 或客戶端已斷開捕獲 IOException從 Map 清理連接多個(gè)線程同時(shí) send 導(dǎo)致數(shù)據(jù)錯(cuò)亂未對(duì) SseEmitter 實(shí)例加鎖加同步鎖或改為單線程隊(duì)列消費(fèi)EventSource 一直重連但收不到數(shù)據(jù)服務(wù)端返回的不是 text/event-stream或接口報(bào)錯(cuò)檢查 Content-Type、HTTP 狀態(tài)碼和網(wǎng)關(guān)日志升級(jí) Spring Boot 版本后連接閃斷異步配置或 Servlet API 版本變化顯式配置 long 超時(shí)和異步線程池回歸壓測(cè)4.6 后端主動(dòng)斷開與客戶端異常斷開這里再單獨(dú)說一個(gè)很容易搞混的場(chǎng)景后端主動(dòng)斷開和客戶端異常斷開代碼處理和前端表現(xiàn)是不一樣的。如果后端要主動(dòng)斷開比如推送完最后一條消息、業(yè)務(wù)結(jié)束應(yīng)該調(diào)用complete()此時(shí)瀏覽器端觸發(fā)onclose或onerror。但注意EventSource 的 onerror 默認(rèn)會(huì)觸發(fā)自動(dòng)重連因此服務(wù)端主動(dòng)關(guān)閉前最好先在消息體里告訴前端“連接即將關(guān)閉”讓前端在收到該消息后手動(dòng)close()從而避免無意義的自動(dòng)重連。如果是客戶端異常斷開比如用戶關(guān)了瀏覽器、斷了網(wǎng)服務(wù)端不會(huì)立刻感知到。這時(shí)send()方法會(huì)在下一次嘗試寫入時(shí)拋出 IOExceptiononCompletion()回調(diào)才可能觸發(fā)。這就是為什么發(fā)送時(shí)一定要捕獲異常并清理連接否則這些“半死不活”的連接會(huì)一直占用服務(wù)端資源。我在生產(chǎn)中還碰到過一種情況客戶端把 EventSource 關(guān)閉了但服務(wù)端的 SseEmitter 連接沒有被回收因?yàn)榈讓泳W(wǎng)絡(luò)沒有任何數(shù)據(jù)流動(dòng)服務(wù)端也不知道對(duì)端已經(jīng)走了。如果沒有設(shè)置超時(shí)時(shí)間這個(gè)連接可能一直掛著。所以我的建議是每個(gè)連接都必須設(shè)置超時(shí)時(shí)間超時(shí)時(shí)間到后服務(wù)端主動(dòng) complete釋放資源。5. 稍微拓展一點(diǎn)SSE 和 WebSocket 的取舍5.1 二者的適用場(chǎng)景對(duì)比很多人會(huì)問既然 WebSocket 能做到雙向通信為什么還要用 SSE其實(shí)這兩個(gè)東西不是替代關(guān)系是“各司其職”。WebSocket 是全雙工通信客戶端和服務(wù)端都能隨時(shí)發(fā)消息適合聊天、實(shí)時(shí)協(xié)作、在線游戲這類場(chǎng)景。SSE 是半雙工只能服務(wù)端主動(dòng)推客戶端要發(fā)消息得另外走普通 HTTP這種設(shè)計(jì)反而讓它比 WebSocket 更輕量、更容易做權(quán)限校驗(yàn)、更容易做斷線重連。我自己的判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果只需要服務(wù)端推送比如狀態(tài)提醒、進(jìn)度播報(bào)用 SSE如果需要雙向高頻交互、多人實(shí)時(shí)協(xié)作用 WebSocket。不要一上來就把架構(gòu)復(fù)雜度拉滿能用 SSE 解決的就先別上 WebSocket。尤其是在 Java 生態(tài)里WebSocket 雖然 Spring 也支持但它涉及到握手會(huì)話管理、心跳檢測(cè)、消息分發(fā)代碼量和排查難度都上一個(gè)臺(tái)階。5.2 什么時(shí)候不該用 SSESSE 也不是銀彈。我有一次在設(shè)計(jì)一個(gè)項(xiàng)目時(shí)業(yè)務(wù)要求“服務(wù)端推消息給前端前端處理完要立刻返回結(jié)果”這種模式下 SSE 就顯得別扭了因?yàn)?SSE 是單向的前端返回結(jié)果只能再發(fā) HTTP 請(qǐng)求來回一多就沒有“實(shí)時(shí)”的感覺了。這種場(chǎng)景還是應(yīng)該用 WebSocket 或者把交互改造成請(qǐng)求-響應(yīng)模式。還有一個(gè)場(chǎng)景不建議用 SSE消息量極其密集、每條消息都很小、實(shí)時(shí)性要求近乎硬實(shí)時(shí)的金融行情推送。SSE 基于 HTTP 長連接每條消息都有 HTTP 層開銷雖然也能撐住但吞吐量和高并發(fā)能力比不上專門做協(xié)議優(yōu)化的方案。這種場(chǎng)景下WebSocket 甚至自研 TCP 協(xié)議都比 SSE 合適。結(jié)尾的話最后分享一點(diǎn)個(gè)人體會(huì)我在項(xiàng)目里第一次用 SseEmitter 時(shí)也是抱著“這玩意能行嗎”的心態(tài)。踩過幾次坑之后慢慢摸索出幾條經(jīng)驗(yàn)比如一定要配心跳、一定要管理好連接 Map、一定要關(guān) Nginx 緩沖做到這三點(diǎn)SSE 在 Spring Boot 里基本就是一條穩(wěn)定的一對(duì)多推送通道了。如果你現(xiàn)在正準(zhǔn)備實(shí)現(xiàn)掃碼登錄、任務(wù)進(jìn)度播報(bào)、實(shí)時(shí)告警這些功能可以先從 SseEmitter 這種低成本方案開始推等到確認(rèn)確實(shí)需要雙向通信時(shí)再上 WebSocket往往能省掉很多不必要的復(fù)雜度。