⚡

API设计Skill designing-apis

API设计技能专注于创建安全、可扩展和可维护的应用程序编程接口，采用RESTful、GraphQL和事件驱动模式。它涵盖资源设计、版本控制、错误处理、分页、速率限制和安全性，适用于设计新API、演进现有API或为团队建立API标准。关键词：API设计、RESTful、GraphQL、事件驱动、安全、可扩展、可维护、版本控制、错误处理。

架构设计 0 次安装 38 次浏览 更新于 3/23/2026

名称: designing-apis 描述: 设计安全、可扩展和可维护的API，使用RESTful、GraphQL和事件驱动模式。适用于设计新API、演进现有API或为团队建立API标准。

设计API

设计结构良好、可扩展的API，使用REST、GraphQL或事件驱动模式。专注于资源设计、版本控制、错误处理、分页、速率限制和安全性。

何时使用此技能

使用当：

  • 设计新的REST、GraphQL或事件驱动API
  • 为团队或组织建立API设计标准
  • 在REST、GraphQL、WebSockets或消息队列之间选择
  • 规划API版本控制和破坏性变更管理
  • 定义错误响应格式和HTTP状态码使用
  • 实现分页、过滤和速率限制模式
  • 设计OAuth2流程或API密钥认证
  • 创建OpenAPI或AsyncAPI规范

不要用于：

  • 实现代码（使用api-patterns技能处理Express、FastAPI代码）
  • 认证实现（使用auth-security技能处理JWT、会话）
  • API测试策略（使用testing-strategies技能）
  • API部署和基础设施（使用deploying-applications技能）

核心设计原则

资源导向设计（REST）

使用名词表示资源，不要在URL中使用动词：

✓ GET    /users              列出用户
✓ GET    /users/123          获取用户123
✓ POST   /users              创建用户
✓ PATCH  /users/123          更新用户123
✓ DELETE /users/123          删除用户123

✗ GET    /getUsers
✗ POST   /createUser

为关系嵌套资源（限制深度到2-3层）：

✓ GET /users/123/posts
✓ GET /users/123/posts/456/comments
✗ GET /users/123/posts/456/comments/789/replies  （太深）

有关完整REST模式，请参阅references/rest-design.md

HTTP方法语义

方法 幂等性 安全性 用途 成功状态
GET 是 是 读取资源 200 OK
POST 否 否 创建资源 201 Created
PUT 是 否 替换整个资源 200 OK, 204 No Content
PATCH 否 否 更新特定字段 200 OK, 204 No Content
DELETE 是 否 移除资源 204 No Content, 200 OK

幂等性意味着多个相同请求与一个请求具有相同效果。

HTTP状态码

成功（2xx）：

  • 200 OK, 201 Created, 204 No Content

客户端错误（4xx）：

  • 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
  • 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests

服务器错误（5xx）：

  • 500 Internal Server Error, 503 Service Unavailable

有关完整状态码指南，请参阅references/rest-design.md

API风格选择

决策矩阵

因素 REST GraphQL WebSocket 消息队列
公共API ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐ ⭐
复杂数据 ⭐⭐⭐ ⭐⭐⭐⭐⭐ ⭐⭐ ⭐⭐
缓存 ⭐⭐⭐⭐⭐ ⭐⭐ ⭐ ⭐
实时性 ⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐⭐
简单性 ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐ ⭐⭐

快速选择

  • 公共API，CRUD操作 → REST
  • 复杂数据，灵活查询 → GraphQL
  • 实时性，双向通信 → WebSockets
  • 事件驱动，微服务 → 消息队列

有关详细协议选择，请参阅references/protocol-selection.md

API版本控制

URL路径版本控制（推荐）

https://api.example.com/v1/users
https://api.example.com/v2/users

优点：明确，易于实现和测试 缺点：维护开销

替代策略

  • 基于头部的：Accept-Version: v1
  • 媒体类型：Accept: application/vnd.example.v1+json
  • 查询参数：?version=1（不推荐）

破坏性变更管理

时间线：

  1. 第0个月：宣布弃用
  2. 第1-3个月：迁移期
  3. 第4-6个月：弃用警告
  4. 第6个月：终止（返回410 Gone）

包括弃用头部：

Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: </api/v2/users>; rel="successor-version"

有关完整版本控制指南，请参阅references/versioning-strategies.md

错误响应标准

RFC 7807问题详情（推荐）

{
  "type": "https://api.example.com/errors/validation",
  "title": "验证错误",
  "status": 400,
  "detail": "一个或多个字段验证失败",
  "errors": [
    {
      "field": "email",
      "message": "必须是有效的电子邮件地址",
      "code": "INVALID_EMAIL"
    }
  ]
}

内容类型：application/problem+json

有关完整错误模式，请参阅references/error-handling.md

分页模式

策略选择

场景 策略 原因
小型数据集（<1000） 基于偏移 简单，页码
大型数据集（>10K） 基于游标 高效，处理写入
排序数据 键集 一致结果
实时流 基于游标 处理新项

基于偏移（简单）

GET /users?limit=20&offset=40

响应包括：limit, offset, total, currentPage

基于游标（可扩展）

GET /users?limit=20&cursor=eyJpZCI6MTIzfQ==

游标是base64编码的JSON，包含位置信息。 响应包括：nextCursor, hasNext

有关实现细节，请参阅references/pagination-patterns.md

速率限制

令牌桶算法

  • 每个用户有一个带令牌的桶
  • 每个请求消耗1个令牌
  • 令牌以恒定速率补充
  • 空桶拒绝请求

速率限制头部

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1672531200

当超过时（429）：

Retry-After: 3600

策略

  • 每用户：100请求/小时
  • 每API密钥：1000请求/小时
  • 每IP：50请求/小时（未认证）
  • 分层：免费（100/小时），专业（1000/小时），企业（10000/小时）

有关实现模式，请参阅references/rate-limiting.md

API安全设计

OAuth 2.0流程

授权码流程（Web应用）：

  1. 重定向用户到授权服务器
  2. 用户授予权限
  3. 交换代码获取访问令牌
  4. 使用令牌进行API请求

客户端凭证流程（服务到服务）：

  1. 使用客户端ID和密钥认证
  2. 接收访问令牌
  3. 使用令牌进行API请求

基于范围的授权

定义细粒度权限：

read:users    - 读取用户数据
write:users   - 创建/更新用户
delete:users  - 删除用户
admin:*       - 完全管理员访问

API密钥管理

使用头部基础密钥：

X-API-Key: sk_live_abc123xyz456

最佳实践：

  • 前缀带环境：sk_live_*, sk_test_*
  • 仅存储哈希密钥
  • 支持密钥轮换
  • 跟踪最后使用时间戳

有关完整安全模式，请参阅references/authentication.md

OpenAPI规范

基本结构

openapi: 3.1.0
info:
  title: 用户管理API
version: 2.0.0

paths:
  /users:
    get:
      summary: 列出用户
      parameters:
        -
name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

OpenAPI启用：

  • 代码生成（服务器存根，客户端SDK）
  • 验证（请求/响应检查）
  • 模拟服务器（针对规范测试）
  • 文档（交互式文档）

有关完整OpenAPI示例，请参阅examples/openapi/

AsyncAPI规范

事件驱动API

AsyncAPI定义基于消息的API（WebSockets、Kafka、MQTT）：

asyncapi: 3.0.0
info:
  title: 订单事件API

channels:
  orders/created:
    address: orders.created
    messages:
      orderCreated:
        payload:
          type: object
          properties:
            orderId:
              type: string

有关AsyncAPI示例，请参阅examples/asyncapi/

GraphQL设计

模式结构

type User {
  id: ID!
  username: String!
  posts(limit: Int): [Post!]!
}

type Query {
  user(id: ID!): User
  users(limit: Int): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

N+1问题解决方案

使用DataLoader批量请求：

const userLoader = new DataLoader(async (userIds) => {
  // 单次查询所有用户
  const users = await db.users.findByIds(userIds);
  return userIds.map(id => users.find(u => u.id === id));
});

有关GraphQL模式，请参阅references/graphql-design.md

快速参考表

分页策略选择

场景 策略
小型数据集 基于偏移
大型数据集 基于游标
排序数据 键集
实时流 基于游标

版本控制策略选择

因素 URL路径 头部 媒体类型
可见性 ⭐⭐⭐⭐⭐ ⭐⭐ ⭐⭐
简单性 ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐
最适合 大多数API 内部API 内容协商

与其他技能集成

  • api-patterns：在Express、FastAPI、Go中实现API设计
  • auth-security：实现OAuth2、JWT、会话管理
  • database-design：为API资源设计数据库模式
  • testing-strategies：API测试（集成、契约、负载）
  • deploying-applications：部署和扩展API
  • observability：监控API性能和错误

附加资源

详细指导：

  • references/rest-design.md - RESTful模式和最佳实践
  • references/graphql-design.md - GraphQL模式和解析器模式
  • references/versioning-strategies.md - 综合版本控制指南
  • references/error-handling.md - RFC 7807实现细节
  • references/pagination-patterns.md - 分页实现模式
  • references/rate-limiting.md - 速率限制算法和策略
  • references/authentication.md - OAuth2、API密钥、范围
  • references/protocol-selection.md - 选择正确的API风格

工作示例：

  • examples/openapi/ - 完整OpenAPI 3.1规范
  • examples/asyncapi/ - 事件驱动API规范
  • examples/graphql/ - GraphQL模式和模式

验证和工具：

  • scripts/validate-openapi.sh - 验证OpenAPI规范