📚 课程目录第4章 Rego 语言核心

4. OPA 入门：OPA 架构、Rego 语言基础、OPA 安装与命令行使用

4.1 OPA 核心架构与设计理念

Open Policy Agent (OPA) 是一个开源的、通用策略引擎，它将策略决策与业务逻辑解耦。OPA 不负责执行策略（如拒绝请求），而是负责评估策略并返回决策结果（Allow/Deny）。其核心架构遵循“决策请求-策略查询”模型。

  关键设计原则： OPA 通过 Rego 语言描述策略，对外提供统一的查询接口。任何需要策略决策的系统（如 API 网关、Kubernetes、CI/CD 流水线）都可以向 OPA 发送查询，OPA 基于加载的策略和数据返回决策。

4.2 Rego 语言基础

Rego 是 OPA 的原生声明式查询语言，灵感来源于 Datalog。Rego 的核心是定义规则 (Rules)，这些规则评估为布尔值、对象或数组。策略即代码的本质就是使用 Rego 编写规则。

4.2.1 基本语法与规则

包 (Package)： 使用 package 关键字组织策略，如 package myapp.authz。
规则 (Rule)： 形如 allow { ... }，当大括号内的所有条件为真时，规则为真。
默认值： 使用 default allow = false 设置规则的默认值，避免未定义。
迭代： 使用 some 关键字进行迭代，如 some user; users[user]。

Rego 核心概念： 规则是“如果-那么”的声明。Rego 没有循环和变量赋值（变量只绑定一次），这使其非常适合静态分析和形式化验证。

# 示例：简单的 RBAC 策略
package myapp.authz

# 默认拒绝
default allow = false

# 允许规则：用户是管理员
allow {
    input.user == "admin"
}

# 允许规则：用户拥有所需角色
allow {
    some role
    input.user_roles[role]
    required_roles[role]
}

# 所需角色数据
required_roles = {"reader", "writer"}

4.2.2 常用内置函数与操作符

类别	函数/操作符	说明
集合操作	`==`, `!=`, `in`	相等、不等、成员检查
字符串操作	`startswith`, `contains`, `regex.match`	字符串匹配与正则
聚合函数	`count`, `sum`, `max`	数组/对象聚合计算
对象操作	`object.get`, `json.marshal`	安全访问对象字段、JSON 序列化
时间函数	`time.now_ns`, `time.parse_rfc3339_ns`	时间戳获取与解析

4.3 OPA 安装与命令行使用

OPA 提供多种安装方式，最常用的是二进制安装和Docker 运行。安装后，通过 opa 命令行工具进行策略评估、测试和调试。

4.3.1 安装方式对比

方式	命令/步骤	适用场景
Linux/macOS 二进制	`curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64` `chmod +x opa && sudo mv opa /usr/local/bin/`	本地开发、CI/CD 代理
Docker	`docker pull openpolicyagent/opa:latest` `docker run -it openpolicyagent/opa run`	容器化部署、隔离测试
macOS Homebrew	`brew install opa`	macOS 开发者快速安装

4.3.2 命令行核心操作

安装完成后，使用 opa 命令进行策略评估。以下是最常用的三个子命令：

opa eval： 直接评估 Rego 表达式，适合快速测试。
opa test： 运行 Rego 测试用例，确保策略正确性。
opa run： 启动 OPA 服务器（REPL 或 HTTP 服务）。

常见陷阱： 使用 opa eval 时，必须通过 -d 参数加载数据文件，通过 -f 参数指定输出格式（如 raw, json, pretty）。忘记加载数据会导致规则中的变量未定义。

# 1. 直接评估表达式
opa eval "1 + 2 == 3"

# 2. 加载策略文件并查询
opa eval -d policy.rego "data.myapp.authz.allow" --input input.json

# 3. 运行测试
opa test ./tests/ -v

# 4. 启动交互式 REPL
opa run

# 5. 启动 HTTP 服务器（端口 8181）
opa run --server --addr :8181

4.3.3 调试工作流示例

以下是一个完整的调试流程，展示如何使用 OPA 命令行验证一个简单的访问控制策略：

编写策略文件 policy.rego：定义 allow 规则。
准备输入数据 input.json：模拟请求上下文。
执行评估：opa eval -d policy.rego "data.example.allow" --input input.json -f pretty
查看输出：如果规则为真，输出 true；否则输出 false 或 undefined。
使用 trace 模式：添加 --explain=full 参数查看详细决策路径。

# policy.rego
package example

default allow = false

allow {
    input.method == "GET"
    input.path == "/api/v1/data"
}

# input.json
{"method": "GET", "path": "/api/v1/data"}

# 执行命令
opa eval -d policy.rego "data.example.allow" --input input.json -f pretty
# 输出: true

# 调试模式
opa eval -d policy.rego "data.example.allow" --input input.json --explain=full

4.4 本章小结

本章介绍了 OPA 的架构设计（决策解耦）、Rego 语言基础（声明式规则）以及安装与命令行使用。掌握这些基础后，你将能够在本地环境中编写、测试和调试策略，为后续将策略集成到 CI/CD 流水线中打下坚实基础。