字段是会变的：目录站给合作方的数据字典怎么做版本管理
字
很多目录站都有一份对外的数据说明页，写着每个字段叫什么、什么类型、取值有哪些。写完那天下班，第二天改了一个字段的含义，文档就开始说谎了。
这类文档会失效不是因为没人维护，而是因为它缺少一个机制：字段变了之后，怎么通知、怎么过渡、什么时候可以真的改。
图片来源：网络，版权归原作者所有，侵权请联系删除
先把变更分成三类
不同性质的变更，下游的承受能力完全不同。分类是版本管理的前提。
| 变更类型 | 例子 | 对下游的影响 | 处理方式 |
|---|---|---|---|
| 兼容变更 | 新增一个字段 | 无 | 直接发，记进日志 |
| 需过渡变更 | 改字段含义、收窄取值 | 可能算错 | 预告 + 并存期 + 到期切换 |
| 破坏性变更 | 删字段、改字段名、改类型 | 直接报错 | 尽量不做，做要留双写 |
兼容变更：新增字段
新增最省心，多数下游会忽略不认识的字段。但有三件事仍然要做：写进变更日志、标注首次出现的版本号、说明它是否必填。
「是否必填」这一项容易被忽略。一个新增字段如果未来会变成必填，要在新增时就写明计划，否则下游永远不会主动适配。
需过渡变更：改含义和收窄取值
这类最危险，因为它不会报错，只会让下游静默算错。
典型的例子：把一个状态字段从「0/1 表示无效有效」扩展成「0/1/2/3 分别表示待审、正常、下架、失效」。原来当布尔值用的下游，会把 2 和 3 都当真，数据立刻失真。
推荐流程是三步。第一步，提前发布预告，说明变更内容、生效日期、以及下游需要做什么。预告期视合作方数量定，通常不少于一个月。第二步，并存期——新旧字段同时提供，旧字段继续按旧口径输出，新字段按新口径。第三步，到期后切换，旧字段进入弃用状态，再保留一段时间才真正移除。
并存期的长短取决于下游的响应速度。给一个不带日期的「未来会废弃」是无效的，必须有明确日期。
破坏性变更：能不做就不做
删字段和改字段名，能避免就避免。真要做的场景通常是字段本身设计错了，留着会持续误导。
做法是新字段先上线，双写一段时间，等确认所有下游都切过去了，再下线旧字段。判断「都切过去了」的依据是日志——统计旧字段的被调用次数，降到零或者只剩自己的内部调用，再下线。
如果合作方是通过文件或者批量接口拿数据，还要考虑他们手上的历史文件。这种情况下可以在数据里保留一个版本号字段，让下游自己知道这一批是什么口径。
版本号怎么发
不用搞得很复杂。语义化版本那套（主版本.次版本.修订号）足够用，关键是定义清楚哪一档对应什么。
- 修订号：文档修正、补充说明，字段本身没变。
- 次版本号：有兼容变更（新增字段），或者开始预告某个需过渡变更。
- 主版本号：有破坏性变更生效。
版本号要出现在两个地方：文档页的显眼位置，和数据本身。数据里带版本号非常有用——出问题时能直接判断对方拿到的是哪一版口径。
变更日志要写什么
一条变更记录至少五样：日期、版本号、字段名、变更类型、下游需要做什么。最后一项最重要，也最常被省略。
「字段 status 增加取值 2、3」这种记录没用。要写成「字段 status 增加取值 2（下架）、3（失效）。原来按布尔值处理的下游需要改为枚举判断，2026 年 3 月 1 日前有效，之后 2、3 会被当作有效值」。
日志要能订阅。RSS 或者邮件都行，关键是让合作方不用每天来翻页面。目录站自己有邮件通知体系的话，挂上去成本很低。
文档页本身怎么组织
字段说明页建议五列：字段名、含义、取值示例、是否必填、最后更新日期。再加一个筛选或者搜索，字段多了之后没有检索等于没有。
每个字段要有稳定锚点，方便合作方直接链到某一行讨论。URL 里带锚点的链接是可以分享的，这比「你看第三节第二个表」清楚得多。
内部字段和对外字段要分开
不是所有字段都该进对外字典。内部状态标记、审核备注、临时字段这些不该暴露——暴露了就等于承诺维护它，以后想改都改不了。
明确一份「对外契约字段」清单，这份清单之外的字段，合作方不应该依赖。写进合作协议里更好，省得日后扯皮。