2. RESTful API 设计原则

REST（Representational State Transfer，表述性状态转移）是一种架构风格，而非具体协议。它由 Roy Fielding 于 2000 年在其博士论文中提出，强调通过资源（Resource）的表述（Representation）来驱动状态转移（State Transfer）。在微服务架构中，RESTful API 是服务间通信与对外暴露接口的主流选择之一。

2.1 REST 架构风格六大约束

一个符合 REST 风格的架构必须满足以下六大约束条件：

2.2 资源导向设计

资源是 REST 的核心抽象。资源导向设计（Resource-Oriented Design）要求将业务实体抽象为名词，并通过 URI 进行唯一标识。URI 只描述资源，不描述操作。

• 资源命名：使用复数名词，如 /users、/orders、/products。
• 层级关系：通过路径表达从属关系，如 /users/{userId}/orders。
• 查询参数：用于过滤、排序、分页，如 /orders?status=active&page=1。
• 避免动词：不要出现 /getUser、/createOrder 等动词路径。

# 反例（非资源导向）
GET /api/getUser?id=123
POST /api/createOrder
POST /api/deleteProduct?id=456

# 正例（资源导向）
GET /api/users/123
POST /api/orders
DELETE /api/products/456

2.3 HTTP 动词与 CRUD 映射

HTTP 协议定义了一组动词（Methods），用于对资源执行操作。RESTful API 严格遵循动词语义：

2.4 HTTP 状态码语义

状态码是服务器对请求结果的标准化反馈。正确使用状态码能让客户端无需解析响应体即可判断请求结果。

2.5 HATEOAS 概念

HATEOAS（Hypermedia As The Engine Of Application State，超媒体作为应用状态引擎）是 REST 架构风格中统一接口约束的关键组成部分。它要求服务器在响应中提供超媒体链接，引导客户端发现并执行后续可能的操作。

• 核心思想：客户端无需预先知道 API 的 URL 结构，通过响应中的链接动态导航。
• 实现方式：在 JSON 或 XML 响应中包含 links 或 _links 字段，每个链接包含 rel（关系）、href（URI）、method（动词）等信息。
• 价值：降低客户端与服务端的耦合，服务端可自由调整 URI 结构而不破坏客户端。

{
  "orderId": "ord-2024-001",
  "status": "pending",
  "totalAmount": 299.00,
  "_links": {
    "self": { "href": "/api/orders/ord-2024-001", "method": "GET" },
    "pay": { "href": "/api/orders/ord-2024-001/payment", "method": "POST" },
    "cancel": { "href": "/api/orders/ord-2024-001", "method": "DELETE" },
    "items": { "href": "/api/orders/ord-2024-001/items", "method": "GET" }
  }
}

2.6 RESTful API 设计流程总览

以下 SVG 图展示了从业务实体到 RESTful API 的完整设计流程：

2.7 REST 与 gRPC 设计哲学对比

在微服务双协议桥接场景中，理解 REST 与 gRPC 的设计差异至关重要：

2.8 RESTful API 设计检查清单

以下清单可用于评审 API 设计是否符合 REST 原则：

• 资源命名：使用复数名词，路径层级不超过 3 层。
• 动词使用：GET 不修改资源状态，POST 用于创建，PUT 用于整体替换，DELETE 用于删除。
• 状态码：成功使用 2xx，客户端错误使用 4xx，服务端错误使用 5xx。
• 版本管理：通过 URI 前缀（/v1/）或请求头（Accept: application/vnd.api+json;version=1）管理。
• 分页：列表接口支持 page 和 size 参数，响应中包含总记录数。
• 错误响应：统一错误格式，包含 error、message、details 字段。
• HATEOAS：关键资源响应中包含 _links 导航。
• 安全性：使用 HTTPS，敏感操作需认证授权。