正文

做接口这些年，一个体会越来越深：接口联调出的问题，多半不是代码写错了，而是动手前没把约定捋清楚。这篇就聊聊接口设计里那些值得提前花时间的地方。

命名和格式先统一

字段名、日期格式、金额单位，先定下来再动手。一次联调里，两边一个用驼峰一个用下划线，一个传时间戳一个传字符串，光是改这些就耗掉大半天。

统一不是难事，难在事前想到。把常见的字段规范列成约定，新接口沿用，团队之间就少了很多来回。

错误要成体系

出错返回什么，得让调用方一眼看懂。直接抛内部堆栈，调用方一头雾水，只能来回问。统一的错误码和提示，能让对方自己判断问题出在哪。

错误分几类也要想清楚。是可重试的、还是参数错了、还是权限不够，分好了，调用方处理起来就有章法。

版本要留余地

接口是要变的，得给变化留出空间。把版本标识加上，改动时新旧能并行一段，调用方从容升级，系统也不至于突然断裂。

留余地也体现在兼容上。能不破坏旧行为就别破坏，实在要改，提前告知并给过渡期，合作的信任才稳。

约定先行，代码才不返工

接口开发里最花时间的，往往不是写代码，而是返工。返工多半来自约定不清：字段含义理解不一、空值处理各写各的、错误码对不上。动手前花半天把关键约定和字段说明写清楚，后面省下的可能是好几天。这份时间花在前面，回报在后面。

约定还有个好处是让协作有依据。前后端、和外部伙伴对接时，有文档对着看，争议就少。文档不用写得多正式，关键信息说到位就行。技术协作里，清晰的约定比聪明的代码更能抵住时间的考验。

约定写好了，还要放对地方。前后端都放在随手能查的地方，改动时同步更新，才不会文档一套、代码一套。约定是协作的一部分，不是写完就归档的文件。让它一直活着，返工自然就少。

关于接口设计

文档要写多细

关键约定和示例写清即可，过细反而难维护，重在准确。

小项目也要这么多规矩吗

简单项目可精简，但命名的统一和错误的规范建议保留。

把功夫下在前面

命名统一、错误成体系、版本留余地，联调才省事。接口设计这件事，值得在动手前多花点时间。先把约定讲清，后面会顺很多。这类问题，信服无限衡水团队在实际项目里经常遇到，也总结了一些可复用的经验。做这行17年，累计上线300+小程序、交付100+商业APP，底子是这么一点点攒的。