⚡

API设计模式 api-design-patterns

API设计模式技能专注于设计高效、可维护的API，涵盖RESTful架构、GraphQL查询、版本控制、错误处理等关键方面。支持OpenAPI规范文档化，提升开发者体验。适用于API设计师、后端开发者、架构师，优化API设计流程。关键词：API设计、REST、GraphQL、OpenAPI、版本控制、错误处理、开发者体验。

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

name: api-design-patterns description: 设计健壮的API，包括RESTful模式、GraphQL架构、版本策略和错误处理约定。支持OpenAPI/Swagger文档和SDK生成模式。触发于API设计、架构定义、端点架构或开发者体验请求。 license: MIT complexity: intermediate time_to_learn: 30min tags:

  • api
  • rest
  • graphql
  • openapi
  • design-patterns inputs:
  • service-requirements
  • data-models outputs:
  • api-specification
  • endpoint-design
  • openapi-document side_effects:
  • creates-files triggers:
  • user-asks-about-api
  • user-asks-about-rest
  • user-asks-about-graphql
  • file-type:*.openapi.yaml
  • project-has-openapi-spec complements:
  • backend-implementation-patterns
  • mcp-builder tier: core

API 设计模式

构建开发者喜爱使用的API。

设计原则

API 设计的三大法则

  1. 可预测性: 全程一致的模式
  2. 可发现性: 自我文档化，直观的命名
  3. 可进化性: 可在不破坏客户端的情况下更改

API 优先思维模式

设计 → 文档化 → 模拟 → 构建 → 测试 → 部署

而非: 构建 → 文档化（可能）→ 希望它能工作

REST 模式

资源命名

# 集合
GET    /users              # 列出用户
POST   /users              # 创建用户

# 项目
GET    /users/{id}         # 获取用户
PUT    /users/{id}         # 替换用户
PATCH  /users/{id}         # 更新用户
DELETE /users/{id}         # 删除用户

# 嵌套资源
GET    /users/{id}/posts   # 用户的帖子
POST   /users/{id}/posts   # 为用户创建帖子

# 操作（当CRUD不适用时）
POST   /users/{id}/activate
POST   /orders/{id}/cancel

命名约定

推荐做法 不推荐做法
/users /getUsers, /user-list
/users/{id} /users/get/{id}
/users/{id}/posts /getUserPosts
复数名词 URL中包含动词
小写字母，连字符 驼峰命名法，下划线

HTTP 方法

方法 目的 幂等性 安全性
GET 读取 是 是
POST 创建 否 否
PUT 替换 是 否
PATCH 更新 否* 否
DELETE 删除 是 否

*PATCH 如果设计得当可以是幂等的

状态码

状态码 含义 使用场景
200 成功 成功的GET、PUT、PATCH
201 已创建 成功的POST并创建新资源
204 无内容 成功的DELETE
400 错误请求 无效输入
401 未授权 缺少或无效的身份验证
403 禁止访问 有效身份验证，但无权限
404 未找到 资源不存在
409 冲突 重复或状态冲突
422 不可处理 语法正确，语义无效
429 请求过多 被限速
500 服务器错误 未处理的服务器错误

请求/响应模式

请求体

{
  "email": "user@example.com",
  "name": "John Doe",
  "preferences": {
    "newsletter": true
  }
}

响应：单个资源

{
  "data": {
    "id": "usr_123",
    "type": "user",
    "attributes": {
      "email": "user@example.com",
      "name": "John Doe",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "relationships": {
      "organization": {
        "id": "org_456",
        "type": "organization"
      }
    }
  }
}

响应：集合

{
  "data": [
    { "id": "usr_123", "type": "user", ... },
    { "id": "usr_124", "type": "user", ... }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "perPage": 20
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}

错误响应

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "无效请求参数",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "必须是有效的电子邮件地址"
      }
    ],
    "requestId": "req_abc123"
  }
}

分页模式

基于偏移量

GET /users?page=2&perPage=20
GET /users?offset=20&limit=20

优点：简单，熟悉 缺点：与实时数据不一致，大数据集上慢

基于游标

GET /users?cursor=eyJpZCI6MTIzfQ&limit=20

响应：

{
  "data": [...],
  "cursors": {
    "before": "eyJpZCI6MTAzfQ",
    "after": "eyJpZCI6MTIzfQ"
  },
  "hasMore": true
}

优点：一致，性能好 缺点：不能跳转到第N页

基于键集

GET /users?after_id=123&limit=20

优点：性能极好 缺点：需要可排序的唯一字段

过滤、排序、搜索

过滤

# 简单
GET /users?status=active

# 多值
GET /users?status=active,pending

# 操作符
GET /users?created_at[gte]=2024-01-01
GET /users?name[contains]=john

# 嵌套
GET /users?organization.name=Acme

排序

# 单字段
GET /users?sort=createdAt

# 降序
GET /users?sort=-createdAt

# 多字段
GET /users?sort=-createdAt,name

字段选择

GET /users?fields=id,name,email
GET /users?fields[user]=id,name&fields[posts]=title

搜索

GET /users?q=john
GET /users?search=john+doe

版本控制策略

URL路径（推荐用于主要版本）

GET /v1/users
GET /v2/users

优点：明确，可缓存 缺点：URL污染

头部

GET /users
Accept: application/vnd.api+json; version=2

优点：干净的URL 缺点：更难测试，不太可见

查询参数

GET /users?version=2

优点：易于测试 缺点：破坏缓存，URL污染

弃用模式

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

身份验证模式

API 密钥

# 头部
Authorization: Api-Key sk_live_abc123

# 查询（避免 - 记录在URL中）
GET /users?api_key=sk_live_abc123 <!-- allow-secret -->

Bearer令牌（OAuth2/JWT）

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

签名请求（AWS风格）

Authorization: HMAC-SHA256 Credential=key/date/region/service,
               SignedHeaders=host;x-date,
               Signature=abc123

速率限制

头部

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000
Retry-After: 60

响应（429）

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "速率限制已超过",
    "retryAfter": 60
  }
}

策略

策略 描述 使用场景
固定窗口 每分钟X次请求 简单限制
滑动窗口 滚动时间窗口 平滑限制
令牌桶 突发允许量 流量峰值
漏桶 恒定速率 稳定吞吐量

GraphQL 模式

架构设计

type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int, after: String): PostConnection!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type Query {
  user(id: ID!): User
  users(filter: UserFilter, first: Int, after: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

命名约定

元素 约定 示例
类型 PascalCase User, BlogPost
字段 camelCase firstName, createdAt
参数 camelCase userId, first
枚举 SCREAMING_SNAKE USER_STATUS, ACTIVE
变更 verbNoun createUser, updatePost

错误处理

{
  "data": null,
  "errors": [
    {
      "message": "用户未找到",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    }
  ]
}

OpenAPI 文档

基本结构

openapi: 3.0.3
info:
  title: 我的API
  version: 1.0.0
  description: API描述

servers:
  - url: https://api.example.com/v1
    description: 生产环境

paths:
  /users:
    get:
      summary: 列出用户
      operationId: listUsers
      tags: [用户]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email

相关技能

互补技能（一起使用）

替代技能（类似目的）

  • mcp-builder - 如果构建MCP服务器而不是REST/GraphQL API

先决技能（先学习）

  • 无需先决 - 这是基础设计技能

参考文献

  • references/openapi-template.md - 完整的OpenAPI模板
  • references/error-codes.md - 标准错误代码目录
  • references/sdk-patterns.md - 客户端SDK设计模式