Go Nil vs Empty Map in Validator Placeholder

概念概覽

語意區分

核心知識

語意區分

在 Go 後端 validator 的分階段實作（Phase ½/3）中，nil 與 map[string]int{} 代表完全不同語意：

• nil map：Noop validator「未回傳任何結果」— 代表校驗未執行（Phase ½ 的 placeholder 行為）
• map[string]int{}（empty map）：validator 執行完畢，結果是「使用量為零」

Cross-Validation 的 Nil Guard

func crossValidateItemUsage(actual map[string]int, reported map[string]int) (bool, error) {
    if actual == nil {
        // Noop validator — 尚未實作，跳過校驗
        // TODO(phase3): 移除此 guard，上線真實 validator
        return false, nil
    }
    // actual 為 empty map → 正常校驗（玩家使用量應為零）
    ...
}

若沒有 nil guard，Noop validator 回傳 nil 時，cross-validation 會把它當作「使用量零」來比對，造成所有使用道具的玩家都被誤判 mismatch 並受到懲罰。

防護機制

• Noop validator 和 gRPC stub 加入 TODO(phase3) 標記，Phase 3 上線前必須移除 nil guard 並換入真實實作
• 測試預期值改為 false, nil（跳過），不是 true, nil（通過）

經驗教訓

• Go nil map 與 empty map 語意完全不同，在 validator 設計中不能混用

• 分階段實作（phase pattern）中的 nil guard 必須配合 TODO 標記，否則 Phase 3 上線後容易被遺忘

• 誤判 nil 為 empty 直接影響玩家懲罰機制，屬於高嚴重性語意錯誤

常見陷阱

• Noop validator 回傳 nil，cross-validation 未加 nil guard → 所有使用道具玩家誤判 mismatch

• Phase 3 validator 上線後忘記移除 nil guard → validator 永遠不執行，安全機制靜默失效

• 測試只測 happy path（通過），未測 noop path（跳過）→ 無法提早發現語意錯誤

相關概念

• Bug Fix vs Capability Expansion Phase Splitting
• Circuit Breaker Outcome Semantics

相關視角

以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：

• Game Item Exemption Resource Architecture — 共享：game-backend / 獨特：architecture-pattern, item-system

來源 Sessions

日期	Session	貢獻摘要

| 2026-04-02 | d088842d-abec-48fc-8a1a-779a5f74e05d | 釐清 Go 中 nil map 與 empty map 在 validator placeholder 設計的語意差異，以及 cross-validation 中必須加 nil guard 的原因 |

---

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-04-02