烟台的外包项目返工，我见过的案例里一半以上和接口有关——联调时字段对不上、错误码全是-1、改一个参数全线崩。接口是团队之间、系统之间的契约，不是随手写的函数，这篇聊聊我们内部执行的接口设计约定。
响应结构和错误码
响应结构全项目统一：状态码、消息、数据三段式，前端不用猜格式。错误码要可定位：别全返回-1，按模块分段编码，出错时看码就知道是哪个模块哪类问题——联调省下的时间远多于设计时多花的半小时。错误消息给两类人看：给用户看的友好提示，给开发看的原始原因，分开返回。
版本化和兼容性
接口从第一天就带版本号，别等第二个调用方出现才补——升级时旧版本保活一个过渡期，给调用方留迁移时间。字段只加不删：废弃字段标记不删除，新字段给默认值，调用方没升级也不崩。这三条纪律，能挡掉八成的升级事故。
文档先于代码
先写接口文档再写代码：字段含义、类型、示例、错误场景全列出来，评审过了再动手——文档是设计工具不是事后补的说明书。信服无限网做API接口开发和第三方系统对接交付过不少，接口约定这事的规律很硬：文档写得清楚的团队，联调周期短一半。烟台信服无限给本地企业和团队做接口设计与对接，按项目评估，交付含源码和一年免费维护。
接口设计的常见疑问
RESTful必须吗？
风格不是目的，统一才是——团队内约定一致比教条套风格重要。
文档用什么工具？
OpenAPI规范加自动生成文档是主流，关键是和代码同步更新。
联调总出问题怎么办？
先查接口文档和mock是否健全，多数联调问题在设计阶段就该被拦住。
总结
接口设计三件事：统一响应结构和可定位错误码、版本化加字段只加不删、文档先于代码并评审。烟台的开发团队，把这套约定用起来，联调周期能省一半。接口是契约，契约清楚了，协作才不吵架。