游戏客户端架构 / 系统课时
ID、枚举和默认值怎么定
ID、枚举和默认值怎么定
配置读取最怕“今天能用,半年后含义变了”。稳定的 ID、枚举和默认值本质上是在固定数据契约:记录能长期被引用,状态不会因排序或文案变化而改义,缺省值也不会和真实业务值混在一起。
学习目标
- 设计不会因改名、排序或迁移而变化的主键。
- 为枚举分配稳定、可扩展的存储值。
- 区分“未填写”“使用默认值”和“业务上就是零”。
ID 只负责身份,不承担业务含义
稳定 ID 最重要的规则是一旦发布就不要改变。不要把名称、章节序号、品质或当前排序编码进主键,否则任何重命名和重排都会引发级联迁移。
例如道具 itemId=1001 可以从“生命药水”改名为“强效生命药水”,商店、掉落、任务奖励仍然引用 1001。若使用 hp_potion_small 这类带语义字符串作为永久主键,名称或分类策略变化后,团队很容易陷入“改 ID 还是保留旧名字”的两难。
ID 的作用域也要先约定清楚。可以全局唯一,也可以只在某类配置内唯一,但读取端、校验器和文档必须采用同一种规则。
枚举值要稳定,展示文本要可变
枚举最容易犯的错误,是把显示文案或当前数组下标直接当存储值。显示文本可能国际化,排序也可能调整,因此真正写进配置的数据应使用明确、稳定的编码。
下面的完整 Python 示例演示读取一条道具配置:ID 必须为正整数,品质只接受预定义编码,stackLimit 缺省时使用 1。
from enum import IntEnum
class Quality(IntEnum):
COMMON = 1
RARE = 2
EPIC = 3
def load_item(raw: dict) -> dict:
item_id = raw.get("itemId")
if not isinstance(item_id, int) or item_id <= 0:
raise ValueError("itemId must be a positive integer")
try:
quality = Quality(raw["quality"])
except (KeyError, ValueError) as exc:
raise ValueError("invalid quality") from exc
stack_limit = raw.get("stackLimit", 1)
if not isinstance(stack_limit, int) or stack_limit < 1:
raise ValueError("stackLimit must be >= 1")
return {
"itemId": item_id,
"quality": quality.name,
"stackLimit": stack_limit,
}
if __name__ == "__main__":
item = load_item({"itemId": 1001, "quality": 2})
print(item)预期输出:
{'itemId': 1001, 'quality': 'RARE', 'stackLimit': 1}这里的 1、2、3 一旦进入正式数据就不要因排序变化而重新编号。新增品质时追加新值即可;若删除某个旧枚举,也应保留对旧值的迁移或拒绝策略,而不是把旧编号悄悄分配给新含义。
默认值必须区分缺失和真实业务值
默认值不是为了“让所有字段都有东西”。它应该代表一个明确、长期稳定的业务语义。
| 场景 | 推荐做法 | 原因 |
|---|---|---|
| 未填写时采用通用行为 | 读取端提供默认值 | 减少重复配置 |
0 本身有业务含义 |
不用 0 表示缺失 |
避免真假值混淆 |
| 字段必须由策划决定 | 设为必填并校验 | 防止静默使用错误默认 |
| 旧版本没有新字段 | 通过版本迁移或兼容默认处理 | 保证历史数据可读 |
例如 stackLimit 缺省为 1 很自然,因为“普通不可堆叠道具”就是明确行为;但 sellPrice 若缺省为 0,可能既表示“免费”,也可能表示“不可出售”,这时应拆成 sellable 与 sellPrice,或明确用空值表示未配置。
发布后再改规则要走迁移
真正危险的不是第一次设计得不完美,而是后续直接改变既有含义。把 RARE 从 2 改成 3、把默认堆叠数从 1 改成 99、重用已经下线的 ID,都会让旧数据在没有报错的情况下被解释成另一种结果。
因此发布后修改 ID、枚举或默认值,应先列出受影响字段,再写显式迁移或兼容逻辑,最后用旧配置和新配置同时验证读取结果。只要坚持“身份不变、编码不复用、默认值有单一含义”,配置数据就能在长期迭代中保持可解释性。