4. Bearer Token 认证：从概念到 OpenAPI 定义

Bearer Token 是当前 RESTful API 中最主流的认证方式之一。它通过在 HTTP 请求头中携带一个“令牌”（Token），让服务端验证请求者的身份。本章将深入剖析 Bearer Token 的核心概念、两种主流 Token 类型的差异，以及如何在 OpenAPI 规范中精确地定义 Bearer 认证方案。

4.1 Bearer Token 的核心概念

Bearer Token 是一种不记名令牌。任何持有该令牌的客户端（Bearer）都可以直接访问受保护的资源，无需额外提供身份证明。其核心流程如下：

1. 客户端获取 Token：通过登录、OAuth2 授权码流程等方式，从认证服务器获取一个 Token。
2. 客户端发送请求：在 HTTP 请求头中添加 Authorization: Bearer <token>。
3. 服务端验证 Token：解析并验证 Token 的有效性、签名和权限。
4. 返回资源或拒绝：验证通过则返回数据，否则返回 401 Unauthorized。

4.2 JWT 与 Opaque Token 的区别

Bearer Token 的实现主要分为两大类：JWT（JSON Web Token）和Opaque Token（不透明令牌）。两者在结构、验证方式和适用场景上有显著差异。

4.3 在 OpenAPI 中定义 Bearer 认证

OpenAPI 3.x 使用 securitySchemes 组件来声明认证方案。Bearer Token 认证属于 http 类型，scheme 为 bearer。以下是完整的定义方式：

4.3.1 基础定义

openapi: 3.0.3
info:
  title: 用户管理 API
  version: 1.0.0
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # 可选，说明 Token 格式
security:
  - BearerAuth: []

4.3.2 字段详解

4.3.3 全局与局部安全要求

安全要求可以定义在全局（security 顶层字段）或局部（每个操作级别）。局部定义会覆盖全局定义。

# 全局安全要求：所有接口默认需要 Bearer Token
security:
  - BearerAuth: []

# 局部覆盖：某个接口不需要认证
paths:
  /public/health:
    get:
      security: []  # 空数组表示无认证要求
      responses:
        '200':
          description: 健康检查通过

# 局部覆盖：某个接口需要额外权限
  /admin/users:
    get:
      security:
        - BearerAuth: ['admin']  # 需要 admin 作用域
      responses:
        '200':
          description: 用户列表

4.3.4 完整示例：带 Bearer 认证的 API 定义

openapi: 3.0.3
info:
  title: 订单服务 API
  version: 2.0.0
  description: 使用 JWT Bearer Token 进行认证
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        通过登录接口获取 JWT Token。
        格式：Authorization: Bearer <token>
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
        product:
          type: string
        amount:
          type: number
security:
  - BearerAuth: []
paths:
  /orders:
    get:
      summary: 获取订单列表
      responses:
        '200':
          description: 成功返回订单列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '401':
          description: 未提供或 Token 无效
    post:
      summary: 创建订单
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: 订单创建成功
        '401':
          description: 认证失败

4.4 最佳实践与避坑指南

• 始终使用 HTTPS：Bearer Token 在 HTTP 头中明文传输，HTTPS 是唯一的安全保障。
• 设置合理的 Token 有效期：JWT 建议 15-60 分钟，Opaque Token 可根据业务需求灵活设置。
• 使用 Refresh Token 机制：避免频繁要求用户重新登录，同时降低长期 Token 泄露的风险。
• 在 OpenAPI 中明确描述 Token 获取方式：在 description 字段中说明登录接口和 Token 格式，降低客户端集成难度。
• 区分认证与授权：Bearer Token 只解决“你是谁”的问题，权限控制（“你能做什么”）需要额外的作用域（scopes）或 RBAC 机制。