📚 课程目录第3章 OpenAPI核心元素（上）

3. OpenAPI 核心元素（上）：Paths、Operations、Parameters、Request Body 的定义与最佳实践

OpenAPI 规范的核心在于描述 API 的“端点”与“数据流动”。本章聚焦于构成 API 契约骨架的四个基础元素：Paths（路径）、Operations（操作）、Parameters（参数） 和 Request Body（请求体）。掌握它们的精确定义与设计约束，是构建高质量、可复用 API 契约的第一步。

3.1 Paths：API 的端点地图

paths 对象是 OpenAPI 文档的根级映射，它将每个相对路径（如 /users 或 /orders/{orderId}）关联到一组可用的 HTTP 方法（Operations）。路径是 API 的入口，其设计直接影响 API 的可读性与可维护性。

  核心设计原则：
  资源导向：路径应代表资源（名词），而非动作（动词）。例如 /users 优于 /getUsers。
层级清晰：使用斜杠 / 表示资源层级关系，如 /organizations/{orgId}/members。
路径参数化：使用花括号 {} 标识动态路径段，如 /items/{itemId}。

以下是一个典型的路径定义片段：

paths:
  /users:
    get:
      summary: 获取用户列表
      operationId: listUsers
      ...
    post:
      summary: 创建新用户
      operationId: createUser
      ...
  /users/{userId}:
    get:
      summary: 根据 ID 获取用户详情
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      ...

3.2 Operations：HTTP 方法的语义绑定

每个路径下可以定义一个或多个 Operation 对象，对应标准的 HTTP 方法（GET、POST、PUT、PATCH、DELETE 等）。Operation 是 API 行为的原子单元，它承载了请求与响应的完整描述。

HTTP 方法	典型语义	幂等性	请求体
GET	检索资源	是	无
POST	创建资源	否	有
PUT	全量替换资源	是	有
PATCH	部分更新资源	否	有
DELETE	删除资源	是	通常无

最佳实践：为每个 Operation 提供有意义的 operationId。它不仅是文档中的唯一标识符，也是代码生成工具生成客户端方法名或服务端接口名的依据。推荐使用驼峰命名法，如 getUserById。

3.3 Parameters：请求参数的分类与定义

Parameters 对象用于描述客户端在请求中传递的附加数据。OpenAPI 将参数按“位置”分为四种类型，每种类型都有其适用场景与约束。

Path Parameters（路径参数）：嵌入在 URL 路径中，如 /users/{userId}。必须设置 required: true。
Query Parameters（查询参数）：附加在 URL 问号后，如 /users?role=admin。常用于过滤、排序、分页。
Header Parameters（请求头参数）：通过 HTTP 头部传递，如 X-Request-Id。常用于认证、追踪、内容协商。
Cookie Parameters（Cookie 参数）：通过 Cookie 头部传递，适用于会话管理。

以下是一个包含多种参数类型的定义示例：

parameters:
  - name: page
    in: query
    description: 页码，从 1 开始
    required: false
    schema:
      type: integer
      minimum: 1
      default: 1
  - name: authorization
    in: header
    description: Bearer token
    required: true
    schema:
      type: string
      pattern: '^Bearer .+$'

常见陷阱：避免在 GET 请求中使用 Request Body 传递过滤条件。虽然技术上可行，但这违反了 HTTP 语义，且许多 HTTP 客户端、代理和缓存服务器可能不支持。应始终使用 Query Parameters 实现过滤与分页。

3.4 Request Body：结构化数据的载体

对于 POST、PUT、PATCH 等需要提交数据的操作，requestBody 对象用于描述请求体的内容。它通过 content 字段指定媒体类型（如 application/json）及其对应的 Schema。

Request Body 的核心结构：

requestBody:
  description: 需要创建的用户对象
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - name
          - email
        properties:
          name:
            type: string
            example: 张三
          email:
            type: string
            format: email
            example: zhangsan@example.com
          age:
            type: integer
            minimum: 0

3.5 核心元素关系与设计流程

下图展示了 Paths、Operations、Parameters 和 Request Body 之间的层级关系与设计流程，帮助你在构建 API 契约时建立全局视角。

3.6 最佳实践清单

元素	最佳实践	反模式
Paths	使用名词复数形式，如 `/products`	使用动词，如 `/getProducts`
Operations	为每个操作定义 `operationId` 和 `summary`	仅依赖 HTTP 方法，无额外描述
Parameters	为参数设置明确的 `schema` 和 `example`	使用字符串描述类型，而非 Schema 对象
Request Body	明确标记 `required`，并提供媒体类型	在 GET 请求中使用 Request Body

Mock 测试启示：在定义 Parameters 和 Request Body 时，尽量提供 example 值。这些示例将被 Mock 工具直接用于生成模拟响应，显著提升前后端联调效率。