干了五年后端，踩过的API设计坑能绕地球三圈。今天不整虚的，把那些年用头发换来的经验抖落抖落。
一、RESTful？那玩意儿是给教科书写的
刚入行那会儿，谁要是不懂RESTful，简直不好意思跟人打招呼。什么GET/POST/PUT/DELETE，资源路径要名词复数，状态码要精确到不能再精确。我曾经为了追求「真正的RESTful」，把一个简单的用户状态更新硬生生拆成了三步：先GET用户信息，再PATCH状态，最后DELETE缓存。
结果呢？产品经理说「这个操作太慢了，能不能点一下就完事？」我差点当场去世。
后来我才明白，RESTful是个指导原则，不是圣经。你在GitHub的API文档里都能看到PATCH方法返回200状态码的同时还附带点额外数据，妥妥的「不规范」操作。人家照样是业界标杆。
忠告：过度设计是病，治法很简单——先写能跑的代码，再谈美感。
二、错误处理这块儿，大部分人都在裸泳
我见过最离谱的API是这样的：
// 成功返回
{"code": 200, "message": "success", "data": {...}}
// 失败返回
{"code": 500, "message": "Internal Server Error"}兄弟，你这500是给机器看的还是给人看的？前端程序员看到这玩意儿，除了骂娘还能干啥？
一个合格的错误响应长这样：
{
"error": {
"code": "USER_NOT_FOUND",
"message": "找不到这个用户，可能是ta删号跑路了",
"details": "user_id: 12345",
"help": "https://api.example.com/docs/errors#USER_NOT_FOUND"
}
}你看，机器知道怎么解析，人知道发生了什么，还知道去哪查文档。这才叫工程化。
三、版本管理：别等到线上炸了才想起来
URL版本？Header版本？我见过最骚的操作是把版本号写在了请求体的某个字段里——那哥们振振有词：「这样前端改版本不用改代码」。
我当时就想问：万一我SDK要自动升级怎么办？难不成还要解析你的请求体？
URL版本是最直观的方式：
GET /api/v1/users
GET /api/v2/users简单粗暴，但有效。配合deprecation header一起用，体验更佳：
Deprecation: Sat, 01 Jan 2028 00:00:00 GMT
Sunset: Sat, 01 Jan 2030 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"告诉调用方「该升级了」，这才是负责任的做法。
四、分页这事儿，门道比你想的多
「用limit+offset啊，简单！」——说这话的人肯定没经历过数据量大了之后的酸爽。
问题在哪？假设你翻到第100页，每页20条，数据库要跳过2000条数据才能给你返回结果。当数据量大的时候，这玩意儿能让你喝完一杯咖啡还没查完。
更好的方案是Cursor-based Pagination（游标分页）：
GET /api/users?limit=20&cursor=eyJpZCI6MTAwMH0返回的时候带上下一页的cursor：
{
"data": [...],
"pagination": {
"next_cursor": "eyJpZCI6MTAyMH0",
"has_more": true
}
}不管数据有几千万条，查询速度基本稳定。当然，如果你做后台管理需要跳页，offset也不是不能用——加个场景判断就行。
五、幂等性：这玩意儿平时不觉得，出事了要命
你有没有想过：用户网差，连点了两下创建订单按钮，咋整？
答案就是幂等性。一个幂等的接口，调用一次和调用N次，效果是一样的。
实现方式很多：
- 给请求加唯一ID，后端做去重
- 利用数据库唯一索引
- 用分布式锁
我现在的做法是：所有写接口必须支持幂等，代价是慢个几毫秒，但能省下无数个排查「为什么这条数据出现了两次」的深夜。
写在最后
API设计没有银弹，但有坑可以绕。记住几点：
- 不要为了规范牺牲可用性
- 错误信息要能帮人解决问题
- 版本管理要提前做，别等出事了再打补丁
- 分页看场景，别无脑limit+offset
- 幂等性是写接口的基本素养
代码是给人看的，顺带让机器跑而已。这句话真的不是在骂人。
有问题欢迎评论区喷，记得带上场景和证据。👋
