REST API最佳实践：现有接口新增非必填参数是否需要升级版本？

新增非必填参数是否属于不良实践 #

只要严格满足向下兼容要求，在现有接口新增非必填参数属于REST API常规迭代操作，不属于不良实践。

选择直接更新当前版本还是发布新版本 #

符合以下所有条件可直接在当前版本更新 #

• 请求侧新增参数均为非必填：参数未传递时的默认值完全不改变原有业务处理逻辑，和新增参数前的执行流程完全一致
• 响应侧新增字段不会触发旧调用方序列化错误：.NET 5默认使用的System.Text.Json、Newtonsoft.Json均默认开启「忽略响应中不存在的字段」规则，绝大多数常规REST客户端也不会对多余响应字段做强校验，不会影响已有商户正常调用
• 新增参数未改变原有接口的幂等性、权限规则、错误码逻辑，原有正常请求的返回结果和更新前完全一致（仅新增字段）

如果满足以上要求，直接更新当前版本是性价比最高的方案，已有商户无需做任何改造即可正常使用，需要用到新参数的商户可根据更新后的文档自行调整对接逻辑。

出现以下情况需发布新接口版本 #

• 部分对接商户的客户端会对响应体做强校验，多余字段会触发解析报错
• 后续迭代计划会修改/删除原有参数、调整原有业务逻辑、新增必填参数
• 新增参数对应的业务场景和原有接口定位差异较大

.NET 5 实操注意事项 #

• 给请求模型的新增属性设置默认值，可通过[DefaultValue(null)]特性标注或者属性初始化赋值，避免未传参数时报错
• 可配置序列化规则忽略响应中值为null的字段，System.Text.Json可配置JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull，减少无意义的null字段返回给旧调用方
• 同步更新接口文档，明确标注新增参数的适用场景、可选值、默认逻辑

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