什么是 Richardson 成熟度模型
Richardson 成熟度模型用四个级别描述 HTTP API 的成熟程度：级别 0 是单端点传参调用，级别 1 引入资源化路径，级别 2 使用 HTTP 方法与状态码表达语义，级别 3 由超媒体驱动客户端。它是沟通定位工具而非评分表，多数业务 API 稳定在级别 2 已经足够。
基本信息
| 提出者 | Leonard Richardson（《RESTful Web Services》相关著作） |
|---|---|
| 四个级别 | 0 单端点、1 资源化、2 动词与状态码、3 超媒体 |
| 判断依据 | URL 是否表达资源、是否用方法语义、是否有状态转移链接 |
| 使用方式 | 作为团队对话框架，用于说明设计取舍而非打分排名 |
四个级别
| 级别 | 特征 | 说明 |
|---|---|---|
| 0 | 单端点传参调用 | 本质是 RPC 风格，用同一路径承载所有操作 |
| 1 | 资源化路径 | 按资源划分 URL，多个端点各自对应一类资源 |
| 2 | 动词与状态码 | 用方法表达动作、用状态码表达结果，多数业务 API 的落点 |
| 3 | 超媒体驱动 | 响应携带可用状态转移链接，客户端更通用 |
典型使用场景
- 接口评审：用级别说明现状与目标，快速对齐期望
- 对外 API 设计：对外接口通常至少达到级别 2，便于第三方理解与缓存
- 内部接口权衡：内部服务调用停在级别 1 或 2，用 RPC 风格反而更直接
- 网关与缓存：级别 2 的方法语义让缓存、重试与限流策略有据可依
- 团队沟通：避免把级别 3 当作必须达成的目标，减少无效投入
- 存量改造：为老接口排优先级，先补方法语义与状态码，再考虑超媒体
级别对照示例
级别对照示例
# 级别 0：单端点传参
POST /api {"action": "getOrder", "id": 1001}
# 级别 1：资源化路径
POST /orders/1001/get
# 级别 2：动词与状态码
GET /orders/1001 -> 200 返回订单
POST /orders -> 201 创建订单
DELETE /orders/1001 -> 204 删除成功
# 级别 3：超媒体驱动（响应内含可用状态转移）
GET /orders/1001 -> { "id": 1001, "status": "pending",
"_links": { "cancel": { "href": "/orders/1001/cancel" } } }级别 2 是多数业务 API 的合理落点：方法语义与状态码带来的可理解性、可缓存性与网关友好度，性价比最高。
成熟度高低与接口质量不划等号：能纠正状态码误用、请求体用错动词等问题，比追求级别 3 更常见也更有价值。