gRPC Proto Pool Resource Design¶
概念概覽
池型資源 Proto 設計原則¶
核心知識¶
池型資源 Proto 設計原則¶
錯誤設計（硬編欄位）：
message PlayerResourceState {
int64 stamina_current = 5;
int64 stamina_max = 6; // 硬編，日後擴充有 wire format 風險
int64 stamina_recover_at = 7;
}
正確設計（repeated 結構）：
message PlayerResourceState {
repeated PoolResource pool_resources = 5; // 未來新增池型資源不需改 schema
}
message PoolResource {
ResourceType type = 1;
int64 current = 2;
int64 max = 3;
int64 recover_at = 4;
}
廢棄欄位處理¶
Proto field number 一旦使用就不可重用。廢棄欄位必須在 message 層加 reserved 宣告，防止 wire format 衝突：
message PlayerResourceState {
reserved 7, 8, 9, 10; // 舊 stamina 硬編欄位，已廢棄
reserved "stamina_max", "stamina_recover_at";
}
命名原則¶
Proto message 命名應反映**業務語義**，不需要對應 DB table 命名。PlayerCurrency 已無意義，應改為 PlayerResourceState。
經驗教訓¶
-
Proto 的 repeated/map 結構讓未來新增池型資源不需要改 schema，避免 client/server 版本不一致時的靜默資料損壞
-
Proto 廢棄欄位必須加 reserved 宣告，應納入 code review checklist
-
Proto message 命名反映業務語義，不需要與 DB table 命名一致
常見陷阱¶
-
硬編每種池型資源的獨立欄位（stamina_max、stamina_recover_at），日後擴充時有 wire format 不相容風險
-
廢棄 Proto 欄位後直接重用 field number，造成舊版 client 解析錯誤
最佳實踐¶
-
Pool 型資源的 proto 設計用 repeated/map 結構，不要硬編每種資源的獨立欄位
-
每次廢棄欄位都要在 message 層加 reserved
宣告
相關概念¶
- buf Proto Code Generation
- Game Resource Vertical Table
- Hero Unlock Idempotency
- Proto Delivery Boundary Design
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Pool Resource Stamina Routing — 共享：
game-backend,pool-resource/ 獨特：honest-boundary,schema
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-19 | 04c2b73d-c00e-4eaf-959f-0dbf0f224e24 | 確立了池型資源的 Proto 應使用 repeated PoolResource 結構而非硬編欄位，以及廢棄欄位必須加 reserved 宣告的 checklist 要求 |