2. API设计原则：RESTful设计核心原则、资源命名规范、HTTP方法语义与状态码选择

RESTful API 设计并非一套僵化的协议，而是一组基于 Web 架构风格的约束与最佳实践。本章聚焦于三个核心维度：资源建模（将业务实体抽象为资源）、统一接口（通过标准 HTTP 方法操作资源）以及无状态通信（每个请求包含完整上下文）。掌握这些原则是构建可维护、可演进 API 的基础。

2.1 RESTful 设计核心原则

REST（Representational State Transfer）由 Roy Fielding 在其博士论文中提出，其核心约束包括：

• 资源标识：每个资源（如用户、订单）通过唯一的 URI 标识。
• 通过表征操作资源：客户端通过资源的表征（如 JSON、XML）与服务端交互。
• 自描述消息：每个请求和响应包含足够的信息（如媒体类型、缓存指令）以理解如何处理。
• 超媒体作为应用状态引擎（HATEOAS）：响应中包含链接，引导客户端发现后续操作。

下图展示了 RESTful 架构中客户端、资源与表征之间的核心交互流程：

2.2 资源命名规范

资源命名是 API 设计的“第一印象”，直接影响可读性和可发现性。以下是经过大量工程验证的命名规范：

2.3 HTTP 方法语义

HTTP 方法定义了客户端对资源期望执行的操作。RESTful API 应严格遵循每种方法的语义：

2.4 状态码选择

状态码是服务端向客户端传达操作结果的“第一语言”。选择正确的状态码能显著提升 API 的自描述能力。以下是 RESTful API 中最常用的状态码分类：

下图展示了 API 请求从发起到响应的完整状态码决策流程：

2.5 综合示例：用户资源 API

以下示例综合展示了资源命名、HTTP 方法和状态码的协同使用：

# 创建用户
POST /api/v2/users
Content-Type: application/json
{
  "name": "张三",
  "email": "zhangsan@example.com"
}
→ 201 Created
Location: /api/v2/users/12345

# 获取用户列表
GET /api/v2/users?page=1&size=20
→ 200 OK
{
  "data": [...],
  "total": 100,
  "page": 1
}

# 获取单个用户
GET /api/v2/users/12345
→ 200 OK
{
  "id": "12345",
  "name": "张三",
  "email": "zhangsan@example.com"
}

# 全量更新用户
PUT /api/v2/users/12345
Content-Type: application/json
{
  "name": "李四",
  "email": "lisi@example.com"
}
→ 200 OK

# 部分更新用户邮箱
PATCH /api/v2/users/12345
Content-Type: application/json
{
  "email": "newemail@example.com"
}
→ 200 OK

# 删除用户
DELETE /api/v2/users/12345
→ 204 No Content

# 权限不足示例
GET /api/v2/admin/settings
→ 403 Forbidden
{
  "error": "FORBIDDEN",
  "message": "当前用户无管理员权限"
}

# 资源不存在示例
GET /api/v2/users/99999
→ 404 Not Found
{
  "error": "NOT_FOUND",
  "message": "用户 99999 不存在"
}