# 接口文档只写成功返回，联调前该补齐哪些字段

- Link: https://www.itor.cn/1466.html
- Published: 2026-11-13T00:19:37+08:00
- Author: it

联调现场经常出现这样的场景：前端同事按接口文档写完了页面，一对接就频繁报错，查了
半天发现文档里只写了成功时返回什么，失败时返回什么、字段能不能为空、长度超了怎么
处理，全都没有交代。问题不在代码能力，而在文档只描述了顺利路径，把大量真实情况留给
了联调现场去猜。

接口文档缺失的信息通常集中在几类。一是错误码与错误结构，只写成功码等于没写异常处理
依据，前端无法判断该提示用户还是该重试。二是必填与选填边界，哪些字段不传会报错，
哪些可以不传，必须逐项标明。三是字段类型与长度，字符串最大多少字符、数字是否允许
小数、时间用什么格式，都要写清楚。四是空值与默认值，字段为空时返回空字符串、null
还是省略该字段，三种情况前端处理方式完全不同。五是分页与排序约定，页码从几开始、
每页上限多少、默认按什么排序，不写清楚就会出现翻页重复或漏数据。

补齐时可以按调用顺序列清单。请求前，确认地址、方法、鉴权方式和公共请求头；请求中，
逐字段核对名称、类型、是否必填、长度范围和示例值；成功响应，写清外层结构和每个业务
字段的含义；失败响应，列出主要错误码、对应含义和建议处理方式；超时与重试，说明超
时时间、是否允许重复提交、重复请求如何识别。这份清单不需要多复杂，关键是每一项都有
明确答案，而不是“视情况而定”。

更实用的做法是做一张对照表，左边写“文档当前写了什么”，右边写“联调实际需要什么”，
逐项比对。比如文档写了“返回用户信息”，联调需要知道手机号是否脱敏、昵称超长是否截断；
文档写了“操作成功”，联调需要知道失败时前端拿什么字段做提示。比对完成后，缺口一目了然，
补文档也有了优先级。

文档变更同样需要约定。口头说一句“这个字段改了”最容易埋雷，应当要求每次调整都落到
文档里，标注修改日期、修改人和影响范围，接口地址或字段含义发生不兼容变化时单独说明。
版本记录不必复杂，但要能让人回查到某次联调时依据的是哪一版约定。

接口文档的质量直接影响交付效率，写得清楚，联调和测试就能少走弯路。it数运在软件开发
协作中，把接口约定当作可核对资料的一部分，需求、字段和异常处理都尽量落到书面，让
前后端对接有据可查。文档不是写给检查看的，而是写给下一个要调用它的人看的。