RESTful API设计：从混乱到优雅的进化之路

如果你写过API，一定遇到过这样的场景：同事问你某个接口怎么用，你打开文档一看，发现文档和代码对不上。或者更惨，你自己写的API，三个月后自己都忘了当初为什么这么设计。

RESTful不是教条，是约定

很多人把RESTful当成一种必须严格遵守的规范，其实它更像是一种约定俗成的沟通方式。就像英语有语法，但日常对话中大家都能理解一样，RESTful的目的是让API更容易理解和使用。

核心原则很简单：

• 用URL表示资源
• 用HTTP方法表示操作
• 用状态码表示结果

URL设计：让资源自己说话

好的URL设计应该像自然语言一样直观。来看一组对比：

糟糕的设计：

GET /getUserById?id=123
POST /createNewUser
POST /deleteUser?id=123
GET /getAllUsers

优雅的设计：

GET /users/123
POST /users
DELETE /users/123
GET /users

看出区别了吗？好的URL设计把动作交给了HTTP方法，URL本身只描述资源。这样即使不看文档，你也能猜出这些接口大概是干嘛的。

HTTP方法：不只是GET和POST

很多人习惯只用GET和POST，但其实HTTP提供了丰富的语义：

幂等性是个重要概念。幂等的操作执行多次和执行一次效果相同。比如DELETE删除一个不存在的资源，返回404或204都可以，但结果是一样的。而POST创建资源每次都会生成新的，所以不是幂等的。

状态码：别只用200和500

我见过太多API不管成功失败都返回200，然后在body里自己定义一套状态码。这完全是画蛇添足。HTTP状态码已经提供了丰富的语义：

• 200 OK – 请求成功
• 201 Created – 资源创建成功
• 204 No Content – 成功但无返回内容（如DELETE）
• 400 Bad Request – 请求参数错误
• 401 Unauthorized – 未认证
• 403 Forbidden – 无权限
• 404 Not Found – 资源不存在
• 409 Conflict – 资源冲突（如重复创建）
• 422 Unprocessable Entity – 语义错误（如邮箱格式不对）
• 429 Too Many Requests – 请求过于频繁
• 500 Internal Server Error – 服务器内部错误

合理使用状态码能让客户端更容易处理错误。比如看到401就知道要重新登录，看到429就知道要限流。

错误处理：给开发者有用的信息

错误响应应该包含足够的信息帮助开发者定位问题。一个好的错误响应长这样：

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "请求参数验证失败",
    "details": [
      {
        "field": "email",
        "issue": "格式不正确"
      }
    ],
    "requestId": "req_abc123xyz"
  }
}

包含错误码、可读的错误信息、具体细节、以及请求ID（便于后端排查日志）。这比一个简单的{“error”: “bad request”}有用得多。

版本控制：API也会变老

API不是一成不变的。当需要破坏性变更时，版本控制能救你一命。常见的版本策略：

URL路径版本：

/v1/users
/v2/users

Header版本：

Accept: application/vnd.api+json;version=2

URL版本更直观，Header版本更优雅。选哪个取决于你的团队偏好，但一定要有版本策略。

分页：大数据的必修课

当列表数据可能很大时，分页是必须的。常见的分页方式：

Offset分页：

GET /users?offset=20&limit=10

简单直观，但深度分页性能差（OFFSET 1000000会很慢）。

Cursor分页：

GET /users?cursor=eyJpZCI6MTIzfQ==&limit=10

性能更好，适合大数据量，但不支持跳页。

响应中应该包含分页元信息：

{
  "data": [...],
  "pagination": {
    "total": 1000,
    "offset": 20,
    "limit": 10,
    "hasMore": true
  }
}

写在最后

好的API设计是一门艺术。它需要在简洁和完备之间找平衡，在规范和灵活之间做取舍。没有完美的API，只有不断改进的API。

记住：API是写给其他开发者（包括未来的自己）看的。多花10分钟设计，能省下未来几小时的调试时间。

最后，推荐几个学习资源：

• 《RESTful Web APIs》 – 经典教材
• GitHub REST API文档 – 业界标杆
• Stripe API文档 – 文档即产品的典范

愿你的API优雅如诗，文档清晰如画。