簡(jiǎn)介這是一份面向Java Web開(kāi)發(fā)初學(xué)者與需要快速驗(yàn)證雙向通信場(chǎng)景的開(kāi)發(fā)者準(zhǔn)備的WebSocket入門(mén)示例工程圍繞瀏覽器與服務(wù)器全雙工通信這一核心機(jī)制展開(kāi)可用于理解握手流程、消息幀傳輸以及服務(wù)端主動(dòng)推送等關(guān)鍵概念。壓縮包共19個(gè)文件約41KB以Eclipse工程配置類(lèi)文件為主包含prefs、xml、component、classpath、project等工程描述文件另有jsp頁(yè)面、java源碼、websocket-api.jar依賴(lài)包及readme說(shuō)明文檔整體結(jié)構(gòu)輕量導(dǎo)入IDE后即可閱讀與調(diào)試。目前已有391人學(xué)習(xí)下載說(shuō)明該示例在同類(lèi)入門(mén)資料中具備一定參考價(jià)值。讀者可借助它快速搭建可運(yùn)行的WebSocket最小環(huán)境對(duì)照源碼理解服務(wù)端端點(diǎn)與前端頁(yè)面的交互方式并在此基礎(chǔ)上擴(kuò)展群聊、消息推送等練習(xí)適合作為協(xié)議入門(mén)與工程配置參考的起點(diǎn)。1. websocket demo從握手到心跳一個(gè)能直接跑通的實(shí)時(shí)通信最小閉環(huán)很多人第一次搜 websocket demo是想找一個(gè)能直接跑起來(lái)的最小示例前端點(diǎn)一下按鈕后端推一條消息瀏覽器控制臺(tái)能看到幀。但真正拿它做業(yè)務(wù)時(shí)翻車(chē)點(diǎn)往往不在“連不上”而在“連上了之后”。連接空閑幾分鐘被中間設(shè)備悄悄掐斷、心跳包發(fā)得太密把移動(dòng)端電量吃光、重連時(shí)消息順序錯(cuò)亂——這些才是 websocket demo 從玩具走向生產(chǎn)必須跨過(guò)的坎。這篇筆記圍繞一個(gè)可復(fù)現(xiàn)的 websocket demo 展開(kāi)先講清握手和幀格式為什么決定了它的行為邊界再給出一份前后端都能跑的最小代碼然后逐項(xiàng)拆解心跳機(jī)制實(shí)現(xiàn)、重連退避、消息可靠性這幾個(gè)高頻需求最后落到壓測(cè)和排查技巧。適合已經(jīng)會(huì)寫(xiě) HTTP 接口、想給項(xiàng)目加實(shí)時(shí)推送能力的后端或全棧工程師也適合前端想搞明白 WebSocket 對(duì)象生命周期的人。讀完你應(yīng)該能自己搭一個(gè)帶心跳和自動(dòng)重連的 demo并知道每個(gè)參數(shù)為什么這么設(shè)。2. 握手、幀與選型websocket demo 背后的三個(gè)硬約束2.1 一次 Upgrade 握手決定了后續(xù)所有行為WebSocket 不是憑空長(zhǎng)出來(lái)的協(xié)議它借用了 HTTP 的握手通道?？蛻?hù)端發(fā)一個(gè)帶Upgrade: websocket和Sec-WebSocket-Key的 GET 請(qǐng)求服務(wù)端如果同意返回 101 Switching Protocols這條 TCP 連接就從 HTTP 語(yǔ)義切換成 WebSocket 幀語(yǔ)義。理解這一點(diǎn)很關(guān)鍵握手階段仍然受 HTTP 中間件影響比如 Nginx 的反代規(guī)則、鑒權(quán)頭、跨域策略都是在握手這一下生效的。很多 demo 在本地跑得好好的一上 Nginx 就 400問(wèn)題幾乎都出在握手請(qǐng)求被當(dāng)普通 HTTP 處理了。握手成功后雙方用幀通信。幀有 opcode 區(qū)分類(lèi)型文本幀、二進(jìn)制幀、ping、pong、close。心跳機(jī)制實(shí)現(xiàn)本質(zhì)上就是利用 ping/pong 幀或者應(yīng)用層自定義文本幀來(lái)?；?。瀏覽器端的 WebSocket API 不暴露 ping/pong 的發(fā)送能力所以前端做心跳通常發(fā)自定義文本消息后端收到后回一個(gè) pong 語(yǔ)義的消息。這是 demo 里第一個(gè)容易踩的認(rèn)知差。2.2 選原生 WebSocket 還是帶兜底的庫(kù)做 websocket demo 時(shí)第一個(gè)選型問(wèn)題是用瀏覽器原生WebSocket還是用 Socket.IO、SockJS 這類(lèi)庫(kù)。原生 API 簡(jiǎn)單直接沒(méi)有額外依賴(lài)適合內(nèi)網(wǎng)工具、Electron 桌面端、以及后端可控的場(chǎng)景。帶兜底的庫(kù)會(huì)在 WebSocket 不可用時(shí)降級(jí)到長(zhǎng)輪詢(xún)并內(nèi)置重連、房間、事件名等抽象代價(jià)是協(xié)議變重、抓包不直觀、前后端必須配套。我的判斷標(biāo)準(zhǔn)是如果客戶(hù)端環(huán)境可控自家 App、內(nèi)部系統(tǒng)、桌面應(yīng)用直接用原生如果要覆蓋各種老舊瀏覽器和不可控網(wǎng)絡(luò)再考慮庫(kù)。demo 階段建議先用原生把鏈路跑通把握手、幀、心跳這些底層行為看清楚再?zèng)Q定要不要上抽象層。下面這份最小實(shí)現(xiàn)就是原生路線(xiàn)。2.3 最小可運(yùn)行 demo 的前后端代碼后端用 Python 的websockets庫(kù)它基于 asyncio代碼短、依賴(lài)少適合驗(yàn)證。先裝依賴(lài)pip install websockets服務(wù)端代碼監(jiān)聽(tīng) 8765 端口收到消息后原樣回顯并額外推一條帶時(shí)間戳的消息import asyncio import websockets from datetime import datetime async def handler(websocket): # 連接建立后先推一條歡迎消息方便前端確認(rèn)鏈路通了 await websocket.send(fconnected at {datetime.now().isoformat()}) try: async for message in websocket: # 回顯收到的內(nèi)容并附帶服務(wù)端時(shí)間 reply fecho: {message} | server_time: {datetime.now().isoformat()} await websocket.send(reply) except websockets.ConnectionClosed: # 客戶(hù)端斷開(kāi)是正?，F(xiàn)象記錄即可不要拋異常刷屏 print(client disconnected) async def main(): async with websockets.serve(handler, 0.0.0.0, 8765): await asyncio.Future() # 永久運(yùn)行 if __name__ __main__: asyncio.run(main())前端一個(gè) HTML 文件即可打開(kāi)控制臺(tái)就能看到收發(fā)!DOCTYPE html html body script // 用 ws 協(xié)議注意不是 http const ws new WebSocket(ws://localhost:8765); ws.onopen () { console.log(連接已建立); ws.send(hello from browser); }; ws.onmessage (event) { // event.data 在文本幀下是字符串 console.log(收到:, event.data); }; ws.onclose (event) { // code 和 reason 是排查斷開(kāi)原因的第一手信息 console.log(連接關(guān)閉, event.code, event.reason); }; ws.onerror (err) { console.error(出錯(cuò), err); }; /script /body /html邏輯說(shuō)明服務(wù)端handler每接受一個(gè)連接就進(jìn)入獨(dú)立協(xié)程async for持續(xù)讀取幀前端onopen后主動(dòng)發(fā)一條觸發(fā)服務(wù)端回顯。參數(shù)上websockets.serve的第二個(gè)參數(shù)是端口0.0.0.0表示監(jiān)聽(tīng)所有網(wǎng)卡本地調(diào)試可換127.0.0.1更安全。前端 URL 的協(xié)議必須是ws://上 HTTPS 后要換成wss://否則瀏覽器會(huì)因混合內(nèi)容攔截。提示如果瀏覽器控制臺(tái)報(bào)WebSocket connection to ... failed先確認(rèn)服務(wù)端進(jìn)程在跑再用curl -i -N -H Connection: Upgrade -H Upgrade: websocket -H Sec-WebSocket-Key: test -H Sec-WebSocket-Version: 13 http://localhost:8765看握手返回是不是 101。3. 心跳機(jī)制實(shí)現(xiàn)讓連接活過(guò)空閑超時(shí)3.1 為什么必須做心跳以及 ping/pong 與應(yīng)用層心跳的區(qū)別TCP 連接本身有 keepalive但默認(rèn)間隔通常兩小時(shí)對(duì)實(shí)時(shí)應(yīng)用毫無(wú)意義。真正掐斷連接的是中間設(shè)備N(xiāo)ginx 的proxy_read_timeout默認(rèn) 60 秒、云負(fù)載均衡的空閑超時(shí)、運(yùn)營(yíng)商 NAT 表的過(guò)期時(shí)間。這些設(shè)備看到一條長(zhǎng)時(shí)間沒(méi)有數(shù)據(jù)流動(dòng)的連接會(huì)直接回收。心跳的作用就是定期制造數(shù)據(jù)流動(dòng)讓連接在中間設(shè)備眼里保持“活躍”。協(xié)議層有 ping/pong 幀服務(wù)端可以主動(dòng)發(fā) ping客戶(hù)端協(xié)議棧自動(dòng)回 pong。但瀏覽器不讓你手動(dòng)發(fā) ping所以前端側(cè)的心跳只能用應(yīng)用層文本幀模擬。常見(jiàn)做法是前端每 N 秒發(fā)一個(gè){type:ping}后端收到后回{type:pong}同時(shí)后端也維護(hù)一個(gè)定時(shí)器超過(guò) M 秒沒(méi)收到任何幀就主動(dòng)關(guān)閉連接釋放資源。兩個(gè)方向都要有只做一端等于沒(méi)做。3.2 前端心跳與超時(shí)判定的完整實(shí)現(xiàn)把前面的前端代碼升級(jí)加入心跳定時(shí)器和超時(shí)檢測(cè)const HEARTBEAT_INTERVAL 30000; // 30 秒發(fā)一次心跳 const HEARTBEAT_TIMEOUT 10000; // 發(fā)出后 10 秒沒(méi)響應(yīng)就判定斷線(xiàn) let ws; let heartbeatTimer; let pongTimer; function connect() { ws new WebSocket(ws://localhost:8765); ws.onopen () { console.log(連接已建立); startHeartbeat(); }; ws.onmessage (event) { const data JSON.parse(event.data); if (data.type pong) { // 收到 pong清掉超時(shí)定時(shí)器 clearTimeout(pongTimer); return; } console.log(業(yè)務(wù)消息:, data); }; ws.onclose () { stopHeartbeat(); // 簡(jiǎn)單重連生產(chǎn)環(huán)境應(yīng)加退避 setTimeout(connect, 3000); }; } function startHeartbeat() { stopHeartbeat(); heartbeatTimer setInterval(() { if (ws.readyState ! WebSocket.OPEN) return; ws.send(JSON.stringify({ type: ping })); // 發(fā)出心跳后啟動(dòng)超時(shí)計(jì)時(shí) pongTimer setTimeout(() { console.warn(心跳超時(shí)主動(dòng)關(guān)閉連接); ws.close(); }, HEARTBEAT_TIMEOUT); }, HEARTBEAT_INTERVAL); } function stopHeartbeat() { clearInterval(heartbeatTimer); clearTimeout(pongTimer); } connect();邏輯說(shuō)明HEARTBEAT_INTERVAL決定心跳頻率HEARTBEAT_TIMEOUT決定容忍度。發(fā)出 ping 后啟動(dòng)pongTimer收到 pong 就清掉如果超時(shí)未清說(shuō)明鏈路已經(jīng)不可用主動(dòng)close()觸發(fā)重連。參數(shù)怎么定移動(dòng)端網(wǎng)絡(luò)切換頻繁間隔可以放到 30 到 45 秒內(nèi)網(wǎng)工具可以縮到 15 秒。超時(shí)時(shí)間一般設(shè)成間隔的三分之一到一半太短會(huì)誤判太長(zhǎng)則斷線(xiàn)發(fā)現(xiàn)慢。3.3 服務(wù)端如何配合心跳并清理死連接服務(wù)端要能識(shí)別應(yīng)用層 ping并回 pong同時(shí)用一個(gè)獨(dú)立的超時(shí)機(jī)制踢掉不再發(fā)幀的連接import asyncio import json import websockets from datetime import datetime CLIENT_TIMEOUT 90 # 90 秒沒(méi)收到任何幀就斷開(kāi) async def handler(websocket): last_active datetime.now() async def watchdog(): # 獨(dú)立協(xié)程定期檢查最后活躍時(shí)間 while True: await asyncio.sleep(30) if (datetime.now() - last_active).total_seconds() CLIENT_TIMEOUT: await websocket.close(code1000, reasonidle timeout) return task asyncio.create_task(watchdog()) try: async for message in websocket: last_active datetime.now() data json.loads(message) if data.get(type) ping: await websocket.send(json.dumps({type: pong})) else: await websocket.send(json.dumps({type: echo, data: data})) except websockets.ConnectionClosed: pass finally: task.cancel()邏輯說(shuō)明watchdog協(xié)程每 30 秒檢查一次CLIENT_TIMEOUT設(shè)為 90 秒意味著客戶(hù)端連續(xù)三次心跳都沒(méi)到才判定死連接避免偶發(fā)丟包誤殺。last_active在每次收到幀時(shí)刷新ping 也算活躍。參數(shù)上CLIENT_TIMEOUT應(yīng)該大于前端心跳間隔的兩到三倍給網(wǎng)絡(luò)抖動(dòng)留余量。注意服務(wù)端close的 code 用 1000 表示正常關(guān)閉前端onclose里可以根據(jù) code 區(qū)分是主動(dòng)踢還是網(wǎng)絡(luò)斷決定要不要立即重連。4. 重連、消息可靠性與多端同步demo 走向可用的三個(gè)補(bǔ)丁4.1 指數(shù)退避重連別讓客戶(hù)端把服務(wù)端打崩前面用的固定 3 秒重連在服務(wù)端重啟或網(wǎng)絡(luò)大面積故障時(shí)會(huì)變成驚群所有客戶(hù)端同時(shí)重連把剛起來(lái)的服務(wù)端又打掛。正確做法是指數(shù)退避加隨機(jī)抖動(dòng)let retryDelay 1000; // 初始 1 秒 const MAX_DELAY 30000; function scheduleReconnect() { // 加 0 到 30% 的隨機(jī)抖動(dòng)避免同時(shí)重連 const jitter retryDelay * 0.3 * Math.random(); const delay Math.min(retryDelay jitter, MAX_DELAY); console.log(將在 ${Math.round(delay)}ms 后重連); setTimeout(connect, delay); retryDelay Math.min(retryDelay * 2, MAX_DELAY); } // 在 onopen 里重置retryDelay 1000;邏輯說(shuō)明每次重連失敗后延遲翻倍上限 30 秒并疊加隨機(jī)抖動(dòng)打散重連時(shí)刻。onopen成功時(shí)把retryDelay重置回 1 秒保證下次故障時(shí)還是從短延遲開(kāi)始。這套參數(shù)在幾百到幾千客戶(hù)端規(guī)模下都能扛住服務(wù)端滾動(dòng)重啟。4.2 消息序號(hào)與斷線(xiàn)補(bǔ)發(fā)解決重連后的順序錯(cuò)亂WebSocket 保證單條連接內(nèi)幀有序但重連會(huì)換一條新連接斷線(xiàn)期間的消息就丟了。如果業(yè)務(wù)不能接受丟消息需要在應(yīng)用層加序號(hào)和補(bǔ)發(fā)機(jī)制。常見(jiàn)做法是服務(wù)端給每條消息帶一個(gè)自增seq客戶(hù)端記錄收到的最大seq重連時(shí)在握手后的第一條消息里帶上last_seq服務(wù)端從last_seq 1開(kāi)始補(bǔ)發(fā)。// 客戶(hù)端重連成功后發(fā)送已收到的最大序號(hào) ws.onopen () { ws.send(JSON.stringify({ type: resume, last_seq: lastSeq })); startHeartbeat(); }; ws.onmessage (event) { const data JSON.parse(event.data); if (data.seq) { lastSeq Math.max(lastSeq, data.seq); } // ...業(yè)務(wù)處理 };服務(wù)端需要維護(hù)一個(gè)短期消息緩沖區(qū)按seq索引收到resume請(qǐng)求后把缺失部分推回去。緩沖區(qū)大小取決于業(yè)務(wù)能容忍多長(zhǎng)的斷線(xiàn)一般保留最近幾分鐘或幾千條。這個(gè)補(bǔ)丁是 demo 和可用系統(tǒng)之間的分水嶺做不做取決于業(yè)務(wù)對(duì)丟消息的敏感度。4.3 多端同步時(shí)的一個(gè)順序陷阱同一個(gè)用戶(hù)多設(shè)備在線(xiàn)時(shí)如果服務(wù)端對(duì)每個(gè)連接獨(dú)立分配seq客戶(hù)端拿到的序號(hào)會(huì)互相沖突補(bǔ)發(fā)邏輯直接失效。正確做法是按業(yè)務(wù)實(shí)體比如用戶(hù) ID 或房間 ID分配全局遞增序號(hào)所有連接共享同一個(gè)序列。這樣無(wú)論從哪臺(tái)設(shè)備重連last_seq都有統(tǒng)一含義。這個(gè)坑我在做多端消息同步時(shí)踩過(guò)表現(xiàn)是手機(jī)和電腦收到的消息順序?qū)Σ簧吓挪榱税胩觳虐l(fā)現(xiàn)是序號(hào)作用域搞錯(cuò)了。5. 避坑與排查websocket demo 上線(xiàn)前必須過(guò)的五道坎現(xiàn)象本地正常部署到 Nginx 后握手返回 400。原因Nginx 默認(rèn)不轉(zhuǎn)發(fā) Upgrade 頭把 WebSocket 握手當(dāng)普通 HTTP 請(qǐng)求處理了。 解決在 location 塊里加proxy_http_version 1.1;、proxy_set_header Upgrade $http_upgrade;、proxy_set_header Connection upgrade;并確認(rèn)proxy_read_timeout大于心跳間隔。現(xiàn)象連接每隔 60 秒準(zhǔn)時(shí)斷開(kāi)。原因幾乎可以斷定是中間設(shè)備的空閑超時(shí)Nginx 默認(rèn)proxy_read_timeout就是 60 秒。 解決把心跳間隔設(shè)成小于超時(shí)值比如 30 秒同時(shí)調(diào)大服務(wù)端和反代的讀超時(shí)。不要靠調(diào)大超時(shí)來(lái)替代心跳因?yàn)榭蛻?hù)端到服務(wù)端之間可能還有別的設(shè)備?，F(xiàn)象前端onmessage收到的數(shù)據(jù)是 Blob 而不是字符串。原因服務(wù)端發(fā)了二進(jìn)制幀或者前端沒(méi)設(shè)binaryType。 解決確認(rèn)服務(wù)端用文本幀發(fā)送如果確實(shí)要傳二進(jìn)制前端設(shè)ws.binaryType arraybuffer再用TextDecoder解碼。現(xiàn)象移動(dòng)端切到后臺(tái)幾分鐘后回來(lái)連接顯示 OPEN 但發(fā)消息沒(méi)反應(yīng)。原因系統(tǒng)掛起了后臺(tái)頁(yè)面的定時(shí)器心跳停了但readyState沒(méi)及時(shí)更新連接實(shí)際已被回收。 解決監(jiān)聽(tīng)visibilitychange頁(yè)面回到前臺(tái)時(shí)主動(dòng)發(fā)一次心跳探測(cè)超時(shí)就重建連接不要信任readyState。現(xiàn)象壓測(cè)時(shí)服務(wù)端文件描述符耗盡。原因每個(gè) WebSocket 連接占一個(gè) fd默認(rèn) ulimit 通常只有 1024。 解決調(diào)大ulimit -n并在服務(wù)端設(shè)置最大連接數(shù)上限和空閑連接回收避免死連接堆積。6. 用壓測(cè)和抓包驗(yàn)證你的 websocket demo 到底穩(wěn)不穩(wěn)demo 跑通只是起點(diǎn)能不能扛住真實(shí)流量得靠驗(yàn)證。我一般分兩步先用腳本壓連接數(shù)再用抓包看幀行為。壓測(cè)用 Python 的websockets庫(kù)并發(fā)建連觀察服務(wù)端內(nèi)存和 fd 增長(zhǎng)import asyncio import websockets async def one_client(idx): try: async with websockets.connect(ws://localhost:8765) as ws: await ws.send(fclient-{idx}) await ws.recv() await asyncio.sleep(60) # 保持連接一分鐘 except Exception as e: print(fclient {idx} error: {e}) async def main(): # 并發(fā) 500 個(gè)連接分批啟動(dòng)避免瞬時(shí)沖擊 tasks [] for i in range(500): tasks.append(asyncio.create_task(one_client(i))) if i % 50 0: await asyncio.sleep(0.5) await asyncio.gather(*tasks) asyncio.run(main())邏輯說(shuō)明分批啟動(dòng)是為了模擬真實(shí)客戶(hù)端陸續(xù)上線(xiàn)而不是瞬間沖擊。跑的時(shí)候用ss -s看連接數(shù)、ps看內(nèi)存重點(diǎn)觀察連接穩(wěn)定后內(nèi)存是否持續(xù)上漲——如果漲多半是連接對(duì)象沒(méi)被回收。參數(shù)上500 是起步量逐步加到目標(biāo)規(guī)模每次觀察服務(wù)端的 fd 和內(nèi)存曲線(xiàn)。抓包用瀏覽器開(kāi)發(fā)者工具的 Network 面板篩選 WS能看到每一幀的 opcode、長(zhǎng)度和時(shí)間戳。重點(diǎn)看三件事心跳幀是否按預(yù)期間隔出現(xiàn)、pong 是否及時(shí)返回、close 幀的 code 是什么。Chrome 的chrome://net-export還能導(dǎo)出更底層的連接事件排查 TLS 握手和連接復(fù)用問(wèn)題時(shí)很有用。一個(gè)我自己的習(xí)慣任何 WebSocket 服務(wù)上線(xiàn)前先讓它空跑 24 小時(shí)只掛心跳不帶業(yè)務(wù)第二天看連接數(shù)和內(nèi)存曲線(xiàn)是否平穩(wěn)。這個(gè)動(dòng)作幫我提前發(fā)現(xiàn)過(guò)好幾次定時(shí)器泄漏和 fd 未釋放的問(wèn)題。實(shí)時(shí)通信的坑大多不在功能而在時(shí)間維度上的穩(wěn)定性多等一天比上線(xiàn)后半夜被叫起來(lái)強(qiáng)。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取