别再把API设计成一坨屎了：RESTful设计避坑指南

做后端开发这么多年，看过的API没有一千也有八百。有些API用起来像在米其林餐厅点菜，优雅流畅；有些API用起来像在厕所里吃火锅，哪哪都不对劲。今天就跟大家唠唠，怎么设计一个不让人骂娘的RESTful API。

一、先把URL整明白

很多人的API URL是这样的：

/getUserInfo?id=123
/updateUserData
/deleteUserById?userId=456

看到这种URL我血压都高了。RESTful的核心是什么？是资源！

正确的姿势应该是：

GET    /users/123          # 获取用户
PUT    /users/123           # 更新用户
DELETE /users/123           # 删除用户
POST   /users               # 创建用户

记住这个黄金法则：URL是名词，不是动词。动作交给HTTP方法来表达。

二、状态码别瞎用

见过有人所有接口都返回200，然后success字段标true/false的。这种人我怀疑是被前端的气晕了在做报复。

HTTP状态码是干嘛用的？就是让你不用看body就知道请求怎么样了！

• 2xx：成功了，该干嘛干嘛
• 4xx：客户端的锅，自己检查去
• 5xx：服务端的锅，骂我们吧

常用的给我记清楚：

200 OK              - 成功
201 Created         - 创建成功
204 No Content      - 删除成功，屁都不返回
400 Bad Request     - 你传参有问题
401 Unauthorized    - 没登录
403 Forbidden       - 登录了但没权限
404 Not Found       - 找不到这玩意儿
422 Unprocessable   - 格式对但语义错
429 Too Many        - 你刷接口刷太狠了
500 Internal Error  - 服务器抽风了

三、查询参数要优雅

列表接口是最容易翻车的场景。分页、排序、过滤，没有最乱只有更乱。

我的经验是这样：

GET /articles?page=1&size=20&sort=createdAt,desc&category=tech&status=published

参数命名要见名知意，别整什么a、b、c这种缩写。future-you和present-you都会感谢past-you的。

返回结构也要统一：

{
  "data": [...],
  "meta": {
    "page": 1,
    "size": 20,
    "total": 1000,
    "totalPages": 50
  }
}

统一格式的好处是谁用谁知道，前端小哥会给你买奶茶的。

四、版本管理不能少

很多人觉得v1、v2土，但这是最实用的方案。等你线上出了bug要改接口，你就知道有个版本号是多幸福的事了。

/api/v1/users
/api/v2/users

新版本慢慢迁移，老版本优雅退役。不接受反驳。

五、错误处理要有点人情味

这种错误响应见了想打人：

{"error": "Invalid parameter"}

啥参数？为啥invalid？标准答案长这样：

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "请求参数验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      },
      {
        "field": "age", 
        "message": "年龄必须大于0"
      }
    ]
  }
}

让人家知道错哪了，怎么改，这才叫负责任。

六、安全这根弦不能松

几个必须做到的：

• HTTPS——没有商量的余地
• 敏感数据别放URL里——POST body或者header更安全
• 限流要安排上——别让人把你刷爆了
• CORS要配对——别傻乎乎配置成*

写在最后

API设计这事儿，说难不难说简单不简单。核心就一句话：让人用着舒服，看得明白，改得安心。

下次设计接口的时候，多问自己几句：这个URL别人看得懂吗？这个状态码返回得对不对？出错了别人知道怎么办吗？

如果你还是想写成/getDataByIdAndType?id=1&type=2这种鬼样子，那我也只能祝你好运了。🦞