帮客户接手一套系统做二开，想调一个查询用户的接口，发现文档里躺着三种写法：getUserInfo、queryUser、user-detail，参数风格还不一样，一个下划线一个驼峰。问原来的开发，答复是写着写着就这样了。后端系统开发的接口规范，就像一座城市的交通规则，没立规矩的城市，堵车是必然的。
规范里最要紧的五件事
- 命名统一：要么全走RESTful风格，资源用名词、动作看请求方式，要么全用动词式命名，但只能选一种，混着用最伤人；
- 返回结构统一：状态码、提示语、数据体三段式，前端拿到任何接口都是同一个读法，错误处理写一遍就够；
- 错误码成表：每个业务错误一个编号加一句人话，联调时看码就知道哪里错了，不用每次都问；
- 分页参数统一：页码、每页条数、总数，所有列表接口一个标准，前端封装一次全站用；
- 版本管理：接口路径带版本号，旧版本标记废弃，给调用方留迁移时间，别一夜之间让别人的系统全挂。
这五件事没有任何技术难度，难的是有人定、有人守。规范文档一页纸就够，但要在第一个接口写出来之前定稿，事后再统一，成本是十倍。
规范的价值在联调时最明显：前端不用追问每个接口的字段含义和错误处理，拿到文档就能Mock着开发，后端没写完的部分前端照样推进。我们带过的项目里，立了规范又配自动文档的，联调期普遍比没规范的短一周以上，这一周就是真金白银。
对二开和接手的影响更直接：规范一致的代码库，新团队一周能上手干活；风格混乱的库，光是搞清楚每个接口的脾气就得耗半个月。接口规范实际上是给未来的人留的路标，你未必是那个受益者，但你的团队一定是。
一份规范省下的联调时间
规范立好之后，把它和自动生成的接口文档绑在一起用，前端按文档Mock数据先行开发，后端接口写完直接对上。后端系统开发的联调期因此普遍能缩短一周以上，这一周就是省出来的真金白银。
怎么让规范落地
光有文档没用，要有执行机制：代码评审时把接口命名和返回结构当作检查项，不合规的打回；用框架的统一封装强制返回结构，想写歪都难；定期跑一次接口清单核对，发现游离在规范外的及时收编。
两条建议：签约时让开发方先交一页接口规范再动工，写不出来的团队水平要打个问号；验收时抽查二十个接口，命名、返回结构、错误码对照规范逐条过。比格网络每个项目开工前都先立这份一页纸规范，成本半小时，省下的是整个项目周期里的无数次扯皮。
