做后端开发这么多年，看过的API没有一千也有八百。有时候我真想把某些API设计者拉出来吊打一顿——不是因为我脾气差，而是他们的设计实在让人血压飙升。

今天咱们就来盘点一下RESTful API设计中最常见的七宗罪，保证你看完感同身受。

第一宗：动词乱用

最常见的问题就是动词滥用。POST用来更新，GET用来删除，PUT用来创建——总之就是怎么乱怎么来。

// 经典反面教材
GET /api/deleteUser?id=123
POST /api/getUserInfo
PUT /api/createOrder  // 创建居然用PUT

REST的精髓是什么？是用HTTP方法表达操作语义。GET就是获取，POST就是创建，PUT就是完整更新，PATCH就是部分更新，DELETE就是删除。记住这个口诀：查 GET、创 POST、改 PUT/PATCH、删 DELETE。

第二宗：命名放飞自我

有些人命名API跟给自己孩子起名似的，想怎么来就怎么来：

/api/getUserInfoByIdAndType
/api/fetch_data_for_display
/api/userDetailQuery
/api/getAllTheUsersPlease

API命名应该简洁、一致、可预测。建议采用名词复数形式，配合HTTP方法区分操作：

GET    /users          # 获取用户列表
GET    /users/{id}     # 获取单个用户
POST   /users          # 创建用户
PUT    /users/{id}     # 更新用户
DELETE /users/{id}     # 删除用户

第三宗：状态码随便返回

见过最离谱的是一个接口，成功了返回200，失败了也返回200，然后在body里写个{"code": 500, "message": "服务器错误"}。我当时就懵了——你这200到底是想说成功还是失败？

HTTP状态码是有明确语义的：

• 2xx：成功（200 OK, 201 Created, 204 No Content）
• 3xx：重定向
• 4xx：客户端错误（400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity）
• 5xx：服务器错误

请严格遵守这套语义，别自己发明轮子。

第四宗：分页是什么不存在

“我这接口返回一万条数据很轻松的”——这是某个同事的原话。拜托，一次性返回一万条数据，数据库压力、网络传输、前端渲染，每个环节都在哭。

标准分页应该是这样：

GET /users?page=1&per_page=20

// 响应
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1000,
    "total_pages": 50
  }
}

或者用游标分页，适合大数据量和高并发场景：

GET /users?cursor=abc123&limit=20

第五宗：版本管理？不存在的

很多项目的API是裸奔的：/api/users。然后业务迭代一多，接口参数变了，返回结构变了，前端天天报bug。

API版本管理是必须的：

/api/v1/users   # 第一版
/api/v2/users   # 第二版，breaking changes

版本号放在URL里是最直观的方式，别搞什么Header版本或者日期版本，那叫自找麻烦。

第六宗：错误信息等于没说

当接口出错时，最怕看到这种响应：

{
  "error": "Error",
  "message": "Something went wrong"
}

我就想问一下：到底是什么错误？哪里出错了？怎么才能修复？

一个好的错误响应应该包含：

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

让调用者知道错在哪里、为什么错、怎么改正，这才是正确的错误处理姿势。

第七宗：安全？不熟

见过太多裸奔的API了。没有认证、没有授权、敏感数据明文传输——这是等着被人薅羊毛还是被人脱裤？

基本的安全措施必须有：

• HTTPS必须启用，别跟我讲什么性能损耗
• 认证机制（JWT、OAuth2等）必须要有
• 敏感操作需要二次验证
• 接口要有流量限制，防止恶意请求
• 日志要记录，但别记录敏感信息

总结

API设计看似简单，实则门道很深。一个好的API应该是什么样的？

简单、一致、可预测、安全、有文档。

做到这五点，你的API至少不会被人骂。做到更好，那你就是个合格的后端工程师了。

下次有人问你API设计经验，直接把这七宗罪甩他脸上，保证他心服口服。