做后端开发这么多年，我见过太多惨不忍睹的API了。有的API返回的数据结构让人想哭，有的状态码乱得像在玩俄罗斯轮盘，还有的安全性做得跟纸糊的一样。今天咱们就来聊聊，怎么设计一个让人用着舒服、看着舒心、出了问题好定位的API。
一、URL不是随便甩的字符串
很多新手写API URL，完全是想到什么用什么：/getUserInfo、/user/query、/fetchDataOfUser...这都啥玩意儿？
RESTful API的第一条铁律：名词复数形式表示资源，HTTP动词表示操作。
正确打开方式：
GET /users- 获取用户列表GET /users/123- 获取ID为123的用户POST /users- 创建新用户PUT /users/123- 完整更新用户PATCH /users/123- 部分更新用户DELETE /users/123- 删除用户
还有，别TM在URL里用动词！/getUsers是错误的，应该用GET /users。动词应该体现在HTTP方法里，这是基本素养。
二、状态码不是用来玩的
我见过太多返回200 OK但实际业务失败的API了。这种行为跟在方便面里吃出异物然后说明书上写"优质产品"有啥区别？
状态码是对HTTP协议的基本尊重。
常用状态码清单：
- 2xx - 成功系列
200 OK- 请求成功，正常返回201 Created- 资源创建成功204 No Content- 请求成功但没有返回内容（比如DELETE）
- 4xx - 客户端错误系列
400 Bad Request- 请求参数有问题401 Unauthorized- 需要认证403 Forbidden- 没权限404 Not Found- 资源不存在422 Unprocessable Entity- 请求格式对但语义错（比如验证失败）
- 5xx - 服务器错误系列
500 Internal Server Error- 服务器抽风了503 Service Unavailable- 服务暂时不可用
最搞笑的是有人404 Not Found当400 Bad Request用，500当万金油。这跟"遇到问题就重启"的运维思路有的一拼。
三、响应结构要有一致性
有的API这个接口返回一个结构，另一个接口返回完全不同的结构。这就像去不同餐厅吃饭，有的用筷子有的用勺子有的上手抓——用户体验极差。
统一的响应格式是API的门面。
// 推荐：统一响应包装
{
"code": 0,
"message": "success",
"data": {
// 实际数据
},
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100
}
}
// 错误示例：裸数据返回
{
"id": 123,
"name": "张三"
}统一响应格式的好处：前端好处理、错误好定位、接口文档好生成。什么？你说裸数据更简洁？你去跟前端同学打一架吧。
四、分页不是你想的那样
很多人写分页就直接limit和offset往上招呼。问题是：
- 数据量大了之后
offset性能会爆炸 - 快速翻页时容易跳到奇怪的位置
推荐方案：游标分页（Cursor Pagination）
// 请求
GET /users?limit=20&after=cursor_value
// 响应
{
"data": [...],
"pagination": {
"nextCursor": "abc123",
"hasMore": true
}
}用最后一条记录的ID作为游标，性能稳定、用户体验好。特别是那种"无限滚动"的场景，游标分页是标配。
五、版本管理：别让改API变成灾难
API上线后总会遇到要改的时候。直接改？等着被前端寄刀片吧。
版本管理策略：
- URL版本：
/api/v1/users、/api/v2/users- 最直观，但也最麻烦 - Header版本：
Accept: application/vnd.myapp.v2+json- 优雅但前端不爱用 - 参数版本：
/users?version=2- 简单但不够规范
我的建议：URL版本最靠谱。为什么？因为它最显眼、最难忽略、最容易追踪。让你改API的时候想不通知调用方都难。
另外，旧版本至少保留6个月。给调用方留够迁移时间，别做那种"今天发版明天就砍旧接口"的缺德事。
六、安全性：别让你的API变成公共厕所
API安全是个大话题，但有几个基本点必须做到：
- 必须用HTTPS：这都啥年代了还在用HTTP？
- 认证授权要分清：Authentication vs Authorization，别混淆
- 敏感数据要脱敏：返回密码MD5、身份证号是几个意思？
- 限流要配上：防止被人一轮请求干翻
- CORS要配对：别
Access-Control-Allow-Origin: *直接往上整
// 正确的CORS配置
Access-Control-Allow-Origin: https://your-frontend.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization七、文档是最好的售后
再好的API，没有文档就是灾难。文档要包含：
- 每个接口的用途
- 请求参数说明（类型、必填/可选、默认值、取值范围）
- 响应示例（成功和失败的都要有）
- 错误码清单
- 调用示例（curl、JavaScript、Java、Go都来点）
工具推荐：Swagger/OpenAPI、Apifox、Postman。自动化生成文档不丢人，丢人的是文档跟代码对不上。
总结
API设计看起来是小事，但体现的是工程师的基本功和职业素养。一个好的API：
- URL清晰明了，看就知道是干啥的
- 状态码用的恰到好处，不会误导人
- 响应格式统一，处理起来顺心
- 分页策略合理，性能有保障
- 版本管理规范，迁移不抓狂
- 安全措施到位，不会被人轻易干翻
- 文档完善，有问题自己查
记住：API是给被人用的，不是给你自己看的。设计之前多想想调用方的心情，毕竟谁用谁知道的道理都懂。
好了，今天的分享就到这里。有问题评论区见，别客气。
