RESTful API设计原则：构建可扩展的Web服务接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// ✅ 好的资源命名
GET    /api/v1/users           // 获取用户列表
GET    /api/v1/users/{id}      // 获取特定用户
POST   /api/v1/users           // 创建用户
PUT    /api/v1/users/{id}      // 更新用户
DELETE /api/v1/users/{id}      // 删除用户

GET    /api/v1/users/{id}/orders        // 获取用户的订单
POST   /api/v1/users/{id}/orders        // 为用户创建订单

// ❌ 避免的命名方式
GET    /api/v1/getAllUsers     // 动词在URL中
POST   /api/v1/createUser      // 动词在URL中
GET    /api/v1/users?getAll=1  // 动作参数化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 用户与订单的关系
GET    /api/v1/users/{userId}/orders              // 用户的订单
GET    /api/v1/orders/{orderId}/user              // 订单的归属用户
GET    /api/v1/users/{userId}/orders/{orderId}    // 特定用户的特定订单

// 嵌套资源的限制
// ✅ 推荐
GET    /api/v1/orders?userId={userId}            // 通过参数过滤

// ❌ 避免过深的嵌套
// GET /api/v1/users/{userId}/orders/{orderId}/items/{itemId}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// GET方法 - 获取资源
GET    /api/v1/users
GET    /api/v1/users/{id}

// POST方法 - 创建资源
POST   /api/v1/users
// 请求体：{ "name": "张三", "email": "zhangsan@example.com" }

// PUT方法 - 完整更新资源
PUT    /api/v1/users/{id}
// 请求体：{ "name": "李四", "email": "lisi@example.com", "age": 30 }

// PATCH方法 - 部分更新资源
PATCH  /api/v1/users/{id}
// 请求体：{ "email": "newemail@example.com" }

// DELETE方法 - 删除资源
DELETE /api/v1/users/{id}

// 特殊操作使用POST
POST   /api/v1/users/{id}/activate     // 激活用户
POST   /api/v1/orders/{id}/cancel      // 取消订单
POST   /api/v1/files/{id}/share        // 分享文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// 幂等操作：多次执行结果相同
GET    /api/v1/users/{id}      // ✅ 幂等
PUT    /api/v1/users/{id}      // ✅ 幂等
DELETE /api/v1/users/{id}      // ✅ 幂等

// 非幂等操作：每次执行可能产生不同结果
POST   /api/v1/users           // ❌ 非幂等（创建多个用户）
POST   /api/v1/orders/{id}/pay // ❌ 非幂等（多次付款）

// 设计幂等的POST操作
POST   /api/v1/users/{id}/activation-token
// 请求体：{ "token": "abc123" }
// 无论调用多少次，结果都是激活用户一次

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// 200 OK - 请求成功
GET    /api/v1/users/{id}      // 返回：200 + 用户数据

// 201 Created - 资源创建成功
POST   /api/v1/users            // 返回：201 + 新用户数据 + Location头

// 202 Accepted - 请求已接受，正在处理
POST   /api/v1/data-import      // 返回：202 + 任务ID

// 204 No Content - 操作成功，无返回内容
DELETE /api/v1/users/{id}      // 返回：204
PUT    /api/v1/users/{id}/profile  // 返回：204

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// 400 Bad Request - 请求参数错误
POST   /api/v1/users
// 请求体：{ "email": "invalid-email" }
// 返回：400 + { "error": "邮箱格式不正确" }

// 401 Unauthorized - 未认证
GET    /api/v1/profile
// 返回：401 + { "error": "请先登录" }

// 403 Forbidden - 无权限
DELETE /api/v1/admin/users/{id}
// 返回：403 + { "error": "权限不足" }

// 404 Not Found - 资源不存在
GET    /api/v1/users/{nonexistentId}
// 返回：404 + { "error": "用户不存在" }

// 409 Conflict - 资源冲突
POST   /api/v1/users
// 请求体：{ "email": "existing@example.com" }
// 返回：409 + { "error": "邮箱已被使用" }

// 422 Unprocessable Entity - 请求格式正确但语义错误
POST   /api/v1/orders
// 请求体：{ "items": [] }
// 返回：422 + { "error": "订单商品不能为空" }

1
2
3
4
5
6

// 500 Internal Server Error - 服务器内部错误
// 返回：500 + { "error": "服务器内部错误", "requestId": "uuid" }

// 502 Bad Gateway - 网关错误
// 503 Service Unavailable - 服务不可用
// 504 Gateway Timeout - 网关超时

1
2
3
4
5
6
7

// 推荐：URL路径版本控制
GET    /api/v1/users
GET    /api/v2/users

// 版本迁移策略
// v1: GET /api/v1/users (简单用户列表)
// v2: GET /api/v2/users (包含详细信息的用户列表)

1
2
3
4
5
6
7
8
9

// 请求头版本控制
GET    /api/users
Headers:
  Accept: application/vnd.myapi.v1+json

// 优先级策略
// 1. 请求头版本
// 2. URL路径版本
// 3. 查询参数版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// 向后兼容的字段添加
// v1 响应
{
  "id": 1,
  "name": "张三"
}

// v2 响应（向后兼容）
{
  "id": 1,
  "name": "张三",
  "firstName": "张",    // 新字段
  "lastName": "三",     // 新字段
  "avatar": "http://..." // 新字段
}

// 废弃字段的处理
{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 30,
  "legacyField": "deprecated", // 标记为废弃
  "_deprecated": ["legacyField"] // 明确标记废弃字段
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// 基础分页
GET    /api/v1/users?page=1&limit=20

// 响应结构
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

// 基于游标的分页（适合大数据集）
GET    /api/v1/users?cursor=abc123&limit=20

// 响应结构
{
  "data": [...],
  "pagination": {
    "nextCursor": "def456",
    "hasNext": true,
    "limit": 20
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// 基础过滤
GET    /api/v1/users?status=active&role=admin

// 日期范围过滤
GET    /api/v1/orders?createdAfter=2024-01-01&createdBefore=2024-12-31

// 数组过滤
GET    /api/v1/products?tags=electronics,premium

// 全文搜索
GET    /api/v1/users?q=zhangsan
GET    /api/v1/products?search=iPhone

// 复杂过滤（POST方式）
POST   /api/v1/users/search
// 请求体
{
  "filters": {
    "status": "active",
    "age": { "min": 18, "max": 65 },
    "tags": ["developer", "javascript"],
    "createdAfter": "2024-01-01"
  },
  "sort": [
    { "field": "createdAt", "order": "desc" },
    { "field": "name", "order": "asc" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20
  }
}

1
2
3
4
5
6
7
8
9

// 单字段排序
GET    /api/v1/users?sort=createdAt
GET    /api/v1/users?sort=createdAt:desc

// 多字段排序
GET    /api/v1/users?sort=createdAt:desc,name:asc

// 排序参数标准化
// ?sort=-createdAt,name  // 等同于 createdAt:desc,name:asc

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// 创建资源请求
POST   /api/v1/users
Content-Type: application/json

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "profile": {
    "age": 30,
    "city": "北京"
  },
  "preferences": {
    "language": "zh-CN",
    "timezone": "Asia/Shanghai"
  }
}

// 批量操作请求
POST   /api/v1/users/batch
Content-Type: application/json

{
  "operation": "create",
  "items": [
    { "name": "张三", "email": "zhangsan@example.com" },
    { "name": "李四", "email": "lisi@example.com" }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

// 成功响应格式
{
  "success": true,
  "data": {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com",
    "createdAt": "2024-12-16T10:00:00Z"
  },
  "meta": {
    "timestamp": "2024-12-16T10:00:00Z",
    "requestId": "req_abc123"
  }
}

// 列表响应格式
{
  "success": true,
  "data": [
    { "id": 1, "name": "张三" },
    { "id": 2, "name": "李四" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  },
  "meta": {
    "timestamp": "2024-12-16T10:00:00Z"
  }
}

// 错误响应格式
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      },
      {
        "field": "age",
        "message": "年龄必须在1-120之间"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-12-16T10:00:00Z",
    "requestId": "req_def456"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// JWT Bearer Token认证
GET    /api/v1/users/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// API Key认证
GET    /api/v1/data
X-API-Key: abc123def456

// OAuth2认证
GET    /api/v1/users
Authorization: Bearer <access_token>

// 多因素认证
POST   /api/v1/auth/mfa
// 请求体
{
  "userId": "user123",
  "code": "123456",
  "backupCode": null
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// 基于角色的访问控制（RBAC）
// 用户角色：admin, manager, user
// 资源权限：read, write, delete

// 权限检查中间件示例
function checkPermission(resource, action) {
  return (req, res, next) => {
    const user = req.user;
    const hasPermission = user.permissions.some(
      perm => perm.resource === resource && perm.actions.includes(action)
    );

    if (!hasPermission) {
      return res.status(403).json({
        success: false,
        error: {
          code: 'INSUFFICIENT_PERMISSIONS',
          message: '权限不足'
        }
      });
    }

    next();
  };
}

// 使用示例
app.delete('/api/v1/users/:id',
  authenticate,
  checkPermission('user', 'delete'),
  deleteUser
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// 安全响应头设置
app.use((req, res, next) => {
  // HTTPS强制
  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');

  // 防止XSS攻击
  res.setHeader('X-XSS-Protection', '1; mode=block');

  // 防止MIME类型嗅探
  res.setHeader('X-Content-Type-Options', 'nosniff');

  // 控制iframe嵌入
  res.setHeader('X-Frame-Options', 'DENY');

  // 内容安全策略
  res.setHeader('Content-Security-Policy', "default-src 'self'");

  // CORS配置
  res.setHeader('Access-Control-Allow-Origin', 'https://trusted-domain.com');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');

  next();
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// Express.js全局错误处理中间件
app.use((err, req, res, next) => {
  // 记录错误日志
  logger.error('API Error', {
    error: err.message,
    stack: err.stack,
    url: req.url,
    method: req.method,
    ip: req.ip,
    userAgent: req.get('User-Agent'),
    requestId: req.id
  });

  // 错误响应
  const errorResponse = {
    success: false,
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message: err.message || '服务器内部错误'
    },
    meta: {
      timestamp: new Date().toISOString(),
      requestId: req.id
    }
  };

  // 开发环境返回堆栈信息
  if (process.env.NODE_ENV === 'development') {
    errorResponse.error.stack = err.stack;
  }

  res.status(err.status || 500).json(errorResponse);
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// 请求日志中间件
app.use((req, res, next) => {
  const requestId = generateRequestId();
  req.id = requestId;

  const startTime = Date.now();

  // 记录请求开始
  logger.info('Request started', {
    requestId,
    method: req.method,
    url: req.url,
    ip: req.ip,
    userAgent: req.get('User-Agent'),
    timestamp: new Date().toISOString()
  });

  // 响应结束时记录日志
  res.on('finish', () => {
    const duration = Date.now() - startTime;

    logger.info('Request completed', {
      requestId,
      method: req.method,
      url: req.url,
      statusCode: res.statusCode,
      duration: `${duration}ms`,
      contentLength: res.get('Content-Length'),
      timestamp: new Date().toISOString()
    });
  });

  next();
});

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# openapi.yaml
openapi: 3.0.3
info:
  title: 用户管理API
  description: RESTful API for user management
  version: 1.0.0
  contact:
    name: API Support
    email: api-support@example.com

servers:
  - url: https://api.example.com/v1
    description: 生产环境
  - url: https://staging-api.example.com/v1
    description: 测试环境

paths:
  /users:
    get:
      summary: 获取用户列表
      description: 分页获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

    post:
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "张三"
        email:
          type: string
          format: email
          example: "zhangsan@example.com"
        createdAt:
          type: string
          format: date-time
          example: "2024-12-16T10:00:00Z"

    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          example: "张三"
        email:
          type: string
          format: email
          example: "zhangsan@example.com"
        age:
          type: integer
          minimum: 1
          maximum: 120
          example: 30

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 100
        totalPages:
          type: integer
          example: 5

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

// Jest + Supertest API测试示例
const request = require('supertest');
const app = require('../app');

describe('User API', () => {
  describe('GET /api/v1/users', () => {
    it('should return users list', async () => {
      const response = await request(app)
        .get('/api/v1/users')
        .expect(200);

      expect(response.body.success).toBe(true);
      expect(response.body.data).toBeInstanceOf(Array);
      expect(response.body.pagination).toBeDefined();
    });

    it('should support pagination', async () => {
      const response = await request(app)
        .get('/api/v1/users?page=1&limit=5')
        .expect(200);

      expect(response.body.data).toHaveLength(5);
      expect(response.body.pagination.page).toBe(1);
      expect(response.body.pagination.limit).toBe(5);
    });
  });

  describe('POST /api/v1/users', () => {
    it('should create a new user', async () => {
      const userData = {
        name: '测试用户',
        email: 'test@example.com',
        age: 25
      };

      const response = await request(app)
        .post('/api/v1/users')
        .send(userData)
        .expect(201);

      expect(response.body.success).toBe(true);
      expect(response.body.data.name).toBe(userData.name);
      expect(response.body.data.email).toBe(userData.email);
    });

    it('should return validation error for invalid data', async () => {
      const invalidData = {
        name: '',
        email: 'invalid-email',
        age: 150
      };

      const response = await request(app)
        .post('/api/v1/users')
        .send(invalidData)
        .expect(422);

      expect(response.body.success).toBe(false);
      expect(response.body.error.code).toBe('VALIDATION_ERROR');
      expect(response.body.error.details).toBeInstanceOf(Array);
    });
  });
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// Redis缓存实现
const redis = require('redis');
const client = redis.createClient();

const cacheMiddleware = (ttl = 300) => {
  return async (req, res, next) => {
    const key = `cache:${req.method}:${req.originalUrl}`;

    try {
      // 尝试从缓存获取数据
      const cachedData = await client.get(key);

      if (cachedData) {
        return res.json(JSON.parse(cachedData));
      }

      // 修改res.json方法以缓存响应
      const originalJson = res.json;
      res.json = function(data) {
        // 缓存响应数据
        client.setex(key, ttl, JSON.stringify(data));
        return originalJson.call(this, data);
      };

      next();
    } catch (error) {
      next();
    }
  };
};

// 使用缓存
app.get('/api/v1/users', cacheMiddleware(600), getUsers);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// 分页查询优化
async function getUsers(page = 1, limit = 20) {
  const offset = (page - 1) * limit;

  // 使用索引优化的查询
  const query = `
    SELECT u.id, u.name, u.email, u.created_at,
           p.avatar_url, p.bio
    FROM users u
    LEFT JOIN user_profiles p ON u.id = p.user_id
    WHERE u.status = 'active'
    ORDER BY u.created_at DESC
    LIMIT ? OFFSET ?
  `;

  // 计数查询（避免COUNT(*)的性能问题）
  const countQuery = `
    SELECT COUNT(*) as total
    FROM users u
    WHERE u.status = 'active'
  `;

  const [users, countResult] = await Promise.all([
    db.query(query, [limit, offset]),
    db.query(countQuery)
  ]);

  return {
    data: users,
    pagination: {
      page,
      limit,
      total: countResult[0].total,
      totalPages: Math.ceil(countResult[0].total / limit)
    }
  };
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Gzip压缩中间件
const compression = require('compression');

app.use(compression({
  filter: (req, res) => {
    // 只压缩文本内容
    if (req.headers['x-no-compression']) {
      return false;
    }
    return compression.filter(req, res);
  },
  threshold: 1024 // 只压缩大于1KB的响应
}));