REST API 设计规范与实践

REST 的核心约束

REST 不是标准，而是一组约束。真正的 RESTful API 需要满足：无状态（Stateless）、统一接口（Uniform Interface）、资源导向（Resource-oriented）。

资源命名规范

✅ 正确
GET    /articles              # 文章列表
GET    /articles/42           # 单篇文章
POST   /articles              # 创建文章
PATCH  /articles/42           # 部分更新
DELETE /articles/42           # 删除

❌ 错误
GET /getArticles
POST /createArticle
GET /articles/delete/42

状态码使用

场景	状态码
查询成功	200 OK
创建成功	201 Created
无内容返回	204 No Content
参数校验失败	400 Bad Request
未认证	401 Unauthorized
无权限	403 Forbidden
资源不存在	404 Not Found
服务端错误	500 Internal Server Error

统一错误格式

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "请求参数不合法",
    "details": [
      { "field": "email", "message": "邮箱格式不正确" }
    ]
  }
}

版本控制

推荐 URL 路径版本控制，简单直观：

/v1/articles
/v2/articles

避免将版本放在 Header 中——增加了客户端复杂度，且难以在浏览器中直接测试。

总结

好的 API 设计是产品的一部分。遵循规范能降低接入成本，减少歧义，让 API 文档几乎成为不必要的存在。