Open Skills Logo
Open Skills

api-patterns

API设计原则与决策制定。REST、GraphQL与tRPC的选择，响应格式，版本控制，分页处理。

作者

@sickn33

分类

开发工具

安装

热度:7

下载并解压到你的 skills 目录

复制命令，发送给 OpenClaw 自动安装：

下载并安装这个技能 https://openskills.cc/api/download?slug=sickn33-skills-api-patterns&locale=zh&source=copy

API Patterns - API 设计决策助手

API Patterns 是一个 API 设计原则与决策指南技能，帮助开发者根据实际场景选择合适的 API 风格（REST、GraphQL、tRPC），并指导响应格式设计、版本控制策略、分页实现等关键架构决策。

适用场景

  • 新项目 API 架构选型：当你开始一个新项目，需要决定使用 REST、GraphQL 还是 tRPC 时，本技能提供决策树和对比分析，帮助你根据团队技术栈、客户端需求、数据复杂度做出选择。

  • API 重构与迁移：当现有 API 遇到性能瓶颈、过度获取数据或类型安全问题，需要评估 GraphQL 或 tRPC 等替代方案时，本技能提供迁移路径和注意事项。

  • API 规范制定与审查：当团队需要制定统一的 API 设计规范（资源命名、HTTP 方法使用、状态码规范、错误处理），或需要审查现有 API 设计是否符合最佳实践时，本技能提供检查清单和反模式警示。

    • 核心功能

  • API 风格决策支持：提供 REST vs GraphQL vs tRPC 的详细对比，包括各自的优势、局限性和适用场景。例如：REST 适合公共 API 和简单 CRUD；GraphQL 适合复杂数据需求和移动端；tRPC 适合 TypeScript 全栈项目，提供端到端类型安全。

  • API 设计规范指导：涵盖 RESTful 资源命名规范、HTTP 方法正确使用、状态码选择、分页策略（游标分页 vs 偏移分页）、错误响应格式设计等，确保 API 一致性和可维护性。

  • API 生命周期管理：包括版本控制策略（URI 版本、Header 版本、Query 参数版本）、认证方案选择（JWT、OAuth、Passkey、API Keys）、限流保护（令牌桶、滑动窗口）以及文档化实践（OpenAPI/Swagger）。

    • 常见问题

    REST、GraphQL 和 tRPC 应该如何选择？

    选择取决于项目上下文：REST 是最通用、标准化的选择，适合公共 API 和简单 CRUD 操作；GraphQL 适合客户端需要灵活查询、减少网络请求、数据关系复杂的场景；tRPC 最适合 TypeScript 全栈项目，提供端到端类型安全和零配置开发体验。关键是要问自己：API 的消费者是谁？团队技术栈是什么？数据查询复杂度如何？

    API 版本控制有哪些最佳实践？

    常见方案包括 URI 版本（/v1/users）、HTTP Header 版本（Accept: application/vnd.api.v1+json）和 Query 参数版本（?version=1）。URI 版本最直观，适合公共 API；Header 版本 URL 更简洁，但需要客户端配合；Query 参数版本最简单但不推荐用于复杂场景。无论选择哪种，都应提前规划版本废弃策略和迁移路径。

    如何设计统一的 API 错误响应格式？

    建议使用 Envelope 模式，将响应包裹在统一结构中：{ data: {...}, errors: [...], meta: {...} }。错误信息应包含机器可读的错误码和人类可读的消息，例如 { "code": "VALIDATION_ERROR", "message": "邮箱格式无效", "field": "email" }。避免直接暴露内部堆栈或数据库错误，使用适当的 HTTP 状态码（4xx 客户端错误，5xx 服务端错误）。