云上接口升级：给旧客户端留出兼容空间

在华为云等云平台运行应用时，服务端可以较快更新，手机应用或合作系统却未必同步升级。例如，订单接口需要增加物流信息，如果顺手修改了原有字段结构，旧客户端可能无法解析。接口升级前，应先检查已有调用方依赖的约定。

一、把字段含义当作约定

字段名相同，并不代表接口没有变化。将金额从元改为分、把字符串编号改成数字，都会改变调用方的理解。新增可选字段通常比修改已有字段更温和，但仍需检查客户端是否拒绝未知字段。字段类型、单位和是否必填，都应在接口说明中写清楚。

二、明确空值和未知状态

物流单号未生成时，返回空字符串、空值或省略字段，可能触发不同的页面逻辑，应选择一致的表达。增加订单状态时，也要考虑旧客户端遇到陌生状态如何展示。可以约定保守的兜底文案，避免默认归入“已完成”等含义明确的状态。

三、为不兼容变化安排过渡

如果确实需要调整返回结构，可以通过独立版本逐步迁移，让旧版本在约定期限内继续服务。同步更新文档与示例，并提前说明替代方式。迁移计划应考虑低频调用方，不能只根据短时间没有请求就认定旧版本已经无人使用。

四、用旧调用方式检查新服务

发布前保留代表性的旧请求及预期结果，检查字段类型、错误响应和关键业务含义。除了验证新功能，也要让旧客户端或其测试程序连接新服务。上线后观察各版本调用量与异常情况，结合调用方确认再安排旧版本退出。

使用 API 网关管理入口，有助于组织接口路由，但业务兼容性仍需要开发与调用双方共同验证。一次稳妥的升级，应让新能力可用，也让已有流程有足够时间完成迁移。