# 小程序接口联调总卡住，前后端先约定哪些字段规范

- Link: https://www.itor.cn/320.html
- Published: 2026-09-27T15:26:12+08:00
- Author: it

接口联调频繁返工，往往并非技术能力不足，而是双方从起点就对字段定义缺乏共识。前端
默认拿到的是数字，后端实际返回字符串；前端按空数组处理，后端却传了空值；时间格式
一边用时间戳，另一边用日期字符串。每暴露一处差异，就得改一次代码、再联调一轮。真正
拖慢进度的不是编码速度，而是接口约定没有在动手前讲明白。

联调启动前，先把基础规则敲定

字段命名必须统一。要么全用小写加下划线，要么统一驼峰，选定一种并落到文档里，切忌
同一接口混用两种风格。命名还要消除歧义，比如用“创建时间”而非“时间”，用“订单编号”
而非“编号”。

数据类型要逐一标注。数字、字符串、布尔值、数组、对象，都应在文档中写明。尤其注意
数字与字符串的区分，像编号类字段用字符串更稳妥，可避免超出精度范围。

空值处理要达成一致。字段无数据时，是返回空字符串、空数组、空对象，还是直接返回空
值，抑或干脆不返回该字段——这四种做法对前端判断逻辑影响极大，必须提前统一。

时间格式要固定。用时间戳还是日期字符串，日期字符串采用哪种格式，时区如何处理，都要
写清楚。建议统一用带时区的标准格式，减少跨地区项目的理解偏差。

错误码结构要规范。成功与失败分别返回什么结构，错误码是数字还是字符串，错误信息放在
哪个字段，都要固定下来。前端才能写出一套通用的错误处理逻辑，而不是每个接口单独适
配。

请求与响应示例要写到能直接对照

示例还要覆盖异常情况。比如参数缺失时返回什么，权限不足时返回什么，数据为空时返回
什么。把这些边界情况写进文档，联调时就不用靠猜。

联调阶段用一张表记录问题

准备一张问题跟踪表，每次联调发现的问题都记下来，并标注属于哪一类。前端问题，比如
参数拼错、请求方式用错；后端问题，比如返回结构不符、字段缺失；需求理解偏差，比如
双方对某个字段的业务含义理解不同。

上线前做一轮接口回归检查

接口联调通过不代表上线后没问题。上线前要把所有接口再跑一遍，重点检查三类情况：修改
过的接口是否影响了关联接口，公共字段的调整是否同步到所有调用方，错误码结构是否保持
一致。

回归检查不需要每次全量跑，但涉及公共字段、公共方法、公共错误码的改动，必须全量验证。
修改一处影响另一处，是上线后最容易出现的问题。

接口规范的价值在于长期稳定

一套清晰的字段规范，短期看是多花了时间写文档，长期看是减少了反复沟通和返工。项目
交接时，新成员看文档就能理解接口结构；项目维护时，改一处不用翻遍所有代码找关联。