做后端开发这些年，我写过不少API，也接别人写的API，也看着一些API从优雅走向崩塌。今天不聊理论，聊点真实的。
第一个坑：URL设计像写日记
见过最离谱的API URL长这样：
GET /api/v1/user/123/order/456/detail?token=xxx&from=app这还不是最绝的，有人把HTTP方法当装饰，GET/POST乱用，URL里塞满了动词：
POST /api/user/getUserInfoById
POST /api/user/updateUserInfoById
POST /api/user/deleteUserById我第一次看到的时候以为自己在读古诗词。RESTful不是让你把动作全塞进URL，而是用HTTP方法本身表达意图：GET查、POST增、PUT改、DELETE删。URL应该是名词，不是动词。
第二个坑：错误处理像在抽奖
有时候调别人接口，状态码200，但返回的数据里写着"code": 500, "message": "系统繁忙"。你得同时看HTTP状态码和业务code，两套体系混着来。
更绝的是错误信息：
{"error": "Bad request"}
{"error": "Request error"}
{"error": "Invalid request"}三个接口三种说法，你根本不知道是参数问题、签名问题还是服务器问题。错误信息要具体，要告诉调用方哪里错了、怎么改。我的经验是：
{
"code": 40001,
"message": "订单ID格式错误，应为纯数字字符串",
"field": "order_id",
"request_id": "req_abc123"
}加上request_id做什么？方便后端查日志，也方便调用方报bug的时候你能快速定位。
第三个坑：版本管理完全随缘
最常见的版本问题：v1上线一年，突然产品说要把某个字段改名。怎么办？有人说直接改，有人说加个新字段让旧的慢慢废弃。
我的建议是：URL带版本号，这是最清晰的约定：
/api/v1/users
/api/v2/users两个版本共存一段时间，通过返回数据里的version字段或者响应头告诉调用方当前版本，让下游有足够的迁移时间。别指望别人能第一时间跟着你升级。
第四个坑：文档和实现各过各的
见过最夸张的情况：文档写了三个月没更新，实际接口已经改了七八版。调用方照着文档调，十次有八次报莫名其妙的问题。
解决方案？要么强制文档即代码，用工具从代码注释生成文档；要么定好规矩，谁改接口谁负责同步文档。文档腐化比代码腐化还难救。
第五个坑：不考虑兼容性问题
你今天加了一个字段，上线了；明天产品说这个字段有些场景要返回null。好，你改了。结果调用方没升级，直接崩溃了——人家代码里没做null判断。
所以新增字段要保守，修改字段要谨慎，删除字段要等所有下游都确认。这不是保守主义，是工程现实。
我的API设计原则
总结一下，这几年下来我给自己定了这么几条规矩：
- URL是名词，方法是动词，别把两个混着用
- 错误信息要实用，能指导调用方定位和修复问题
- 版本要显式管理，不指望别人主动跟你的节奏
- 文档跟着代码走，做不到就先用工具约束
- 字段变更要向后兼容，删除前先确认没有人用了
API是服务之间的界面，界面烂了，整个系统都会跟着遭殃。写代码的时候多花十分钟想清楚结构，后面能省下不知道多少小时的沟通成本。
以上，踩过的坑分享给你，希望能少走点弯路。
