本模組承接模組一的並發主題：read pump / write pump 對應 goroutine ownership，heartbeat 對應 select loop 與 ticker，send buffer 對應 backpressure，訂閱集合對應共享狀態與 copy boundary。

章節列表

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。Client 可以訂閱 topic，server 會依 topic 推送 notification、status update 或 error message。

範例只用來展示 Go WebSocket 服務設計，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

• 用一個 read pump 負責 client 輸入。
• 用一個 write pump 負責所有 WebSocket 寫入。
• 用 channel 作為 client send queue。
• 用 context、done channel 或 hub unregister 管理連線生命週期。
• 用 ticker 實作 heartbeat，但由 write pump 統一寫 ping。
• 用 mutex 或 hub event loop 保護訂閱狀態。
• 用 non-blocking send 保護 hub 不被慢 client 卡住。

學習重點

學完本模組後，你應該能判斷：

1. 哪個 goroutine 可以讀 WebSocket，哪個 goroutine 可以寫 WebSocket
2. read pump、write pump、hub unregister 之間如何協作
3. heartbeat 失敗後應該走哪一條清理路徑
4. client action 應該在 router、usecase 還是 hub 裡處理
5. send buffer 滿載時應該丟棄、斷線、回錯或改用可靠儲存

章節粒度說明

WebSocket 章節依照連線生命週期拆分。Read/write pump、heartbeat、subscription routing、slow client 是四個不同責任；它們常在同一個 hub 或 client type 中互相呼叫，但教學上應分開建立模型。

如果只想處理單一問題，可以這樣查：

本模組不處理

本模組不討論 WebSocket 壓縮、水平擴展、跨節點廣播或完整身份驗證。這些都是實務重要主題，但必須先建立單一 Go process 內的連線生命週期與容量邊界；後續可接 跨節點 WebSocket、presence 與重連協定。

先備知識

• 模組一：進階並發模式
• Go 入門：標準庫 HTTP
• 知道 goroutine、channel、select、context 的基本用法

學習時間

預計 3-4 小時

HTTP protocol test 的驗證對象

Request 格式

Client 端發送的 request 是否符合 API 規格。Content-Type header、JSON body 的欄位名稱和型別、query parameter 的格式 — 這些在 mock client 中通常不被驗證（mock 接受任何 request），但真實 API 可能因為格式不符而拒絕。

Response 解析

Client 端能否正確解析真實 API 的 response。Mock response 通常是開發者手寫的 JSON，可能和真實 API 的 response 有微妙差異 — 欄位名稱大小寫、數值型別（integer vs float）、null vs 缺失欄位、巢狀結構。

Error response 處理

真實 API 的 error response 格式可能和 success response 不同。Mock client 通常只模擬 success case，偶爾模擬簡化的 error case。真實 API 的 400/401/403/404/500 各自可能有不同的 error body 結構。

認證流程

API 的認證流程（API key、OAuth token、session cookie）在 mock 中通常被跳過。真實 API 的認證包括 token 取得、token 過期、refresh flow — 每一步都可能失敗。

Test 結構

HTTP protocol test 的結構和 WebSocket protocol test 類似 — 對真實 API 發送真實 request、驗證真實 response。

 1test('POST /api/resource creates resource'):
 2  response = await httpClient.post(
 3    'http://localhost:8080/api/resource',
 4    body: jsonEncode({'name': 'test', 'type': 'A'}),
 5    headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer ...'},
 6  )
 7  expect(response.statusCode, 201)
 8  body = jsonDecode(response.body)
 9  expect(body['id'], isNotNull)
10  expect(body['name'], 'test')
11
12test('POST /api/resource with invalid body returns 400'):
13  response = await httpClient.post(
14    'http://localhost:8080/api/resource',
15    body: jsonEncode({'invalid_field': 'value'}),
16    headers: {'Content-Type': 'application/json', 'Authorization': 'Bearer ...'},
17  )
18  expect(response.statusCode, 400)
19  body = jsonDecode(response.body)
20  expect(body['error'], isNotNull)  // 驗證 error body 結構

Consumer-driven contract test

當 client 和 server 由不同團隊開發時，consumer-driven contract test 是 protocol integration test 的延伸。Client 團隊定義「我期望的 request/response 格式」（contract），server 團隊驗證 server 實作是否符合 contract。

Consumer-driven contract test 的工具（Pact、Spring Cloud Contract）自動化了 contract 的定義、驗證和版本管理。適合 API 有多個 consumer 且需要獨立部署的場景。

自用工具或 client/server 同一人開發的場景不需要 contract test 工具 — 直接對真實 server 跑 protocol integration test 更簡單。

下一步路由

• CI 中如何管理 test 用的 server → CI 中的服務 fixture 管理
• WebSocket 的 protocol test → WebSocket 協議測試實作
• 什麼時候用 contract test 替代 protocol integration test → 成本判斷表
• Backend 的 contract testing 實務 → Backend 可靠性 contract testing