PG官网

  项目刚进联调那周，群里消息一条接一条。前端问这个接口为什么返回了三种不同的结构，后端回那个错误码到底算参数错误还是系统错误，两个人对着文档翻半天，谁也没说服谁。这种场面做定制开发的基本都见过，问题往往不在技术难度，在接口一开始就没有一套统一的约定。这篇就把前后端接口规范里最容易扯皮的几件事说清楚，从返回格式到错误码，再到怎么让规范真正被执行。

第一步，先定返回格式，一个接口只认一种形状

  后端接口怎么返回，是最先要拍板的事。常见做法是统一包一层外壳，比如 code、message、data 三个字段，成功失败都走这一个结构，前端拿到响应先解包，再根据 code 判断业务结果。别小看这一层，它省掉的是前端每个接口单独写判断逻辑的功夫。

  数据本身怎么放也要有约定。列表接口的分页结构固定下来，比如 total、page、size、records 四个字段，各页面引用同一个分页组件；对象字段的 null 和空数组要区分清楚，空列表返回空数组而不是 null，前端渲染就不会莫名其妙报错。这些细节看起来琐碎，写进规范里，比到时候一个个对代码省事得多。

第二步，错误码怎么设计，才不至于对不上号

  错误码是接口规范里最容易打架的地方。一个接口调不通，前端要看是参数问题、权限问题还是系统异常，如果后端全部返回 200 加一个看不懂的 code，前端就只能靠猜。设计上建议业务错误码和 HTTP 状态码分开用，HTTP 状态码表达传输层面的结果，业务 code 表达业务层的具体原因，两边各管一段。

  错误码本身要可枚举、可查。定一个错误码清单，每个码对应一个固定文案，放进接口文档或者错误码表里，前端拿到 code 直接映射提示语，不用每次去问后端这是什么意思。最怕的是错误码随手写，这次返回 50001 下次返回 50002，语义还一样，前端维护映射表维护到崩溃。

第三步，字段命名和分页，约定要写在文档里

  字段命名不统一是联调里最隐蔽的坑。后端返回 createTime，前端自己字段叫 create_time，两个系统之间全靠各自转换，接口一多全是这种碎活。规范里明确一件事，字段命名用哪种风格全项目统一，接口层和前端保持完全一致，谁也不要偷偷转。

  时间格式、金额单位这些也要提前说死。时间统一一个格式传，别一个接口传时间戳一个接口传字符串；金额统一到分还是到元，写清楚单位，前端展示才不会差一位小数点。这些约定看起来都是小事，但正是这些小事，决定联调是在赶进度还是在扯皮。

第四步，规范定下来还不够，怎么保证落地

  写一份规范文档很容易，难的是大家真的按它做。项目一开始就把接口文档当成验收的一部分，接口没定稿前端不开始写页面，后端不按规范返回前端直接打回，这个关口卡住了，后面的返工就少一大半。

  工具层面也能帮上忙。接口文档平台（比如 Swagger、Apifox）生成在线文档，前端对着文档就能 Mock 数据联调，不用等后端全部写完；再往上一层可以做契约测试，自动化校验返回结构有没有变，变了第一时间报出来。规范是死的，人是活的，把检查交给工具，比靠自觉靠谱。