API响应新增null字段是否属于破坏性变更？

结论：这种情况通常属于破坏性变更，具体取决于客户端的实现逻辑，但绝大多数场景下会对现有客户端产生影响。

为什么算破坏性变更？ #

• 强类型语言客户端（如Java、C#）的DTO（数据传输对象）如果未定义新增的key2字段，反序列化时会直接报错。比如Java使用Jackson框架时，默认会抛出UnrecognizedPropertyException，导致请求失败。
• 客户端逻辑可能依赖“不存在的字段即无值”的假设。比如前端代码中用if (data.key2)判断是否有值，之前key2不存在时会返回undefined，逻辑上等同于“无值”；现在返回null，同样会进入false分支，但如果有代码是通过Object.prototype.hasOwnProperty.call(data, 'key2')判断字段是否存在来执行不同逻辑，新增key2:null就会触发原本不会执行的分支。
• 部分客户端会严格校验响应结构，比如使用JSON Schema验证的场景，新增未定义的字段会直接导致验证失败。

有没有例外情况？ #

如果客户端是弱类型且处理逻辑完全兼容null和“字段不存在”的情况（比如JS中直接读取data.key2并统一按“无值”处理，不区分null和undefined），那可能不会出现问题，但这种场景属于少数，不能作为变更的依据。

建议 #

API变更应优先保证向后兼容：

• 如果必须新增字段，优先返回非null的默认值（比如空字符串、空数组），而非null；
• 提前通过文档告知客户端即将新增的字段，给客户端预留适配时间；
• 可通过可选参数让客户端自主选择是否返回新增字段，避免强制变更影响现有用户。

内容的提问来源于stack exchange，提问作者yasmineek