Twirp Error Code Single Channel Architecture¶
概念概覽
架構核心¶
核心知識¶
架構核心¶
MatchRPG Server 的錯誤碼系統是**單通道設計**：只有 Twirp meta.error_code（string 格式）是實際在 runtime 傳遞的錯誤碼。Proto enum（如 commonv1.ErrorCode）不做 wire serialization，只是 string emit 的來源。
Dead Code 識別¶
commonv1.ErrorCode enum 是 dead code（0 個 runtime consumer）。ErrorHandlingReference.md 描述的是這個已死掉的 enum，不是實際運行的錯誤碼系統。這是一個長期存在的架構誤解。
安全性含義¶
因為是 string emit 而非 wire integer，重新編號（如 Dungeon 從 1-20 改到 3000-3099）不影響協議相容性。但已生成的 pb.go 和 Unity CS 檔案仍需要重新 regenerate。
經驗教訓¶
-
回答架構問題前必須先讀設計文檔（SoT），不能憑假設
-
proto enum 存在 ≠ proto enum 有 wire 效果，需區分 string emit vs wire serialization
-
文檔描述的系統可能已是 dead code，需要交叉驗證 runtime consumer 數量
常見陷阱¶
-
ErrorHandlingReference.md 描述的是死掉的 commonv1.ErrorCode，不是實際錯誤碼系統，容易誤導
-
刪除 dead enum 前需確認 Unity 客戶端是否有 literal 比對（外部依賴不易發現）
最佳實踐¶
-
架構澄清必須以 doc 33 §1.1 range table 為 SoT
-
新模組分配錯誤碼區段前，先 grep 確認無衝突
相關概念¶
- Dungeon Reward Dual-Path Contract
- Error Code Range Collision
- PD Spec Rebase vs Patch Strategy
- proto-dead-code-pattern----dangling-------dangling---
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Twirp Error Handling — 共享：
rpc,twirp/ 獨特：api,error-handling
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-07 | 13536126-c4f1-4c71-ae73-a6544e9167bf | 確認 Twirp meta.error_code 是唯一實際的錯誤碼通道，proto enum 不做 wire serialization |