RESTful API 设计规范

传统 API:
GET  /getUsers
POST /createUser
POST /deleteUser?id=123

RESTful API:
GET    /users        # 获取用户列表
POST   /users        # 创建新用户
DELETE /users/123    # 删除指定用户

✅ 推荐: https://api.example.com
❌ 避免: http://api.example.com

https://api.example.com

https://example.org/api/

https://api.example.com/v1/
https://api.example.com/v2/

https://api.example.com/v1/users
https://api.example.com/v2/users

GET /users HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v1+json

✅ 正确示例:
GET    /zoos              # 动物园集合
GET    /zoos/123          # 特定动物园
GET    /zoos/123/animals  # 特定动物园的动物集合
GET    /animals?zoo_id=123 # 通过查询参数筛选

❌ 错误示例:
GET    /getZoos           # 不应包含动词
GET    /zoo               # 应使用复数形式
GET    /Zoos              # 应使用小写
GET    /zoos/123/animals/456/keepers  # 嵌套过深

# 一对多关系
GET    /zoos/123/animals          # 获取动物园123的所有动物
POST   /zoos/123/animals          # 在动物园123中添加动物

# 多对多关系
GET    /students/123/courses      # 获取学生123的所有课程
GET    /courses/456/students      # 获取课程456的所有学生

# 资源集合操作
GET    /zoos              # 列出所有动物园
POST   /zoos              # 新建一个动物园

# 单个资源操作
GET    /zoos/123          # 获取ID为123的动物园信息
PUT    /zoos/123          # 更新ID为123的动物园（完整更新）
PATCH  /zoos/123          # 更新ID为123的动物园（部分更新）
DELETE /zoos/123          # 删除ID为123的动物园

# 子资源操作
GET    /zoos/123/animals  # 获取动物园123的所有动物
POST   /zoos/123/animals  # 在动物园123中创建新动物
DELETE /zoos/123/animals/456  # 删除动物园123中ID为456的动物

# 条件查询
GET    /animals?zoo_id=123&species=tiger  # 查询特定动物园的老虎

GET /users?page=2&per_page=20
GET /users?offset=20&limit=20

GET /users?sortby=created_at&order=desc
GET /users?sort=+name,-created_at  # 多字段排序

GET /animals?species=tiger&age_gte=3
GET /users?status=active&role=admin

GET /users?fields=id,name,email

GET /users?q=john
GET /products?search=phone&fields=name,description

Content-Type: application/json; charset=utf-8

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "北京动物园",
    "location": "北京市西城区",
    "created_at": "2024-01-15T08:30:00Z"
  }
}

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 123,
      "name": "北京动物园"
    },
    {
      "id": 124,
      "name": "上海动物园"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "total_pages": 5
  }
}

HTTP/1.1 201 Created
Location: https://api.example.com/v1/zoos/125

{
  "code": 201,
  "message": "created",
  "data": {
    "id": 125,
    "name": "新动物园",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

HTTP/1.1 204 No Content

请求 → 认证检查 → 权限检查 → 参数验证 → 业务处理 → 响应
        ↓           ↓           ↓           ↓
      401         403         400/422      200/201/204
                                          或 500

{
  "code": 400,
  "message": "请求参数错误",
  "error": "INVALID_PARAMETER",
  "details": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    },
    {
      "field": "password",
      "message": "密码长度至少8位"
    }
  ],
  "request_id": "req_abc123xyz",
  "timestamp": "2024-01-15T10:30:00Z"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 400,
  "message": "请求参数验证失败",
  "error": "VALIDATION_ERROR",
  "details": [
    {
      "field": "name",
      "message": "名称不能为空",
      "value": ""
    }
  ]
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer realm="api"

{
  "code": 401,
  "message": "认证失败",
  "error": "AUTHENTICATION_FAILED",
  "details": "Token 已过期，请重新登录"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "code": 403,
  "message": "权限不足",
  "error": "PERMISSION_DENIED",
  "details": "您没有权限执行此操作"
}

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "code": 404,
  "message": "资源不存在",
  "error": "RESOURCE_NOT_FOUND",
  "details": "动物园 ID 999 不存在"
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "code": 422,
  "message": "无法处理请求",
  "error": "BUSINESS_ERROR",
  "details": "该动物园仍有动物，无法删除"
}

GET /users HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Header.Payload.Signature

# 获取授权码
GET /oauth/authorize?
    response_type=code&
    client_id=CLIENT_ID&
    redirect_uri=REDIRECT_URI&
    scope=read

# 获取访问令牌
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET

GET /api/v1/users HTTP/1.1
Host: api.example.com
X-API-Key: your-api-key-here

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400

const cors = require('cors');

app.use(cors({
  origin: ['https://example.com', 'https://admin.example.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
  maxAge: 86400
}));

OPTIONS /api/v1/users HTTP/1.1
Host: api.example.com
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, Authorization

GET /v1/users?page=1&per_page=20&status=active&sortby=created_at&order=desc HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "username": "zhang_san",
      "email": "zhangsan@example.com",
      "status": "active",
      "created_at": "2024-01-10T08:00:00Z"
    },
    {
      "id": 2,
      "username": "li_si",
      "email": "lisi@example.com",
      "status": "active",
      "created_at": "2024-01-09T10:30:00Z"
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "total_pages": 5
  }
}

POST /v1/users HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "username": "wang_wu",
  "email": "wangwu@example.com",
  "password": "SecurePass123!",
  "role": "user"
}

HTTP/1.1 201 Created
Location: https://api.example.com/v1/users/3

{
  "code": 201,
  "message": "created",
  "data": {
    "id": 3,
    "username": "wang_wu",
    "email": "wangwu@example.com",
    "role": "user",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

PATCH /v1/users/3 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "email": "newemail@example.com"
}

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 3,
    "username": "wang_wu",
    "email": "newemail@example.com",
    "role": "user",
    "status": "active",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

DELETE /v1/users/3 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

HTTP/1.1 204 No Content

✅ 推荐:
/users                    # 小写复数名词
/user-profiles            # 多词用连字符
/orders/123/items         # 清晰的层级关系

❌ 避免:
/Users                    # 大写
/user                     # 单数
/userProfiles             # 驼峰命名
/getUsers                 # 包含动词

✅ RESTful 风格:
GET    /users            # 获取用户列表
POST   /users            # 创建用户
DELETE /users/123        # 删除用户

❌ RPC 风格:
GET    /getUsers
POST   /createUser
POST   /deleteUser?id=123

// ✅ 正确做法：使用语义化的状态码
res.status(201).json(newResource);  // 创建成功
res.status(204).send();              // 删除成功，无返回内容

// ❌ 错误做法：所有响应都返回 200
res.status(200).json({ code: 201, data: newResource });
res.status(200).json({ code: 404, error: 'Not found' });

// 保持向后兼容的策略
// v1 版本响应
{
  "id": 123,
  "name": "张三"
}

// v2 版本响应（添加新字段，保持旧字段）
{
  "id": 123,
  "name": "张三",
  "full_name": "张三",
  "nickname": "小张"
}

// ✅ 推荐：使用游标分页（大数据量场景）
GET /messages?cursor=abc123&limit=20

// ✅ 推荐：限制单页数量
GET /users?per_page=20  // 最大不超过100

// ❌ 避免：深度分页
GET /users?page=10000  // 性能问题

{
  "data": {
    "id": 123,
    "name": "北京动物园"
  },
  "links": {
    "self": "/zoos/123",
    "animals": "/zoos/123/animals",
    "employees": "/zoos/123/employees"
  }
}

# 响应头设置缓存
Cache-Control: public, max-age=3600
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Wed, 15 Jan 2024 10:00:00 GMT

# 条件请求
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

# 响应头包含限流信息
X-RateLimit-Limit: 100        # 时间窗口内最大请求数
X-RateLimit-Remaining: 95     # 剩余请求数
X-RateLimit-Reset: 1642234567 # 重置时间戳

# 超限时返回 429
HTTP/1.1 429 Too Many Requests
Retry-After: 60

# 方式1：POST 请求体包含数组
POST /users/batch
Content-Type: application/json

{
  "users": [
    {"name": "用户1"},
    {"name": "用户2"}
  ]
}

# 方式2：使用查询参数
POST /users/activate?ids=1,2,3

POST /upload HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg

[binary data]
------WebKitFormBoundary--

{
  "code": 201,
  "data": {
    "url": "https://cdn.example.com/files/abc123.jpg",
    "filename": "example.jpg",
    "size": 102400,
    "mime_type": "image/jpeg"
  }
}

# 创建异步任务
POST /exports
Content-Type: application/json

{
  "type": "users",
  "format": "xlsx"
}

# 响应返回任务ID
HTTP/1.1 202 Accepted
Location: /tasks/abc123

{
  "code": 202,
  "data": {
    "task_id": "abc123",
    "status": "pending",
    "estimated_time": 300
  }
}

# 轮询任务状态
GET /tasks/abc123

{
  "code": 200,
  "data": {
    "task_id": "abc123",
    "status": "completed",
    "progress": 100,
    "result_url": "/downloads/export_abc123.xlsx"
  }
}

# 简单搜索
GET /users?q=zhang

# 高级搜索
GET /users?filter=name:like:zhang;age:gte:18;status:eq:active
      &sort=-created_at
      &fields=id,name,email

# 删除时添加 deleted_at 标记
DELETE /users/123

# 响应
HTTP/1.1 204 No Content

# 获取已删除记录
GET /users?include_deleted=true

# 永久删除
DELETE /users/123?force=true

# 获取用户的所有订单
GET /users/123/orders

# 创建订单并关联用户
POST /users/123/orders
Content-Type: application/json

{
  "product_id": 456,
  "quantity": 2
}

# 更新关联关系
PUT /users/123/roles
Content-Type: application/json

{
  "role_ids": [1, 2, 3]
}

// 测试 RESTful API
const BASE_URL = 'http://localhost:3000/api'

// GET 请求
const users = await fetch(`${BASE_URL}/users`).then(r => r.json())

// POST 请求
const newUser = await fetch(`${BASE_URL}/users`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' })
}).then(r => r.json())

// PUT 请求
const updated = await fetch(`${BASE_URL}/users/1`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Alice Updated' })
}).then(r => r.json())

// DELETE 请求
await fetch(`${BASE_URL}/users/1`, { method: 'DELETE' })

import { describe, it } from 'node:test'
import assert from 'node:assert/strict'

describe('用户 API', () => {
  it('GET /users 返回用户列表', async () => {
    const response = await fetch('http://localhost:3000/api/users')
    assert.strictEqual(response.status, 200)
    const data = await response.json()
    assert.ok(Array.isArray(data))
  })

  it('POST /users 创建用户', async () => {
    const response = await fetch('http://localhost:3000/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ name: 'Test User' })
    })
    assert.strictEqual(response.status, 201)
  })
})