2. REST API 基础：RESTful 架构风格定义、资源导向设计、HTTP 方法与状态码

2.1 RESTful 架构风格定义

REST（Representational State Transfer，表述性状态转移）是由 Roy Fielding 在 2000 年博士论文中提出的一种架构风格，而非具体协议或标准。其核心思想是将网络中的一切视为资源，并通过统一的接口对资源进行无状态操作。

RESTful 架构的六大约束条件：

1. 客户端-服务器（Client-Server）：分离关注点，客户端不关心数据存储，服务器不关心用户界面。
2. 无状态（Stateless）：每个请求包含所有必要信息，服务器不保存客户端上下文。
3. 可缓存（Cacheable）：响应隐式或显式标记为可缓存或不可缓存，提升网络效率。
4. 统一接口（Uniform Interface）：通过标准方法操作资源，简化架构。
5. 分层系统（Layered System）：客户端无法直接感知是否与端服务器或中间层通信。
6. 按需代码（Code on Demand，可选）：服务器可向客户端传输可执行代码（如 JavaScript）。

2.2 资源导向设计（Resource-Oriented Design）

资源导向设计是 RESTful API 的核心设计范式。每个资源通过 URI（统一资源标识符） 唯一标识，资源的表现形式（JSON/XML/HTML）通过 Content-Type 协商确定。

典型资源 URI 设计示例：

2.3 HTTP 方法（GET/POST/PUT/DELETE）与语义

RESTful API 通过标准 HTTP 方法对资源执行 CRUD（创建、读取、更新、删除）操作。每个方法具有明确的幂等性和安全性语义。

实际 API 调用示例：

// 获取用户列表
GET /users
Response 200:
[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob", "email": "bob@example.com" }
]

// 创建新用户
POST /users
Request Body: { "name": "Charlie", "email": "charlie@example.com" }
Response 201:
{ "id": 3, "name": "Charlie", "email": "charlie@example.com" }

// 全量更新用户
PUT /users/3
Request Body: { "name": "Charlie Updated", "email": "charlie.new@example.com" }
Response 200:
{ "id": 3, "name": "Charlie Updated", "email": "charlie.new@example.com" }

// 删除用户
DELETE /users/3
Response 204: (No Content)

2.4 HTTP 状态码（Status Codes）

HTTP 状态码是服务器对请求处理结果的标准化响应。RESTful API 应使用精确的状态码表达操作结果，而非统一返回 200。

2.5 完整请求-响应流程示例

以下展示一个完整的 RESTful API 交互流程，涵盖资源创建、查询、更新和删除：

// 1. 创建订单（POST）
POST /orders
Content-Type: application/json
{
  "userId": 1,
  "items": [
    { "productId": 101, "quantity": 2 },
    { "productId": 202, "quantity": 1 }
  ]
}
Response: 201 Created
Location: /orders/1001
{
  "id": 1001,
  "userId": 1,
  "status": "pending",
  "total": 299.99,
  "createdAt": "2025-01-15T10:30:00Z"
}

// 2. 查询订单（GET）
GET /orders/1001
Response: 200 OK
{
  "id": 1001,
  "userId": 1,
  "status": "pending",
  "items": [
    { "productId": 101, "name": "Widget A", "quantity": 2, "price": 99.99 },
    { "productId": 202, "name": "Gadget B", "quantity": 1, "price": 100.01 }
  ],
  "total": 299.99
}

// 3. 更新订单状态（PATCH）
PATCH /orders/1001
Content-Type: application/json
{ "status": "shipped" }
Response: 200 OK
{
  "id": 1001,
  "status": "shipped",
  "updatedAt": "2025-01-15T11:00:00Z"
}

// 4. 删除订单（DELETE）
DELETE /orders/1001
Response: 204 No Content