Open Policy Agent Rego 速查手册：从规则骨架到集合推导与内置函数的完整语法指南

后端认证鉴权云原生【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址https://gitcode.com/gh_mirrors/op/opa点击查看免费下载本文以 OPA 官方仓库中的 Rego 速查表 为主体骨架系统梳理 Rego 策略语言的高频语法单值/多值规则、迭代与控制流、测试与调试手段、集合推导式以及常用内置函数。文中每个示例均可直接在 OPA Playground 中的DocKind/RuleKind与 内置函数注册表 讲解底层语义。读完本文你将掌握编写、测试与调试 Rego 策略的完整实战技能。本文所有 Rego 代码示例共享同一前置声明package cheat即所有规则定义在data.cheat文档名下查询时使用data.cheat作为入口。一、规则RulesRego 的构建基石Rego 中规则是把输入input和外部数据data转化为策略结论的基本单元。从源码角度看每条规则头部Head会按产出文档的类型被分类。在 v1/ast/policy.go 中定义了三种DocKindCompleteDoc规则完整定义了一个文档对应下文单值规则PartialSetDoc规则部分定义了集合文档对应下文多值集合规则PartialObjectDoc规则部分定义了对象文档对应下文多值对象规则。同时Head.RuleKind()将规则划分为SingleValue单值与MultiValue多值两类。理解这套分类是读懂下文三种写法的钥匙。1.1 单值规则Single-Value Rules单值规则为某个变量赋一个确定的值。在较老的文档中这类规则也被称为 complete rules完整规则。由于同一文档名的多条单值规则之间是或的关系通常会配合default关键字提供一个兜底值避免查询无定义时报错。输入样例input.json{ user: { role: admin, internal: true } }策略样例policy.regodefault allow : false allow if { input.user.role admin input.user.internal } default request_quota : 100 request_quota : 1000 if input.user.internal request_quota : 50 if input.user.plan.trial运行data.cheat得到的结果中allow为true两条条件同时满足request_quota为1000因为input.user.internal为真且没有 trial 计划。default分支只有在没有任何一条规则体被满足时才会生效——这正是单值规则与default协同的典型模式。关于单值规则的解析细节可参考 v1/ast/parser_ext.go 中的parseCompleteRuleFromEq它以等式:形式的表达式为起点解析出完整规则这也解释了为什么单值规则的头部必须是name : value或name if ...形态。1.2 多值集合规则Multi-Value Set Rules多值集合规则会向某个变量追加contains多个值最终聚合成一个集合set。旧文档中称为 partial set rules部分集合规则。集合中的元素彼此去重且无序。输入样例{ user: { teams: [ ops, eng ] } }策略样例paths contains /handbook/* paths contains path if { some team in input.user.teams path : sprintf(/teams/%v/*, [team]) }运行结果为paths是集合{/handbook/*, /teams/eng/*, /teams/ops/*}。some ... in用于遍历数组sprintf负责格式化出带团队名的路径模式。注意contains左侧是集合名右侧是要加入集合的值这是多值集合规则区别于单值规则的标志性语法。1.3 多值对象规则Multi-Value Object Rules多值对象规则以paths_by_prefix[prefix] contains path的形式为对象动态生成键→集合值的映射。旧文档中称为 partial object rules部分对象规则。适合把一批数据按键分组统计。输入样例{ paths: [ a/123.txt, a/456.txt, b/foo.txt, b/bar.txt, c/x.txt ] }策略样例# Creates an object with sets as the values. paths_by_prefix[prefix] contains path if { some path in input.paths parts : split(path, /) prefix : parts[0] }运行结果为{ a: {123.txt, 456.txt}, b: {bar.txt, foo.txt}, c: {x.txt} }这里的split按/切分路径取第一段作为前缀键。对象规则的价值在于一次遍历即可完成分组-聚合两步操作无需像通用编程语言那样手动维护中间容器。二、迭代Iteration高效处理集合数据2.1 some为局部查询变量命名some用来声明规则体中的局部变量使代码可读性更高也能配合in实现遍历。下面的例子同时展示了双重遍历与sprintf的组合all_regions : { emea: {west, east}, na: {west, east, central}, latam: {west, east}, apac: {north, south}, } allowed_regions contains region_id if { some area, regions in all_regions some region in regions region_id : sprintf(%s_%s, [area, region]) }some area, regions in all_regions同时取出对象的键area与值regions内层再对regions这个集合做some region in regions遍历最终生成诸如emea_west、na_central一类的区域 ID 集合。这种写法在遍历嵌套数据结构并投影出新值的场景下非常高效。2.2 every对每个元素断言条件every用于声明容器中的每一个元素都必须满足某条件一旦有任一元素不满足整个规则体即失败。注意every的块体是条件断言而非赋值语句。输入样例{ userID: u123, paths: [ /docs/u123/notes.txt, /docs/u123/q4-report.docx ] }策略样例allow if { prefix : sprintf(/docs/%s/, [input.userID]) every path in input.paths { startswith(path, prefix) } }只有当input.paths中每一个路径都以/docs/u123/开头时allow才为true。every在源码层面是 AST 中一种独立的表达式节点见 v1/ast/policy.go 中Every结构体及其IsEvery判断逻辑它与some的差异在于some关心存在every关心全部。三、控制流Control Flow处理不同条件分支3.1 逻辑与Logical ANDRego 规则体内的多个语句之间默认是逻辑与关系——所有条件都必须为真规则才成立。这是 Rego 最常见的隐含语义。输入样例{ email: joeexample.com }策略样例valid_staff_email if { regex.match(^\S\S\.\S$, input.email) # and endswith(input.email, example.com) }这里同时要求邮箱格式合法且域名以example.com结尾。注释# and用于强调两行是并且关系。regex.match与endswith都是 OPA 内置函数下文会详述。3.2 逻辑或Logical ORRego 没有||运算符表达或关系有三种惯用法多条同名规则、函数重载、以及in成员判断。输入样例{ email: opaexample.com, name: anna, method: GET }策略样例# using multiple rules valid_email if endswith(input.email, example.com) valid_email if endswith(input.email, example.org) valid_email if endswith(input.email, example.net) # using functions allowed_firstname(name) if { startswith(name, a) count(name) 2 } allowed_firstname(joe) # if name joe valid_name if allowed_firstname(input.name) valid_request if { input.method in {GET, POST} # using in }三条valid_email规则只要有一条被满足valid_email即为真这是多条规则 或的直观体现。allowed_firstname展示了带参规则函数形式的重载满足以 a 开头且长度大于 2的名字通过且joe被显式放行。in则把方法在白名单内的判断写成一元表达式比input.method GET配合or更简洁。四、测试Testing用 with 覆写输入与数据Rego 测试函数以test_为前缀命名详见 策略测试文档with关键字可在测试中临时替换input或data的值从而无需构造真实环境即可覆盖各种分支。策略样例allow if input.admin true test_allow_when_admin if { allow with input as {admin: true} }test_allow_when_admin验证当input被覆写为{admin: true}时allow成立。with的作用域仅限于当前规则体不会污染其他测试。这是 OPA 单元测试的基石写法配合opa test命令即可在 CI 中持续校验策略行为。五、调试Debugging用 print 观察运行期值print是 Rego 内置的调试函数可在规则体执行期间把中间变量输出到日志帮助定位规则为什么没被满足。策略样例allowed_users : {alice, bob} allow if { some user in allowed_users print(user) input.user user }当input.user为alice或bob时allow为真print(user)会在评估过程中把每次尝试的user值打出来。print在opa eval、opa run以及测试运行时都会输出可通过--log-level等选项控制是快速排查规则逻辑的首选手段。六、推导式Comprehensions加工与重组集合推导式是 Rego 中从既有集合生成新集合的一等公民语法按产出类型分为数组、集合、对象三种。6.1 数组推导式数组推导式产出有序且保留重复项的数组doubled : [m | some n in [1, 2, 3, 3] m : n * 2 ]结果为[2, 4, 6, 6]——注意3出现两次数组保留重复。6.2 集合推导式集合推导式产出无序且去重的集合unique_doubled contains m if { some n in [10, 20, 30, 20, 10] m : n * 2 }结果为{20, 40, 60}——20与10的重复输入被自动合并。集合推导式通常写成多值集合规则 contains的形态这也是它区别于数组推导式的标志。6.3 对象推导式对象推导式产出键值对键必须唯一重复键会以最后写入者为准is_even[number] : is_even if { some number in [1, 2, 3, 4] is_even : (number % 2) 0 }结果为{1: false, 2: true, 3: false, 4: true}。这种键 : 值 规则体的写法本质上就是多值对象规则用来把数组投影成按某种规则键控的对象十分顺手。七、内置函数Builtins常用任务的一站式工具所有内置函数都在 v1/ast/builtins.go 中通过Builtin结构体注册包含函数名、类型签名与描述其求值实现在 topdown/builtins/builtins.go。下面按速查表的分类逐一展开。7.1 正则表达式Regexexample_string : Build Policy as Code with OPA! check_match if regex.match(\w, example_string) check_replace : regex.replace(example_string, \s, _)regex.match(pattern, value)判断value是否匹配pattern返回布尔值源码见 v1/ast/builtins.go。此处\w能匹配到单词字符故check_match为真。regex.replace(s, pattern, value)按正则\s空白序列替换为_结果check_replace为Build_Policy_as_Code_with_OPA!源码见 v1/ast/builtins.go。Rego 的正则语法基于 RE2规则引擎在求值时编译并缓存模式适合高频匹配场景。7.2 字符串Stringsexample_string : Build Policy as Code with OPA! check_contains if contains(example_string, OPA) check_startswith if startswith(example_string, Build) check_endswith if endswith(example_string, !) check_replace : replace(example_string, OPA, OPA!) check_sprintf : sprintf(OPA is %s!, [awesome])contains/startswith/endswith分别判断包含、前缀、后缀均返回布尔值注册位置见 v1/ast/builtins.go、L1220、L1234。replace纯文本替换非正则将OPA换成OPA!v1/ast/builtins.go。sprintf格式化字符串占位符%s对应参数数组中的元素结果为OPA is awesome!v1/ast/builtins.go。7.3 聚合函数Aggregatesvals : [5, 1, 4, 2, 3] vals_count : count(vals) vals_max : max(vals) vals_min : min(vals) vals_sorted : sort(vals) vals_sum : sum(vals)函数结果语义count(vals)5元素个数max(vals)5最大值min(vals)1最小值sort(vals)[1, 2, 3, 4, 5]升序排序sum(vals)15求和上述函数的注册位置分别为 v1/ast/builtins.gocount、L800sum、L832max、L848min、L868sort。聚合函数与数组/集合推导式结合可在策略内完成过滤→聚合的完整计算链。7.4 对象操作数据提取Extracting Dataobj : {userid: 18472, roles: [{name: admin}]} # paths can contain array indexes too val : object.get(obj, [roles, 0, name], missing) defaulted_val : object.get( obj, [roles, 0, permissions], # path unknown, # default if path is missing ) keys : object.keys(obj)object.get(object, path, default)沿路径可混合对象键与数组下标安全取值路径缺失时返回默认值。val为admindefaulted_val为unknownpermissions键不存在。源码注释明确说明路径可包含数组索引v1/ast/builtins.go。object.keys(obj)返回对象所有键组成的集合{roles, userid}v1/ast/builtins.go。object.get是处理可能缺失的嵌套字段最安全的写法能避免直接索引导致的未定义错误。7.5 对象操作数据转换Transforming Dataunioned : object.union({foo: true}, {bar: false}) subset : object.subset( {foo: true, bar: false}, {foo: true}, # subset object ) removed : object.remove( {foo: true, bar: false}, {bar}, # remove keys )object.union(a, b)合并两个对象结果为{bar: false, foo: true}v1/ast/builtins.go。object.subset(superset, subset)判断第二个对象是否为第一个的子集返回布尔值truev1/ast/builtins.go。object.remove(obj, keys)从对象中删除指定键结果为{foo: true}v1/ast/builtins.go。这三个函数覆盖了合并配置校验覆盖关系剥离敏感字段等常见策略场景。八、更多学习路径本文覆盖的是 Rego 最高频的语法与函数完整语言参考请继续阅读仓库中的两份核心文档Rego 语言完整参考规则结构、引用语法、模块组织、future.keywords等进阶主题策略测试指南opa test命令、表驱动测试、覆盖率opa test --coverage与 mocking 技巧内置函数索引按类别列出全部内置函数及其签名。官方还提供了速查表的可打印 PDF 版本cheatsheet.pdf适合离线查阅。将本文的示例逐段放入 OPA Playground 或本地opa eval中运行是快速内化这些语法的最高效方式。赞分享后端认证鉴权云原生【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址https://gitcode.com/gh_mirrors/op/opa点击查看免费下载相关推荐Trivy 内置 Rego 检查规则贡献指南从元数据、Schema 到 result.new 的完整实践Trivy 内置 Rego 检查规则贡献指南从元数据、Schema 到 result.new 的完整实践 本篇围绕 Trivy 官方文档《Contribute应用安全漏洞扫描SBOM供应链安全云原生KaTeX 支持函数完整指南从 Accents 到 Units 的 TeX 语法速查手册KaTeX 支持函数完整指南从 Accents 到 Units 的 TeX 语法速查手册 KaTeX 是面向 Web 的高性能数学排版引擎而 docs/su前端ToastFish终极Windows通知栏背单词解决方案如何在工作间隙高效提升英语能力ToastFish终极Windows通知栏背单词解决方案如何在工作间隙高效提升英语能力 你是否曾经在工作间隙想要学习英语却发现传统学习软件太过显眼或者需开发工具代码质量静态分析上一篇Apache Airflow Cohere Provider 详解安装、连接配置与 Embedding / Rerank 算子实战下一篇解决Flutter网络崩溃难题Dio全方位状态监听与优雅处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考