API 模式

api-patterns

分类编程

作者Agentic Awesome Skills 社区

许可MIT

评分4.80/5

使用10.8K

API 模式 (API Patterns)

> 2025 年的 API 设计原则与决策指南。
> 学会思考，而非死板地套用模式。

🎯 选择性阅读原则

仅阅读与请求相关的文件！ 请查看内容地图，寻找所需内容。

---

📑 内容地图

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

---

🔗 相关技能

| 需求 | 技能 |
|------|-------|
| API 实现 | @[skills/backend-development] |
| 数据结构 | @[skills/database-design] |
| 安全细节 | @[skills/security-hardening] |

---

✅ 决策清单

在设计 API 之前：

[ ] 是否询问了 API 的调用方是谁？

[ ] 是否针对当前场景选择了合适的 API 风格？ (REST/GraphQL/tRPC)

[ ] 是否定义了统一的响应格式？

[ ] 是否规划了版本控制策略？

[ ] 是否考虑了认证需求？

[ ] 是否规划了限流机制？

[ ] 是否确定了文档编写方案？

---

❌ 反模式

避免：

无论什么场景都默认使用 REST

在 REST 终结点中使用动词 (例如 /getUsers)

返回不一致的响应格式

将内部错误直接暴露给客户端

忽略限流机制

建议：

根据具体场景选择 API 风格

确认客户端的具体需求

编写详尽的文档

使用正确的 HTTP 状态码

---

脚本

| 脚本 | 用途 | 命令 |
|--------|---------|---------|
| scripts/api_validator.py | API 终结点验证 | python scripts/api_validator.py <project_path> |

使用时机

当需要执行概览中描述的工作流或操作时，适用此技能。

局限性

仅在任务明确符合上述范围时使用此技能。

不要将输出结果视为环境特定验证、测试或专家评审的替代方案。

如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。