约定先于编码
接口路径、请求方法、参数位置、响应结构、错误码，这些必须在动手前落到文档里。口头约定在联调阶段必然产生分歧。
响应结构统一为固定外层加数据体，前端可以写一套通用的请求拦截处理，不必为每个接口写不同的解析逻辑。
错误码区分业务错误与系统错误。业务错误需要前端展示具体提示，系统错误展示统一提示并上报，两者的处理路径不同。错误码要预留区间，不同模块按段分配，避免新增业务时和已有编号撞车。
Mock 的定位
Mock 的作用是让前端在后端接口完成前就能推进，而不是替代后端。Mock 数据要按约定结构生成，结构正确比内容真实更重要。
Mock 与真实接口的切换通过配置控制，不要靠改代码注释。环境变量或代理配置是更干净的方式，能避免误提交。
接口一旦完成就应尽快切到真实数据。长期依赖 Mock 开发，会积累大量只在 Mock 下成立的假设，切真实数据时集中爆发。Mock 服务最好由后端维护或者由接口定义自动生成，前端手写容易与约定逐渐偏离。
契约的维护
字段一旦约定并开始使用，修改就要走同步流程。新增字段前端可以忽略，删除或改类型必须双方确认。
枚举值的含义要写清楚，只给数字编号会让前端只能硬编码映射，后端调整时前端不知情。
分页、排序、筛选这类通用参数定义一次，所有列表接口保持一致。参数名五花八门会让调用方反复查文档。通用参数如果要调整默认值，等于改变行为，需要按不兼容变更来对待。
处理联调中的时间差
后端未完成时前端用 Mock 推进，后端完成但前端未接入时后端用测试脚本验证。两边各自有验证手段，能减少互相等待。
联调阶段准备一份冒烟用例清单，覆盖正常、边界、异常三类输入。逐条核对响应，比自由点击更容易发现问题。
真实联调时优先跑通核心主流程，再补边界。一开始就纠结边缘分支，会拖慢整体进度。联调环境的数据要能被重置，否则用例跑第二遍结果就不可复现。
分歧预防与联调收尾
空值与缺失要区分：字段返回空值还是干脆不返回，前端处理方式不同。约定里必须明确，否则会出现判空逻辑到处补的情况。
时间格式统一为带时区的标准格式，不要混用时间戳和格式化字符串。前端展示层做本地化转换，不要依赖后端已转换。金额、比例这类需要精度的数值，明确用字符串还是数值传输。
接口文档要补齐最终实现与约定的差异说明，把临时加的字段正式化或者清理掉。遗留的临时字段过一段时间就没人敢删了。
把联调中发现的问题归类：是约定不清、实现偏差还是需求变更。归类后修订约定模板，下一次能少踩同样的坑。
