校验、导出与代码生成

Category

production / config 子树。节点定位：错误处理成本由发现位置决定——校验左移、结构定义先行、引用校验、环境隔离、代码生成的收益与代价。

Definition

配置管线里，一个错误的处理成本几乎完全由它被发现的位置决定。同样的字段类型写错，在编辑器里当场标红，是几秒钟的事；到测试环境加载时报错，是半天；到线上表现为规则异常，就可能是几天的事故加一轮补偿。所以校验体系的核心不是“查得多严”，而是“查得多早”。校验做得好不好，就看错误能不能在离犯错最近的那一刻被拦住。

导出和代码生成则是编辑与运行之间的桥梁。这两件事做得顺，配置管线的存在感很低，策划改完东西自然就生效了；做得别扭，管线会变成一个需要专人伺候的黑箱，每次发布都在祈祷。

Problem

同一个字段类型错误，编辑器标红是几秒、测试环境报错是半天、线上异常是几天事故加补偿。校验的核心不是「多严」而是「多早」；环境隔离是最容易失守的一环（测试表进生产）；校验通过不等于内容正确——合法但离谱的数值要有语义校验兜底。

校验为什么应该尽量左移

同一个错误在不同阶段被发现的成本差异，值得单独算一遍：

• 编辑期：填错的瞬间被提示，成本几乎为零，改动者自己就能修。
• 提交期：提交时跑增量校验，成本是几分钟的等待和一次重新提交。
• 发布期：导出或审批时被拦截，成本是一次作废的发布和一轮排查。
• 加载期：服务端启动或热更时失败，轻则回退版本，重则进程起不来。
• 运行期：数据合法但语义错误，以玩家投诉或指标异常的形式暴露。

常见的左移手段并不复杂：编辑界面按字段定义做即时校验，本地工具提供一键自检，提交钩子跑增量检查。这些手段共同的目标，是把错误尽量压在最便宜的区间。一个管线成熟与否，看它的错误分布就能猜出大概——错误集中在编辑期说明体系在起作用，集中在运行期说明校验基本缺位。

结构定义是一切校验的前提

想在校验期拦住错误，先要有一个明确的“什么是错的”的定义。这通常落在一份结构描述上：每张表有哪些字段、什么类型、取值范围、是否必填、枚举值有哪些。没有这份定义，校验只能靠散落在代码里的 if 语句和人的记忆。

结构定义真正值钱的地方在于它把隐式知识显式化了：

• “这个字段是百分比，最大一百”从口头约定变成机器可查的规则。
• “这个枚举只能取这几个值”让填错在录入时就被发现。
• 字段用途说明跟着定义走，而不是散落在聊天记录里。
• 字段之间的复合约束（A 大于 B、二者不能同时为空）也能进定义，让业务规则同样可查。

维护结构定义本身有成本，表多字段多的项目里尤其明显。常见的松动方式是允许表格式先行为先、定义后补，短期省事，长期代价是定义与实际数据脱节，校验形同虚设。定义漂移本身也值得被监控：当校验规则和实际数据长期对不上时，通常不是数据的错，而是定义老了。

引用校验：最常见的断裂点

配置错误里出现频率最高的一类，是引用断裂：这张表填了一个 ID，那个被引用的东西不存在。掉落表引用了不存在的物品，界面引用了不存在的图片，任务链引用了不存在的下一步。引用校验因此通常是校验体系里回报最高的投入：

• 跨表引用要有全量检查：单看一行数据无法判断引用是否成立，只有把所有表放在一起才能确认。
• 删除被引用的内容应该被拦截或至少被警告，而不是静默通过。
• 引用关系本身值得可视化或清单化，“这个 ID 被哪些地方用到”是策划和程序都高频需要的问题。

引用校验的性能往往被低估。表和引用多了以后，全量校验可能从几秒涨到几分钟，人们开始绕过它，校验形同虚设。所以引用校验通常需要配增量机制：平时只查改动涉及的引用，全量校验留给发布前的最后关口。

语义校验：从合法到合理

结构合法、引用完整的配置，仍然可能是错的：掉率加起来超过百分之百，经济产出远大于回收，两个互斥的活动被排在同一时间。这一层通常被称为语义校验，它和结构校验的本质区别是规则来自业务而不是类型系统：

• 概率类：各档位概率之和、期望产出的上界。
• 经济类：产出与回收的比值区间、货币沉淀速度。
• 时间类：活动区间不重叠、前置任务早于后续任务。
• 依赖类：新玩法依赖的系统在目标版本已经存在。

语义规则难以一次写全，通常的做法是随事故积累：每出一次规则事故，问一句“这条规则能不能变成校验”，能就沉淀进校验库。几年下来，一个项目的校验库内容，往往就是它的事故史的反面。

导出环节真正在解决什么

导出不只是格式转换。它通常同时承担几件事：把编辑格式转换成运行时格式，把一份源数据分发到多个目标端，把人类友好的宽表折叠成程序友好的结构。这些转换里藏着管线的常见事故点：

• 同一份源数据导出多个目标时，目标之间的版本要能对上，否则客户端和服务端各拿一份不一致的数据。
• 转换过程中的默认值和类型收窄会悄悄吞掉异常数据，导出成功不等于内容无损。
• 导出产物是发布物，值得像代码制品一样被版本化和存档，而不是每次发布临时生成、用完即弃。

一个值得养的判断习惯：导出环节出的问题，往往表现为“数据是对的，程序读出来不对”。遇到这类问题，先怀疑转换层，再怀疑加载层，最后才是怀疑填表的人。

导出层还有一个常被忽略的天然优势：它是所有目标端数据的必经之路，在这里做一次发布前的终检，往往比在各加载端分别设防更便宜。

环境隔离为什么容易失守

配置管线连接着多个环境：策划的自测环境、开发环境、测试环境、预发布、线上。环境之间的墙，是最容易在赶工期时被拆掉的。失守的典型形态包括：

• 测试数据混进线上批次，玩家看到内部占位文案或测试奖励。
• 为了赶一次活动临时打通环境，之后再也没关上。
• 各环境配置来源不一致，测试环境验证通过的批次在线上加载出不同结果。
• 环境清单被硬编码在工具里，新加一个环境要改代码，隔离策略逐渐与现实脱节。

环境隔离的常见做法是让环境成为发布目标的一等概念：发布时明确选择目标环境，环境之间不共享可写入口，跨环境的借调用有期限的通道。隔离每宽松一分，之后每次发布的心智负担就重一分。

代码生成的收益与代价

从结构定义生成加载代码和访问接口，是很多团队的选择。收益通常很直接：字段访问获得类型安全，结构变更时编译期就能暴露受影响的代码，散落在各处的手工解析逻辑消失。代价则容易被轻描淡写：

• 生成物是否入库、何时再生成、谁负责再生成，需要明确约定，否则会出现改了定义忘了生成、或生成物被手工修改的死局。
• 生成器本身成为项目基础设施，它的升级和兼容要按正式工具维护。
• 报错的间接性增加：运行时看到的是生成代码，排查时要回到定义和生成规则。

代码生成适合结构相对稳定、读方众多的场景。如果结构天天变、读方只有一两处，手工维护的轻量方案有时反而更省。

校验通过不等于内容正确

校验体系再完整，也只能覆盖被规则化的那部分判断。数值手感好不好、活动节奏顺不顺、文案是否得体，仍然要靠人来看。所以成熟的管线通常在自动校验之后，还保留人工确认的位置：

• 发布前的 diff 审阅：这次批次到底改了什么，由人来扫一遍。
• 灰度观察：先小范围生效，看真实表现再放量。
• 生效后抽检：关键内容在测试服或内部账号上实际走一遍。

自动校验负责人不会犯的错，人工确认负责只有人会犯的错，两者互不替代。把全部希望压在任一侧，都会在某个时候付出代价。

常见误区

• 校验集中在加载期，服务端启动报错成为发现配置问题的第一现场。
• 只有结构校验没有引用和语义校验，拦得住格式错误拦不住规则事故。
• 把导出当成临时脚本，产物不版本化，出问题无法对证是哪一批数据。
• 环境之间长期打通，测试数据流到线上，回收无期。
• 生成代码被手工修改，再生成时改动无声丢失。

校验、导出与生成的共同目标只有一个：让配置从编辑到生效的每一步都可检查、可追溯、可回退。做到这个程度，管线的存在感越低，说明它做得越好。

Used By

配置校验体系建设（结构/引用/语义三层）；导出与发布链路设计；代码生成的适用判断；环境隔离与权限防呆。

Related

关系链：校验左移 → 结构定义 → 引用校验 → 语义校验 → 导出与环境隔离。上游：config/02（表结构，校验的前提）。下游：production/05 的实战案例（环境失守的事故形态）。

Reference

本页为工程经验归纳。