用途:面向 REST API 设计与文档工作,提供一套可参考的架构原则与规范实践,涵盖资源设计、HTTP 方法、查询参数、版本化、OpenAPI/Swagger 规范、限流、错误处理、认证、性能与缓存、文档编写等主题。
主要能力:资源使用复数名词与层级结构(如 /users、/users/{userId}/orders),避免 URI 中出现动词;GET/POST/PUT/PATCH/DELETE 的语义与幂等性说明;查询参数用于过滤、排序、分页;URI 或 Header 版本化策略;OpenAPI 3.0+/3.1 规范与 webhook、Overlay 等扩展;429 与 X-RateLimit-* 等限流模式;统一错误响应结构与状态码;OAuth 2.1、JWT、API Key 认证要点;HTTP 缓存头与压缩、字段选择、异步操作等优化;以及 Swagger UI、Postman 等文档工具建议。
使用方式:资料为方法论与规范参考,未提供安装命令或代码运行方式。文中包含记忆协议:开始前执行 cat .claude/context/memory/learnings.md,完成后记录新发现;并提示上下文可能重置,若未写入记忆则视为未发生。
适用场景:设计或评审 REST API、编写 OpenAPI 文档、制定版本化与限流策略、统一错误与认证规范等。
限制:未提供具体收费、价格、平台支持或实测效果信息;示例代码为规范片段,未给出完整可运行项目;部分内容涉及 2025/2026 版本特性,实际适用性需结合所用工具版本确认。