API版本控制最佳实践：v1与v2接口的数据返回规则疑问

1. 调用v1的Get接口：绝对不能返回v2新增数据 #

• v1的API契约已经固化（要支持18个月），客户端完全基于v1的实体结构开发。突然多出未约定的字段，很容易导致强类型语言客户端反序列化失败，甚至引发业务逻辑异常。
• 保持v1接口的行为一致性是版本支持的核心原则，必须严格按照v1定义的实体结构返回数据，v2的新增属性一律不允许出现在v1的响应里。

2. 调用v2的Get接口：必须返回完整的v2实体数据 #

• v2的设计初衷就是兼容v1并扩展，所以v2接口的契约就是返回包含v1所有字段+新增属性的完整v2实体，不能只返回v1的数据。
• 如果客户端只需要v1级别的数据，应该让他们继续调用v1接口——API版本化的意义就是让不同需求的客户端自主选择对应版本的接口，而不是让高版本接口降级输出。

3. 新增属性的空值处理规则 #

• 可选属性：可以返回null、空字符串或业务默认值（比如数字类型返回0），但必须在v2的API文档里明确标注该字段的可选性，以及空值/默认值的业务含义。
• 必填属性：绝对不能留空返回。要么在数据迁移或初始化时提前填充合理的默认值（比如从现有数据推导、设置行业通用默认），要么在接口逻辑里确保生成合法值，否则会违反v2的契约，导致客户端处理异常。

核心原则总结 #

1. 每个版本的API严格遵守自身契约，不跨版本输出字段
2. 新增字段优先设计为可选，降低数据兼容成本
3. 文档同步更新，明确告知客户端每个字段的规则和含义

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