名称: restful-hateoas 描述: 遵循Richardson成熟度模型直至第3级（HATEOAS）的Ruby on Rails RESTful API设计指南。此技能应用于设计、构建、审查或重构REST API，以确保正确的资源建模、HTTP方法语义、超媒体控制、内容协商和API可进化性。触发涉及Rails中API控制器、序列化器、路由、链接关系、分页、错误处理或HTTP缓存的任务。
社区RESTful HATEOAS最佳实践
在Ruby on Rails中构建达到REST荣耀（Richardson成熟度级别3）的REST API的全面指南。包含9个类别中的47条规则，按请求/响应生命周期排序——从资源URI设计到超媒体链接关系到API进化。
何时应用
在以下情况参考这些指南：
- 设计新的REST API端点和资源URI
- 向API响应添加超媒体控制（_links, affordances）
- 使用HAL、JSON:API或供应商媒体类型实现内容协商
- 构建分页、可过滤、可排序的集合端点
- 审查API以获取正确的HTTP方法语义和状态码
- 在不破坏现有客户端的情况下进化API
规则类别按优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 资源建模 | 关键 | res- |
| 2 | HTTP方法语义 | 关键 | http- |
| 3 | 超媒体和链接关系 | 关键 | link- |
| 4 | 状态码和响应头 | 高 | status- |
| 5 | 内容协商和媒体类型 | 高 | media- |
| 6 | 集合模式 | 中高 | coll- |
| 7 | 错误语义 | 中 | err- |
| 8 | 缓存和条件请求 | 中 | cache- |
| 9 | API进化 | 低中 | evolve- |
快速参考
1. 资源建模（关键）
res-noun-based-uris- URI必须是名词，不是动词res-plural-collection-uris- 始终使用复数名词表示集合res-limit-nesting-depth- 限制嵌套资源到最多2级res-model-business-entities- 建模业务实体，不是数据库表res-use-consistent-identifiers- 使用不透明标识符，永不使用自增IDres-sub-resources-for-relationships- 将关系表达为子资源
2. HTTP方法语义（关键）
http-get-must-be-safe- 保持GET请求无副作用http-post-for-creation- 从POST返回201 Created并带Location头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. 超媒体和链接关系（关键）
link-self-link-every-resource- 在每个资源中包含自链接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-Typemedia-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?进行条件GETcache-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 | 版本和参考信息 |