游戏客户端架构 / 系统课时

ID、枚举和默认值怎么定

ID、枚举和默认值怎么定

配置读取最怕“今天能用,半年后含义变了”。稳定的 ID、枚举和默认值本质上是在固定数据契约:记录能长期被引用,状态不会因排序或文案变化而改义,缺省值也不会和真实业务值混在一起。

学习目标

  • 设计不会因改名、排序或迁移而变化的主键。
  • 为枚举分配稳定、可扩展的存储值。
  • 区分“未填写”“使用默认值”和“业务上就是零”。

ID 只负责身份,不承担业务含义

稳定 ID 最重要的规则是一旦发布就不要改变。不要把名称、章节序号、品质或当前排序编码进主键,否则任何重命名和重排都会引发级联迁移。

例如道具 itemId=1001 可以从“生命药水”改名为“强效生命药水”,商店、掉落、任务奖励仍然引用 1001。若使用 hp_potion_small 这类带语义字符串作为永久主键,名称或分类策略变化后,团队很容易陷入“改 ID 还是保留旧名字”的两难。

ID 的作用域也要先约定清楚。可以全局唯一,也可以只在某类配置内唯一,但读取端、校验器和文档必须采用同一种规则。

枚举值要稳定,展示文本要可变

枚举最容易犯的错误,是把显示文案或当前数组下标直接当存储值。显示文本可能国际化,排序也可能调整,因此真正写进配置的数据应使用明确、稳定的编码。

下面的完整 Python 示例演示读取一条道具配置:ID 必须为正整数,品质只接受预定义编码,stackLimit 缺省时使用 1。

python
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)

预期输出:

text
{'itemId': 1001, 'quality': 'RARE', 'stackLimit': 1}

这里的 1、2、3 一旦进入正式数据就不要因排序变化而重新编号。新增品质时追加新值即可;若删除某个旧枚举,也应保留对旧值的迁移或拒绝策略,而不是把旧编号悄悄分配给新含义。

默认值必须区分缺失和真实业务值

默认值不是为了“让所有字段都有东西”。它应该代表一个明确、长期稳定的业务语义。

场景 推荐做法 原因
未填写时采用通用行为 读取端提供默认值 减少重复配置
0 本身有业务含义 不用 0 表示缺失 避免真假值混淆
字段必须由策划决定 设为必填并校验 防止静默使用错误默认
旧版本没有新字段 通过版本迁移或兼容默认处理 保证历史数据可读

例如 stackLimit 缺省为 1 很自然,因为“普通不可堆叠道具”就是明确行为;但 sellPrice 若缺省为 0,可能既表示“免费”,也可能表示“不可出售”,这时应拆成 sellable 与 sellPrice,或明确用空值表示未配置。

发布后再改规则要走迁移

真正危险的不是第一次设计得不完美,而是后续直接改变既有含义。把 RARE 从 2 改成 3、把默认堆叠数从 1 改成 99、重用已经下线的 ID,都会让旧数据在没有报错的情况下被解释成另一种结果。

因此发布后修改 ID、枚举或默认值,应先列出受影响字段,再写显式迁移或兼容逻辑,最后用旧配置和新配置同时验证读取结果。只要坚持“身份不变、编码不复用、默认值有单一含义”,配置数据就能在长期迭代中保持可解释性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

ID、枚举和默认值怎么定

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通