【数据存储】数据字典建设：玩家变量键名的团队协作规范

服务端跑久了，HUMAN变量里的键名会失控：同义键、僵尸键、魔法数字遍地都是，接手的人根本分不清哪个还在用。数据字典是治本工具。本文讲996引擎项目里变量字典的建立与维护方法。

场景与痛点

一个运营三年的服务端，HUMAN变量轻松超过四百个键。新功能上线前，开发者想复用已有变量却不敢：不知道旧键是否还有别的逻辑在写。重复造键又造成数据冗余，同一个人气值存在两个键里，两边数值还对不上。根因是键名定义只存在于某段代码里，没有全局视图。

实现思路

建一份变量字典文档，每个键登记五项：键名、含义、取值范围、读写模块、生命周期。写键的模块必须在字典登记，评审时对照检查。进一步把键名定义集中到一个Lua表里，代码全部引用常量，杜绝手拼字符串。

关键实现

local VKEY = {
    ARENA_PT   = { desc = "竞技场段位分", min = 0, max = 3000, save = 1 },
    DAILY_SIGN = { desc = "连续签到天数", min = 0, max = 999,  save = 1 },
    FB_SWEEP   = { desc = "副本扫荡次数", min = 0, max = 20,   save = 0 },
}
function VKEY:write(actor, name, val)
    local def = assert(self[name], "未登记变量键:" .. tostring(name))
    if val < def.min or val > def.max then
        error("变量越界:" .. name .. "=" .. val)
    end
    setplayvar(actor, "HUMAN", name, val, def.save)
end

读侧同样走字典入口，越界立即报错，脏数据在写入那一刻就被拦住。

function VKEY:read(actor, name)
    assert(self[name], "未登记变量键:" .. tostring(name))
    return getplayvar(actor, 2, name)
end

细节与避坑

save位对应setplayvar的持久化参数，临时变量标0可以减少存档体积。历史僵尸键不要在字典里删除，标记deprecated并注明替代键，老存档里还留着数据，直接删记录会丢排查线索。上线新键前用getplayvar抽查老玩家样本，确认没有历史同名键冲突。字典表在服务启动时加载，运行期只读不改。

小结

变量字典把散落在几百个脚本里的隐式知识集中成一份活文档，写入统一入口后还附带校验能力。维护成本很低，收益随项目时间线性放大。

延伸思考

字典表可以导出成CSV给运营做数据看板，每个键的实时分布一目了然。配合定期扫描线上样本，能自动发现字典外的新增键，防止有人跳过规范直写变量。