4. 路径与操作：路径定义、HTTP方法映射、operationId、参数分类

路径（Path）与操作（Operation）是OpenAPI契约的核心骨架。路径定义了资源的访问入口，操作则描述了在该入口上允许的HTTP方法及其行为。本章将深入解析路径定义规范、HTTP方法映射规则、operationId的唯一性约束以及参数的四种分类方式，帮助你在设计缓存友好的API时，从契约层面建立清晰的资源边界。

4.1 路径定义规范

OpenAPI中的路径以/开头，支持静态路径与动态路径参数。路径设计应遵循RESTful资源命名原则，使用名词复数形式，避免动词。

4.2 HTTP方法映射与语义

每个路径下可定义多个操作，每个操作对应一个HTTP方法。OpenAPI 3.0支持的方法包括：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。在缓存设计中，不同方法的幂等性和副作用决定了缓存策略。

4.3 operationId：唯一标识与缓存键设计

operationId是每个操作的唯一标识符，在整个API文档中必须唯一。它不仅是代码生成的基础，也是缓存键设计的重要参考。

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      summary: 根据ID获取用户信息
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

operationId的命名规范：

• 使用驼峰命名法（camelCase），如 getUserById
• 动词+名词结构，清晰表达操作语义
• 避免重名，即使在不同路径下
• 可作为缓存键的前缀，如 getUserById:{userId}

4.4 参数分类与缓存影响

OpenAPI 3.0将参数分为四种位置类型（in字段），每种类型对缓存键的构建方式不同。

4.5 参数分类与缓存键构建流程

下图展示了从OpenAPI契约定义到缓存键生成的完整流程，帮助理解不同参数类型在缓存系统中的角色。

4.6 参数定义规范与缓存键设计示例

以下是一个完整的OpenAPI路径定义示例，展示了如何为缓存友好的接口设计参数。

paths:
  /products:
    get:
      operationId: listProducts
      summary: 分页查询商品列表
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
        - name: category
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 商品列表
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=60
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  /products/{productId}:
    get:
      operationId: getProductById
      summary: 根据ID获取商品详情
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
        - name: includeReviews
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: 商品详情
          headers:
            Cache-Control:
              schema:
                type: string
                example: public, max-age=300
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

4.7 参数分类的缓存策略总结

根据参数类型的不同，缓存策略应有所区别：

• 路径参数：强制作为缓存键组成部分，每个不同的路径参数值对应一个独立的缓存条目。
• 查询参数：评估参数组合的基数，基数较小的参数（如枚举值）可纳入缓存键；基数大的参数（如搜索关键词）建议使用较短TTL或绕过缓存。
• 请求头参数：仅当影响响应内容（如Accept-Language）时才纳入缓存键，否则忽略。
• Cookie参数：避免直接用于缓存键，建议通过Vary响应头处理。