SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场api-design-patterns

api-design-patterns

编程与开发

查看项目

更新于 10-15 12:09

技能介绍

用途

API Design Patterns 是一套关于 API 设计的模式与最佳实践集合，目标是在设计 REST、GraphQL、gRPC 等 API 时应用经过验证的模式，覆盖版本管理、认证与错误处理等关键环节。适合后端开发者、架构师与需要评审 API 设计的技术团队参考。

主要内容

API 风格选择

内容给出三种风格的适用与不适用场景：

  • REST：适合基于资源的 CRUD、需要 HTTP 原生缓存（ETag、Cache-Control）、需要广泛平台兼容（浏览器、移动端、IoT）、简单无状态客户端-服务器模型。不适合复杂嵌套关系获取（N+1 查询）、以实时更新为主、需要强类型与代码生成、微服务间高性能 RPC。典型场景：公开 API、移动后端、传统 Web 服务。
  • GraphQL：适合客户端驱动查询、复杂嵌套数据图、多客户端不同数据需求、需要实时订阅、需要强类型与模式校验。不适合简单 CRUD 为主、HTTP 缓存关键（GraphQL 使用 POST）、文件上传为主要功能、团队缺乏 GraphQL 经验、性能优化复杂（N+1 问题）。典型场景：面向客户端的 API、仪表盘、界面多样的移动应用。
  • gRPC：适合微服务间通信、高性能低延迟、双向流、Protocol Buffers 强类型、多语言环境。不适合浏览器客户端（支持有限，需要 grpc-web）、必须 HTTP/JSON 兼容、偏好人类可读载荷、简单请求-响应模式。典型场景：内部微服务、流式数据、服务网格。

通用设计原则

  • 一致性优于取巧：遵循所选风格的既定约定，统一命名（snake_case 或 camelCase 选其一），统一错误响应格式，破坏性变更必须版本化。
  • 为演进而设计：从第一天规划版本管理，使用带默认值的可选字段，优雅弃用并提供 sunset 日期，区分破坏性与非破坏性变更。
  • 默认安全：除非明确公开否则要求认证，生产端点使用 HTTPS/TLS，实施限流与节流，校验与净化所有输入，向客户端返回最小错误细节。
  • 开发者体验优先：提供完整文档（OpenAPI、GraphQL schema），返回可操作的错误信息，正确使用标准 HTTP 状态码，提供请求 ID 便于调试，提供 SDK 与代码生成器。

REST 模式

  • 资源命名：使用复数名词与层级结构（如 GET /users、GET /users/123/orders）；避免动词、大小写混用、单复数混用。
  • HTTP 状态码：涵盖 2xx（200/201/202/204）、4xx（400/401/403/404/409/422/429）、5xx（500/502/503/504）及各自含义。
  • 统一错误格式：包含 error.code、error.message、details（字段级错误）、request_id、documentation_url。
  • 分页：offset（简单、熟悉，适合小数据集与管理界面）、cursor（稳定高效，适合无限滚动、实时流、大数据集）、keyset（性能好，适合有序数据与数据库索引友好场景）。

GraphQL 模式

  • Schema 设计：默认可空、明确非空标记（ID!、String!），定义 Query、Mutation、Input 与 Payload 类型，使用连接（Connection）风格分页。
  • Resolver 模式：使用 DataLoader 批量查询避免 N+1 问题。
  • 查询复杂度分析：通过复杂度限制规则防止昂贵查询。

gRPC 模式

  • 服务定义：proto3 语法定义 service 与 message，支持一元调用、服务端流、双向流。
  • 错误处理：使用 gRPC codes（InvalidArgument、NotFound、Internal 等）与 status.Error 返回错误。

版本管理

  • URI 版本：/v1/users，直观易路由，但版本与 URL 耦合。
  • Header 版本：Accept: application/vnd.myapi.v2+json，URL 干净但可见性较低。
  • 内容协商：资源级版本，向后兼容但实现复杂。
  • 弃用流程：返回 deprecated、sunset_date、migration_guide、replacement_version，并通过 Deprecation、Sunset、Link 响应头提示。

认证与授权

  • OAuth 2.0：用于第三方访问、用户授权、令牌刷新，包含授权码流程与令牌交换示例。
  • JWT：用于微服务、无状态认证、短时令牌，建议最小声明与短过期时间。
  • API Key：用于服务间、CLI、Webhook，建议按环境加前缀、存储前哈希、支持轮换与多密钥、按密钥限流。

限流、幂等与缓存

  • 限流：令牌桶（允许突发）、滑动窗口（分布公平），区分按用户与按 IP，返回 X-RateLimit-* 与 Retry-After 头，429 响应结构。
  • 幂等：GET/PUT/DELETE/HEAD/OPTIONS 天然幂等，POST/PATCH 不幂等；使用 Idempotency-Key 使 POST 幂等，重复请求返回已存结果，冲突返回 409；可用 ETag 与 If-Match 做条件更新。
  • 缓存：Cache-Control（public/private/no-store 等）、ETag 与 If-None-Match、Last-Modified 与 If-Modified-Since，命中返回 304。

Webhook

包含事件投递请求头（签名、ID、时间戳）、载荷结构、HMAC-SHA256 签名验证代码、指数退避重试策略（1s 到 64s）、超时与最大尝试次数、死信队列与手动重试。

API 文档

提供 OpenAPI 3.0 示例，包括 info、paths、参数、响应与组件 schema 引用。

使用方式

该内容以速查表与参考文件形式组织，正文给出核心模式与代码示例，更深入的内容指向 references/ 目录下的 rest-patterns.md、graphql-patterns.md、grpc-patterns.md、versioning-strategies.md、authentication.md 等文件。具体的安装命令、调用方式与平台信息暂未提供。

适用场景与限制

适用于设计公开 API、移动后端、内部微服务、流式服务、面向客户端的数据图等场景，也可作为 API 设计评审的对照清单。限制方面：内容以模式与最佳实践为主，未提供具体产品的价格、收费或平台支持信息；部分场景（如浏览器使用 gRPC）存在已知限制，需结合 grpc-web 等方案。