Rego 语言风格指南：从 Styra 官方最佳实践解读

前言

Rego 作为 Open Policy Agent (OPA) 的核心策略语言，其优雅的声明式语法为策略即代码提供了强大支持。本文基于 Styra 官方发布的 Rego 风格指南，结合多年实战经验，系统性地梳理 Rego 语言的编码规范与最佳实践。

基础原则

可读性优于性能

Rego 作为声明式语言，开发者应聚焦于表达"做什么"而非"如何做"。过度优化往往适得其反：

• 避免假设性能特征进行微观优化
• 保持代码直观清晰，便于团队协作
• 性能问题应通过 OPA 引擎优化而非策略代码

典型案例：复杂的嵌套推导式虽然紧凑，但会显著降低可维护性。

格式化工具统一

使用 opa fmt 工具确保团队代码风格一致：

# 格式化文件
opa fmt -w policy.rego

# 检查格式（CI/CD场景）
opa fmt --fail policy.rego

编辑器集成建议：配置保存时自动格式化，GitHub 展示时可配置 .editorconfig 调整缩进显示。

严格模式启用

严格模式能捕获常见错误：

opa check --strict policy.rego

典型检查项：

• 冗余导入
• 未使用变量
• 语法不规范

元数据注释规范

优先使用结构化注释而非普通注释：

# METADATA
# title: 访问控制规则
# description: 验证用户管理员权限
# custom:
#   error_code: E401
deny if {
    not input.is_admin
    metadata := rego.metadata.rule()
}

优势：

• 工具链可解析
• 便于生成文档
• 错误码集中管理

代码风格规范

命名约定

1. 蛇形命名法：与内置函数风格一致

   # 推荐
   user_is_admin if "admin" in input.roles
   
   # 避免
   userIsAdmin if "admin" in input.roles
   

2. 内部标识符：前缀下划线表示模块内私有

   _validate_user(user) if {
       # 内部校验逻辑
   }
   

行长度控制

保持单行≤120字符，复杂逻辑换行：

# 不推荐
admins := [user | some user in input.users; "admin" in user.roles; user.active]

# 推荐
admins := [user |
    some user in input.users
    "admin" in user.roles
    user.active
]

规则设计模式

辅助规则分解

将复杂条件拆分为语义化辅助规则：

allow if {
    is_developer
    is_read_method
    is_api_path
}

is_developer if "developer" in input.user.roles
is_read_method if input.method in {"GET", "HEAD"}
is_api_path if startswith(input.path, "/api")

优势：

• 提高可读性
• 便于复用
• 更易调试

未定义处理技巧

使用否定式处理未定义情况：

deny contains "无效用户" if not valid_user

valid_user if {
    input.user_id != "anonymous"
    input.user_id != ""
}

对比传统方案：

• 避免逐字段检查
• 统一处理未定义和非法值
• 错误消息更友好

推导式优化

优先使用部分规则替代内联推导式：

# 推荐（可复用）
high_risk_users contains user if {
    some user in data.users
    user.risk_score > 80
}

# 不推荐（难以调试）
allow if {
    input.user in [user | some user in data.users; user.risk_score > 80]
}

数据类型与操作

集合操作最佳实践

1. 成员检查：in 操作符

   # 推荐
   is_valid if "admin" in input.roles
   
   # 避免
   is_valid if input.roles[_] == "admin"
   

2. 迭代方式：some...in 结构

   # 推荐
   admins := [name | 
       some user in input.users
       "admin" in user.roles
       name := user.name
   ]
   

3. 全量断言：every 表达式

   all_secure if every container in input.containers {
       container.security_context.read_only_root_filesystem
   }
   

变量声明规范

1. 避免未声明变量：使用 some 显式声明

   # 正确
   allow if {
       some user_id in input.user_ids
       # ...
   }
   
   # 错误（隐式声明）
   allow if input.user_ids[user_id]
   

2. 集合优于数组：当元素唯一性重要时

   # 推荐（自动去重）
   unique_roles := {role | some role in input.user.roles}
   
   # 不推荐（允许重复）
   all_roles := [role | some role in input.user.roles]
   

函数设计原则

参数设计规范

1. 显式参数传递：避免隐式依赖

   # 推荐
   has_permission(user, resource) if {
       # ...
   }
   
   # 避免
   has_permission if {
       # 隐式依赖input
   }
   

2. 返回值位置：避免末位参数模式

   # 推荐（标准返回）
   normalize_path(p) = processed if {
       processed := trim(p, "/")
   }
   
   # 避免（非常规模式）
   normalize_path(p, processed) if {
       processed := trim(p, "/")
   }
   

正则表达式规范

使用原始字符串避免转义：

# 推荐
valid if regex.match(`^\d{4}-\d{2}-\d{2}$`, input.date)

# 避免
valid if regex.match("^\\d{4}-\\d{2}-\\d{2}$", input.date)

模块化设计

包结构规范

包名需匹配文件路径：

policies/
└── authz/
    ├── api.rego   # package authz.api
    └── db.rego    # package authz.db

导入策略

1. 包级别导入：增强可读性

   # 推荐
   import data.authz.rules
   
   # 避免
   import data.authz.rules.allow
   

2. 输入隔离：避免直接导入input

   # 不推荐
   import input.user.roles
   

演进建议

未来关键字处理

对保留字使用显式导入：

import future.keywords.in
import future.keywords.every

结语

良好的编码风格是高效策略开发的基础。通过本文介绍的规范，开发者可以：

1. 编写更易维护的 Rego 代码
2. 避免常见陷阱和反模式
3. 建立团队统一的编码标准
4. 提升策略执行效率

随着 OPA 的持续演进，建议定期关注语言特性的更新，及时调整编码实践。对于复杂策略场景，建议结合 JSON Schema 进行类型校验，并考虑使用相关工具进行自动化检查。