mcpField
A
api-patterns

api-patterns

github.com/vudovn开发8.2k204 次安装10 周前更新
代码仓库

关于 api-patterns

api-patterns 是供 API 设计者参考的决策指南，涵盖 API 风格、响应结构、安全与演进等主题，并提供端点验证脚本。

主要功能

  1. 01REST、GraphQL 与 tRPC 选择
  2. 02资源命名与 HTTP 状态码指引
  3. 03响应格式与分页建议
  4. 04版本管理与认证方案
  5. 05限流、安全测试与文档指引
  6. 06API 端点验证脚本

适用场景

  1. 01为项目选择合适的 API 风格
  2. 02规划一致的响应格式与版本策略
  3. 03评估认证、限流和安全测试需求
  4. 04使用脚本验证 API 端点

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vudovn/ag-kit --skill api-patterns

安装后在 Claude Code 中输入/api-patterns确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

api-style.md
auth.md
documentation.md
graphql.md
rate-limiting.md
response.md
rest.md
security-testing.md
trpc.md
versioning.md
scripts/
api_validator.py

详细介绍

API 模式

API 设计原则与决策。 学会思考，而不是照搬固定模式。

🎯 选择性阅读规则

只阅读与请求相关的文件！ 查看内容索引，找到所需内容。

📑 内容索引

文件描述阅读时机
api-style.mdREST、GraphQL 与 tRPC 决策树选择 API 类型时
rest.md资源命名、HTTP 方法、状态码设计 REST API 时
response.md信封模式、错误格式、分页设计响应结构时
graphql.mdSchema 设计、适用场景、安全性考虑采用 GraphQL 时
trpc.mdTypeScript 单体仓库、类型安全TS 全栈项目
versioning.mdURI/Header/Query 版本控制规划 API 演进时
auth.mdJWT、OAuth、Passkey、API Keys选择认证模式时
rate-limiting.md令牌桶、滑动窗口保护 API 时
documentation.mdOpenAPI/Swagger 最佳实践编写文档时
security-testing.mdOWASP API Top 10、认证/授权测试安全审计时

🔗 相关技能

需求技能
API 实现@[skills/nodejs-best-practices]
数据结构@[skills/database-design]
安全详情@[skills/vulnerability-scanner]

✅ 决策清单

设计 API 之前：

  • 是否询问过用户有哪些 API 使用方？
  • 是否针对当前场景选择了 API 风格？（REST/GraphQL/tRPC）
  • 是否定义了一致的响应格式？
  • 是否规划了版本控制策略？
  • 是否考虑了身份验证需求？
  • 是否规划了速率限制？
  • 是否确定了文档方案？

❌ 反模式

不要：

  • 默认所有场景都使用 REST
  • 在 REST 端点中使用动词（/getUsers）
  • 返回不一致的响应格式
  • 向客户端暴露内部错误
  • 跳过速率限制

应该：

  • 根据场景选择 API 风格
  • 询问客户端需求
  • 完善文档
  • 使用适当的状态码

脚本

脚本用途命令
scripts/api_validator.pyAPI 端点验证python scripts/api_validator.py <project_path>

评论

支持 Markdown