华华仕在线houshionline.com
技术 · 开发实战

接口改字段名 为什么老客户端就报错

对外约定换了词,装在用户手机里的旧版本不会跟着改。

技术组约 3 分钟技术 · 开发实战

服务端把一个字段从旧名字改成新名字,测试环境一切正常,上线之后老版本的客户端开始报解析错误,用户看到的只是白屏或者一句含糊的失败提示。

接口是对外的约定,字段名一改,等于把双方约定的语言换了词。已经装在用户手机里的旧版本不会跟着更新,它仍然按旧名字去找数据,找不到就当缺失。

有的框架在反序列化时对未知字段宽容、对缺失字段严格,缺了必填项就直接抛出异常,客户端拿不到内容,只好弹一个自己也说不清的错误。

更隐蔽的是名字看着差不多的情况,比如把缩写换成全拼,人一眼能看懂,程序却只认完全一致的字符串,大小写和连字符差一点都会失败。

灰度发布能暴露这类问题,但要真的把旧版本客户端纳入验证。只在浏览器里点几下新页面,测不到安装包里那套旧代码。

稳妥的做法是新旧字段并存一段时间,服务端同时返回两份,客户端逐步迁移,等旧版本的调用量降到很低,再删除旧字段。

需要更名的字段,可以在网关层做一层映射,把请求与响应里的名字翻译成对方认识的样子,改动集中在一处,排查也方便。

版本号与文档要同步,接口文档里注明字段的生命周期和下线时间,避免有人照着旧文档开发,也避免运维在半夜被叫起来救火。

所以字段名不是内部实现细节,而是对外承诺的一部分。改名之前先想清楚谁还在用旧名字,比事后补兼容要省力得多。

本文由本站编辑部整理撰写,内容仅作知识分享,不构成医疗、投资、法律建议,转载请注明出处。

读者留言 · 3 条

接
服务端开发

我们现在改名一律双写一段时间,旧版本降到零才敢删,麻烦但省心。

客
移动端开发

客户端最怕静默失败,能不能给个明确的错误码,排查起来快很多。

文
接口维护

文档里写上字段下线日期之后,来问的人明显少了。

留言为读者个人观点,不代表本站立场。