Networking on Tarragon

Bind Address

Tue, 12 May 2026 00:00:00 +0000

Bind address 的核心概念是「伺服器啟動時決定『監聽哪個網路介面上的請求』」。同一個 port 在不同 bind address 下、能接受的請求來源完全不同；對本地 LLM 推論伺服器（Ollama / llama-server / LM Studio）來說、bind address 是決定誰能連到模型的最直接設定。

概念位置

三層典型 bind address 的暴露範圍：

bind address	接受來源	個人 dev 場景的常見用途
`127.0.0.1` / `localhost`	只本機 process	VS Code 連本機 server、最安全預設
具體 LAN IP（如 `192.168.x.x`）	同網段設備	想分享給家裡桌機 / 筆電
`0.0.0.0`	所有網路介面	容器化 / 想接受 LAN + WAN（風險高）

關鍵差異：

127.0.0.1 只接 loopback、無論其他網路介面狀態都不接外部請求。
0.0.0.0 在所有介面上監聽、若機器有 public IP 或在公開 Wi-Fi、就會被網路上其他人連到。
具體 LAN IP 是中間地帶、限定來源到該介面的網段。

檢查當前 bind 狀態的指令：

1# macOS / Linux
2lsof -i -P -n | grep LISTEN | grep <port>
3
4# Linux
5ss -lntp | grep <port>
6
7# 或
8netstat -an | grep LISTEN | grep <port>

看到 127.0.0.1:<port> 是 loopback、*:<port> 或 0.0.0.0:<port> 是所有介面。

設計責任

理解 bind address 後可以解釋兩個現象：為什麼預設安全的伺服器都 bind 到 127.0.0.1（避免不小心暴露）、為什麼 Docker -p 8080:8080 預設 bind 到 0.0.0.0（容器化的便利性、但對個人 dev 是潛在暴露點）。

設計本地推論伺服器時、預設 loopback、想分享 LAN 時 bind 到具體 LAN IP（不要直接 0.0.0.0）、要對外時加 reverse proxy + auth + TLS。詳見 6.1 推論伺服器的綁定與暴露範圍跟 7.3 入口治理與伺服器防護。

2.1 read pump / write pump 模式

Wed, 22 Apr 2026 00:00:00 +0000

Read pump / write pump 的核心規則是單一 WebSocket 連線的讀取與寫入必須分成兩個協調的 goroutine。Read pump 擁有讀取權，write pump 擁有寫入權；其他元件不直接操作底層 connection，而是透過 channel 或 method 協作。

本章目標

學完本章後，你將能夠：

分辨 read pump、write pump、hub 的責任
避免多 goroutine 同時寫同一條 WebSocket connection
用 send channel 作為 server-to-client 推送邊界
設計 client unregister 與 close path
用 fake router 測試 read pump 的行為邊界

【觀察】WebSocket 是一條長生命週期雙向連線

WebSocket 連線的核心特徵是 client 和 server 都可能主動送訊息。Client 可能送 subscribe、unsubscribe、ping 或 command；server 可能推送 notification、status update 或 error。

若讀寫責任不分開，程式很容易出現這種結構：

 1func handleConnection(conn *websocket.Conn) {
 2    go func() {
 3        for msg := range serverMessages {
 4            conn.WriteJSON(msg)
 5        }
 6    }()
 7
 8    for {
 9        var msg ClientMessage
10        if err := conn.ReadJSON(&msg); err != nil {
11            return
12        }
13        if msg.Action == "subscribe" {
14            conn.WriteJSON(ServerMessage{Type: "subscribed"})
15        }
16    }
17}

這段程式的問題是多個路徑可能同時寫 connection：背景 goroutine 寫推送，read loop 裡也直接寫回應。多個 goroutine 同時寫 WebSocket 會讓錯誤、資料交錯與 close path 變得難以推理。

【判讀】read pump 和 write pump 是 ownership 邊界

Read pump / write pump 的核心價值是 ownership。Read pump 是唯一讀取者，write pump 是唯一寫入者，其他元件只能透過它們的公開邊界互動。

1type Client struct {
2    id   string
3    conn *websocket.Conn
4    send chan ServerMessage
5}

conn 是底層連線，send 是 server 要推給 client 的訊息佇列。其他元件不直接呼叫 conn.WriteJSON，而是把 ServerMessage 放進 send。

責任表：

元件	責任	不應做的事
read pump	讀 client message、交給 router	直接寫 WebSocket
write pump	寫 server message、送 heartbeat、送 close	處理 client action
hub	註冊、取消註冊、廣播	直接讀寫 connection
router	解析 action、呼叫 usecase 或更新訂閱	關閉底層 connection

這個分工讓連線生命週期可以被測試與替換，而不是散在多個 goroutine 裡。

【策略】Client 型別要表達連線邊界

Client 型別的核心責任是封裝單一連線的狀態與輸出佇列。它不應包含整個系統的業務狀態。

 1type Client struct {
 2    id   string
 3    conn *websocket.Conn
 4    send chan ServerMessage
 5
 6    mu            sync.RWMutex
 7    subscriptions map[string]struct{}
 8}
 9
10func NewClient(id string, conn *websocket.Conn, sendBuffer int) *Client {
11    return &Client{
12        id:            id,
13        conn:          conn,
14        send:          make(chan ServerMessage, sendBuffer),
15        subscriptions: make(map[string]struct{}),
16    }
17}

send 有固定容量，避免慢 client 無限制累積訊息。subscriptions 屬於這條連線的狀態，若會被多個 goroutine 讀寫，就需要 mutex 或集中到 hub event loop。

【執行】read pump 只處理 client 輸入

Read pump 的核心責任是從 connection 讀訊息、轉成 ClientMessage、交給 router。它不應直接操作所有業務規則。

 1type MessageRouter interface {
 2    Route(ctx context.Context, client *Client, message ClientMessage) error
 3}
 4
 5func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 6    defer func() {
 7        hub.unregister <- c
 8    }()
 9
10    for {
11        var message ClientMessage
12        if err := c.conn.ReadJSON(&message); err != nil {
13            return
14        }
15
16        if err := router.Route(ctx, c, message); err != nil {
17            c.TrySend(ServerMessage{
18                Type:  "error",
19                Error: err.Error(),
20            })
21        }
22    }
23}

Read pump 收到 read error 時退出，並通知 hub unregister。這裡不直接 close send，因為 send 的關閉責任交給 hub 統一處理。

【執行】write pump 是唯一寫入者

Write pump 的核心責任是把 send channel 裡的 server message 寫回 WebSocket。所有寫入都集中在這一個 goroutine，能避免 concurrent write。

 1func (c *Client) writePump() {
 2    for {
 3        message, ok := <-c.send
 4        if !ok {
 5            _ = c.conn.WriteMessage(websocket.CloseMessage, []byte{})
 6            return
 7        }
 8
 9        if err := c.conn.WriteJSON(message); err != nil {
10            return
11        }
12    }
13}

當 send 被關閉時，write pump 送出 close message 並退出。這表示 hub 或 connection manager 是 send 的 owner，write pump 是 receiver。

下一章會把 heartbeat ticker 加進 write pump。原則不變：ping 也是寫入，所以也要由 write pump 統一執行。

【策略】send channel 是推送邊界

send channel 的核心意義是把內部事件轉成 client 輸出佇列。其他元件可以嘗試送訊息，但不能直接寫 connection。

1func (c *Client) TrySend(message ServerMessage) bool {
2    select {
3    case c.send <- message:
4        return true
5    default:
6        return false
7    }
8}

TrySend 使用 non-blocking send，表示 client buffer 滿時不阻塞呼叫端。Hub 可以根據 false 決定丟棄訊息、取消註冊 client 或記錄 metric。

這個方法把 WebSocket 寫入問題轉成前一模組的 backpressure 問題：滿載時要有明確策略。

【執行】hub 統一管理 unregister

Unregister 的核心目標是讓清理流程只有一個責任中心。Read pump、write pump、heartbeat 都可能發現連線失效，但不要讓每個地方各自 close channel 和 connection。

 1type Hub struct {
 2    clients    map[*Client]struct{}
 3    register   chan *Client
 4    unregister chan *Client
 5    broadcast  chan ServerMessage
 6}
 7
 8func (h *Hub) run() {
 9    for {
10        select {
11        case client := <-h.register:
12            h.clients[client] = struct{}{}
13
14        case client := <-h.unregister:
15            if _, ok := h.clients[client]; ok {
16                delete(h.clients, client)
17                close(client.send)
18                _ = client.conn.Close()
19            }
20        }
21    }
22}

這個設計讓 client.send 只會在 hub 中被 close。其他 goroutine 只送 unregister 訊號，不直接關閉資源。

實務上要避免重複 unregister 造成 channel 重複 close。上例透過 clients map 判斷 client 是否仍註冊，讓 unregister 具備 idempotent 行為。

【判讀】read pump 結束不代表 write pump 立刻結束

Read pump 與 write pump 的核心關係是協作，不是互相任意關閉。Read pump 發現錯誤後通知 hub；hub 關閉 send；write pump 收到 send 關閉後送 close message 並退出。

流程：

 1read error
 2   │
 3   ▼
 4hub.unregister <- client
 5   │
 6   ▼
 7hub closes client.send and conn
 8   │
 9   ▼
10write pump exits

這條路徑讓 close ownership 清楚。若 read pump 同時 close send，hub 也 close send，就會有 double close panic。

【測試】router 可以用 fake 驗證 read pump 邊界

Read pump 測試的核心目標是確認 client message 會交給 router，而不是在 read pump 裡塞入業務邏輯。完整 WebSocket integration test 可以留到測試模組；這裡先用 router 的小介面讓行為可替換。

1type fakeRouter struct {
2    messages []ClientMessage
3}
4
5func (r *fakeRouter) Route(ctx context.Context, client *Client, message ClientMessage) error {
6    r.messages = append(r.messages, message)
7    return nil
8}

若測試需要真實 connection，可用 httptest.Server 建立 WebSocket。若只測 router 規則，應直接測 router，不必繞過 network。

Write pump 的測試通常放在 integration test，因為它依賴真實 connection 寫入行為。單元測試則可以集中在 TrySend、router、hub unregister 這些純邊界。

本章不處理

本章先處理單一連線的 read/write ownership；跨節點 hub 與 broker 互動，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 goroutine ownership、channel 與 backpressure；如果你要先回看語言教材，可以讀：

小結

Read pump / write pump 模式把一條 WebSocket 連線拆成清楚的 ownership：read pump 讀 client message，write pump 寫 server message，hub 統一註冊與清理。send channel 是推送邊界，所有 close path 應收斂到同一個 unregister 流程。這樣長連線才不會因為 concurrent write、double close 或慢 client 而失控。

6.1 如何新增一個即時訊息 action

Wed, 22 Apr 2026 00:00:00 +0000

新增即時訊息 action 的核心流程是先定義 client 意圖，再把 action 轉成 application command。WebSocket handler 負責傳輸邊界，domain state 的修改交給 usecase 或 processor。本章用一個簡化的 topic subscription action 示範完整路徑。

本章目標

學完本章後，你將能夠：

用 action type 表達 client intent
用 request struct 定義 JSON payload 邊界
把 WebSocket message 轉成 application command
設計穩定的 response 與 error 格式
把 router、usecase 與 WebSocket integration test 分層測試

【觀察】action 表達 client intent

action 的核心語意是 client 想要系統做什麼。它是 client 和 server 之間的訊息合約，命名應描述行為意圖，而不是 UI 按鈕或 handler 函式名稱。

例如即時通知服務可能有三種 action：

action	client 意圖
`subscribe_topic`	訂閱某個 topic 的即時通知
`unsubscribe_topic`	取消某個 topic 的訂閱
`get_snapshot`	取得目前狀態快照

用字串常數定義 action，可以避免 handler 到處散落 magic string：

1const (
2    ActionSubscribeTopic   = "subscribe_topic"
3    ActionUnsubscribeTopic = "unsubscribe_topic"
4    ActionGetSnapshot      = "get_snapshot"
5)

action 名稱應該描述行為意圖。subscribe_topic 比 ws_subscribe 更穩定，因為未來同一個 usecase 也可能被 HTTP endpoint 或 background job 呼叫。

【判讀】外部訊息先進入 envelope

WebSocket message 的核心邊界是 envelope。client 傳來的 JSON 應該先被解析成一個共同外殼，再根據 action 解析 payload。

1type ClientMessage struct {
2    ID      string          `json:"id"`
3    Action  string          `json:"action"`
4    Payload json.RawMessage `json:"payload"`
5}

ID 是 client message ID，可用來讓 response 對應原始 request。Action 決定路由方向。Payload 使用 json.RawMessage，讓 router 可以先看 action，再把 payload 解成對應 struct。

例如 client 可以送出：

1{
2  "id": "msg_1001",
3  "action": "subscribe_topic",
4  "payload": {
5    "topic": "deployments",
6    "includeHistory": true
7  }
8}

這種 envelope 設計讓新 action 可以共用同一套外層格式。新增 action 時，不需要改整個 WebSocket 讀取流程，只要新增 payload struct 與路由分支。

【策略】payload struct 要表達資料語意

payload struct 的核心責任是把外部 JSON 轉成明確的 Go 型別。必填欄位、可選欄位與相容性都應該在 struct 與驗證函式中清楚表達。

1type SubscribeTopicRequest struct {
2    Topic          string `json:"topic"`
3    IncludeHistory bool   `json:"includeHistory,omitempty"`
4}

Topic 是必填欄位，因為沒有 topic 就無法訂閱。IncludeHistory 是可選欄位，零值 false 可以代表「不要求歷史資料」。這裡使用 omitempty 是在表達：輸出 response 或轉送資料時，這個欄位可以省略；它不是必填資料。

驗證規則應該靠明確函式完成，讓 router 分支只負責呼叫驗證與轉換：

1func (r SubscribeTopicRequest) Validate() error {
2    if strings.TrimSpace(r.Topic) == "" {
3        return fmt.Errorf("topic is required")
4    }
5    return nil
6}

外部資料進入系統後，要先完成解碼與驗證，才轉成 application command。這可以避免 usecase 同時處理 JSON 格式、欄位缺漏與業務規則。

【執行】router 只做解析、驗證與轉換

message router 的核心責任是把 client message 轉成 application command。router 只處理傳輸邊界，狀態修改與訂閱規則交給 usecase。

先定義 usecase 需要的 command：

1type SubscribeTopicCommand struct {
2    ClientID       string
3    Topic          string
4    IncludeHistory bool
5}

command 是 application layer 的輸入模型，只描述 usecase 需要的資料。它不需要 JSON tag，因為外部傳輸格式已經停在 request struct。

接著定義 usecase 介面：

1type SubscriptionUsecase interface {
2    SubscribeTopic(ctx context.Context, cmd SubscribeTopicCommand) error
3}

這個介面小而明確，只描述 router 目前需要的能力。不要一開始就建立大型 Service 介面，把所有 action 都塞進去。

router 可以這樣組裝：

1type MessageRouter struct {
2    subscriptions SubscriptionUsecase
3}
4
5func NewMessageRouter(subscriptions SubscriptionUsecase) *MessageRouter {
6    return &MessageRouter{subscriptions: subscriptions}
7}

處理入口接收原始 JSON bytes，回傳可序列化的 response：

 1func (r *MessageRouter) Handle(ctx context.Context, clientID string, data []byte) ServerMessage {
 2    var msg ClientMessage
 3    if err := json.Unmarshal(data, &msg); err != nil {
 4        return ErrorMessage("", "invalid_json", "message must be valid JSON")
 5    }
 6
 7    switch msg.Action {
 8    case ActionSubscribeTopic:
 9        return r.handleSubscribeTopic(ctx, clientID, msg)
10    default:
11        return ErrorMessage(msg.ID, "unknown_action", "action is not supported")
12    }
13}

Handle 不知道 WebSocket connection 怎麼讀寫，也不處理網路錯誤。這讓 router 可以被普通單元測試覆蓋。

subscribe_topic 的分支負責 payload 解碼、驗證與 command 建立：

 1func (r *MessageRouter) handleSubscribeTopic(ctx context.Context, clientID string, msg ClientMessage) ServerMessage {
 2    var req SubscribeTopicRequest
 3    if err := json.Unmarshal(msg.Payload, &req); err != nil {
 4        return ErrorMessage(msg.ID, "invalid_payload", "payload must match subscribe_topic schema")
 5    }
 6
 7    if err := req.Validate(); err != nil {
 8        return ErrorMessage(msg.ID, "invalid_payload", err.Error())
 9    }
10
11    cmd := SubscribeTopicCommand{
12        ClientID:       clientID,
13        Topic:          req.Topic,
14        IncludeHistory: req.IncludeHistory,
15    }
16
17    if err := r.subscriptions.SubscribeTopic(ctx, cmd); err != nil {
18        return ErrorMessage(msg.ID, "subscribe_failed", "topic subscription failed")
19    }
20
21    return OKMessage(msg.ID, map[string]string{
22        "topic": req.Topic,
23    })
24}

這段程式保留了清楚的轉換路徑：JSON message -> request struct -> command -> usecase。每一層只處理自己的責任。

【判讀】response 也需要穩定格式

response 格式的核心目標是讓 client 能穩定判斷一個 action 的結果。成功、輸入錯誤與不支援 action 都應該使用同一個外層格式。

1type ServerMessage struct {
2    ReplyTo string `json:"replyTo,omitempty"`
3    OK      bool   `json:"ok"`
4    Code    string `json:"code,omitempty"`
5    Message string `json:"message,omitempty"`
6    Data    any    `json:"data,omitempty"`
7}

成功 response 可以用 helper 建立：

1func OKMessage(replyTo string, data any) ServerMessage {
2    return ServerMessage{
3        ReplyTo: replyTo,
4        OK:      true,
5        Data:    data,
6    }
7}

錯誤 response 也應該用 helper 建立：

1func ErrorMessage(replyTo string, code string, message string) ServerMessage {
2    return ServerMessage{
3        ReplyTo: replyTo,
4        OK:      false,
5        Code:    code,
6        Message: message,
7    }
8}

WebSocket action 失敗不一定要關閉連線。JSON 格式錯誤、未知 action 或 payload 驗證失敗，通常可以回一筆 error message，讓 client 修正下一次請求；只有協定嚴重錯誤、授權失效或連線狀態不可恢復時，才考慮關閉連線。

【策略】WebSocket handler 聚焦 connection I/O

WebSocket handler 的核心責任是 connection I/O。它可以讀 message、呼叫 router、寫 response；每種 action 的業務規則交給 router 後方的 usecase。

簡化後的連線處理可以像這樣：

 1func handleClientMessage(ctx context.Context, router *MessageRouter, clientID string, data []byte) []byte {
 2    resp := router.Handle(ctx, clientID, data)
 3
 4    encoded, err := json.Marshal(resp)
 5    if err != nil {
 6        fallback := ErrorMessage("", "encode_failed", "response could not be encoded")
 7        encoded, _ = json.Marshal(fallback)
 8    }
 9
10    return encoded
11}

真實 WebSocket server 會有 read loop、write loop、heartbeat 與 slow client 處理。這些都屬於連線生命週期，應和 action routing 分開維護。

【執行】router 測試先覆蓋協定行為

router 測試的核心目標是確認 message 進入後會產生正確 command 與 response。這類測試不需要啟動真實 WebSocket server。

先建立 fake usecase：

 1type fakeSubscriptionUsecase struct {
 2    got SubscribeTopicCommand
 3    err error
 4}
 5
 6func (f *fakeSubscriptionUsecase) SubscribeTopic(ctx context.Context, cmd SubscribeTopicCommand) error {
 7    if f.err != nil {
 8        return f.err
 9    }
10    f.got = cmd
11    return nil
12}

成功案例測試可以檢查 command 是否正確：

 1func TestMessageRouterSubscribeTopic(t *testing.T) {
 2    fake := &fakeSubscriptionUsecase{}
 3    router := NewMessageRouter(fake)
 4
 5    data := []byte(`{
 6        "id": "msg_1",
 7        "action": "subscribe_topic",
 8        "payload": {
 9            "topic": "deployments",
10            "includeHistory": true
11        }
12    }`)
13
14    resp := router.Handle(context.Background(), "client_1", data)
15
16    if !resp.OK {
17        t.Fatalf("response OK = false, want true")
18    }
19    if fake.got.ClientID != "client_1" {
20        t.Fatalf("client ID = %q, want %q", fake.got.ClientID, "client_1")
21    }
22    if fake.got.Topic != "deployments" {
23        t.Fatalf("topic = %q, want %q", fake.got.Topic, "deployments")
24    }
25    if !fake.got.IncludeHistory {
26        t.Fatalf("include history = false, want true")
27    }
28}

輸入錯誤案例應該測 response code。錯誤文案可以調整，code 才是較穩定的協定欄位：

 1func TestMessageRouterUnknownAction(t *testing.T) {
 2    router := NewMessageRouter(&fakeSubscriptionUsecase{})
 3
 4    resp := router.Handle(context.Background(), "client_1", []byte(`{
 5        "id": "msg_1",
 6        "action": "missing_action",
 7        "payload": {}
 8    }`))
 9
10    if resp.OK {
11        t.Fatalf("response OK = true, want false")
12    }
13    if resp.Code != "unknown_action" {
14        t.Fatalf("code = %q, want %q", resp.Code, "unknown_action")
15    }
16}

這些測試保護的是 action 協定。未來 WebSocket library、connection manager 或 repository 改變時，router 行為仍然能被快速驗證。

【判讀】usecase 測試要離開傳輸格式

usecase 測試的核心目標是驗證行為規則，而不是 JSON 格式。當 router 已經把 message 轉成 command，usecase 測試就應該直接餵 command。

 1func TestSubscriptionServiceSubscribeTopic(t *testing.T) {
 2    repo := NewInMemorySubscriptionRepository()
 3    service := NewSubscriptionService(repo)
 4
 5    cmd := SubscribeTopicCommand{
 6        ClientID:       "client_1",
 7        Topic:          "deployments",
 8        IncludeHistory: true,
 9    }
10
11    if err := service.SubscribeTopic(context.Background(), cmd); err != nil {
12        t.Fatalf("subscribe topic: %v", err)
13    }
14
15    if !repo.IsSubscribed("client_1", "deployments") {
16        t.Fatalf("client should be subscribed")
17    }
18}

這裡不需要出現 JSON、WebSocket 或 ClientMessage。usecase 只關心訂閱規則與 repository 狀態。

實作檢查清單

新增 action 時，可以依序檢查：

action 名稱是否描述 client intent
是否有獨立 request struct
必填欄位是否有驗證
router 是否只做解析、驗證與 command 轉換
usecase 是否不依賴 WebSocket 型別
response 是否有穩定 ok、code、message 格式
錯誤 action 是否回 error message，而不是直接關閉連線
router 測試是否覆蓋成功、未知 action、invalid JSON、invalid payload
usecase 測試是否直接使用 command

設計檢查

檢查一：handler 只處理傳輸邊界

handler 只處理讀寫、編碼與連線狀態，可以讓 HTTP API、CLI 或背景工作共用同一個 usecase。handler 直接改 map、slice 或 repository 時，傳輸協定和業務規則會綁在一起。

檢查二：payload 轉成明確 command

map[string]any 適合短暫承接未知 JSON，不適合傳進 usecase。usecase 應該接收明確 command，讓欄位、型別與驗證規則可讀可測。

檢查三：action 失敗和連線失敗分開處理

單一 action payload 錯誤不代表 WebSocket 連線壞掉。多數 client input error 應該用 error response 表達，避免 client 因小錯誤被斷線。

檢查四：router interface 跟著 usecase 成長

router 依賴的 interface 應該由當下需要的 usecase 定義。過早建立大型 service interface，會讓每個測試都被迫實作不相關方法。

本章不處理

本章先處理單一 server 內的 action routing 與 response contract；完整 WebSocket lifecycle 與跨節點推送，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 action、command 與 handler 邊界；如果你要先回看語言教材，可以讀：

2.2 heartbeat、deadline 與連線清理

Wed, 22 Apr 2026 00:00:00 +0000

Heartbeat 的核心目標是讓失效的長連線可以被發現並清理。Deadline 定義讀寫最多能停滯多久，ping/pong 在沒有業務訊息時確認連線仍然活著，unregister 流程負責釋放連線與訂閱狀態。

本章目標

學完本章後，你將能夠：

分辨 read deadline、write deadline、ping period、pong wait 的角色
在 read pump 設定 pong handler 與 read limit
在 write pump 用 ticker 統一送 ping
讓 heartbeat 失敗進入同一條 unregister 路徑
測試 timeout 設定與清理流程的邊界

【觀察】長連線可能在沒有錯誤訊息時失效

WebSocket 長連線的核心風險是失效不一定立刻表現成明確錯誤。Client 可能斷網、瀏覽器休眠、代理中斷、行動網路切換，server 的 read 或 write 可能長時間卡住。

沒有 heartbeat 的服務可能出現：

client 已離線，但 server 還保留 client。
訂閱狀態沒有清理，broadcast 仍嘗試推送。
write pump 卡在慢或失效的 connection。
goroutine、send buffer、記憶體逐步累積。

Heartbeat 的目的是讓失敗可以在合理時間內被觀測並進入清理流程。

【判讀】四個時間參數負責不同邊界

Heartbeat 設計的核心是四個時間參數的關係。這些參數是讀寫生命週期的合約。

1const (
2    writeWait  = 10 * time.Second
3    pongWait   = 60 * time.Second
4    pingPeriod = 50 * time.Second
5    maxMessage = 1 << 20
6)

參數	角色	常見關係
`writeWait`	單次寫入最多等待多久	小於 `pongWait`
`pongWait`	多久沒讀到資料就視為失效	大於 `pingPeriod`
`pingPeriod`	多久主動送一次 ping	小於 `pongWait`
`maxMessage`	單筆 client message 大小上限	依協定需求設定

pingPeriod 應小於 pongWait，讓 server 有時間送 ping 並等待 client 回 pong。writeWait 保護每次寫入，避免 write pump 無限卡住。

【執行】read pump 設定 read deadline 與 pong handler

Read deadline 的核心語意是超過指定時間沒有讀取進展，下一次 read 會失敗。Pong handler 的核心責任是每次收到 pong 時延長 read deadline。

1func (c *Client) configureRead() {
2    c.conn.SetReadLimit(maxMessage)
3    _ = c.conn.SetReadDeadline(time.Now().Add(pongWait))
4    c.conn.SetPongHandler(func(string) error {
5        return c.conn.SetReadDeadline(time.Now().Add(pongWait))
6    })
7}

Read pump 啟動時先設定：

 1func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 2    defer func() {
 3        hub.unregister <- c
 4    }()
 5
 6    c.configureRead()
 7
 8    for {
 9        var message ClientMessage
10        if err := c.conn.ReadJSON(&message); err != nil {
11            return
12        }
13        if err := router.Route(ctx, c, message); err != nil {
14            c.TrySend(errorMessage(err))
15        }
16    }
17}

ReadJSON 回錯時，read pump 不需要判斷每一種錯誤都如何清理；它只要退出並通知 hub。錯誤分類可以用於 log，但清理路徑應一致。

【執行】write pump 用 ticker 送 ping

Ping 的核心規則是由 write pump 送出，因為 ping 也是 WebSocket write。讓其他 goroutine 直接送 ping 會破壞「write pump 是唯一寫入者」的原則。

 1func (c *Client) writePump() {
 2    ticker := time.NewTicker(pingPeriod)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case message, ok := <-c.send:
 8            _ = c.conn.SetWriteDeadline(time.Now().Add(writeWait))
 9            if !ok {
10                _ = c.conn.WriteMessage(websocket.CloseMessage, []byte{})
11                return
12            }
13            if err := c.conn.WriteJSON(message); err != nil {
14                return
15            }
16
17        case <-ticker.C:
18            _ = c.conn.SetWriteDeadline(time.Now().Add(writeWait))
19            if err := c.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
20                return
21            }
22        }
23    }
24}

每次寫入前設定 write deadline。這包含正常訊息、ping、close message；只保護部分寫入會留下卡住路徑。

【判讀】heartbeat 失敗走共用清理流程

Heartbeat 失敗的核心語意是連線不可用。它應該進入和 read error、write error、client disconnect 相同的 unregister 流程，而不是在 ping 錯誤處重寫一套清理。

推薦流程：

 1read error / write error / ping error
 2          │
 3          ▼
 4read pump exits or write pump exits
 5          │
 6          ▼
 7hub unregisters client
 8          │
 9          ▼
10close send, close conn, remove subscriptions

實作可以用 hub unregister channel、context cancellation 或 connection manager。重點是所有失效都收斂到同一個 owner。

【策略】read pump 和 write pump 都可能先失敗

連線失效的核心不確定性是 read pump 和 write pump 哪個先看到錯誤不可預測。讀不到 pong 可能讓 read pump 先退出；寫 ping 失敗可能讓 write pump 先退出。

因此 unregister 必須可重複呼叫而不出錯：

1func (h *Hub) unregisterClient(client *Client) {
2    if _, ok := h.clients[client]; !ok {
3        return
4    }
5
6    delete(h.clients, client)
7    close(client.send)
8    _ = client.conn.Close()
9}

用 clients map 判斷 client 是否仍註冊，可以避免重複 close send。這是 WebSocket cleanup 最容易漏掉的細節之一。

【策略】heartbeat 參數要符合部署環境

Heartbeat 參數的核心取捨是偵測速度與誤判風險。偵測太快會讓短暫網路抖動造成大量斷線；偵測太慢會讓失效連線保留太久。

調整時要考慮：

load balancer 或 proxy idle timeout
行動網路與瀏覽器背景分頁行為
server 可接受的失效連線保留時間
ping 對大量連線造成的週期性流量
client 是否會自動重連

若基礎設施會在 60 秒 idle 後關閉連線，server 的 ping period 就不能長於這個時間。這是部署環境合約，不是單純 Go 程式碼問題。

【測試】把時間參數和清理邊界拆開測

Heartbeat 的測試核心是不要用真實分鐘級等待。時間參數可以測設定值關係，清理流程可以測 unregister 是否 idempotent。

1func TestHeartbeatDurations(t *testing.T) {
2    if pingPeriod >= pongWait {
3        t.Fatalf("pingPeriod must be smaller than pongWait")
4    }
5    if writeWait >= pongWait {
6        t.Fatalf("writeWait should be smaller than pongWait")
7    }
8}

Unregister 測試：

 1func TestUnregisterClientIsIdempotent(t *testing.T) {
 2    hub := NewHub()
 3    client := NewClient("c1", nil, 1)
 4    hub.clients[client] = struct{}{}
 5
 6    hub.unregisterClient(client)
 7    hub.unregisterClient(client)
 8
 9    if _, ok := hub.clients[client]; ok {
10        t.Fatalf("client should be removed")
11    }
12}

真實 ping/pong 行為適合放在 integration test。單元測試先保證時間合約與 cleanup owner 不會被破壞。

本章不處理

本章先處理單一 WebSocket 連線的存活偵測與 cleanup；client 重連與 load balancer 參數，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 read/write pump、time control 與 shutdown；如果你要先回看語言教材，可以讀：

小結

Heartbeat/deadline 的目的是讓失效連線在可預期時間內被發現並清理。Read deadline 搭配 pong handler 保護讀取端，write deadline 保護每次寫入，ping ticker 由 write pump 統一執行，所有錯誤最後都應進入同一個 unregister 流程。

模組二：WebSocket 服務架構

Wed, 22 Apr 2026 00:00:00 +0000

WebSocket 服務的核心難點是連線建立後的長生命週期管理。HTTP upgrade 只是入口；每個 client 都有讀取、寫入、心跳、訂閱、推送佇列與清理流程。任何一個邊界不清楚，都可能造成 goroutine leak、concurrent write、慢 client 拖垮服務或訂閱狀態不一致。

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

章節列表

章節	主題	關鍵收穫
2.1	read pump / write pump 模式	讓單一連線的讀取、寫入與清理責任可推理
2.2	heartbeat、deadline 與連線清理	用 ping/pong、deadline 與統一 unregister 偵測失效連線
2.3	訂閱模型與訊息路由	把 client action 轉成可測的 command 與訂閱狀態
2.4	慢客戶端與 send buffer 管理	用 bounded buffer、drop policy 與 byte budget 控制容量風險

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。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 卡住。

學習重點

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

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

章節粒度說明

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

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

問題	優先閱讀
concurrent write 或讀寫責任混亂	read pump / write pump 模式
連線失效沒有被清理	heartbeat、deadline 與連線清理
action、payload、訂閱狀態混在一起	訂閱模型與訊息路由
慢 client 拖垮 hub	慢客戶端與 send buffer 管理

本模組不處理

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

先備知識

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

學習時間

預計 3-4 小時

機器連不到或起不來

Thu, 02 Jul 2026 00:00:00 +0000

一台原本能連的機器突然連不上，或一台虛擬機根本開不起來，判讀的方向是「從你這端往那台機器，一層一層確認哪裡斷了」，而不是反覆重試同一個連線動作。連線失敗是最終症狀，真正斷掉的可能是網路、可能是那台機器的某個服務沒起來、可能是虛擬機的宿主側出問題、也可能是一個把上面全部拖下水的共同根因：磁碟滿。這篇從網路層與宿主側的權威狀態切入，把「連不上」拆成可定位的環節。

遠端機器突然連不上：先分清是哪一段斷

一台昨天還能 SSH 的機器今天連不上，第一步是確認「網路層通不通」，跟「SSH 服務在不在」分開。連線在 TCP 就 timeout（連 port 22 卡住沒回應），多半是網路層或機器沒在跑；連線有回應但被拒（Connection refused），是網路通、但那台機器上沒有服務在聽 port 22。

對虛擬機或同網段的機器，一個很有用的權威來源是鄰居表（IP 對 MAC 的對應）。要填起來需要對方在鏈路層有回應，所以它直接反映「對方在不在」。用 ip neigh 看目標 IP 的條目——優先用 ip neigh 而不是 arp -a，因為 ip（iproute2）在現代最小系統一定有，arp（net-tools）常常沒裝、跑了會 command not found 反而誤導。如果狀態是 INCOMPLETE（arp -a 顯示的是 incomplete），代表這個 IP 在鏈路層上根本沒有機器回應——不是 SSH 的問題，是那台機器的網路沒起來、或根本沒在跑。一個實際案例：一台虛擬機 SSH timeout，鄰居表顯示整個網段的 guest 位址全是 incomplete、只有閘道（宿主那側的橋接介面）是好的——這就定位到「宿主的橋沒問題，但橋的另一頭沒有 VM 在講話」，方向立刻從「調 SSH」轉到「去看 VM 的網路或開機狀態」。

定位到「機器在跑但網路沒起來」後，去那台機器的主控台（不是 SSH，SSH 正是連不上的東西）確認：ip -brief a 看有沒有拿到 IP、systemctl status <網路服務>（dhcpcd / systemd-networkd）看網路服務起了沒，需要時 sudo systemctl restart <網路服務> 重拉。IP 回來、鄰居表的條目從 incomplete 變成有 MAC，就通了。

還有一個常見誤區是 IP 變了。SSH 的別名、金鑰、known_hosts 都綁在特定機器身分上；換機器 / 重裝 / DHCP 重配後 IP 或 host key 變了，用舊別名會連錯或被 host key 檢查擋。這條的判讀與修法（ssh user@新IP 直連、ssh-keygen -R）見外部連入與無 key 的 bootstrap 路徑。

網路通、但域名解析不了

有一種故障看起來像「網路壞了」，其實是 DNS 解析斷了：能連 IP、卻連不上任何用域名的東西——ping 8.8.8.8 通、但 ping google.com、pacman -Sy、curl https://... 全失敗。判讀要跟前面「網路沒起來」分開，因為網路層是通的，斷的是「域名 → IP」這一步。權威檢查：ping 通而 ping <域名> 不通、或 getent hosts <域名>（resolvectl query <域名> 若有 systemd-resolved）解不出位址，就定位到 DNS。常見成因是 /etc/resolv.conf 沒有可用的 nameserver（新裝或網路重設後沒填），或負責 DNS 的服務沒起來。修：確認 /etc/resolv.conf 有一行 nameserver（如 nameserver 1.1.1.1）、systemctl status systemd-resolved（若用它）。這一層在剛裝好的最小系統特別常撞到——ip -brief a 明明有 IP，pacman 或 bootstrap 卻抓不到套件，看起來像「網路好好的卻裝不了東西」，根因是 DNS 沒設。

虛擬機開不起來：分清 guest 內部還是宿主側

虛擬機開機失敗時，關鍵判斷是「錯誤來自 guest 內部（作業系統層）還是宿主側（虛擬化軟體 / QEMU 層）」。宿主側的錯誤訊息通常來自虛擬機軟體本身、在 guest 還沒開始開機前就跳出來，跟 guest 裡裝了什麼無關。

一個實例是 QEMU 報「找不到某個 ROM 檔」（例如 efi-virtio.rom）而拒絕啟動。第一反應可能是「檔案不見了要重裝」，但正確的第一步是去確認那個檔在不在——實際去虛擬機軟體的安裝目錄裡找（find <安裝目錄> -name ''），會發現 ROM 檔明明就在。既然檔案在，「找不到」就不是缺檔，是 QEMU 執行時在它預期的路徑下找不到——成因隨宿主 OS 不同。在 macOS + UTM 宿主上，最常見的是 Gatekeeper app translocation：帶隔離屬性的 app 被搬到一個隨機唯讀路徑跑，讓 QEMU 解析資源的相對路徑失效，明明存在的檔案在那個執行路徑下就找不到。在 Linux 宿主上（沒有 translocation 這回事），同樣的「找不到 ROM」通常是缺對應套件（ovmf / ipxe-roms / edk2-ovmf）、libvirt XML 指的 ROM 路徑錯、或檔案權限不對——一樣先確認檔在哪、QEMU 是用哪個路徑去找。

另外兩個常見的「VM 起不來」故障也順手一起排除，它們不會特定產生「找不到 ROM」但常伴隨出現：上一次崩潰殘留的 helper 行程卡著（pgrep -af 'qemu|<虛擬機軟體名>' 找，沒清乾淨會佔住資源），以及宿主磁碟滿（df -h，啟動要寫暫存 / 狀態檔）。多數情況下，完全退出虛擬機軟體（連殘留 helper 一起清）+ 清出宿主磁碟空間 + 重新啟動，就恢復了。

判讀通則：虛擬機開不起來，先讀錯誤訊息判斷是 guest 還是宿主側；宿主側報「找不到某資源」而資源其實存在時，往「QEMU 是用哪個路徑找、那條路徑對不對」查（macOS 是 translocation、Linux 是缺套件 / 路徑 / 權限），再順手排除殘留行程與磁碟滿，而不是急著重裝。

磁碟滿是連鎖故障的共同根因

很多看起來各自獨立的故障，共同根因是磁碟滿。磁碟一滿，寫入就會失敗，而系統裡太多東西依賴寫入：SSH session 可能因為寫不了而被斷、正在跑的編譯 / 安裝會中途失敗、log 寫不進去、虛擬機狀態檔存不下導致連不上或開不起來。所以當你在短時間內撞到「連線斷了 + 某個任務失敗 + 服務怪怪的」這種一串症狀時，df -h 應該是很早就要做的檢查——一個廉價的檢查就可能一次解釋掉全部。

這裡有一個容易搞錯的點：清錯了地方。宿主跟 guest 是兩個獨立的檔案系統；虛擬機的宿主磁碟滿，跟 guest 內部磁碟滿，是兩件事。如果你 SSH 進 guest 裡 df 看到還有空間就以為沒事，但真正滿的是宿主的磁碟，那問題不會解決。判讀時要分清這串故障是「哪一台機器的哪個檔案系統」滿了——在宿主上 df -h 看宿主、在 guest 裡 df -h 看 guest，兩邊都要確認。清空間也要清在對的那一側。

判讀路由

SSH timeout（TCP 卡住）→ 網路層或機器沒跑，查 ip neigh（INCOMPLETE = 對方沒回應）→ 去主控台看 ip -brief a / 網路服務。
Connection refused → 網路通、但沒有服務在聽 → 去機器上確認 sshd 起了沒。
能 ping IP、不能用域名（pacman / curl 失敗）→ DNS 解析問題，查 /etc/resolv.conf 有沒有 nameserver、systemd-resolved 起了沒，不是網路層斷。
連錯 / host key 被擋 → IP 或身分變了，見外部連入與無 key 的 bootstrap 路徑。
虛擬機開不起來、宿主側報「找不到資源」但資源在 → 主因查路徑隔離，再排除殘留行程（pgrep -af 'qemu\|...'）/ 磁碟。
一串症狀同時發生 → 早點 df -h，宿主與 guest 兩側都查，磁碟滿常是共同根因。

連不上只是最終症狀，真正的定位靠網路表、服務狀態、資源用量這些權威來源一層層往回推——完整的判讀紀律見診斷心法。

2.3 訂閱模型與訊息路由

Wed, 22 Apr 2026 00:00:00 +0000

訂閱模型的核心目標是把 client action 轉成明確的連線狀態與回應訊息。WebSocket 是長連線，單次 action 失敗通常不應直接關閉連線；router 應把錯誤轉成可理解的 server message。

本章目標

學完本章後，你將能夠：

設計穩定的 client action envelope
把 router、handler、usecase 與 client state 分開
用訂閱集合表達 client 想收到的 topic
在 broadcast 前檢查訂閱狀態
測試 action routing、payload validation 與 error response

【觀察】client message 很容易變成臨時協定

WebSocket action 的核心風險是前後端快速加功能時，訊息格式變成一堆臨時欄位。若 action 名稱依賴按鈕、畫面或短期 UI 狀態，server 很快會累積難以維護的分支。

不穩定的訊息格式：

1{
2  "button": "watch",
3  "tab": "jobs",
4  "id": "topic_1"
5}

這種訊息描述 UI 發生什麼，不是描述 client 想對服務做什麼。服務端應該接收穩定 action，例如 subscribe_topic、unsubscribe_topic、list_subscriptions。

【判讀】action 是 client intent

Client action 的核心語意是「client 想做什麼」。它不是 domain event，因為它還沒被驗證、授權或套用規則。Domain event 表示已經發生的事，action 表示請求。

 1type ClientAction string
 2
 3const (
 4    ActionSubscribeTopic   ClientAction = "subscribe_topic"
 5    ActionUnsubscribeTopic ClientAction = "unsubscribe_topic"
 6    ActionListTopics       ClientAction = "list_topics"
 7)
 8
 9type ClientMessage struct {
10    Action ClientAction    `json:"action"`
11    Data   json.RawMessage `json:"data,omitempty"`
12}

外層 envelope 穩定，內層 Data 依 action 解析。這讓 read pump 可以先解析 envelope，router 再依 action 決定 payload 型別。

【策略】router 負責分派，不擁有全部規則

Router 的核心責任是把 action 分派到對應 handler。它應該知道有哪些 action，但不應把訂閱規則、權限檢查、資料查詢全部塞在一個巨大 switch 裡。

 1type Router struct {
 2    subscriptions *SubscriptionService
 3}
 4
 5func (r Router) Route(ctx context.Context, client *Client, message ClientMessage) error {
 6    switch message.Action {
 7    case ActionSubscribeTopic:
 8        return r.handleSubscribe(ctx, client, message.Data)
 9    case ActionUnsubscribeTopic:
10        return r.handleUnsubscribe(ctx, client, message.Data)
11    case ActionListTopics:
12        return r.handleListTopics(ctx, client)
13    default:
14        return fmt.Errorf("unknown action: %s", message.Action)
15    }
16}

switch 讓支援的 action 集中可見。真正的訂閱狀態修改可以交給 SubscriptionService 或 client method，避免 router 變成所有規則的聚集地。

【執行】payload validation 在 action 邊界完成

Payload validation 的核心責任是讓內部服務只收到有效 command。訂閱 topic 至少要檢查 JSON 格式、topic 是否空白、topic 名稱是否符合規則。

 1type SubscribeTopicRequest struct {
 2    Topic string `json:"topic"`
 3}
 4
 5type SubscribeTopicCommand struct {
 6    ClientID string
 7    Topic    string
 8}
 9
10func (r Router) handleSubscribe(ctx context.Context, client *Client, raw json.RawMessage) error {
11    var req SubscribeTopicRequest
12    if err := json.Unmarshal(raw, &req); err != nil {
13        return fmt.Errorf("decode subscribe request: %w", err)
14    }
15
16    topic := strings.TrimSpace(req.Topic)
17    if topic == "" {
18        return fmt.Errorf("topic is required")
19    }
20
21    cmd := SubscribeTopicCommand{
22        ClientID: client.ID(),
23        Topic:    topic,
24    }
25
26    return r.subscriptions.Subscribe(ctx, client, cmd)
27}

Request struct 是 wire format，command 是內部意圖。兩者分開後，JSON 命名、驗證錯誤與內部服務規則不會混在同一個型別。

【執行】訂閱集合是連線狀態

訂閱集合的核心語意是「這個 client 目前想收到哪些 topic」。它可以放在 client 上，也可以由 hub 集中保存；重點是 owner 要明確。

Client owner 版本：

 1type Client struct {
 2    id string
 3
 4    mu            sync.RWMutex
 5    subscriptions map[string]struct{}
 6}
 7
 8func (c *Client) Subscribe(topic string) {
 9    c.mu.Lock()
10    defer c.mu.Unlock()
11    c.subscriptions[topic] = struct{}{}
12}
13
14func (c *Client) Unsubscribe(topic string) {
15    c.mu.Lock()
16    defer c.mu.Unlock()
17    delete(c.subscriptions, topic)
18}
19
20func (c *Client) IsSubscribed(topic string) bool {
21    c.mu.RLock()
22    defer c.mu.RUnlock()
23    _, ok := c.subscriptions[topic]
24    return ok
25}

map[string]struct{} 是 Go 常見 set 表示法。若 read pump 修改訂閱，hub broadcast 讀取訂閱，就需要 lock 或把所有訂閱操作集中到 hub event loop。

【策略】訂閱狀態也需要 copy boundary

訂閱列表的核心風險是直接回傳 map 會暴露內部狀態。若需要列出目前訂閱，應回傳 slice 或 map copy。

 1func (c *Client) Subscriptions() []string {
 2    c.mu.RLock()
 3    defer c.mu.RUnlock()
 4
 5    topics := make([]string, 0, len(c.subscriptions))
 6    for topic := range c.subscriptions {
 7        topics = append(topics, topic)
 8    }
 9    sort.Strings(topics)
10    return topics
11}

回傳 sorted slice 讓測試更穩定，也避免呼叫端修改內部 map。排序不是業務必要條件，但對 API response 與測試可讀性有幫助。

【執行】成功與失敗都應回 server message

WebSocket action 的核心互動模式是 request-like，但連線不會因單次 action 結束。成功或失敗都應回一筆 server message，讓 client 能更新 UI 或顯示錯誤。

 1type ServerMessage struct {
 2    Type  string `json:"type"`
 3    Topic string `json:"topic,omitempty"`
 4    Error string `json:"error,omitempty"`
 5}
 6
 7func (s *SubscriptionService) Subscribe(ctx context.Context, client *Client, cmd SubscribeTopicCommand) error {
 8    client.Subscribe(cmd.Topic)
 9    ok := client.TrySend(ServerMessage{
10        Type:  "topic_subscribed",
11        Topic: cmd.Topic,
12    })
13    if !ok {
14        return ErrClientQueueFull
15    }
16    return nil
17}

若 action 失敗，read pump 或 router wrapper 可以把錯誤轉成 ServerMessage{Type: "error"}。不要只寫 server log，因為 client 需要知道該 action 沒有成功。

【執行】broadcast 前檢查訂閱

Broadcast 的核心規則是 producer 只產生 topic 與 message，hub 決定哪些 client 應該收到。訂閱邏輯不應散落在每個 producer 裡。

 1func (h *Hub) Broadcast(topic string, message ServerMessage) {
 2    for client := range h.clients {
 3        if !client.IsSubscribed(topic) {
 4            continue
 5        }
 6
 7        if ok := client.TrySend(message); !ok {
 8            h.unregister <- client
 9        }
10    }
11}

這段程式先檢查訂閱，再嘗試送出。若 client 的 send buffer 滿了，hub 可以 unregister 或採用其他慢 client 策略；下一章會專門處理。

【測試】router test 不需要真實 WebSocket

Router 的測試核心是 action 到行為的對應。它不需要真實 WebSocket connection，只需要 fake client 或檢查 client state。

 1func TestSubscribeActionAddsTopic(t *testing.T) {
 2    client := NewTestClient("client_1")
 3    router := Router{subscriptions: NewSubscriptionService()}
 4
 5    data := json.RawMessage(`{"topic":"alerts"}`)
 6    err := router.Route(context.Background(), client, ClientMessage{
 7        Action: ActionSubscribeTopic,
 8        Data:   data,
 9    })
10    if err != nil {
11        t.Fatalf("route subscribe: %v", err)
12    }
13
14    if !client.IsSubscribed("alerts") {
15        t.Fatalf("client should subscribe to alerts")
16    }
17}

Payload validation 也應獨立測：

 1func TestSubscribeActionRequiresTopic(t *testing.T) {
 2    client := NewTestClient("client_1")
 3    router := Router{subscriptions: NewSubscriptionService()}
 4
 5    err := router.Route(context.Background(), client, ClientMessage{
 6        Action: ActionSubscribeTopic,
 7        Data:   json.RawMessage(`{"topic":" "}`),
 8    })
 9    if err == nil {
10        t.Fatalf("empty topic should return error")
11    }
12}

WebSocket integration test 留給「真實 client/server 互動」；router 單元測試先確保協定語意正確。

本章不處理

本章先處理 action envelope 到 subscription 的路由與 ownership；授權、presence 與跨節點同步，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 WebSocket action、event fusion 與 handler boundary；如果你要先回看語言教材，可以讀：

小結

訂閱模型把 client action 轉成連線狀態與 server response。Action 是 client intent，不是 domain event；router 負責分派，payload validation 在邊界完成，訂閱集合要有明確 owner，broadcast 由 hub 統一檢查訂閱。這樣新增 action 或 topic 時，修改範圍會清楚且可測。

2.4 慢客戶端與 send buffer 管理

Wed, 22 Apr 2026 00:00:00 +0000

慢客戶端管理的核心問題是單一 client 的讀取速度可能低於 server 推送速度。若 send buffer 沒有上限，慢 client 會把訊息堆在記憶體裡；若 hub 使用 blocking send，慢 client 會拖住所有 client。

本章目標

學完本章後，你將能夠：

分辨慢 client 對 hub、write pump、記憶體的影響
用 bounded send channel 限制單一 client 的排隊量
設計 queue full 時的 drop、disconnect、coalesce 策略
在必要時用 byte budget 管理大型 payload
測試 send buffer 滿載與 client unregister 行為

【觀察】慢 client 會把局部問題變成全域問題

慢 client 的核心風險是它不只影響自己。若 hub broadcast 時對每個 client 使用 blocking send，其中一個 client 的 send channel 滿了，hub 就可能卡住，其他 client 也收不到訊息。

反模式：

1func (h *Hub) Broadcast(message ServerMessage) {
2    for client := range h.clients {
3        client.send <- message
4    }
5}

這段程式看起來保證送達，但實際上把整個 hub 的可用性綁在最慢的 client 上。只要一個 client 不讀，所有 broadcast 都可能停住。

【判讀】send channel 是每個 client 的容量邊界

Send channel 的核心責任是作為單一 client 的輸出佇列。它必須有容量上限，否則 server 會替慢 client 無限制保存訊息。

 1const sendBufferSize = 64
 2
 3type Client struct {
 4    id   string
 5    send chan ServerMessage
 6}
 7
 8func NewClient(id string) *Client {
 9    return &Client{
10        id:   id,
11        send: make(chan ServerMessage, sendBufferSize),
12    }
13}

Buffer 的目的只是吸收短暫尖峰，不是讓 client 長期落後。若 client 長期消費速度低於推送速度，任何有限 buffer 都會滿。

【策略】滿載策略取決於訊息語意

慢 client 滿載的核心決策是訊息能不能遺失。不同資料類型需要不同策略。

訊息類型	常見策略	理由
即時狀態 snapshot	可丟棄舊訊息或 coalesce	最新狀態比每個中間狀態重要
action result	優先送達，滿載時可斷線	client 需要知道操作結果
診斷 log stream	可取樣或丟棄	資料量大，通常不是唯一真相
金流、訂單、稽核事件	不應只靠 WebSocket	需要可靠儲存或可重播來源

WebSocket send buffer 不應承擔資料可靠性。若訊息不能遺失，可靠性應放在資料庫、queue 或 event log，WebSocket 只負責即時通知。

【執行】non-blocking send 保護 hub

Hub 的核心保護是 broadcast 時不被單一 client 阻塞。TrySend 可以讓 hub 立即知道該 client 是否已滿載。

1func (c *Client) TrySend(message ServerMessage) bool {
2    select {
3    case c.send <- message:
4        return true
5    default:
6        return false
7    }
8}

Hub 可以把滿載 client 送進 unregister：

 1func (h *Hub) Broadcast(topic string, message ServerMessage) {
 2    for client := range h.clients {
 3        if !client.IsSubscribed(topic) {
 4            continue
 5        }
 6
 7        if ok := client.TrySend(message); !ok {
 8            h.unregister <- client
 9        }
10    }
11}

這種策略犧牲慢 client，保護整體服務。對即時通知服務來說，讓慢 client 重連並重新取得 snapshot，通常比讓所有 client 等它更合理。

【策略】drop newest、drop oldest、disconnect 是不同語意

Queue full 策略的核心差異是保留哪一筆資料，以及是否繼續維持連線。

策略	行為	適用情境
drop newest	新訊息不進 queue	舊訊息仍有價值
drop oldest	移除舊訊息，保留最新	狀態型更新
disconnect	關閉 client，要求重連	client 已明顯跟不上
coalesce	合併多筆更新成一筆	topic 最新狀態可覆蓋

Drop oldest 範例：

 1func (c *Client) TrySendLatest(message ServerMessage) bool {
 2    select {
 3    case c.send <- message:
 4        return true
 5    default:
 6    }
 7
 8    select {
 9    case <-c.send:
10    default:
11    }
12
13    select {
14    case c.send <- message:
15        return true
16    default:
17        return false
18    }
19}

這段程式表示「新狀態比舊狀態重要」。它不適合 action result 或不可遺失事件，因為它會主動丟掉尚未送出的舊訊息。

【策略】byte budget 比 message count 更接近記憶體風險

Message count 的核心限制是每筆訊息大小不同。64 筆小訊息和 64 筆大型 JSON payload 的記憶體成本差很多；當 payload 大小差異明顯時，可以加上 byte budget。

 1type Client struct {
 2    send      chan ServerMessage
 3    sendBytes int64
 4    maxBytes  int64
 5}
 6
 7func (c *Client) TrySend(message ServerMessage) bool {
 8    size := int64(message.Size())
 9    if atomic.AddInt64(&c.sendBytes, size) > c.maxBytes {
10        atomic.AddInt64(&c.sendBytes, -size)
11        return false
12    }
13
14    select {
15    case c.send <- message:
16        return true
17    default:
18        atomic.AddInt64(&c.sendBytes, -size)
19        return false
20    }
21}

Write pump 成功取出並寫出訊息後，必須扣回 byte budget：

1func (c *Client) markSent(message ServerMessage) {
2    atomic.AddInt64(&c.sendBytes, -int64(message.Size()))
3}

Byte budget 更接近記憶體風險，但也更複雜。只有在訊息大小差異大、或服務連線數高時才值得加入；小型服務先用固定 buffer 通常足夠。

【判讀】write pump 慢不一定是 client 的錯

慢寫入的核心原因可能在 client，也可能在 server。Client 網路慢、瀏覽器停住、行動裝置休眠會造成慢寫；server payload 太大、序列化太慢、單次寫入沒有 deadline 也會造成問題。

排查方向：

send buffer 長期接近滿載
write deadline 錯誤增加
單筆 message size 過大
broadcast 頻率超過 client 消費能力
某些 topic 推送量異常高

queue full 的歸因應同時檢查 client 與 server 端訊號。若所有 client 都慢，通常是 server 推送量、payload 大小或下游網路策略出問題。

【策略】滿載要有觀測欄位

慢 client 策略的核心要求是可觀測。若系統選擇 drop 或 disconnect，應記錄足夠欄位讓工程師知道原因。

 1func (h *Hub) handleFullClient(client *Client, topic string) {
 2    metrics.Inc("websocket_client_send_full")
 3    h.logger.Warn("websocket client send buffer full",
 4        "client_id", client.ID(),
 5        "topic", topic,
 6        "send_queue_len", len(client.send),
 7        "send_queue_cap", cap(client.send),
 8    )
 9    h.unregister <- client
10}

Log 用來追單次事件，metric 用來看趨勢。若滿載數量突然增加，可能是某個 topic 推送量上升，也可能是 client 版本或網路環境改變。

【測試】滿載測試要先填滿 buffer

慢 client 測試的核心是直接建立滿載條件。容量為 1 的 channel 加上預先填滿的資料，可以穩定製造 queue full；sleep 只是在等待排程運氣。

 1func TestTrySendReturnsFalseWhenBufferFull(t *testing.T) {
 2    client := &Client{
 3        id:   "client_1",
 4        send: make(chan ServerMessage, 1),
 5    }
 6    client.send <- ServerMessage{Type: "first"}
 7
 8    ok := client.TrySend(ServerMessage{Type: "second"})
 9    if ok {
10        t.Fatalf("TrySend should return false when buffer is full")
11    }
12}

Hub unregister 行為也可以測：

 1func TestBroadcastUnregistersFullClient(t *testing.T) {
 2    hub := NewHub()
 3    client := NewTestClient("client_1", 1)
 4    client.Subscribe("alerts")
 5    client.send <- ServerMessage{Type: "existing"}
 6    hub.clients[client] = struct{}{}
 7
 8    hub.Broadcast("alerts", ServerMessage{Type: "new"})
 9
10    select {
11    case got := <-hub.unregister:
12        if got != client {
13            t.Fatalf("unregister client mismatch")
14        }
15    default:
16        t.Fatalf("full client should be unregistered")
17    }
18}

這類測試直接驗證服務策略：client 滿載時，hub 不阻塞，而是走指定降級路徑。

本章不處理

本章先處理單一 server 內的慢 client 與 send buffer 邊界；跨節點 fan-out 與持久化同步，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 channel backpressure 、non-blocking send 與 rate limiting；如果你要先回看語言教材，可以讀：

小結

慢客戶端是 WebSocket 服務的容量控制問題。每個 client 的 send buffer 必須有上限，hub broadcast 不應被單一 client 阻塞，queue full 策略要符合訊息語意。必要時可加入 byte budget，但更重要的是明確決定 drop、disconnect、coalesce 或可靠儲存，並用 log、metric、測試讓降級行為可見。

5.4 HTTP handler 測試

Wed, 22 Apr 2026 00:00:00 +0000

HTTP handler 測試的核心規則是不用啟動真實 server，也能驗證 request 進入 handler 後產生的 response。net/http/httptest 提供 request builder 與 response recorder，讓 handler 可以像普通函式一樣被測試。

`httptest` 把 HTTP 測試變成函式呼叫

httptest 的核心用途是建立測試用 request 與 response writer。handler 本來就是 func(http.ResponseWriter, *http.Request)，所以測試可以直接呼叫 handler。

1func handleHealth(w http.ResponseWriter, r *http.Request) {
2    if r.Method != http.MethodGet {
3        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
4        return
5    }
6
7    w.Header().Set("Content-Type", "application/json")
8    fmt.Fprint(w, `{"status":"ok"}`)
9}

這個 handler 可以不用啟動 port，也不用發出真實網路請求。

 1func TestHandleHealth(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodGet, "/health", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handleHealth(rec, req)
 6
 7    res := rec.Result()
 8    defer res.Body.Close()
 9
10    if res.StatusCode != http.StatusOK {
11        t.Fatalf("status = %d, want %d", res.StatusCode, http.StatusOK)
12    }
13}

httptest.NewRequest 建立 request，httptest.NewRecorder 記錄 response。測試直接呼叫 handleHealth(rec, req)，再檢查 recorder 產生的結果。

status code 是第一個行為合約

HTTP response 的核心合約通常先看 status code。成功、輸入錯誤、方法不允許與伺服器錯誤，都應該有明確狀態碼。

 1func TestHandleHealthMethodNotAllowed(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodPost, "/health", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handleHealth(rec, req)
 6
 7    if rec.Code != http.StatusMethodNotAllowed {
 8        t.Fatalf("status = %d, want %d", rec.Code, http.StatusMethodNotAllowed)
 9    }
10}

rec.Code 可以直接取得 handler 寫出的狀態碼。若 handler 沒有呼叫 WriteHeader，但有寫 body，狀態碼通常會是 200。

測試狀態碼時，不要只檢查 body 字串。body 可能改文案，但 status code 才是呼叫端最依賴的協定訊號。

body 檢查要符合輸出格式

response body 的核心檢查方式應該配合輸出格式。純文字可以比對字串；JSON 應該解析成 struct 或 map 後再比對欄位。

 1func TestHandleHealthBody(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodGet, "/health", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handleHealth(rec, req)
 6
 7    var body struct {
 8        Status string `json:"status"`
 9    }
10
11    if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
12        t.Fatalf("decode response body: %v", err)
13    }
14
15    if body.Status != "ok" {
16        t.Fatalf("status field = %q, want %q", body.Status, "ok")
17    }
18}

解析 JSON 後檢查欄位，比直接比對 {"status":"ok"} 更穩定。JSON 欄位順序、空白與換行不應該讓測試失敗。

request body 可以用 `strings.NewReader`

測試 JSON request 的核心做法是把字串或 bytes 包成 reader。handler 看到的是 io.Reader，不需要知道資料來自檔案、網路或測試字串。

 1func TestHandleCreateUser(t *testing.T) {
 2    body := strings.NewReader(`{"name":"Alice","email":"alice@example.com"}`)
 3    req := httptest.NewRequest(http.MethodPost, "/users", body)
 4    req.Header.Set("Content-Type", "application/json")
 5
 6    rec := httptest.NewRecorder()
 7    handler := newCreateUserHandler(fakeUserCreator{})
 8
 9    handler.ServeHTTP(rec, req)
10
11    if rec.Code != http.StatusCreated {
12        t.Fatalf("status = %d, want %d", rec.Code, http.StatusCreated)
13    }
14}

strings.NewReader 讓測試資料留在測試檔中，適合小型 JSON。若 request 很大或要重複使用，可以把測試資料放在 testdata 目錄。

依賴應該用 fake 隔離

handler 測試的核心邊界是 HTTP 行為，不是資料庫或外部服務。若 handler 需要呼叫內部服務，可以提供 fake 實作，讓測試專注於 request/response。

 1type fakeUserCreator struct {
 2    id  string
 3    err error
 4}
 5
 6func (f fakeUserCreator) CreateUser(ctx context.Context, name string, email string) (string, error) {
 7    if f.err != nil {
 8        return "", f.err
 9    }
10    return f.id, nil
11}

成功案例可以讓 fake 回傳 id，失敗案例可以讓 fake 回傳錯誤。這樣測試可以分別驗證 201 Created 與 500 Internal Server Error。

 1func TestHandleCreateUserServiceError(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodPost, "/users", strings.NewReader(`{"name":"Alice","email":"alice@example.com"}`))
 3    rec := httptest.NewRecorder()
 4
 5    handler := newCreateUserHandler(fakeUserCreator{err: errors.New("database unavailable")})
 6    handler.ServeHTTP(rec, req)
 7
 8    if rec.Code != http.StatusInternalServerError {
 9        t.Fatalf("status = %d, want %d", rec.Code, http.StatusInternalServerError)
10    }
11}

這是 handler 單元測試。資料庫連線、migration、真實網路等行為應該放在更高層級的整合測試處理。

下一章會處理時間注入，說明如何避免測試依賴真實現在時間。

3.5 net/http 與 handler 設計

Wed, 22 Apr 2026 00:00:00 +0000

Go 的 net/http 把 HTTP endpoint 簡化成一個核心模型：handler 接收 request，然後寫出 response。後端服務可以有複雜的資料庫、queue、背景工作或即時連線，但 HTTP 入口本身應該先保持清楚。

handler 是 HTTP 邊界

HTTP handler 的核心責任是處理協定邊界。它應該讀取 request、驗證輸入、呼叫內部邏輯，最後寫出 status code、header 與 body。

 1func handleHealth(w http.ResponseWriter, r *http.Request) {
 2    if r.Method != http.MethodGet {
 3        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 4        return
 5    }
 6
 7    w.Header().Set("Content-Type", "application/json")
 8    w.WriteHeader(http.StatusOK)
 9    fmt.Fprint(w, `{"status":"ok"}`)
10}

這個 handler 只處理健康檢查：確認 HTTP method，設定回應格式，寫出 JSON。它沒有讀取資料庫，也沒有啟動背景工作，因為健康檢查的責任就是讓呼叫者知道服務是否能回應。

handler 可以呼叫內部服務，但不應該把所有業務規則都塞在 HTTP 層。HTTP 層越薄，測試越容易，未來改成 CLI、queue consumer 或其他入口時也比較不會重寫核心邏輯。

`http.HandlerFunc` 是函式轉接器

http.HandlerFunc 的核心意義是讓普通函式符合 http.Handler 介面。只要函式形狀是 func(http.ResponseWriter, *http.Request)，就能成為 HTTP handler。

1func hello(w http.ResponseWriter, r *http.Request) {
2    fmt.Fprint(w, "hello")
3}
4
5func main() {
6    http.HandleFunc("/hello", hello)
7    http.ListenAndServe(":8080", nil)
8}

http.HandleFunc 會把 hello 轉成 handler 並註冊到預設 mux。小範例可以這樣寫，但實際應用通常會建立自己的 ServeMux，避免全域註冊讓測試與組裝變得不清楚。

1func newRouter() http.Handler {
2    mux := http.NewServeMux()
3    mux.HandleFunc("/health", handleHealth)
4    mux.HandleFunc("/users", handleUsers)
5    return mux
6}

回傳 http.Handler 可以隱藏路由實作，呼叫端只需要知道這是一個可被 server 使用的 handler。

`ServeMux` 負責路由分派

ServeMux 的核心責任是把 request path 對應到 handler。標準庫的 http.NewServeMux 足以建立許多小型服務與教學範例。

 1func main() {
 2    mux := http.NewServeMux()
 3    mux.HandleFunc("GET /health", handleHealth)
 4    mux.HandleFunc("POST /users", handleCreateUser)
 5
 6    server := &http.Server{
 7        Addr:    ":8080",
 8        Handler: mux,
 9    }
10
11    if err := server.ListenAndServe(); err != nil {
12        log.Fatal(err)
13    }
14}

新版 Go 的 ServeMux 支援在 pattern 裡寫 HTTP method，例如 GET /health。這能讓 method 與 path 在註冊處一起呈現。

若你的專案需要 middleware group、path parameter 或更完整的路由功能，可以使用第三方 router。入門階段先理解標準庫模型，會更容易看懂任何 router 的抽象。

request 讀取要有明確限制

讀取 request 的核心原則是只接受你預期的內容。handler 應該檢查 method、content type、body 大小與 JSON 格式，避免把任意輸入直接交給內部邏輯。

 1type createUserRequest struct {
 2    Name  string `json:"name"`
 3    Email string `json:"email"`
 4}
 5
 6func handleCreateUser(w http.ResponseWriter, r *http.Request) {
 7    if r.Method != http.MethodPost {
 8        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 9        return
10    }
11
12    defer r.Body.Close()
13    r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
14
15    var req createUserRequest
16    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
17        http.Error(w, "invalid json", http.StatusBadRequest)
18        return
19    }
20
21    if req.Email == "" {
22        http.Error(w, "email is required", http.StatusBadRequest)
23        return
24    }
25
26    w.WriteHeader(http.StatusCreated)
27}

http.MaxBytesReader 限制 body 大小，避免大型輸入消耗過多記憶體。json.Decoder 解析 body，失敗時回傳 400 Bad Request。欄位驗證通過後，handler 才進入真正的建立流程。

這段範例省略了資料儲存，因為本章重點是 HTTP 邊界。實務上通常會把建立使用者的規則放到 service 函式，handler 只負責轉換 request 與 response。

response 要先決定狀態碼

寫 response 的核心規則是先決定 status code，再寫 header 與 body。只要 body 開始寫出，Go 就會送出預設或目前設定的 status code。

1func writeJSON(w http.ResponseWriter, status int, value any) {
2    w.Header().Set("Content-Type", "application/json")
3    w.WriteHeader(status)
4
5    if err := json.NewEncoder(w).Encode(value); err != nil {
6        // response 已經開始寫出，這裡通常只能記錄錯誤。
7        log.Printf("write json response: %v", err)
8    }
9}

WriteHeader 應該在 Encode 之前呼叫。若先寫 body，再呼叫 WriteHeader，狀態碼可能已經固定為 200 OK。

1writeJSON(w, http.StatusCreated, map[string]string{
2    "id": "user_123",
3})

小型範例可以直接在 handler 裡寫 response；當多個 handler 都要輸出 JSON 時，抽出 writeJSON 這類 helper 可以減少重複。

handler 可以依賴介面

handler 依賴介面的核心好處是測試與替換更容易。HTTP 層不需要知道資料來自資料庫、記憶體或遠端 API，只需要知道它可以呼叫某個能力。

 1type UserCreator interface {
 2    CreateUser(ctx context.Context, name string, email string) (string, error)
 3}
 4
 5type UserHandler struct {
 6    creator UserCreator
 7}
 8
 9func (h UserHandler) Create(w http.ResponseWriter, r *http.Request) {
10    // 解析與驗證 request 後：
11    id, err := h.creator.CreateUser(r.Context(), "alice", "alice@example.com")
12    if err != nil {
13        http.Error(w, "create user", http.StatusInternalServerError)
14        return
15    }
16
17    writeJSON(w, http.StatusCreated, map[string]string{"id": id})
18}

這裡的 UserHandler 不知道使用者如何被建立，只知道有一個 UserCreator。測試時可以提供假的 creator，正式環境再接上真正實作。

介面不需要一開始就為所有東西建立。當 handler 真的需要隔離外部依賴，或測試需要替換依賴時，再抽出小介面會更自然。

小結

下一章會回到 logging，說明如何用 slog 讓服務輸出可搜尋、可關聯的結構化資訊。

8.6 Cloudflare：DNS、SSL 與長連線服務

Thu, 23 Apr 2026 00:00:00 +0000

Cloudflare 是理解 Go 高併發價值的最佳案例之一。官方文章提到 Go 被用在 Railgun、DNS infrastructure、SSL、load testing 與多個生產服務中。這些工作共同點都很明顯：大量 I/O、長連線、網路協調與對 latency 的敏感。

你應該看什麼

這個案例告訴我們什麼

goroutine 與 channel 很適合處理大量網路事件。
Go 在低延遲連線服務中特別自然。
服務邊界、節奏控制與生命週期管理是關鍵，不只是 raw throughput。

可對照的公開原始碼

這兩個 repo 很適合拿來看長連線代理、API client、context 使用與依賴組裝。

8.8 Stream：Feeds 與 Chat

Thu, 23 Apr 2026 00:00:00 +0000

Stream 的官方案例很適合教學用途，因為它把 Go 的幾個核心優勢講得很直接：ecosystem、easy onboarding、fast performance、solid support for concurrency 與 productive programming environment。官方案例還特別提到，這讓一個小團隊能支撐超過 5 億使用者的 feeds 與 chat。

你應該看什麼

這個案例告訴我們什麼

Go 很適合即時 feed 與 chat 這種高事件量服務。
小團隊也能利用 Go 把服務做大。
SDK 與 server-side service 都能用同一套語言思維來維護。

可對照的公開原始碼

GetStream/getstream-go

這個 Go SDK 很適合拿來看 request/response model、client 設計、testing 與 OpenAPI codegen 的邊界。

8.9 ByteDance / CloudWeGo：微服務基礎設施

Thu, 23 Apr 2026 00:00:00 +0000

CloudWeGo 是理解 Go 在大型公司內部如何演化成基礎設施層的好案例。官方介紹指出，它是 ByteDance Infrastructure Service Framework 團隊開源的 middleware 集合，核心關注是高性能、高擴展性、高可靠性與微服務溝通與治理。

你應該看什麼

這個案例告訴我們什麼

Go 可以從單一服務語言，進一步變成微服務平台語言。
大型服務常會把 RPC、HTTP、networking、serialization 拆成不同 middleware。
Go 的簡潔語法與高性能 runtime 很適合做基礎設施層。

可對照的公開原始碼

這三個 repo 很適合對照第 4、6、7 模組，尤其是高併發控制、HTTP 邊界與 ports/adapters 的組織方式。