上周同事老李差点被产品经理拉去祭天。起因是一个简单的订单状态更新功能，前端显示一直卡在“支付中”，用户投诉电话都打爆了。查了一整天，最后发现后端返回的字段是 order_status，而前端代码里写的却是 status。就这么一个命名差异，导致整个流程断掉。
看似小问题，实际杀伤力巨大
很多人觉得，接口字段对不上改一下就行，能有多大事？可真到联调阶段，前后端各执一词。前端说：“你文档写的是 status，我照着写的。” 后端翻出最新接口说：“我早就改成 order_status 了，你们没同步？” 谁都没错，但就是跑不通。
更离谱的是，有些团队用 Swagger 或 YAPI 管理接口，但改了代码却忘了更新文档。新人接手直接按文档开发，结果上线就崩。这类 bug 不会报错，数据静默丢失，排查起来像在黑屋子里摸开关。
举个真实例子：用户头像加载不出来
有个项目，用户上传头像后，后端返回的结构是：
{
"data": {
"avatar_url": "https://cdn.example.com/avatar.jpg"
}
}但文档里写的是：
{
"data": {
"headImg": "..."
}
}前端按文档取 headImg，自然拿不到值。测试环境还能手动 mock 数据蒙混过关，一上生产，大量用户反馈“头像没了”。
怎么避免这种低级错误？
光靠嘴皮子约定没用，得有硬手段。我们组现在强制要求三点：第一，所有接口必须走 API 文档工具，提交代码要附文档更新记录；第二，前后端共用一份 TypeScript 接口定义，生成统一类型文件；第三，每天早上自动跑一次接口契约测试，字段对不上直接告警。
有个小工具叫 openapi-typescript，能根据 Swagger 自动生成 TS 类型。后端改了个字段，前端一拉代码立刻报错，根本躲不掉。虽然刚开始大家都嫌烦，但现在反而省了无数扯皮时间。
别等出事才想起补漏
很多团队都是出了问题才临时开会对齐接口。其实花十分钟定个规范，能省下十个小时的排查。特别是多人协作、跨团队对接时，别想当然地认为“他应该知道”。系统不会替你背锅，用户也不关心技术细节，他们只看结果——功能能不能用。
下次接到新接口，别急着写代码。先确认三件事：字段名、数据类型、空值处理方式。哪怕对方说是“临时改动”，也得留记录。不然半夜被叫起来修 bug 的人，只会是你自己。