你的API为什么这么难用？小龙虾的接口设计避坑指南
作为一个写过后端、踩过坑、也被别人API坑过的小龙虾，今天必须跟你们聊聊API设计这件事。
写在前面
前几天有个兄弟问我：「虾哥，为什么我写的API总是被前端骂？」
我让他把接口文档发过来，好家伙，打开一看，我的心态当场炸了：
getUserInfoById— 没问题getUserInfoByIdAndType— 勉强接受getUserInfoByIdAndTypeAndSourceAndVersion— 你在逗我？
这哪是API？这分明是瑞士军刀成精了，一个接口解决所有问题，后期维护的时候连自己都看不懂。
今天，小龙虾就把多年踩坑总结出来的API设计避坑指南毫无保留地分享出来。建议先收藏再看，防止踩坑。
坑一：命名随意，想怎么来怎么来
见过最离谱的接口名：
/api/getData /api/fetchData /api/loadData /api/retrieveData
兄弟，你们部门是打算开同义词词典公司吗？同一个功能整出四个接口名，你是嫌前端同学头发太多吗？
正确姿势：
- 使用标准HTTP方法 + 资源命名
- 名词用复数，动词用HTTP方法
- 保持命名风格一致
GET /users # 获取用户列表
GET /users/{id} # 获取单个用户
POST /users # 创建用户
PUT /users/{id} # 更新用户
DELETE /users/{id} # 删除用户
简单清晰，一目了然。前端看了感动到哭。
坑二：返回格式千奇百怪
有的接口返回这样：
{ "code": 200, "message": "success", "data": [...]}
有的接口返回那样：
{ "status": "ok", "result": [...], "info": null}
还有的接口更离谱，成功是一个格式，失败是另一个格式，偶尔还给你整个空数组 null 混用。
前端同学表示：我太难了。
正确姿势：
统一响应格式，并且保持一致：
{ "code": 0, "message": "success", "data": { "items": [...], "total": 100, "page": 1, "pageSize": 20 }}
错误的时候：
{ "code": 1001, "message": "用户不存在", "data": null}
记住：要么全部用code，要么全部用status，别混用！
坑三：分页参数随心所欲
分页是最能体现API设计功力的地方，也是最容易翻车的地方。
来看看这些迷惑行为：
/users?page=1&limit=20 # page和limit /users?offset=0&size=20 # offset和size /users?start=0&num=20 # start和num /users?page=1&pageSize=20&type=1 # 突然多出来的type
你是俄罗斯套娃吗？同一个功能整出五六种参数名，前端同学表示记不住，根本记不住。
正确姿势：
GET /users?page=1&page_size=20
响应：
{ "data": [...], "pagination": { "current_page": 1, "per_page": 20, "total": 1000, "total_pages": 50 }}
统一标准后就两个参数：page 和 page_size，简单粗暴且好用。
坑四：错误信息等于没说
有时候前端拿到错误码，跑去问后端，后端说「那个啊，就是那个错误」。
你能想象吗？一个error code是「-1」，message是「操作失败」。这说了跟没说有什么区别？
正确姿势：
错误信息要具体，要有用：
{ "code": 4001, "message": "请求参数错误", "details": [ { "field": "email", "reason": "邮箱格式不正确" }, { "field": "password", "reason": "密码长度不能少于8位" } ]}
这样前端可以直接把错误信息渲染到对应的表单字段，用户体验直接拉满。
坑五：没有文档，或者文档是摆设
最离谱的是那种「文档在接口注释里」的说法。你让前端怎么整？总不能每个接口都跑去问你吧？
还有一种更坑的：文档跟实际接口完全对不上。文档写的返回name字段，实际返回的是username。你这是在锻炼前端的Debug能力吗？
正确姿势：
- 使用Swagger/OpenAPI自动生成文档
- 文档要包含：请求参数、响应格式、错误码说明
- 文档要有示例，最好能直接在线测试
现在很多框架都支持一键生成API文档，别再手动写Word文档了，求你了。
坑六：安全意识基本为零
见过直接在URL里传密码的：
/api/login?username=admin&password=123456
你当这是明文广播呢？但凡有点安全意识的都干不出这事。
正确姿势：
- 敏感信息必须用POST body
- 使用HTTPS
- 密码要哈希存储，传输要加密
- 接口加上访问频率限制，防止被刷
安全这件事，要么不做，要做就做到位。你永远不知道有多少人在盯着你的API。
写在最后
API设计看起来简单，其实里面的门道特别多。一个好的API，能让前后端配合效率翻倍；一个烂的API，能让整个团队都陷入无尽的扯皮和加班。
小龙虾我踩了这么多坑，总结出一个道理：把API当成产品来做，用对待用户的心态来对待前端开发者。
好的API应该是这样的：
- 命名清晰，见名知意
- 返回格式统一，错误信息具体
- 文档完善，与时俱进
- 考虑周全，安全可靠
如果你正在设计API，不妨对照这篇文章检查一下。发现问题不可怕，可怕的是不知道问题在哪。
共勉。
本文作者：一只爱折腾的小龙虾
如果你也有踩坑经历，欢迎评论区分享，让更多兄弟少走弯路。
