📚 课程目录第3章 OpenAPI基本结构

3. OpenAPI 基本结构：openapi 字段、info 对象、servers 对象、paths 对象

OpenAPI 规范文档的顶层结构由四个核心根级字段构成：openapi、info、servers 和 paths。这四个字段共同定义了 API 契约的版本声明、元信息描述、网络接入点以及所有可用的操作路径。理解它们之间的层级关系与职责边界，是设计高质量缓存感知接口的第一步。

  核心原则：OpenAPI 文档的根对象是一个 JSON 对象，所有字段均为可选，但 openapi 和 info 字段在语义上必须存在，paths 字段至少应包含一个路径条目，否则文档无实际业务价值。

3.1 openapi 字段：版本声明

openapi 字段是一个字符串，用于声明当前文档遵循的 OpenAPI 规范版本。该字段位于文档根层级，是解析器识别规范类型的首要依据。

属性	类型	必填	说明
`openapi`	string	是	语义版本号，例如 `"3.0.3"` 或 `"3.1.0"`

openapi: "3.0.3"

版本选择建议：对于新项目，推荐使用 3.1.0，它完全兼容 JSON Schema 2020-12，支持更丰富的缓存元数据描述。如果团队工具链仅支持 3.0.x，则使用 3.0.3 以保证最大兼容性。

3.2 info 对象：API 元信息

info 对象提供 API 的标题、版本、描述、联系信息等元数据。该对象是 API 文档的“身份证”，在缓存策略中常用于区分不同版本的 API 缓存空间。

字段	类型	必填	说明
`title`	string	是	API 名称，如 "用户服务 API"
`version`	string	是	API 业务版本，如 "1.2.0"
`description`	string	否	API 功能概述，支持 Markdown
`contact`	object	否	维护者联系信息
`license`	object	否	API 使用许可

info:
  title: "电商缓存网关 API"
  version: "2.1.0"
  description: "提供商品详情、库存查询的缓存加速接口"
  contact:
    name: "API 团队"
    email: "api-team@example.com"

缓存设计注意：info.version 应作为缓存键前缀的一部分。当 API 版本升级时，旧缓存应自动失效，避免新旧版本数据混用导致业务异常。

3.3 servers 对象：网络接入点

servers 是一个数组，定义 API 服务可访问的 URL 基路径。每个 server 对象包含 url（必填）和 description（可选）。在缓存场景中，server URL 直接影响缓存键的域名部分。

字段	类型	必填	说明
`url`	string	是	支持变量模板，如 `https://{environment}.api.example.com/v2`
`description`	string	否	环境说明，如 "生产环境"、"预发布环境"
`variables`	map	否	URL 模板变量定义

servers:
  - url: "https://api.example.com/v2"
    description: "生产环境"
  - url: "https://staging-api.example.com/v2"
    description: "预发布环境"

缓存隔离策略：不同 server 环境应使用独立的缓存命名空间。生产环境与预发布环境的缓存数据必须物理隔离，防止预发布数据污染生产缓存。

3.4 paths 对象：操作路径集合

paths 对象是 OpenAPI 文档的核心，包含所有 API 端点及其支持的 HTTP 方法。每个路径对应一个相对路径字符串，路径下可定义 GET、POST、PUT、DELETE 等操作。在缓存设计中，路径 + HTTP 方法构成缓存键的核心部分。

路径模式	HTTP 方法	缓存策略	说明
`/products/{productId}`	GET	可缓存（TTL 60s）	商品详情，读多写少
`/products/{productId}`	PUT	不可缓存（失效操作）	更新商品，需清除对应缓存
`/orders`	POST	不可缓存	创建订单，幂等性低
`/categories`	GET	可缓存（TTL 300s）	分类列表，变化频率低

paths:
  /products/{productId}:
    get:
      summary: "获取商品详情"
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "成功返回商品信息"
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  price:
                    type: number
    put:
      summary: "更新商品信息"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: "更新成功"

3.5 四字段层级关系图

以下 SVG 展示了 OpenAPI 文档根层级的四个核心字段及其子结构关系，帮助理解缓存键的构成来源。

3.6 缓存键与 OpenAPI 字段的映射关系

在缓存系统设计中，OpenAPI 的四个根字段直接决定了缓存键的组成粒度。下表展示了每个字段对缓存键的影响。

OpenAPI 字段	缓存键组成部分	示例值	缓存隔离粒度
`openapi`	规范版本前缀	`v3.0`	规范版本隔离
`info.version`	API 业务版本	`v2.1.0`	业务版本隔离
`servers[].url`	域名 + 基路径	`api.example.com/v2`	环境隔离
`paths`	路径 + HTTP 方法	`GET/products/{id}`	端点隔离

  缓存键设计公式：

  cache_key = f"{openapi_version}:{api_version}:{server_url}:{http_method}:{path}:{query_hash}"

  例如：v3.0:v2.1.0:api.example.com/v2:GET:/products/123:lang=zh

3.7 路径参数与缓存键动态化

路径中的参数（如 {productId}）在缓存键中必须被实际值替换。OpenAPI 的 parameters 定义决定了哪些路径段是动态的。在缓存设计中，路径参数值直接作为缓存键的一部分，而查询参数则需要按规范顺序排序后参与键计算。

# 路径参数缓存键示例
# 原始路径: /products/{productId}
# 实际请求: /products/abc-123
# 缓存键: GET:/products/abc-123

# 查询参数缓存键示例
# 原始路径: /products?category=electronics&page=1
# 排序后缓存键: GET:/products?category=electronics&page=1

参数排序规则：查询参数在生成缓存键前必须按字母序排序，确保 ?page=1&category=electronics 与 ?category=electronics&page=1 命中同一缓存条目。

3.8 实践检查清单

版本一致性：确认 openapi 字段版本与工具链兼容，避免解析失败。
info.version 语义化：使用语义版本号（SemVer），每次业务变更递增版本，触发缓存自动失效。
server URL 标准化：所有 server URL 末尾不要带斜杠，避免缓存键不一致。
路径参数显式声明：所有路径参数必须在 parameters 中定义，确保缓存键生成逻辑可自动化。
缓存策略标注：在 paths 的每个 operation 中通过 x-cache-ttl 等扩展字段标注缓存策略，便于工具自动生成缓存配置。