拉卡拉开放平台

业务多了一种属性，最直觉的做法是在现有结构里找个位置放进去。这个做法短期有效，长期却会埋下隐患。

直接复用的隐患

字段的含义一旦被稀释，数据就不再是数据，而是一堆需要靠猜的字符串。

三种扩展做法

• 新增平级字段：最清晰，适合属性数量可预期时；
• 新增扩展结构：把不确定的属性集中放置，适合属性多变时；
• 新增关联记录：把属性独立成另一份数据，适合属性较多且有独立生命周期时。

选择哪一种，取决于属性的稳定性：越不稳定，越应该与主结构解耦。

解析端为什么要宽容

如果解析时对未知字段直接报错，那么对方每加一个字段，你就要改一次代码。更合理的做法是：

1. 认识的字段按规则解析；
2. 不认识的字段忽略，但可选择保留；
3. 只有真正缺失的必填字段才报错。

这个原则通常被称为宽容读取，它能让系统在面对扩展时保持稳定。

字段名一旦确定很难改

字段名会进入代码、文档、日志与数据库，改动成本随时间快速上升。

• 命名应描述含义，而不是描述当前用途；
• 避免把易变信息编进字段名；
• 命名风格全系统统一。

多花十分钟想名字，能省掉日后几天的重构。

枚举值的扩展

枚举字段的扩展比普通字段更危险：调用方往往会对枚举做穷举判断，新增一个值就可能导致走到未预期的分支。

• 解析端应对未知枚举值有默认处理，而不是直接异常；
• 新增枚举值时应在文档中明确含义与出现条件；
• 不要复用或重新定义已有枚举值的含义。

枚举值只增不改，这是一条应当长期坚持的约束。

空值语义要明确

这三种情形在语义上完全不同，如果混用，后续统计与判断都会出现偏差。特别是数值字段，零与空的含义差别极大。

结构嵌套的层数

扩展结构虽然灵活，但嵌套层数过多会让解析变得困难，也让文档难以阅读。

1. 控制嵌套层数，一般不超过两到三层；
2. 每层职责单一，不要把不相关的内容塞在一起；
3. 命名保持清晰，避免多层同名。

灵活性是好事，但过度的灵活会让结构失去表达力。

文档与实现保持一致

字段扩展最常见的问题是：代码加了字段，文档没更新，或者反过来。两者不一致，调用方就会按错误的文档去理解。

一份滞后的文档，比没有文档更危险——因为它会让人确信一个错误的结论。

建议把字段定义集中管理，文档从定义生成，至少要在同一次变更里同时更新。

字段扩展考验的是克制：是图省事塞进旧结构，还是多花一点力气开一个新位置。前者省下的是今天的时间，后者省下的是明年的时间。

结构决定表达的边界。一个字段该放在哪里，表面上是命名问题，实质上是对未来变化方式的判断。

字段结构一旦稳定下来，后续所有扩展都会变得轻松；反之，每一次扩展都是在偿还最初草率设计时欠下的债。

换句话说，扩展能力体现的不是技术，而是预判。预判准了，后续改动就轻；预判错了，每一次调整都要付出额外代价。