Circuit Breaker Outcome Semantics¶
概念概覽
Tri-State 語義定義¶
核心知識¶
Tri-State 語義定義¶
Circuit Breaker 的結果應為三態而非二態： - Success：呼叫成功，breaker 應記為正面信號 - Failure：呼叫失敗，breaker 應記為負面信號，累積後觸發熔斷 - Ignored：呼叫結果不應影響 breaker 計數
Context 錯誤的語義歸屬¶
context.Canceled → Ignored // 客戶端主動取消，不懲罰下游服務
context.DeadlineExceeded → Failure // 下游服務超時，是真實的可靠性問題
理由：context.Canceled 是呼叫方主動中止（例如使用者離開頁面），與下游服務健康度無關；若計入 Failure 會導致 breaker 被客戶端行為誤觸發。context.DeadlineExceeded 則反映下游真實的慢回應問題，應計入。
測試保護¶
context.Canceled → Ignored 這個決策**必須有明確的測試用例**，防止未來維護者「修正」成 Failure 而不知道這是刻意的業務決策。
經驗教訓¶
-
context.Canceled 設為 Ignored 是業務語義選擇而非實作細節，必須在測試和 PR 描述中明確說明理由
-
tri-state 比 bool 更能精確表達 circuit breaker 的語義，Ignored 狀態是關鍵設計
常見陷阱¶
-
將 context.Canceled 誤計為 Failure 會讓客戶端行為誤觸發 breaker，造成誤熔斷
-
缺乏測試保護的語義決策容易被後人「修正」成看似合理但錯誤的行為
最佳實踐¶
-
為 context.Canceled → Ignored 的語義決策寫明確的測試用例，並在測試名稱或注釋中說明業務理由
-
PR 描述中區分 runtime 語義決策與 API 簽名重構，不要混在同一個 PR
相關概念¶
- API Refactoring PR Splitting Strategy
- Go Middleware Chain Ordering
- Go Nil vs Empty Map in Validator Placeholder
- RPC Idempotency for Gacha / Random Pack Opening
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-26 | 59325dc8-0079-4c87-a93e-f2734386d733 | 定義了 Circuit Breaker tri-state（Success/Failure/Ignored）中 context 錯誤的明確語義歸屬，以及這個決策的業務理由 |