2. OpenAPI 基础回顾：RESTful API 设计原则、OpenAPI 规范（Swagger）核心概念、API 版本管理

在构建缓存一致性闭环与错误处理链路之前，必须夯实 OpenAPI 基础。本章回顾 RESTful 设计原则、OpenAPI/Swagger 核心概念以及 API 版本管理策略，为后续的缓存失效、重试、降级等高级设计提供统一的契约语言。

2.1 RESTful API 设计原则

REST（Representational State Transfer）是一种架构风格，强调资源导向、无状态通信和统一接口。以下六项约束是设计高质量 API 的基础：

资源命名与 HTTP 方法映射是 RESTful 设计的核心实践：

• 资源路径：使用名词复数形式，如 /users、/orders/{orderId}。
• HTTP 方法：
  • GET — 读取资源（幂等、安全）
  • POST — 创建资源（非幂等）
  • PUT — 全量替换资源（幂等）
  • PATCH — 部分更新资源（幂等）
  • DELETE — 删除资源（幂等）
• 查询参数：用于过滤、排序、分页，如 ?status=active&page=1&size=20。

2.2 OpenAPI 规范（Swagger）核心概念

OpenAPI 规范（原 Swagger 规范）是描述 RESTful API 的行业标准，提供机器可读的接口定义文件（通常为 JSON 或 YAML）。核心概念包括：

以下是一个简化的 OpenAPI 3.0 片段，展示如何定义缓存相关的响应头：

openapi: 3.0.3
info:
  title: 用户服务 API
  version: 2.1.0
paths:
  /users/{userId}:
    get:
      summary: 获取用户信息
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回用户信息
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=60
            ETag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        requestId:
          type: string

2.3 API 版本管理

API 版本管理是保证向后兼容、支持渐进式演进的关键策略。在缓存一致性场景中，版本管理直接影响缓存键的命名空间和缓存失效范围。

主流版本管理策略对比：

版本管理的最佳实践清单：

• 语义化版本：遵循 MAJOR.MINOR.PATCH（如 2.1.0），MAJOR 变更表示不兼容的 API 修改。
• 废弃策略：在 OpenAPI 定义中使用 deprecated: true 标记废弃端点，并在响应头中添加 Sunset 头部告知客户端迁移时间线。
• 缓存命名空间：缓存键必须包含版本号（如 v2:users:1），避免新版本数据污染旧版本缓存。
• 版本共存：至少同时维护两个 MAJOR 版本，给客户端足够的迁移窗口。