本章目標

學完本章後，你將能夠：

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. 理解 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. 分辨 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. 理解 shutdown、readiness 與 connection draining 的順序
2. 看懂平台 timeout 對 Go server 的影響
3. 分辨 health 與 readiness 的不同責任
4. 把 memory limit 與 Go runtime 的資源管理接在一起
5. 讓部署平台和程式彼此遵守同一份合約

前置章節

• Go 進階：GC 與 memory limit
• Go 進階：graceful shutdown 與 signal handling
• Go 進階：健康檢查與診斷 endpoint
• Backend：Graceful Shutdown
• Backend：Failover

後續撰寫方向

1. SIGTERM、shutdown timeout、readiness false 與 connection draining 的順序。
2. Kubernetes terminationGracePeriodSeconds 與 Go http.Server.Shutdown 如何配合。
3. Load balancer idle timeout 如何影響 WebSocket heartbeat 參數。
4. Container memory limit、Go memory limit 與 OOM killer 之間的關係。
5. systemd restart policy 與 health endpoint 的責任分工。

【觀察】平台會主動改變服務生命週期

Go 程式不會在真空裡執行。Kubernetes、systemd、load balancer、container runtime 都會影響服務何時接新請求、何時開始收尾、何時被強制終止。這表示程式不只要「能跑」，還要能跟平台協調。

常見的生命週期訊號有：

• SIGTERM
• readiness false
• HTTP shutdown
• connection draining
• memory pressure

【判讀】health 與 readiness 有不同合約

health 通常表示服務自己還活著，readiness 則表示它是否適合接新流量。

• health 可以用來讓平台知道 process 還活著。
• readiness 可以用來讓 load balancer 停止送新請求。

如果兩者混在一起，部署時就容易出現「服務還沒收尾就被塞新流量」或「其實還能接流量卻被誤判下線」的問題。

【策略】shutdown 應該是可預期流程

典型的 shutdown 順序是：

1. 接收到停止訊號。
2. 先把 readiness 關掉。
3. 停止接新流量。
4. 讓現有 request / worker / websocket 收尾。
5. 超時後強制結束。

這個順序能讓平台有時間把流量移走，也讓應用有時間清理資源。

【執行】資源限制要和 runtime 觀念一起看

container memory limit 不只是部署平台的事，也會影響 Go runtime 的行為。當可用記憶體變少時，應用更需要控制：

• goroutine 數量
• buffer 大小
• cache 體積
• in-memory queue 長度

如果這些沒有限制，平台的 OOM killer 可能會比你的 graceful shutdown 先來。

【延伸】平台合約要被測試

部署平台合約需要在測試或預備環境驗證。至少要確認：

• shutdown 時 request 是否停止接入
• worker 是否有機會收尾
• WebSocket 是否有 close path
• health 與 readiness 是否分工清楚

本章不處理

本章不會完整教 Kubernetes 或 systemd 操作。重點是讓 Go 程式設計能清楚暴露平台需要的生命週期訊號。

和 Go 教材的關係

這一章承接的是 Go 的 shutdown 與 runtime 限制；如果你要先回看語言教材，可以讀：

• Go 進階：GC 與 memory limit
• Go 進階：graceful shutdown 與 signal handling
• 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 的設計邊界