RESTful API

RESTful API 基本概念

REST（Representational State Transfer）是一种软件架构风格，用于设计网络应用程序的API。

什么是 RESTful API

• RESTful API 是基于 REST 架构风格设计的 Web API
• 使用 HTTP 协议的标准方法（GET、POST、PUT、DELETE等）
• 通过 URL 和 HTTP 方法来表示资源和操作
• 无状态、可缓存、统一接口的设计原则

• REST 的核心思想：

  • 资源（Resource）：网络上的任何信息都可以被视为资源
  • 表现层（Representation）：资源的具体表现形式（JSON、XML等）
  • 状态转移（State Transfer）：通过HTTP方法改变资源状态

RESTful API 设计原则

1. 资源识别 (Resource Identification)

概念：每个资源都应该有一个唯一的标识符（URI），通过URI可以访问和操作资源。

语法规则：

  • 使用名词而不是动词：/users 而不是 /getUsers
  • 使用复数形式：/users 而不是 /user
  • 使用层级结构：/users/123/posts
  • 避免深层嵌套：最多2-3层

作用：

  • 提供清晰的资源定位
  • 便于API的理解和使用
  • 支持RESTful的CRUD操作

资源命名规范

1
2
3
4
5
6
7
8
9
10
# 好的资源命名
GET    /users                    # 获取所有用户
GET    /users/123                # 获取ID为123的用户
GET    /users/123/posts          # 获取用户123的所有文章
GET    /users/123/posts/456      # 获取用户123的文章456

# 不好的资源命名
GET    /getUsers                  # 使用动词
GET    /user                      # 使用单数
GET    /users/123/getPosts        # 嵌套操作

资源层级设计

1
2
3
4
5
6
7
8
9
# 合理的层级结构
GET    /api/v1/users                    # 用户集合
GET    /api/v1/users/123                 # 特定用户
GET    /api/v1/users/123/posts          # 用户的文章
GET    /api/v1/users/123/posts/456      # 特定文章
GET    /api/v1/users/123/posts/456/comments  # 文章评论

# 避免过深嵌套
GET    /api/v1/users/123/posts/456/comments/789/replies/101/likes  # 太深

2. HTTP 方法 (HTTP Methods)

概念：使用标准的HTTP方法来表示对资源的操作，每个方法都有特定的语义。

语法规则：

  • GET：获取资源
  • POST：创建资源
  • PUT：更新整个资源
  • PATCH：部分更新资源
  • DELETE：删除资源
  • HEAD：获取资源头信息
  • OPTIONS：获取支持的方法

作用：

  • 提供统一的接口标准
  • 明确操作的语义
  • 支持缓存和代理

HTTP 方法详解

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
# GET - 获取资源（幂等、安全）
GET /users                    # 获取所有用户
GET /users/123                # 获取特定用户
GET /users/123/posts          # 获取用户的文章

# POST - 创建资源（非幂等、非安全）
POST /users                   # 创建新用户
POST /users/123/posts         # 为用户创建文章

# PUT - 更新整个资源（幂等、非安全）
PUT /users/123                # 更新整个用户信息
PUT /users/123/posts/456      # 更新整个文章

# PATCH - 部分更新资源（非幂等、非安全）
PATCH /users/123              # 部分更新用户信息
PATCH /users/123/posts/456    # 部分更新文章

# DELETE - 删除资源（幂等、非安全）
DELETE /users/123             # 删除用户
DELETE /users/123/posts/456   # 删除文章

# HEAD - 获取资源头信息（幂等、安全）
HEAD /users/123               # 获取用户头信息

# OPTIONS - 获取支持的方法（幂等、安全）
OPTIONS /users                # 获取支持的方法

HTTP 方法特性

方法 幂等性 安全性 缓存 请求体 响应体
GET ✅ ✅ ✅ ❌ ✅
POST ❌ ❌ ❌ ✅ ✅
PUT ✅ ❌ ❌ ✅ ✅
PATCH ❌ ❌ ❌ ✅ ✅
DELETE ✅ ❌ ❌ ❌ ✅
HEAD ✅ ✅ ✅ ❌ ❌
OPTIONS ✅ ✅ ✅ ❌ ✅

3. 状态码 (Status Codes)

概念：使用标准的HTTP状态码来表示请求的处理结果，提供清晰的响应信息。

语法规则：

  • 2xx：成功状态
  • 3xx：重定向状态
  • 4xx：客户端错误
  • 5xx：服务器错误

作用：

  • 提供明确的响应状态
  • 便于错误处理和调试
  • 支持自动化处理

常用状态码

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
# 2xx 成功状态
200 OK                    # 请求成功
201 Created               # 资源创建成功
202 Accepted              # 请求已接受，异步处理
204 No Content            # 请求成功，无返回内容

# 3xx 重定向状态
301 Moved Permanently     # 资源永久移动
302 Found                 # 资源临时移动
304 Not Modified          # 资源未修改

# 4xx 客户端错误
400 Bad Request           # 请求格式错误
401 Unauthorized          # 未授权
403 Forbidden             # 禁止访问
404 Not Found             # 资源不存在
405 Method Not Allowed    # 方法不允许
409 Conflict              # 资源冲突
422 Unprocessable Entity  # 请求格式正确，语义错误

# 5xx 服务器错误
500 Internal Server Error # 服务器内部错误
502 Bad Gateway           # 网关错误
503 Service Unavailable   # 服务不可用
504 Gateway Timeout       # 网关超时

状态码使用示例

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
# 成功响应
GET /users/123
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com"
}

# 创建成功
POST /users
HTTP/1.1 201 Created
Location: /users/124
Content-Type: application/json
{
  "id": 124,
  "name": "李四",
  "email": "lisi@example.com"
}

# 资源不存在
GET /users/999
HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}

# 请求格式错误
POST /users
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Invalid request format",
  "details": "Name is required"
}

4. 数据格式 (Data Formats)

概念：使用标准的数据格式来传输数据，通常使用JSON格式。

语法规则：

  • Content-Type：指定数据格式
  • Accept：指定接受的格式
  • 统一使用JSON格式
  • 支持XML格式（可选）

作用：

  • 提供统一的数据交换格式
  • 便于解析和处理
  • 支持多种客户端

JSON 数据格式

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
# 用户资源
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

# 用户集合
{
  "data": [
    {
      "id": 123,
      "name": "张三",
      "email": "zhangsan@example.com"
    },
    {
      "id": 124,
      "name": "李四",
      "email": "lisi@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 2,
    "total_pages": 1
  }
}

# 错误响应
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

请求和响应头

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 请求头
GET /users/123
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-Agent: MyApp/1.0
X-Request-ID: 123e4567-e89b-12d3-a456-426614174000

# 响应头
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 156
Cache-Control: public, max-age=3600
ETag: "1234567890"
Last-Modified: Wed, 01 Jan 2023 00:00:00 GMT

5. 无状态性 (Statelessness)

概念：每个请求都应该包含处理该请求所需的所有信息，服务器不应该保存客户端的状态。

语法规则：

  • 每个请求独立处理
  • 不依赖服务器端会话
  • 使用Token进行身份验证
  • 客户端负责状态管理

作用：

  • 提高可扩展性
  • 简化服务器设计
  • 支持负载均衡
  • 便于缓存

无状态设计示例

1
2
3
4
5
6
7
8
9
# 有状态设计（不推荐）
GET /users/123
Cookie: sessionid=abc123
# 服务器需要查找session来验证用户

# 无状态设计（推荐）
GET /users/123
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# 服务器通过JWT Token验证用户，无需保存状态

身份验证

1
2
3
4
5
6
7
8
9
10
11
# JWT Token 认证
GET /users/123
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

# API Key 认证
GET /users/123
X-API-Key: your-api-key-here

# Basic 认证
GET /users/123
Authorization: Basic dXNlcjpwYXNzd29yZA==

6. 版本控制 (Versioning)

概念：API版本控制允许在不破坏现有客户端的情况下发布新版本。

语法规则：

  • URL路径版本：/api/v1/users
  • 请求头版本：Accept: application/vnd.api+json;version=1
  • 查询参数版本：/api/users?version=1
  • 子域名版本：v1.api.example.com

作用：

  • 支持API演进
  • 向后兼容
  • 平滑升级
  • 多版本并存

版本控制策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# URL路径版本（推荐）
GET /api/v1/users           # 版本1
GET /api/v2/users           # 版本2

# 请求头版本
GET /api/users
Accept: application/vnd.api+json;version=1

# 查询参数版本
GET /api/users?version=1

# 子域名版本
GET https://v1.api.example.com/users
GET https://v2.api.example.com/users

版本兼容性

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 版本1 API
GET /api/v1/users
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com"
}

# 版本2 API（向后兼容）
GET /api/v2/users
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",  # 新增字段
  "profile": {            # 新增嵌套对象
    "avatar": "https://example.com/avatar.jpg",
    "bio": "Hello world"
  }
}

7. 错误处理 (Error Handling)

概念：统一的错误处理机制，提供清晰的错误信息和错误码。

语法规则：

  • 使用标准HTTP状态码
  • 提供错误详情
  • 使用错误码标识
  • 提供解决建议

作用：

  • 便于调试和排错
  • 提供用户友好的错误信息
  • 支持自动化错误处理
  • 提高API可用性

错误响应格式

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
# 标准错误响应
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format",
        "value": "invalid-email"
      }
    ],
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2023-01-01T00:00:00Z"
  }
}

# 简单错误响应
{
  "error": "User not found",
  "code": "USER_NOT_FOUND"
}

# 详细错误响应
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to access this resource",
    "details": {
      "required_permission": "admin",
      "current_permission": "user"
    },
    "suggestion": "Contact your administrator to request admin access"
  }
}

错误处理最佳实践

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
# 400 Bad Request - 请求格式错误
POST /users
{
  "name": "张三"
  // 缺少email字段
}

HTTP/1.1 400 Bad Request
{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field 'email' is missing",
    "details": {
      "field": "email",
      "type": "required"
    }
  }
}

# 422 Unprocessable Entity - 语义错误
POST /users
{
  "name": "张三",
  "email": "invalid-email-format"
}

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format",
        "value": "invalid-email-format"
      }
    ]
  }
}

# 500 Internal Server Error - 服务器错误
GET /users/123

HTTP/1.1 500 Internal Server Error
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

8. 分页和过滤 (Pagination and Filtering)

概念：提供分页和过滤功能，处理大量数据的查询和展示。

语法规则：

  • 分页参数：page、per_page、limit、offset
  • 排序参数：sort、order
  • 过滤参数：filter、q（搜索）
  • 字段选择：fields、include

作用：

  • 提高性能
  • 减少数据传输
  • 提供灵活的查询
  • 改善用户体验

分页实现

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
# 基本分页
GET /users?page=1&per_page=10

# 响应格式
{
  "data": [
    {
      "id": 1,
      "name": "张三",
      "email": "zhangsan@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 100,
    "total_pages": 10,
    "has_next": true,
    "has_prev": false
  }
}

# 游标分页（推荐用于大数据集）
GET /users?cursor=eyJpZCI6MTIzfQ&limit=10

# 响应格式
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTMzfQ",
    "has_next": true
  }
}

过滤和搜索

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 基本过滤
GET /users?status=active&role=admin

# 搜索
GET /users?q=张三

# 日期范围过滤
GET /users?created_after=2023-01-01&created_before=2023-12-31

# 复合过滤
GET /users?status=active&role=admin&q=张三&created_after=2023-01-01

# 字段选择
GET /users?fields=id,name,email

# 包含关联数据
GET /users?include=posts,comments

排序

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 基本排序
GET /users?sort=name&order=asc

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

# 排序响应
{
  "data": [
    {
      "id": 1,
      "name": "张三",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ],
  "sort": {
    "field": "created_at",
    "order": "desc"
  }
}

9. 缓存策略 (Caching)

概念：使用HTTP缓存机制提高API性能，减少服务器负载。

语法规则：

  • Cache-Control：控制缓存行为
  • ETag：资源版本标识
  • Last-Modified：最后修改时间
  • Expires：过期时间

作用：

  • 提高响应速度
  • 减少服务器负载
  • 节省带宽
  • 改善用户体验

缓存头设置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 可缓存的GET请求
GET /users/123

HTTP/1.1 200 OK
Cache-Control: public, max-age=3600
ETag: "1234567890"
Last-Modified: Wed, 01 Jan 2023 00:00:00 GMT

# 条件请求
GET /users/123
If-None-Match: "1234567890"

HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=3600
ETag: "1234567890"

# 不可缓存的请求
POST /users

HTTP/1.1 201 Created
Cache-Control: no-cache, no-store, must-revalidate

缓存策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 静态资源 - 长期缓存
GET /api/v1/users

HTTP/1.1 200 OK
Cache-Control: public, max-age=86400  # 24小时
ETag: "v1.0.0"

# 动态资源 - 短期缓存
GET /users/123

HTTP/1.1 200 OK
Cache-Control: private, max-age=300   # 5分钟
ETag: "1234567890"

# 实时数据 - 不缓存
GET /users/123/online-status

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate

10. 安全性 (Security)

概念：API安全性包括身份验证、授权、数据加密、输入验证等方面。

语法规则：

  • HTTPS：强制使用加密传输
  • 身份验证：JWT、API Key、OAuth
  • 授权：基于角色的访问控制
  • 输入验证：防止注入攻击

作用：

  • 保护数据安全
  • 防止未授权访问
  • 确保数据完整性
  • 符合安全标准

身份验证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# JWT Token 认证
GET /users/123
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

# API Key 认证
GET /users/123
X-API-Key: your-api-key-here

# Basic 认证
GET /users/123
Authorization: Basic dXNlcjpwYXNzd29yZA==

# OAuth 2.0 认证
GET /users/123
Authorization: Bearer access_token_here

授权和权限

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 基于角色的访问控制
GET /admin/users
Authorization: Bearer admin_token

HTTP/1.1 200 OK
{
  "data": [...]
}

# 权限不足
GET /admin/users
Authorization: Bearer user_token

HTTP/1.1 403 Forbidden
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Admin access required"
  }
}

输入验证

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
# 输入验证
POST /users
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 25
}

# 验证失败
POST /users
{
  "name": "",
  "email": "invalid-email",
  "age": -1
}

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "name",
        "message": "Name cannot be empty"
      },
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "age",
        "message": "Age must be positive"
      }
    ]
  }
}

11. 文档和测试 (Documentation and Testing)

概念：提供完整的API文档和测试工具，便于开发者使用和集成。

语法规则：

  • OpenAPI/Swagger：标准API文档格式
  • Postman：API测试工具
  • 示例代码：多种语言示例
  • 交互式文档：在线测试

作用：

  • 降低集成难度
  • 提高开发效率
  • 减少沟通成本
  • 确保API质量

API文档

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
# OpenAPI 3.0 文档示例
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: 用户管理API

paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  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/CreateUser'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time

测试示例

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
# 用户API测试用例

# 1. 获取用户列表
GET /api/v1/users
Accept: application/json

# 2. 创建用户
POST /api/v1/users
Content-Type: application/json
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 25
}

# 3. 获取特定用户
GET /api/v1/users/123
Accept: application/json

# 4. 更新用户
PUT /api/v1/users/123
Content-Type: application/json
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 26
}

# 5. 删除用户
DELETE /api/v1/users/123

12. 性能优化 (Performance Optimization)

概念：通过各种技术手段提高API的性能，包括响应时间、吞吐量等。

语法规则：

  • 数据库优化：索引、查询优化
  • 缓存策略：Redis、Memcached
  • CDN：内容分发网络
  • 压缩：Gzip、Brotli

作用：

  • 提高响应速度
  • 减少服务器负载
  • 改善用户体验
  • 降低运营成本

数据库优化

1
2
3
4
5
6
7
8
9
10
-- 创建索引
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_created_at ON users(created_at);

-- 查询优化
-- 好的查询
SELECT id, name, email FROM users WHERE status = 'active' LIMIT 10;

-- 不好的查询
SELECT * FROM users WHERE email LIKE '%@example.com';

缓存实现

1
2
3
4
5
6
7
8
9
10
11
12
# Redis缓存示例
GET /users/123

# 缓存命中
HTTP/1.1 200 OK
X-Cache: HIT
Cache-Control: public, max-age=3600

# 缓存未命中
HTTP/1.1 200 OK
X-Cache: MISS
Cache-Control: public, max-age=3600

响应压缩

1
2
3
4
5
6
7
# 启用Gzip压缩
GET /users
Accept-Encoding: gzip, deflate

HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json

13. 监控和日志 (Monitoring and Logging)

概念：监控API的运行状态，记录日志，确保API的可用性和性能。

语法规则：

  • 日志格式：结构化日志
  • 监控指标：响应时间、错误率、吞吐量
  • 告警机制：阈值告警、异常告警
  • 链路追踪：请求追踪

作用：

  • 实时监控API状态
  • 快速定位问题
  • 性能分析
  • 容量规划

日志格式

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
# 访问日志
{
  "timestamp": "2023-01-01T00:00:00Z",
  "method": "GET",
  "url": "/api/v1/users/123",
  "status_code": 200,
  "response_time": 150,
  "user_id": "123",
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "ip": "192.168.1.1",
  "user_agent": "MyApp/1.0"
}

# 错误日志
{
  "timestamp": "2023-01-01T00:00:00Z",
  "level": "ERROR",
  "message": "Database connection failed",
  "error": {
    "type": "ConnectionError",
    "message": "Connection timeout",
    "stack": "..."
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174000"
}

监控指标

1
2
3
4
5
6
7
8
9
10
11
# API监控指标
{
  "timestamp": "2023-01-01T00:00:00Z",
  "metrics": {
    "requests_per_second": 100,
    "average_response_time": 150,
    "error_rate": 0.01,
    "p95_response_time": 300,
    "p99_response_time": 500
  }
}

14. 最佳实践 (Best Practices)

概念：RESTful API开发的最佳实践和推荐做法。

语法规则：

  • 遵循REST原则
  • 使用标准HTTP方法
  • 提供清晰的错误信息
  • 实现适当的缓存策略

使用场景：

  • 提高API质量
  • 改善开发体验
  • 确保API一致性
  • 便于维护和扩展

设计原则

  1. 资源导向：以资源为中心设计API
  2. 统一接口：使用标准HTTP方法
  3. 无状态：每个请求独立处理
  4. 可缓存：合理使用缓存机制
  5. 分层系统：支持代理和网关

命名规范

1
2
3
4
5
6
7
8
9
10
11
12
13
# 好的命名
GET /users                    # 获取用户列表
GET /users/123                # 获取特定用户
POST /users                   # 创建用户
PUT /users/123                # 更新用户
DELETE /users/123             # 删除用户

# 不好的命名
GET /getUsers                 # 使用动词
GET /user                     # 使用单数
POST /createUser              # 冗余操作
PUT /updateUser/123           # 冗余操作
DELETE /removeUser/123        # 冗余操作

响应格式

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
# 成功响应
{
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com"
  }
}

# 错误响应
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User not found",
    "details": {
      "user_id": 123
    }
  }
}

# 分页响应
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 100,
    "total_pages": 10
  }
}