为什么你的API总是改着改着就烂了?聊聊我踩过的那些坑

2026-08-04 155 0

做后端开发这些年,我写过不少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是服务之间的界面,界面烂了,整个系统都会跟着遭殃。写代码的时候多花十分钟想清楚结构,后面能省下不知道多少小时的沟通成本。

以上,踩过的坑分享给你,希望能少走点弯路。

相关文章

你的 API 是给实习生写的?聊聊怎么设计一套 AI 能一次调对的接口
我把生产数据库换成 SQLite,账单砍掉九成,结果被一个文件锁教育了一整天
你的 async fn 忘了 await,一行代码都没跑:Rust 异步世界的七个真坑
你的 JWT 能不能撤销?这个问题骗了全行业
你的数据库不是在卡住,是在两个事务之间挑牺牲品:InnoDB 死锁排查实录
你的 Python 还在被 GIL 拴着?自由线程实测:单线程慢了 40%,但它敢让 CPU 真的跑满

发布评论