4. Rego 数据模型：文档模型、完整文档与部分文档、默认值规则

Rego 的数据模型是策略即代码的基石。理解其“文档模型”的核心理念，以及“完整文档”与“部分文档”的差异，是编写高效、可维护策略的前提。本章将深入剖析这些概念，并重点讲解默认值规则的最佳实践。

4.1 文档模型：一切皆文档

在 Rego 中，所有数据——无论是输入（input）、系统状态（data）还是你定义的规则——都被视为一个巨大的、嵌套的 JSON 文档。这个文档模型是 Rego 查询和策略评估的基础。

• 统一视图：策略引擎将外部数据（如 Kubernetes 资源清单）和内部规则输出合并到一个单一的、可查询的文档树中。
• 分层结构：文档通过点号（.）访问其嵌套属性，例如 input.namespace 或 data.resources.cpu。
• 不可变性：在单次策略评估中，输入文档是只读的。规则通过定义新文档（即规则输出）来产生结果。

4.2 完整文档与部分文档

Rego 规则根据其定义方式，可以生成两种类型的文档：完整文档和部分文档。这是 Rego 数据模型中最重要的区分之一。

4.2.1 完整文档示例

完整文档在评估后产生一个固定的值。它不依赖于任何输入变量（除了全局的 input 或 data）。

# 完整文档：返回一个静态对象
allowed_regions := ["us-east-1", "eu-west-1", "ap-southeast-1"]

# 完整文档：基于 input 计算出一个单一值
max_cpu_cores := 4 if {
    input.tier == "production"
} else := 2

4.2.2 部分文档示例

部分文档类似于一个函数。它根据提供的参数返回不同的结果。这在实现查找表或动态策略时非常有用。

# 部分文档：根据命名空间返回 CPU 配额
namespace_cpu_quota(namespace) := quota if {
    quota := data.quotas[namespace].cpu
}

# 部分文档：检查某个资源类型是否被允许
allowed_resource_type(kind) := true if {
    kind in ["Deployment", "StatefulSet", "DaemonSet"]
}

4.3 默认值规则

默认值规则是 Rego 中处理“未定义”或“缺失数据”的优雅方式。当一条规则在所有条件下都无法被满足时，它不会返回 false，而是返回 undefined。默认值规则允许你为这种情况提供一个安全的回退值。

• 语法：使用 default 关键字，后跟规则名称和默认值。
• 优先级：默认值规则的优先级最低。只有当其他所有同名规则都未定义时，默认值才会生效。
• 应用场景：为配额设置默认限制、为缺失的标签提供默认行为、防止因数据不完整导致的策略评估错误。

4.3.1 默认值规则示例

# 默认值规则：如果未定义，则 CPU 配额默认为 2
default cpu_quota := 2

# 常规规则：为特定命名空间定义配额
cpu_quota := 8 if {
    input.namespace == "production"
}

cpu_quota := 4 if {
    input.namespace == "staging"
}

# 查询：如果 input.namespace 是 "development"，则 cpu_quota 返回 2

4.3.2 默认值规则与部分文档结合

默认值规则也可以与部分文档结合，为函数提供默认行为。

# 为部分文档设置默认值
default namespace_allowed(_) := false

# 常规规则：允许特定命名空间
namespace_allowed(namespace) := true if {
    namespace in ["default", "kube-system", "production"]
}

# 查询：namespace_allowed("random-ns") 返回 false