重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
restful-hateoas by pproenca/dot-skills
npx skills add https://github.com/pproenca/dot-skills --skill restful-hateoas在 Ruby on Rails 中构建达到 REST 荣耀(Richardson 成熟度模型第 3 级)的 REST API 的全面指南。包含 9 个类别共 47 条规则,按请求/响应生命周期排序——从资源 URI 设计到超媒体链接关系,再到 API 演进。
在以下情况下参考这些指南:
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 资源建模 | 关键 | res- |
| 2 | HTTP 方法语义 | 关键 | http- |
| 3 | 超媒体与链接关系 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 关键 |
link- |
| 4 | 状态码与响应头 | 高 | status- |
| 5 | 内容协商与媒体类型 | 高 | media- |
| 6 | 集合模式 | 中高 | coll- |
| 7 | 错误语义 | 中 | err- |
| 8 | 缓存与条件请求 | 中 | cache- |
| 9 | API 演进 | 低中 | evolve- |
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 - 将关系表达为子资源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 重试安全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 - 在嵌入和链接之间做出选择status-201-with-location - 返回 201 Created 并附带 Location 头status-204-for-no-content - 对于空响应返回 204 No Contentstatus-409-for-conflicts - 对于状态冲突返回 409 Conflictstatus-202-for-async - 对于异步操作返回 202 Acceptedstatus-allow-header-on-405 - 对于错误的方法返回 405 并附带 Allow 头status-rate-limit-headers - 在 API 响应中包含速率限制头media-accept-header-negotiation - 尊重 Accept 头进行内容协商media-content-type-in-responses - 在每个响应中设置正确的 Content-Typemedia-vendor-media-types - 使用供应商媒体类型进行 API 版本控制media-406-for-unsupported-types - 对于不支持的媒体类型返回 406coll-cursor-pagination - 使用基于游标的分页而非偏移量coll-link-header-pagination - 在正文和 Link 头中包含分页链接coll-filtering-via-query-params - 通过类型化查询参数支持过滤coll-sorting-convention - 使用标准化的排序参数支持排序coll-field-selection - 通过 fields 参数支持稀疏字段集err-problem-details - 使用问题详情(RFC 9457)处理错误err-validation-errors - 返回结构化的验证错误err-error-links - 在错误响应中包含恢复链接err-machine-readable-codes - 使用机器可读的错误代码err-auth-error-codes - 区分 401 Unauthorized 和 403 Forbiddencache-etag-conditional-get - 将 ETag 与 stale? 结合使用以实现条件 GETcache-last-modified - 设置 Last-Modified 以进行基于时间的验证cache-cache-control-headers - 设置明确的 Cache-Control 头cache-vary-header - 包含 Vary 头以实现内容相关缓存evolve-additive-changes-only - 仅对响应进行增量的更改evolve-deprecation-headers - 使用 Deprecation 和 Sunset 头evolve-hateoas-reduces-versioning - 利用 HATEOAS 消除 URL 版本控制阅读各个参考文件以获取详细说明和代码示例:
| 文件 | 描述 |
|---|---|
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本和参考信息 |
每周安装次数
60
代码仓库
GitHub 星标数
95
首次出现
2026年2月12日
安全审计
已安装于
codex56
github-copilot55
gemini-cli55
kimi-cli54
opencode54
claude-code52
Comprehensive guide to building REST APIs that reach the Glory of REST (Richardson Maturity Level 3) in Ruby on Rails. Contains 47 rules across 9 categories, ordered by the request/response lifecycle — from resource URI design through hypermedia link relations to API evolution.
Reference these guidelines when:
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Resource Modeling | CRITICAL | res- |
| 2 | HTTP Method Semantics | CRITICAL | http- |
| 3 | Hypermedia & Link Relations | CRITICAL | link- |
| 4 | Status Codes & Response Headers | HIGH | status- |
| 5 | Content Negotiation & Media Types | HIGH | media- |
| 6 | Collection Patterns | MEDIUM-HIGH | coll- |
| 7 | Error Semantics | MEDIUM | err- |
| 8 | Caching & Conditional Requests | MEDIUM | cache- |
| 9 | API Evolution | LOW-MEDIUM | evolve- |
res-noun-based-uris - URIs must be nouns, not verbsres-plural-collection-uris - Always use plural nouns for collectionsres-limit-nesting-depth - Limit nested resources to max 2 levelsres-model-business-entities - Model business entities, not database tablesres-use-consistent-identifiers - Use opaque identifiers, never auto-increment IDshttp-get-must-be-safe - Keep GET requests free of side effectshttp-post-for-creation - Return 201 Created with Location header from POSThttp-put-for-full-replacement - Use PUT only for full resource replacementhttp-patch-for-partial-updates - PATCH for partial updates with merge semanticshttp-delete-is-idempotent - Ensure DELETE is idempotentlink-self-link-every-resource - Include a self link in every resourcelink-related-resource-links - Link to related resources instead of foreign keyslink-action-affordances - Expose available actions as conditional linkslink-standard-relation-types - Use IANA-registered link relation typeslink-entry-point - Provide a root API entry pointstatus-201-with-location - Return 201 Created with Location headerstatus-204-for-no-content - Return 204 No Content for empty responsesstatus-409-for-conflicts - Return 409 Conflict for state conflictsstatus-202-for-async - Return 202 Accepted for async operationsstatus-allow-header-on-405 - Return 405 with Allow header for wrong methodsmedia-accept-header-negotiation - Respect the Accept header for content negotiationmedia-content-type-in-responses - Set the correct Content-Type in every responsemedia-vendor-media-types - Use vendor media types for API versioningmedia-406-for-unsupported-types - Return 406 for unsupported media typescoll-cursor-pagination - Use cursor-based pagination instead of offsetcoll-link-header-pagination - Include pagination links in body and Link headercoll-filtering-via-query-params - Support filtering via typed query parameterscoll-sorting-convention - Support sorting with a standardized sort parametercoll-field-selection - Support sparse fieldsets via fields parametererr-problem-details - Use Problem Details (RFC 9457) for errorserr-validation-errors - Return structured validation errorserr-error-links - Include recovery links in error responseserr-machine-readable-codes - Use machine-readable error codeserr-auth-error-codes - Distinguish 401 Unauthorized from 403 Forbiddencache-etag-conditional-get - Use ETags with stale? for conditional GETcache-last-modified - Set Last-Modified for time-based validationcache-cache-control-headers - Set explicit Cache-Control headerscache-vary-header - Include Vary header for content-dependent cachingevolve-additive-changes-only - Make only additive changes to responsesevolve-deprecation-headers - Use Deprecation and Sunset headersevolve-hateoas-reduces-versioning - Leverage HATEOAS to eliminate URL versioningRead individual reference files for detailed explanations and code examples:
| File | Description |
|---|---|
| references/_sections.md | Category definitions and ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and reference information |
Weekly Installs
60
Repository
GitHub Stars
95
First Seen
Feb 12, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex56
github-copilot55
gemini-cli55
kimi-cli54
opencode54
claude-code52
lark-cli 共享规则:飞书资源操作指南与权限配置详解
48,600 周安装
TanStack Start 全栈开发:基于 Cloudflare 的 React 19 + D1 数据库应用构建指南
1,300 周安装
Doublecheck AI 内容验证工具 - GitHub Copilot 三层事实核查流程,自动识别幻觉风险
1,400 周安装
Sentry问题修复指南:利用AI分析生产环境错误并自动修复
1,300 周安装
退货与逆向物流管理指南:策略、分级、处置与欺诈检测全流程解析
1,400 周安装
Next.js Turbopack 开发指南:加速启动与热更新,提升开发效率
1,400 周安装
Unity测试运行器 - 命令行自动化执行Unity EditMode/PlayMode测试,集成CI/CD
45 周安装
res-sub-resources-for-relationshipshttp-head-for-metadatahttp-idempotency-key - Use idempotency keys for safe POST retrieslink-pagination-linkslink-embedded-vs-linked - Choose between embedding and linkingstatus-rate-limit-headers