# 旧接口文档和现行代码对不上，按什么顺序梳理

- Link: https://www.itor.cn/1473.html
- Published: 2026-11-13T02:09:20+08:00
- Author: it

联调阶段最让人头疼的情形，往往不是代码写不出来，而是照着旧接口文档传参，接口却直接
返回字段缺失。开发者一遍遍核对请求地址和参数名，看起来都和文档一致，问题却始终存在。
多数情况下，不是请求写错了，而是文档停留在几个月前的版本，代码早已改过几轮。这类
问题在软件维护中非常常见，处理的关键不是急着改代码，而是先按固定顺序把差异梳理清楚。

先分清三类不一致

接口文档和现行代码的差异，通常可以归为三类。第一类是字段增减，代码新增了必填字段，
文档里没有；或者某个字段已经废弃，文档仍在要求传。第二类是字段改名，含义没变，但
命名从一种写法换成了另一种，旧文档没有同步。第三类是字段含义变化，名字没动，取值
范围、单位或默认值却变了，比如状态码从数字改成字符串，时间从秒改成毫秒。三类问题
的排查方式不同，混在一起看只会越查越乱。梳理时先给每个差异打上类别标签，后续处理
才有明确方向。

梳理顺序从现行请求样例开始

建议的顺序是先从现行代码或测试环境拉取一份真实可用的请求样例，包含完整的请求方法、
路径、请求头和参数体。以这份样例为基准，再打开旧文档逐字段对照。对照时给每个字段
标注四种状态：一致、新增、已废弃、含义变更。标注完成后，反向再查一遍文档中存在但
样例中没有的字段，确认是可选字段还是已经删除。这个顺序的好处是以实际运行结果为准，
而不是以文档为准，避免在错误的基础上反复推演。

一份可执行的核对清单

逐字段标注之后，还需要从整体结构上补一轮核对。请求方式是否一致，GET和POST的混用是
常见问题。参数位置是否一致，查询参数、路径参数和请求体参数容易错位。必填性是否一致，
文档写可选、代码要求必填的情况最容易在联调时暴露。返回结构是否一致，包括外层包装、
分页字段和空值处理方式。错误码是否一致，尤其是业务错误码的范围和提示信息。这五项
核对完成后，接口的基本轮廓才算对齐。

梳理完成后要留档

差异梳理完不能只停留在聊天记录里。建议在文档中保留一份变更说明，记录本次核对的时间、
对照的代码版本、每类差异的处理结果。字段增减和改名直接更新到文档正文，含义变化单独
加注说明。这样下次再有人按文档调用接口，看到的就是当前有效的信息。留档的意义不只是
方便别人，也是给自己下一次维护留一条清晰的线索。

维护节奏与边界

接口文档很难做到和代码完全同步，但可以把差距控制在可管理范围内。比较实际的做法是
每次接口有变更时，同步更新文档中对应的字段说明，并在版本记录里写一句变更原因。对于
历史遗留的旧文档，不必一次性全部重写，优先处理仍在使用中的接口。需要说明的是，不同
团队的协作方式和发布流程不同，具体节奏应结合实际情况安排，涉及对外接口的变更，还
应以相关官方规定和专业人士意见为准。把梳理顺序固定下来，比追求一次做完更可持续。