bittern.cn
2API Design Patterns

CRUD模式

基础操作

创建读取更新删除资源命名

🎯 AI 时代的学习建议：不要只读理论。理解这一章的设计动机（为什么需要这个概念？）和边界条件（什么情况下会失效？）。当 AI 生成的代码涉及这些概念时，你能判断它是否用对了场景。AI 能帮你总结内容，但无法替代你亲手阅读、思考、建立直觉的过程。

第2章：CRUD模式（CRUD Patterns）

一、导读

1.1 本章学习目标

第2章讲解 API 设计中最基础的模式——CRUD（创建、读取、更新、删除）。

本章的核心学习目标包括：

  • 掌握资源命名的最佳实践
  • 理解 HTTP 方法的语义
  • 学会设计请求和响应格式
  • 掌握错误处理的标准模式

1.2 为什么本章如此重要

CRUD 是 80% 的 API 操作。设计好 CRUD 模式，就奠定了整个 API 的基础。

1.3 核心问题引导

REST 的 CRUD 操作如何映射到 HTTP 方法？

如何设计清晰的资源命名？

错误响应应该包含什么信息？

创建操作应该返回什么？

二、核心概念详解

2.1 HTTP 方法语义

HTTP 方法与 CRUD 的映射：

POST   → Create（创建）
GET    → Read（读取）
PUT    → Replace（全量替换）
PATCH  → Update（部分更新）
DELETE → Delete（删除）

幂等性：
- GET, PUT, DELETE：幂等（多次执行结果相同）
- POST：非幂等（每次创建新资源）
- PATCH：通常幂等

2.2 资源命名

资源命名规则：

1. 使用名词，不用动词
   ✓ GET /users
   ✗ GET /getUsers

2. 使用复数形式
   ✓ GET /users/123
   ✗ GET /user/123

3. 层级关系用路径表示
   ✓ GET /users/123/orders
   ✗ GET /orders?userId=123

4. 使用 kebab-case
   ✓ GET /order-items
   ✗ GET /orderItems

2.3 错误处理

json
// 标准错误响应格式
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format",
        "code": "INVALID_FORMAT"
      }
    ],
    "requestId": "req_abc123"
  }
}

// HTTP 状态码使用
200 OK           // 成功
201 Created      // 创建成功
204 No Content   // 删除成功
400 Bad Request  // 请求格式错误
401 Unauthorized // 未认证
403 Forbidden    // 无权限
404 Not Found    // 资源不存在
409 Conflict     // 冲突
422 Unprocessable // 验证失败
500 Internal     // 服务器错误

2.4 字段掩码（Field Mask）

// 请求指定返回字段
GET /api/v1/users/123?fields=name,email

// 响应只包含指定字段
{
  "name": "Alice",
  "email": "alice@example.com"
}

// 减少数据传输，提高性能

三、实战案例

3.1 案例一：完整的 CRUD API

用户管理 API：

# 创建
POST /api/v1/users
Content-Type: application/json
{
  "name": "Alice",
  "email": "alice@example.com"
}
→ 201 Created
{
  "id": "usr_123",
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2024-01-01T00:00:00Z"
}

# 读取
GET /api/v1/users/usr_123
→ 200 OK

# 列表
GET /api/v1/users?pageToken=xxx&pageSize=20
→ 200 OK

# 更新
PATCH /api/v1/users/usr_123
{
  "name": "Alice Smith"
}
→ 200 OK

# 删除
DELETE /api/v1/users/usr_123
→ 204 No Content

四、本章小结

HTTP 方法：POST 创建、GET 读取、PUT 替换、PATCH 更新、DELETE 删除。

资源命名：名词复数、kebab-case、层级路径。

错误处理：标准格式、合适的状态码、详细信息。

字段掩码：减少数据传输。

五、思考与练习

设计一个商品管理 API 的完整 CRUD 操作。

PUT 和 PATCH 有什么区别？各适用于什么场景？

如何设计一个支持批量操作的 API？

2/7CRUD
0%