API风格指南

🪷 我是荷花，我想开了

---

最近在学 NestJS，
有时候总会想到：这样不合理，那又不好看，从而在钻牛角尖。不如从规范入手，毕竟这是大家公认的（合理）

RESTful

1. 资源（Resources）

• 使用名词（复数形式）表示资源
• 示例：/users, /articles, /products

2. HTTP 方法

方法	描述	幂等性	示例
GET	获取资源	是	GET /users
POST	创建新资源	否	POST /users
PUT	更新整个资源（全量替换）	是	PUT /users/1
PATCH	部分更新资源	否	PATCH /users/1
DELETE	删除资源	是	DELETE /users/1

3. 状态码

• 200 OK - 成功
• 201 Created - 创建成功
• 204 No Content - 成功但无返回内容
• 400 Bad Request - 请求错误
• 401 Unauthorized - 未认证
• 403 Forbidden - 无权限
• 404 Not Found - 资源不存在
• 500 Internal Server Error - 服务器错误

4. URL 设计

• 使用小写字母和连字符 -
• 使用 / 表示层级关系
• 示例：/users/123/orders

5. 查询参数

• 用于过滤、排序、分页等
• 示例：
  • 过滤：/users?role=admin
  • 分页：/users?page=2&limit=10
  • 排序：/users?sort=-created_at,name

6. 版本控制

• URL 中包含版本号：/api/v1/users
• 或使用请求头：Accept: application/vnd.myapp.v1+json

7. 响应格式

• 使用 JSON 格式
• 包含元数据（如分页信息）
• 示例：

  {
    "data": [...],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10
    }
  }

8. 错误处理

• 包含错误码和描述信息
• 示例：

  {
    "error": {
      "code": "invalid_input",
      "message": "Name is required",
      "details": {
        "field": "name",
        "issue": "required"
      }
    }
  }

9. 安全

• 使用 HTTPS
• 使用适当的认证机制（如 JWT、OAuth2.0）
• 实现速率限制

10. 最佳实践

• 使用名词而非动词
• 保持 URL 简洁
• 使用适当的 HTTP 状态码
• 提供清晰的文档
• 实现 HATEOAS（可选）

11. 常见端点示例

GET    /users           # 获取用户列表
POST   /users           # 创建用户
GET    /users/{id}      # 获取单个用户
PUT    /users/{id}      # 更新用户（全量）
PATCH  /users/{id}      # 更新用户（部分）
DELETE /users/{id}      # 删除用户