restful-hateoas

社区 RESTful HATEOAS 最佳实践

全面介绍如何在 Ruby on Rails 中构建达到 REST 卓越境界（Richardson 成熟度模型第 3 级）的 REST API。包含 9 个类别中的 47 条规则，按请求／响应生命周期排序，涵盖从资源 URI 设计到超媒体链接关系，再到 API 演进。

适用场景

在以下情况中可参考这些指南：

• 设计新的 REST API 端点和资源 URI
• 在 API 响应中添加超媒体控件（_links、操作选项）
• 使用 HAL、JSON:API 或供应商媒体类型实现内容协商
• 构建支持分页、筛选和排序的集合端点
• 检查 API 是否正确使用 HTTP 方法语义和状态码
• 在不破坏现有客户端的前提下演进 API

按优先级划分的规则类别

优先级	类别	影响	前缀
1	资源建模	CRITICAL	res-
2	HTTP 方法语义	CRITICAL	http-
3	超媒体与链接关系	CRITICAL	link-
4	状态码与响应标头	HIGH	status-
5	内容协商与媒体类型	HIGH	media-
6	集合模式	MEDIUM-HIGH	coll-
7	错误语义	MEDIUM	err-
8	缓存与条件请求	MEDIUM	cache-
9	API 演进	LOW-MEDIUM	evolve-

快速参考

1. 资源建模（CRITICAL）

• res-noun-based-uris - URI 必须使用名词，而不是动词
• res-plural-collection-uris - 集合 URI 始终使用复数名词
• res-limit-nesting-depth - 嵌套资源最多限制为 2 层
• res-model-business-entities - 对业务实体建模，而不是数据库表
• res-use-consistent-identifiers - 使用不透明标识符，切勿使用自增 ID
• res-sub-resources-for-relationships - 将关系表示为子资源

2. HTTP 方法语义（CRITICAL）

• http-get-must-be-safe - 确保 GET 请求没有副作用
• http-post-for-creation - POST 请求应返回带有 Location 标头的 201 Created
• http-put-for-full-replacement - 仅在完整替换资源时使用 PUT
• http-patch-for-partial-updates - 使用 PATCH 进行具有合并语义的部分更新
• http-delete-is-idempotent - 确保 DELETE 具有幂等性
• http-head-for-metadata - 使用 HEAD 获取元数据，无需传输正文
• http-idempotency-key - 使用幂等键安全地重试 POST 请求

3. 超媒体与链接关系（CRITICAL）

• link-self-link-every-resource - 在每个资源中包含 self 链接
• link-related-resource-links - 链接到相关资源，而不是使用外键
• link-action-affordances - 通过条件链接公开可用操作
• link-standard-relation-types - 使用 IANA 注册的链接关系类型
• link-entry-point - 提供 API 根入口
• link-pagination-links - 使用超媒体链接实现分页
• link-embedded-vs-linked - 选择嵌入资源还是使用链接

4. 状态码和响应标头（高）

• status-201-with-location - 返回 201 Created，并包含 Location 标头
• status-204-for-no-content - 空响应返回 204 No Content
• status-409-for-conflicts - 状态冲突时返回 409 Conflict
• status-202-for-async - 异步操作返回 202 Accepted
• status-allow-header-on-405 - 方法不正确时返回 405，并包含 Allow 标头
• status-rate-limit-headers - 在 API 响应中包含速率限制标头

5. 内容协商和媒体类型（高）

• media-accept-header-negotiation - 遵循 Accept 标头进行内容协商
• media-content-type-in-responses - 在每个响应中设置正确的 Content-Type
• media-vendor-media-types - 使用厂商媒体类型对 API 进行版本控制
• media-406-for-unsupported-types - 对不支持的媒体类型返回 406

6. 集合模式（中高）

• coll-cursor-pagination - 使用基于游标的分页，而不是偏移量
• coll-link-header-pagination - 在正文和 Link 标头中包含分页链接
• coll-filtering-via-query-params - 支持通过类型化查询参数进行筛选
• coll-sorting-convention - 使用标准化的排序参数支持排序
• coll-field-selection - 通过 fields 参数支持稀疏字段集

7. 错误语义（中）

• err-problem-details - 使用 Problem Details（RFC 9457）表示错误
• err-validation-errors - 返回结构化的验证错误
• err-error-links - 在错误响应中包含恢复链接
• err-machine-readable-codes - 使用机器可读的错误代码
• err-auth-error-codes - 区分 401 Unauthorized 和 403 Forbidden

8. 缓存和条件请求（中）

• cache-etag-conditional-get - 使用 ETag 和 stale? 进行条件 GET
• cache-last-modified - 设置 Last-Modified 以进行基于时间的验证
• cache-cache-control-headers - 设置明确的 Cache-Control 标头
• cache-vary-header - 针对依赖内容的缓存添加 Vary 标头

9. API 演进（低至中）

• evolve-additive-changes-only - 仅对响应进行增量式更改
• evolve-deprecation-headers - 使用 Deprecation 和 Sunset 标头
• evolve-hateoas-reduces-versioning - 利用 HATEOAS 消除 URL 版本控制

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 用于添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息