📚 课程目录第4章全局与局部安全声明

4. 全局与局部安全声明：security 字段作用域、全局声明 vs 操作级声明、覆盖与合并规则

在 OpenAPI 3.x 规范中，security 字段是定义 API 鉴权契约的核心入口。它既可以出现在根级（全局），也可以出现在每个操作（Operation）内部。理解这两者的作用域、覆盖与合并规则，是构建可维护、无歧义的安全契约的前提。

4.1 全局 security 声明

在 OpenAPI 文档根对象中声明的 security 字段，默认应用于所有路径下的所有操作。它相当于一个“基线安全策略”，适用于绝大多数需要统一鉴权的 API。

全局声明示例：

openapi: "3.0.3"
info:
  title: 统一鉴权 API
  version: "1.0.0"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
# 全局 security：所有操作默认需要 Bearer Token
security:
  - BearerAuth: []
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功
  /orders:
    get:
      summary: 获取订单列表
      responses:
        '200':
          description: 成功

上述配置中，/users 和 /orders 的 GET 操作都默认要求提供有效的 Bearer Token。

4.2 操作级 security 声明

当某个操作需要不同的鉴权策略（例如公开接口、使用不同认证方式、或无需认证）时，可以在操作对象内部声明 security 字段。操作级声明会完全覆盖全局声明，而不是追加。

关键规则：操作级 security 一旦出现，全局 security 对该操作失效。这意味着你必须在该操作中显式列出所有需要的安全方案。

paths:
  /public/health:
    get:
      summary: 健康检查（公开）
      # 操作级 security：空数组表示无需认证
      security: []
      responses:
        '200':
          description: 健康
  /admin/users:
    get:
      summary: 管理员获取用户（需要双重认证）
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      responses:
        '200':
          description: 成功

4.3 覆盖与合并规则详解

理解 security 的覆盖与合并规则，需要区分两个维度：作用域层级和安全方案列表的语义。

规则维度	说明	示例
全局 → 操作覆盖	操作级 security 完全替代全局 security，不会自动继承全局方案。	全局要求 BearerAuth，操作级声明 ApiKeyAuth，则该操作仅需 ApiKeyAuth。
空数组表示公开	操作级 `security: []` 表示该操作不需要任何认证，覆盖全局要求。	全局要求 BearerAuth，健康检查接口声明 `security: []`，则公开访问。
列表内 AND 逻辑	同一数组元素内的多个安全方案是“与”关系，必须同时满足。	`security: [ { BearerAuth: [], ApiKeyAuth: [] } ]` 表示同时需要 Token 和 API Key。
列表间 OR 逻辑	数组中的不同元素是“或”关系，满足其一即可。	`security: [ { BearerAuth: [] }, { ApiKeyAuth: [] } ]` 表示 Token 或 API Key 任一即可。

常见陷阱：很多开发者误以为操作级 security 会“追加”到全局 security 之后。实际上，OpenAPI 规范明确规定操作级 security 会完全替换全局 security。如果你希望操作同时保留全局方案并增加新方案，必须在操作级显式列出所有需要的方案。

4.4 作用域与合并流程

下图展示了 OpenAPI 解析器在处理 security 字段时的决策流程：

4.5 实战：多环境安全策略设计

在实际项目中，合理利用全局与操作级 security 可以显著减少重复代码。以下是一个典型的多环境安全策略设计模式：

全局基线：在根级声明最常用的安全方案（如 BearerAuth），覆盖 80% 的接口。
公开接口：在健康检查、登录、注册等操作上使用 security: [] 覆盖全局。
高安全接口：在管理后台、敏感操作上使用操作级 security 增加额外认证（如双重认证）。
第三方回调：在 Webhook 或回调接口上使用独立的安全方案（如签名认证）。

  最佳实践：始终在操作级 security 中显式列出所有需要的安全方案，不要依赖“全局+操作”的隐式合并。这虽然会增加少量代码，但能避免因全局策略变更导致的意外安全漏洞。

4.6 常见错误与校验

错误场景	错误示例	正确做法
误以为操作级会追加全局	全局 BearerAuth，操作级只写 ApiKeyAuth，期望同时生效	操作级显式写 `[ { BearerAuth: [] }, { ApiKeyAuth: [] } ]`
公开接口忘记覆盖	全局 BearerAuth，健康检查接口未写 security	健康检查接口写 `security: []`
AND/OR 逻辑混淆	`[ { A: [] }, { B: [] } ]` 误以为需要同时满足 A 和 B	需要同时满足时写 `[ { A: [], B: [] } ]`
securitySchemes 未定义	security 中引用了未在 components 中定义的方案	确保所有引用的安全方案都在 `components.securitySchemes` 中定义

通过掌握全局与操作级 security 的声明规则、覆盖与合并逻辑，你可以在 OpenAPI 契约中精确表达任何鉴权需求，避免因作用域误解导致的安全漏洞或认证失败。