2. OPA基础回顾：Rego策略语言核心概念、数据模型、输入输出格式、决策缓存机制

在深入API网关延迟诊断之前，必须牢固掌握OPA（Open Policy Agent）的核心基础。OPA通过Rego策略语言将策略决策从业务逻辑中解耦，其执行效率直接影响网关的端到端延迟。本节将系统梳理Rego语言的核心概念、数据模型、输入输出规范以及关键的决策缓存机制。

2.1 Rego策略语言核心概念

Rego是一种专为策略定义而设计的声明式查询语言，其语法深受Datalog影响。理解以下核心概念是编写高效策略的前提：

2.2 数据模型：文档与规则

OPA将策略数据视为一个层次化的文档（Document）模型。所有输入、输出和策略规则都存储在这个全局文档树中。

• 基础文档（Base Document）： 通过data前缀访问，包含从外部加载的JSON数据（如用户列表、角色绑定）和策略规则。
• 虚拟文档（Virtual Document）： 由Rego规则计算得出的结果，在查询时动态生成，不占用持久化存储。
• 输入文档（Input Document）： 通过input前缀访问，是每次API请求传入的上下文数据（如HTTP方法、路径、JWT令牌）。

2.3 输入输出格式

OPA与API网关的交互通过标准化的JSON格式完成。输入格式决定了网关如何构造请求，输出格式决定了网关如何执行决策。

2.3.1 输入格式（Input）

API网关在每次请求到达时，将请求信息打包为JSON对象传递给OPA。典型结构如下：

{
  "request": {
    "method": "GET",
    "path": ["api", "v2", "users", "123"],
    "headers": {
      "authorization": "Bearer eyJhbGciOiJSUzI1NiIs..."
    },
    "query": {
      "page": "1",
      "limit": "20"
    }
  },
  "client": {
    "ip": "10.0.1.100",
    "user_agent": "Mozilla/5.0"
  }
}

2.3.2 输出格式（Output）

OPA的决策输出通常包含一个布尔值（allow）和可选的元数据（如拒绝原因、响应头修改指令）。

2.4 决策缓存机制

OPA的决策缓存是降低API网关延迟的核心机制。它通过缓存策略评估结果，避免对相同输入的重复计算。

2.4.1 缓存层级

• OPA进程内缓存（In-memory Cache）： 默认启用，基于输入文档的哈希值缓存决策结果。缓存键由input和查询路径组成。
• HTTP条件请求缓存（Conditional Request）： 网关侧通过ETag或If-None-Match头与OPA交互，减少网络传输。
• 外部缓存层（External Cache）： 在网关与OPA之间引入Redis或Memcached，适用于多OPA实例共享缓存。

2.4.2 缓存命中与失效

2.4.3 缓存配置参数

在OPA启动参数或配置文件中，以下参数直接影响缓存行为与延迟：

# OPA 配置文件 (config.yaml)
decision_logs:
  console: true

caching:
  inter_query_builtin_cache:
    max_size_bytes: 104857600  # 100MB，限制内置函数缓存大小
  inter_query_value_cache:
    enabled: true               # 启用进程内决策缓存
    max_num_entries: 10000      # 最大缓存条目数

server:
  http_cache:
    max_age: 300                # HTTP缓存最大年龄（秒）
    etag: true                  # 启用ETag支持

2.5 小结