你應該看什麼

• Using Go at Google
• How Google’s Core Data Solutions Team Uses Go
• Go at Google: Language Design in the Service of Software Engineering

這個案例告訴我們什麼

1. Go 很適合大型服務拆分之後的邊界管理。
2. built-in concurrency 對高併發索引與資料處理很重要。
3. Go 的簡單語法與明確依賴，能讓大團隊維持可讀性。

可對照的公開原始碼

• kubernetes/kubernetes

Kubernetes 不是 Google 內部產品，但它很好地呈現了 Google 文化裡常見的 Go 工程模式：大型 codebase、明確 package 邊界、cmd 入口與大量服務協調。

本章目標

學完本章後，你將能夠：

1. 判斷 [transaction boundary](/go-advanced/backend/knowledge-cards/transaction-boundary) 應該放在 repository 還是 usecase
2. 理解 migration 為什麼要維持向前相容
3. 分辨 application validation、constraint 與 isolation level 的責任
4. 用 contract test 保護 memory repository 與 database repository 的一致行為
5. 讓 SQL 細節留在 adapter，讓 domain 規則留在 application

前置章節

• Go 入門：如何新增 repository port
• Go 入門：狀態管理的安全邊界
• Go 進階：Source of Truth：狀態邊界
• Backend：Source of Truth
• Backend：Connection Pool

後續撰寫方向

1. Repository method 如何表達交易語意，讓 SQL 細節留在 adapter。
2. 一個 usecase 需要多筆寫入同時成功或失敗時，transaction boundary 應放在哪裡。
3. Migration 如何維持向前相容，避免新舊程式版本互相破壞資料。
4. Isolation level、unique constraint 與 application-level validation 如何分工。
5. Contract test 如何保護 memory repository 與 database repository 的一致行為。

【觀察】transaction 是一致性邊界

transaction 的核心用途是把一組資料庫操作綁成單一一致性單位。判斷重點是：這個 usecase 哪些狀態要一起成功或一起失敗。效能與寫入便利性都應放在一致性需求之後評估。

例如建立訂單時，可能同時需要：

• 寫入 order 主表
• 寫入 order items
• 更新 inventory
• 寫入 outbox event

如果其中一個步驟失敗，整組操作就應回滾，避免 application 狀態和資料庫狀態分裂。

【判讀】transaction boundary 應該跟 usecase 對齊

交易邊界最常見的錯誤，是把 transaction 放得太低或太高。

• 放太低：repository 各自開 transaction，usecase 層看起來成功，實際上無法保證整體一致。
• 放太高：把不需要一致性的讀取、外部 API、長迴圈也包進 transaction，讓連線被占住太久。

一般原則是：

• 要維持同一個 domain 不變式的寫入，應放在同一個 transaction。
• 可以重試或可補償的外部互動，通常應放在 transaction 之外。

【策略】Migration 要讓舊版與新版可以共存

schema migration 的核心是讓部署期間的新舊版本能同時活著。實務上常見的是 Expand / Contract 流程：

1. 先新增欄位、表或索引。
2. 讓新舊程式都能讀寫。
3. 確認流量已切到新版本。
4. 再移除舊欄位或舊邏輯。

這樣做的目的，是避免應用版本與資料庫版本在 rolling deploy 時互相踩到。

【判讀】constraint、validation 與 isolation level 各管不同風險

這三者的責任應清楚分工：

• application validation：在進資料庫前先檢查基本輸入是否合法。
• unique / foreign key / check constraint：在資料庫層保底，防止不合法資料落地。
• isolation level：處理多交易同時進行時的可見性與衝突問題。

如果只靠 application validation，資料庫仍可能被其他路徑寫入不合法資料。如果只靠資料庫 constraint，錯誤回報可能太晚。兩者通常要一起用。

【執行】contract test 檢查 repository 語意一致

當你同時有 memory repository 與 database repository 時，測試重點是它們對外暴露的語意是否一致。SQL 細節屬於 database adapter 的內部實作。

通常要測：

• 找不到資料時怎麼回傳
• 重複寫入時怎麼回傳
• transaction 失敗時是否維持一致狀態
• 欄位驗證與預設值是否相同

這類測試可以讓 repository adapter 保持可替換，讓資料庫替換時 usecase 維持穩定。

本章不處理

本章不會選定特定資料庫或 ORM。真正的重點是 Go application 如何定義資料一致性責任，讓 SQLite、PostgreSQL 或其他儲存技術都能成為可替換 adapter。

和 Go 教材的關係

這一章承接的是 Go 的 repository port 與狀態邊界；如果你要先回看語言教材，可以讀：

• Go：如何新增 repository port
• Go：狀態管理的安全邊界
• Go 進階：Source of Truth

本章目標

學完本章後，你將能夠：

1. 分辨 event ID 去重與 domain key 去重的差異
2. 用 subject、event type、source group 與時間窗口設計 DedupKey
3. 避免把不穩定欄位放進去重鍵
4. 設計去重表的過期與清理策略
5. 用 table-driven test 驗證去重邊界

【觀察】重複事件不一定長得一樣

重複事件的核心困難是外觀可能不同。HTTP callback 可能每次都有新的 request ID，queue message 可能因 retry 改變 delivery tag，timer 可能在下一輪掃描再次產生類似事件。

兩筆外部輸入可能長這樣：

1{
2  "request_id": "req_1001",
3  "event_id": "provider_7788",
4  "account_id": "acct_1",
5  "event_name": "activated",
6  "timestamp": "2026-04-22T10:00:03Z"
7}

1{
2  "request_id": "req_1002",
3  "event_id": "provider_7788_retry",
4  "account_id": "acct_1",
5  "event_name": "activated",
6  "timestamp": "2026-04-22T10:00:05Z"
7}

如果直接比對整包 JSON，這兩筆不同；如果從 domain 看，它們可能都是「同一個 account 在同一小段時間內變成 active」。

【判讀】去重鍵是語意決策

去重鍵的核心責任是把「相同事件」的定義寫進型別。它不是單純把 payload 做 hash；hash 只能回答 bytes 是否相同，不能回答領域事件是否相同。

1type DedupKey struct {
2    SubjectID string
3    Type      EventType
4    SourceSet string
5    Window    int64
6}

這個 key 表示：同一個 subject、同一種 event type、同一組來源語意、落在同一個時間窗口的事件，視為同一件事。

SourceSet 不一定等於原始來源名稱。多個來源若只是同一件事的不同傳輸管道，可以映射到同一個 source set；若兩個來源代表不同權威資料，則應分開。

【策略】先選擇去重層級

去重層級的核心選擇是 event ID、domain key 或兩者並用。不同層級解決的問題不同。

小型服務可以先使用 domain key。若上游提供可靠 event ID，則 event ID 可以成為第一層快速去重，domain key 作為跨來源重複的保護。

【執行】用內部事件建立 DedupKey

DedupKey 應該建立在 DomainEvent 上，而不是 raw input 上。這能讓 HTTP、queue、timer 進來的同類事件共用去重規則。

 1func NewDedupKey(event DomainEvent, window time.Duration) DedupKey {
 2    return DedupKey{
 3        SubjectID: event.SubjectID,
 4        Type:      event.Type,
 5        SourceSet: sourceSet(event.Source),
 6        Window:    event.OccurredAt.UnixNano() / int64(window),
 7    }
 8}
 9
10func sourceSet(source EventSource) string {
11    switch source {
12    case SourceHTTPCallback, SourceQueue:
13        return "external_delivery"
14    case SourceTimer:
15        return "internal_scan"
16    default:
17        return string(source)
18    }
19}

OccurredAt 通常比 ReceivedAt 更適合事件語意去重。兩筆 retry 可能收到時間不同，但實際描述的發生時間相近；若使用收到時間，系統忙碌或網路延遲就會改變去重結果。

【判讀】哪些欄位不該放進 key

去重鍵的核心限制是不能包含每次都會變的欄位。這類欄位適合用於追蹤、除錯或觀測，不適合用於判斷是否同一事件。

不適合放進 key 的欄位：

• request_id：每次 request 都可能不同。
• received_at：取決於系統接收時間，不一定是事件語意。
• delivery_attempt：重試次數本身就是重複事件的證據。
• raw payload hash：欄位順序、metadata 或非語意欄位可能改變。
• client IP、瀏覽器識別字串：代表傳輸脈絡，不代表事件本身。

適合放進 key 的欄位：

• subject ID：事件作用的對象。
• event type：發生了什麼事。
• source set：資料權威或來源語意。
• occurred time window：同一事件可接受的時間範圍。

【策略】時間窗口是取捨

時間窗口的核心作用是容忍短時間內的重送。窗口越短，越不容易誤殺不同事件；窗口越長，越能吸收延遲與 retry。

1const defaultDedupWindow = 30 * time.Second

窗口大小應該依事件語意決定：

時間窗口不是萬用答案。若事件本身允許短時間內多次發生，就需要更細的 subject 或 event ID，而不是把窗口調小到碰運氣。

【執行】Deduper 要保護共享 map

in-memory deduper 的核心責任是記住近期看過的 key，並在多 goroutine 下保持安全。只要 processor 可能同時處理事件，就需要 mutex 或單一 goroutine 擁有去重表。

 1type Deduper struct {
 2    mu      sync.Mutex
 3    seen    map[DedupKey]time.Time
 4    window  time.Duration
 5    expires time.Duration
 6}
 7
 8func NewDeduper(window, expires time.Duration) *Deduper {
 9    return &Deduper{
10        seen:    make(map[DedupKey]time.Time),
11        window:  window,
12        expires: expires,
13    }
14}
15
16func (d *Deduper) Seen(ctx context.Context, event DomainEvent) (bool, error) {
17    d.mu.Lock()
18    defer d.mu.Unlock()
19
20    key := NewDedupKey(event, d.window)
21    if _, ok := d.seen[key]; ok {
22        return true, nil
23    }
24
25    d.seen[key] = event.ReceivedAt
26    return false, nil
27}

ctx 在 memory 實作中可能用不到，但保留在 port 上能讓未來改成 Redis、資料庫或遠端服務時支援取消與逾時。

【執行】去重表必須清理

去重表的核心風險是無限制成長。只要把 key 放進 map，就必須定義 key 何時過期。

 1func (d *Deduper) Cleanup(now time.Time) {
 2    d.mu.Lock()
 3    defer d.mu.Unlock()
 4
 5    for key, seenAt := range d.seen {
 6        if now.Sub(seenAt) > d.expires {
 7            delete(d.seen, key)
 8        }
 9    }
10}

expires 通常應該大於 window。窗口決定兩筆事件是否可能被視為相同，過期時間決定 key 在記憶體中保留多久；兩者不是同一個概念。

【測試】用 table-driven test 固定語意

去重測試的核心目標是把「什麼算相同」寫成案例。這比只測 map 是否有資料更重要。

 1func TestDedupKey(t *testing.T) {
 2    base := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 3
 4    tests := []struct {
 5        name string
 6        a    DomainEvent
 7        b    DomainEvent
 8        same bool
 9    }{
10        {
11            name: "same subject type and window",
12            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
13            b: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceQueue, OccurredAt: base.Add(5 * time.Second)},
14            same: true,
15        },
16        {
17            name: "different subject",
18            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
19            b: DomainEvent{SubjectID: "acct_2", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
20            same: false,
21        },
22        {
23            name: "outside window",
24            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
25            b: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base.Add(2 * time.Minute)},
26            same: false,
27        },
28    }
29
30    for _, tt := range tests {
31        t.Run(tt.name, func(t *testing.T) {
32            got := NewDedupKey(tt.a, time.Minute) == NewDedupKey(tt.b, time.Minute)
33            if got != tt.same {
34                t.Fatalf("same key = %v, want %v", got, tt.same)
35            }
36        })
37    }
38}

這個測試把來源融合、subject 差異與時間窗口都明確化。未來調整 key 時，測試會提醒你正在改變事件語意，而不只是改一個 struct。

本章不處理

本章先處理單一服務內的事件去重語意；跨節點一致性與 idempotency store，會在下列章節再往外延伸：

• Backend：快取與 Redis
• Backend：資料庫與持久化
• Go 進階：Durable queue、outbox 與 idempotency

和 Go 教材的關係

這一章承接的是 event normalization、processor 與 source priority；如果你要先回看語言教材，可以讀：

• Go：如何新增一種 domain event
• Go：如何新增背景工作流程
• Go：用 interface 隔離外部依賴
• Go：事件去重邏輯的重構策略

小結

事件去重是領域語意設計，不是 payload 比對。好的 DedupKey 會使用 subject、event type、source set 與合適的 occurred time window，並避免 request ID、收到時間與 raw payload hash 這類不穩定欄位。去重表還必須有清理策略，否則事件系統會用記憶體 leak 換取短期正確性。

本章目標

學完本章後，你將能夠：

1. 理解 outbox 為什麼能避免半成功
2. 分辨 domain dedup key 與 idempotency key 的用途
3. 設計可重入的 consumer / processor
4. 用 retry、DLQ 與回補流程處理失敗事件
5. 把事件可靠性寫進資料結構，讓規則可以被程式與測試驗證

前置章節

• Go 進階：非阻塞送出與事件丟棄策略
• Go 進階：事件去重與語義鍵設計
• Go 進階：多來源 event 融合
• Backend：Ack / Nack
• Backend：Retry Policy
• Backend：Dead-Letter Queue
• Backend：Consumer Lag

後續撰寫方向

1. Outbox 如何避免「狀態已寫入，但事件沒送出」的半成功。
2. Idempotency key 如何和 domain dedup key 分工。
3. Consumer retry、dead-letter queue 與 poison message 如何設計處理流程。
4. At-least-once delivery 下，processor 如何保持可重入。
5. Queue lag、retry count、dead-letter count 應如何進入 log 與 metric。

【觀察】outbox 是把資料與事件綁在同一個 transaction

outbox 的核心概念是：先把業務狀態與待發事件一起寫進資料庫，再由獨立 publisher 把 outbox 內容送到 queue 或 broker。這樣即使 process 在寫完資料後當機，也不會丟掉事件。

典型流程是：

1. usecase 開 transaction。
2. 寫入 domain data。
3. 寫入 outbox record。
4. commit。
5. background publisher 讀出未送出的 outbox。
6. 成功後把 outbox 標成已送出。

這個模型的重點是讓「至少會被發現並補送」成為可能。它承認跨 process 傳遞很難保證絕對只送一次，所以後續還要搭配 idempotency。

【判讀】idempotency 是跨 process 的必要邊界

只要事件可能重送，consumer 就要能承受重複訊息。idempotent processor 的核心是讓同一筆事件重複進來時，結果仍然穩定。

常見做法包括：

• 用 event ID 記錄已處理過的訊息
• 用 domain key 去重，讓同一個業務操作不會重複套用
• 用狀態機檢查 transition 是否已發生

【策略】DLQ 是流程的一部分

當事件重試失敗，dead-letter queue 要變成可處理的操作流程。你要知道：

• 為什麼失敗
• 要重試幾次
• 什麼錯誤可以直接放棄
• 什麼錯誤需要人工回補

如果沒有這些規則，DLQ 只會變成看不完的黑洞。

【執行】可重入 processor 的基本形式

可重入的核心要求是同一事件重跑時，不會把資料弄壞。簡化的處理流程通常長這樣：

 1func (p *Processor) Handle(ctx context.Context, evt Event) error {
 2    if p.store.Seen(evt.ID) {
 3        return nil
 4    }
 5
 6    if err := p.store.Apply(ctx, evt); err != nil {
 7        return err
 8    }
 9
10    return p.store.MarkSeen(ctx, evt.ID)
11}

實際實作時，Seen 與 MarkSeen 通常要跟業務狀態放在同一個一致性邊界裡，避免競態。

【延伸】queue lag 與 retry 需要被觀測

只要有 durable queue，就一定會有 backlog、retry 與 failure pattern。這些訊號應進入 log 與 metric，讓工程師知道是 producer 變慢、consumer 壞掉，還是下游依賴正在抖動。

本章不處理

本章不追求 exactly-once 的口號。教材重點會放在 Go 服務如何承認 at-least-once 的現實，並用 idempotent processor、outbox 與可觀測欄位降低風險。

和 Go 教材的關係

這一章承接 Go 的事件邊界與非阻塞送出；如果你要先回看語言教材，可以讀：

• Go 進階：非阻塞送出與事件丟棄策略
• Go 進階：事件去重與語義鍵設計
• Go 進階：多來源 event 融合

本章目標

學完本章後，你將能夠：

1. 理解單節點 hub 為什麼不夠
2. 看懂 presence store 與 broker 在系統中的角色
3. 設計 reconnect 後的補資料流程
4. 分辨訂閱路由、連線管理與授權邊界
5. 讓多台 server 在語意上看起來像同一個訊息系統

前置章節

• Go 進階：read pump / write pump 模式
• Go 進階：heartbeat、deadline 與連線清理
• Go 進階：訂閱模型與訊息路由
• Go 進階：慢客戶端與 send buffer 管理

後續撰寫方向

1. 多台 server 如何知道某個 topic 的訂閱者在哪些節點。
2. Presence store 如何記錄 client online、offline 與最後活動時間。
3. Broker fan-out 如何和每個節點本地 send buffer 策略銜接。
4. Client reconnect 如何使用 cursor、last event ID 或 snapshot 補資料。
5. Topic ACL 與 subscription authorization 應放在 router、usecase 還是 gateway。

【觀察】跨節點 WebSocket 的核心問題是狀態協調

WebSocket 協定解決的是單一連線的雙向通訊，但跨節點之後，真正麻煩的是狀態分散在多台 server。某個 client 可能連到 A 節點，但它關注的 topic 事件卻從 B 節點產生，這時就需要能夠路由、轉送與補資料。

所以跨節點 WebSocket 的問題不只是「能不能推送」，而是：

• 這個 client 現在在哪台 server
• 它訂閱了哪些 topic
• 推送失敗後要不要重送
• 重新連線後要從哪裡補回遺漏事件

【判讀】presence store 是操作查詢

presence store 的用途是讓系統知道某個 client 或節點目前大概在線上還是離線。它通常是操作性資料，不一定是業務真相。

常見欄位包括：

• client ID
• node ID
• connected at
• last seen
• subscription keys

這類資料要允許過期與清理，因為斷線、網路抖動與 crash 都可能讓狀態暫時不準。

【策略】reconnect 一定要有補資料設計

只靠重新連上 WebSocket 並不能保證使用者不漏訊息。當連線中斷時，常見的補資料方式有：

• last event ID
• cursor / offset
• snapshot + delta

選哪一種，取決於你的事件是否可排序、是否可回放，以及業務能容忍多大的缺口。

【執行】推送路徑通常要分三層

跨節點場景下，推送路徑常見會分成：

1. 事件產生端把訊息交給 broker 或 routing layer。
2. 節點收到後，交給本機 hub / connection manager。
3. write pump 再把訊息送到單一 client。

這樣可以維持單一寫入者原則，避免多個 goroutine 同時寫 WebSocket。

【延伸】授權應該在進入路由前就處理

Topic ACL 要在訂閱建立時就確認這個 client 是否有資格加入。這能減少不必要的 fan-out 與敏感資料外流。

本章不處理

本章不會選定特定 broker 或 presence database。重點是先讓跨節點責任可見，再依服務需求選擇 Redis、NATS、Kafka、PostgreSQL 或其他基礎設施。

和 Go 教材的關係

這一章承接的是 WebSocket 連線架構與事件路由；如果你要先回看語言教材，可以讀：

• Go 進階：read/write pump 模式
• Go 進階：heartbeat、deadline 與連線清理
• Go 進階：訂閱模型與訊息路由
• Go 進階：慢客戶端與 send buffer 管理

本章目標

學完本章後，你將能夠：

1. 分辨來源差異與 domain 規則差異
2. 為不同來源設計 adapter 與 normalize
3. 用 channel 或直接呼叫收斂事件入口
4. 為突發流量設計 backpressure 策略
5. 決定錯誤應回給上游、重試、丟棄或記錄

【觀察】來源增加後規則容易分裂

事件來源增加的核心風險是每個來源各自實作一套處理規則。HTTP handler 有一套 validation，queue consumer 有一套 retry 判斷，timer worker 又有一套狀態更新；最後同一種 domain event 在不同入口產生不同結果。

反模式示意：

1HTTP callback ──> validate A ──> update state A
2queue message ──> validate B ──> update state B
3timer scan    ──> validate C ──> update state C

這種結構的問題是 domain 規則分裂。新增來源時，應該新增 adapter，不應複製 processor。

【判讀】來源差異應限制在 adapter

事件融合的核心原則是來源差異停在 adapter 與 normalizer。來源可以有不同 authentication、ack、HTTP status、payload 格式與重試語意；但轉成 DomainEvent 後，processor 應該面對一致模型。

目標結構：

1HTTP callback ─┐
2queue message ─┼─> normalize ─> DomainEvent ─> processor
3timer scan    ─┘

這個結構讓新增來源變成局部擴充。你新增一個 adapter 與 normalize test，而不是複製 validation、dedup、repository update 與 publish 邏輯。

【策略】先定義每個來源的責任

來源設計的核心動作是明確寫出每個 adapter 對上游的承諾。不同來源的錯誤回應方式不同，但進入 processor 的事件語意應一致。

表格是設計工具。若某一列寫不清楚，代表 adapter 與 processor 的邊界還不清楚。

【執行】HTTP adapter 轉成 DomainEvent

HTTP adapter 的核心責任是處理 HTTP 協定與外部 payload。它可以回應 status code，但不應直接決定狀態如何更新。

 1type HTTPEventHandler struct {
 2    processor *EventProcessor
 3    now       func() time.Time
 4}
 5
 6func (h HTTPEventHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 7    var raw RawHTTPEvent
 8    if err := json.NewDecoder(r.Body).Decode(&raw); err != nil {
 9        writeError(w, http.StatusBadRequest, "invalid_json")
10        return
11    }
12
13    event, err := NormalizeHTTPEvent(raw, h.now())
14    if err != nil {
15        writeError(w, http.StatusBadRequest, "invalid_event")
16        return
17    }
18
19    if err := h.processor.Process(r.Context(), event); err != nil {
20        writeError(w, http.StatusServiceUnavailable, "event_not_accepted")
21        return
22    }
23
24    w.WriteHeader(http.StatusAccepted)
25}

StatusAccepted 表示事件已被系統接收，不一定表示所有下游推送都完成。若 API 語意要求同步完成，就需要在文件與測試中明確定義成功條件。

【執行】queue adapter 控制 ack/nack

queue adapter 的核心責任是把 message lifecycle 對應到 processor 結果。processor 不應知道 ack、nack 或 delivery tag。

 1type QueueMessage struct {
 2    Body        []byte
 3    Ack         func() error
 4    Nack        func(requeue bool) error
 5}
 6
 7type QueueConsumer struct {
 8    processor *EventProcessor
 9    now       func() time.Time
10}
11
12func (c QueueConsumer) Handle(ctx context.Context, msg QueueMessage) error {
13    event, err := NormalizeQueueMessage(msg.Body, c.now())
14    if err != nil {
15        return msg.Nack(false)
16    }
17
18    if err := c.processor.Process(ctx, event); err != nil {
19        return msg.Nack(true)
20    }
21
22    return msg.Ack()
23}

這段程式把 queue 的重試決策留在 adapter。對 processor 來說，事件只是一筆 DomainEvent；對 queue 來說，錯誤需要轉成 ack/nack 策略。

【策略】共用 channel 需要 backpressure

共用 channel 的核心用途是把多個來源收斂到同一個處理 loop。它不是必要架構，但在多來源、突發流量或單一 worker 順序處理時很有用。

1events := make(chan DomainEvent, 1024)

channel 一旦有容量限制，就必須設計滿載策略。沒有滿載策略的 channel 只會把問題延後到 goroutine 堆積或 request 卡住。

 1func EnqueueEvent(ctx context.Context, events chan<- DomainEvent, event DomainEvent) error {
 2    select {
 3    case events <- event:
 4        return nil
 5    case <-ctx.Done():
 6        return ctx.Err()
 7    default:
 8        return ErrEventQueueFull
 9    }
10}

HTTP handler 遇到 ErrEventQueueFull 可以回 503。queue consumer 可以 nack 並 requeue。timer scan 可以跳過本輪。不同來源的上游回應不同，但進入 channel 的事件模型相同。

【執行】processor loop 擁有消費節奏

processor loop 的核心責任是決定事件如何被消費與停止。它應該接受 context，並在 shutdown 時停止讀取新事件。

 1type EventLoop struct {
 2    processor *EventProcessor
 3    events    <-chan DomainEvent
 4    logger    *slog.Logger
 5}
 6
 7func (l EventLoop) Run(ctx context.Context) error {
 8    for {
 9        select {
10        case <-ctx.Done():
11            return ctx.Err()
12        case event := <-l.events:
13            if err := l.processor.Process(ctx, event); err != nil {
14                l.logger.Error("process event failed",
15                    "event_type", event.Type,
16                    "subject_id", event.SubjectID,
17                    "error", err,
18                )
19            }
20        }
21    }
22}

正式實作還要處理 channel close。若事件來源會關閉 channel，讀取時應使用 event, ok := <-l.events；若 channel 由長生命週期服務持有，通常由 context 控制 shutdown。

【判讀】錯誤策略要依來源與資料語意決定

錯誤策略的核心問題是「失敗後誰能重送，重送是否安全」。HTTP、queue、timer 的答案不同。

錯誤策略不能只看技術來源，也要看資料語意。若事件已經成功更新狀態但即時推送失敗，HTTP 是否要回錯取決於 API 是否承諾推送已完成。

【策略】觀測欄位要跨來源一致

事件融合後的 log 與 metric 也應使用共同欄位。這讓你能跨 HTTP、queue、timer 比較同一類事件的行為。

 1func LogAttrsForEvent(event DomainEvent) []slog.Attr {
 2    return []slog.Attr{
 3        slog.String("event_id", event.ID),
 4        slog.String("event_type", string(event.Type)),
 5        slog.String("event_source", string(event.Source)),
 6        slog.String("subject_id", event.SubjectID),
 7        slog.Time("occurred_at", event.OccurredAt),
 8        slog.Time("received_at", event.ReceivedAt),
 9    }
10}

adapter 可以額外記錄 HTTP path、queue name 或 timer name，但共同欄位應該來自 DomainEvent。這樣排查問題時，讀者不用先知道事件從哪個來源進來。

【測試】融合測試要驗證同類事件走同一規則

多來源測試的核心目標是確認不同 adapter 產生同一種 DomainEvent，並且 processor 對它們套用同一組規則。

 1func TestHTTPAndQueueNormalizeToSameDomainEvent(t *testing.T) {
 2    receivedAt := time.Date(2026, 4, 22, 10, 0, 10, 0, time.UTC)
 3
 4    httpEvent, err := NormalizeHTTPEvent(RawHTTPEvent{
 5        EventID:   "evt_1",
 6        AccountID: "acct_1",
 7        EventName: "activated",
 8        Timestamp: "2026-04-22T10:00:00Z",
 9    }, receivedAt)
10    if err != nil {
11        t.Fatalf("normalize http event: %v", err)
12    }
13
14    queueEvent, err := NormalizeQueueMessage([]byte(`{
15        "id":"evt_1",
16        "subject":"acct_1",
17        "type":"account.activated",
18        "occurred_at":"2026-04-22T10:00:00Z"
19    }`), receivedAt)
20    if err != nil {
21        t.Fatalf("normalize queue event: %v", err)
22    }
23
24    if httpEvent.Type != queueEvent.Type || httpEvent.SubjectID != queueEvent.SubjectID {
25        t.Fatalf("sources should normalize to same domain semantics")
26    }
27}

這個測試不是要求兩個 event 完全相同。Source 可以不同；重點是 domain semantics 一致，processor 才能共用規則。

本章不處理

本章先處理多來源事件如何在單一服務內融合；queue driver、outbox 與 tracing，會在下列章節再往外延伸：

• Go 進階：Durable queue、outbox 與 idempotency
• Go 進階：Observability pipeline、metrics 與 tracing
• Backend：訊息佇列與事件傳遞

和 Go 教材的關係

這一章承接的是多來源 adapter、normalize 與 processor 的路線；如果你要先回看語言教材，可以讀：

• Go：如何新增一個即時訊息 action
• Go：如何新增背景工作流程
• Go：如何新增一種 domain event
• Go：用 interface 隔離外部依賴

小結

事件融合的核心是把來源差異限制在 adapter 與 normalizer，讓 processor 只面對一致的 DomainEvent。HTTP、queue、timer 可以有不同的 backpressure 與錯誤回應，但不應複製 domain 規則。當來源增加時，系統應該增加 adapter，而不是增加另一套狀態更新流程。

本章目標

學完本章後，你將能夠：

1. 分辨 log、metric、trace 與 profile 各自回答什麼問題
2. 設計穩定的 correlation 欄位
3. 讓 Go 服務輸出適合聚合的診斷訊號
4. 在產生端控制敏感資料進入觀測管線
5. 了解 dashboard 與 alert 為什麼需要依賴穩定欄位

前置章節

• Go 入門：log/slog：結構化日誌
• Go 進階：pprof 基礎診斷流程
• Go 進階：結構化日誌欄位設計
• Go 進階：健康檢查與診斷 endpoint
• Backend：SLI / SLO
• Backend：Metric Cardinality
• Backend：Alert Runbook

後續撰寫方向

1. Log、metric、trace、profile 分別回答哪些問題。
2. request_id、event_id、trace_id、span_id 與 correlation_id 如何分工。
3. OpenTelemetry 導入時，Go 程式碼應保留哪些清楚邊界。
4. Sensitive data policy 如何套用到 log、trace attribute 與 error event。
5. Dashboard 與 alert 應依賴穩定欄位，讓查詢與告警規則可以被重複執行。

【觀察】診斷資料要先可關聯，再談漂亮

Observability pipeline 的第一個要求是關聯能力。Log、metric、trace 的格式可以各自精緻，但欄位需要對齊，才能把同一筆請求、同一個事件、同一條 goroutine 路徑串起來。

通常會先建立幾個穩定欄位：

• request_id
• event_id
• trace_id
• span_id
• user_id 或 tenant_id

【判讀】不同訊號回答不同問題

• log：這次發生了什麼。
• metric：這類事件發生得多不多、快不快、慢不慢。
• trace：它在多個元件之間怎麼走。
• profile：CPU、記憶體、goroutine 與等待成本落在哪裡。

如果某個問題要靠自由文字 log 去猜，通常代表欄位設計還不夠穩。

【策略】敏感資料要在產生端就攔住

敏感資料政策應在產生端執行。Go 服務應該在輸出 log 或 trace attribute 前就決定哪些資訊可以外送。

常見要注意的資料有：

• token
• email
• 身分證號
• raw payload
• 內部路徑與配置

【執行】結構化 log 是 pipeline 的起點

當 Go 服務使用結構化 log 時，最重要的是欄位穩定與語意清楚。這些 log 後面可能會被：

• 集中式 log system 搜尋
• metric extraction 轉成趨勢指標
• alert rule 用來偵測異常

所以 log 欄位要維持穩定命名，分類資訊要放在結構化欄位裡。

【延伸】診斷和容量規劃要串在一起

觀測資料不只是事後排障，也會反過來影響容量規劃與 release 判斷。當你看到 goroutine 數、queue lag、DB latency 或 retry rate 持續變高，就代表系統邊界已經開始吃緊。

本章不處理

本章不會綁定特定 observability SaaS。教材重點會放在 Go 服務如何輸出穩定訊號，讓不同收集平台都能使用。

和 Go 教材的關係

這一章承接的是 Go 的結構化日誌與 runtime 診斷；如果你要先回看語言教材，可以讀：

• Go：結構化日誌
• Go 進階：pprof 基礎診斷流程
• Go 進階：結構化日誌欄位設計
• Go 進階：健康檢查與診斷 endpoint

本章目標

學完本章後，你將能夠：

1. 分辨不同測試層級各自要防的風險
2. 把 race、fuzz、load 與 chaos 放到合適的流程裡
3. 設計能回饋容量規劃的驗證流程
4. 不把端到端測試當成萬能答案
5. 讓測試結果回到 deployment 與 runtime 邊界

前置章節

• Go 入門：testing 基礎
• Go 進階：WebSocket integration test
• Go 進階：race condition 檢查
• Go 進階：table-driven test 的設計邊界

後續撰寫方向

1. CI 中哪些測試應每次執行，哪些可以排程或合併前執行。
2. Fuzzing 適合驗證 parser、normalizer 與 protocol decoder 的哪些邊界。
3. Load test 如何設定 client 數、message rate、payload size 與觀測指標。
4. Chaos testing 如何模擬 broker 斷線、資料庫延遲、server shutdown 與網路抖動。
5. 測試結果如何回饋到 capacity planning 與 feature gate。

【觀察】不同測試層級回答不同問題

可靠性驗證最怕的錯誤，是把所有測試都塞成一種樣子。不同層級應該分工：

• unit test：規則有沒有寫對
• integration test：協定與元件有沒有接對
• race test：並發邊界有沒有資料競爭
• fuzz test：輸入邊界有沒有漏掉
• load test：容量與延遲是否能接受
• chaos test：失敗發生時系統能不能復原

【判讀】race test 是輔助檢查

go test -race 能抓出實際跑到的資料競爭，但它不是正確性保證。真正的重點仍然是：

• state owner 是誰
• 哪些資料需要 lock
• 哪些資料應該只讓單一 goroutine 擁有
• 哪些資料應該複製而不是共享

【策略】load test 的輸出要能回到容量判斷

load test 不應只是跑出一個數字，還要能回答：

• 哪個 queue 開始變長
• 哪個 DB connection pool 開始飽和
• 哪種 message rate 會讓 latency 明顯上升
• 哪個 memory curve 表示需要調整 buffer 或 GC 參數

如果沒有這些觀察點，壓測結果就很難轉成實際修正。

【執行】chaos test 應該模擬真實失敗

chaos test 的重點是模擬真實世界常見的失敗：

• broker 暫時不可用
• database 延遲上升
• shutdown 中斷流量
• 網路抖動或 timeout

這些情境應該回到 graceful shutdown、retry、idempotency 與 backpressure 設計。

【延伸】測試結果應回饋到 feature gate

如果某個功能在 load test 或 chaos test 下風險太高，最直接的做法不一定是先修完整系統，也可能是先用 feature gate 逐步推出、觀察與回收。

本章不處理

本章不會綁定特定 CI 或壓測平台。教材重點會放在測試層級分工，避免把所有風險都塞進端到端測試。

和 Go 教材的關係

這一章承接的是 Go 的並發測試與可靠性驗證；如果你要先回看語言教材，可以讀：

• Go：測試基礎
• Go 進階：WebSocket integration test
• Go 進階：race condition 檢查
• Go 進階：table-driven test 的設計邊界

你應該看什麼

• Why Go was the right choice for CockroachDB
• Why CockroachDB?

這個案例告訴我們什麼

1. Go 不只適合 API，也適合超大型資料系統。
2. 大型系統裡，語言的可讀性與團隊進入門檻很重要。
3. Go 在複雜系統中的優勢，常常是讓工程複雜度可控。

可對照的公開原始碼

• cockroachdb/cockroach
• cockroachdb/cockroach-go

這是本模組最值得讀的 repo 之一。你可以對照第七模組的 package 邊界、接口設計與 composition root，理解大型 Go 系統如何組織。

本模組已開始補成正文。章節先定義問題邊界與前置脈絡，再逐步補上 transaction、outbox、跨節點 WebSocket、observability、部署與可靠性驗證的實作語意；後續仍可依實戰需求繼續擴寫。

與 Backend 教材的分工

本模組保留在 Go 進階篇，因為它要回答的是「Go 服務跨出單一 process 前，程式內部需要準備哪些 port、訊號、錯誤語意與測試合約」。具體資料庫、Redis、RabbitMQ、observability、Kubernetes 或 CI 平台操作，會放在跨語言的 Backend 服務實務指南。

章節列表

本模組和前面章節的關係

本模組適合在你已經理解單一 Go 服務的內部邊界後閱讀，用來補足生產環境常見的外部系統責任。

• 事件與狀態邊界先讀 模組四：架構邊界與事件系統。
• WebSocket lifecycle 先讀 模組二：WebSocket 服務架構。
• 測試可靠性先讀 模組五：測試與可靠性。
• 操作語意先讀 模組六：生產操作。

學習時間

目前已可作為第一輪正文閱讀，完整學習時間可隨後續擴寫再調整。