4. 常见语法错误类型（二）：变量未定义、类型不匹配、函数调用错误

在云原生安全策略（如 OPA/Gatekeeper ConstraintTemplate、Kyverno ClusterPolicy 或自定义准入控制器 Webhook）的编写与调试过程中，除了结构性问题外，语义级错误是导致策略静默失效或执行异常的主要原因。本章聚焦三类高频语义错误：变量未定义、类型不匹配与函数调用错误，并结合 Rego 与 JSON 逻辑进行剖析。

4.1 变量未定义（Undefined Variable）

变量未定义指在策略规则中引用了尚未声明或不在当前作用域内的变量。在 Rego 等声明式策略语言中，未定义变量不会直接报错，而是导致规则求值为 undefined，使策略“静默通过”或“永远不触发”。

4.2 类型不匹配（Type Mismatch）

类型不匹配发生在策略引擎期望某种数据类型（如字符串、数组、对象），但实际传入的值类型不同。这类错误在动态类型语言中尤为隐蔽，常在运行时才暴露。

4.3 函数调用错误（Function Call Error）

函数调用错误包括：调用不存在的内置函数、参数数量或类型与函数签名不匹配、以及自定义函数未定义或循环引用。

• 内置函数拼写错误： 如将 regex.match 误写为 regex.mach，导致编译失败。
• 参数数量错误： split("a,b,c", ",") 正确，但 split("a,b,c") 缺少分隔符参数。
• 自定义函数未导出： 在 Rego 包中，函数名首字母小写为私有，大写为公有；跨包调用私有函数会报 undefined function。
• 递归或循环依赖： 自定义函数直接或间接调用自身，导致栈溢出或超时。

# 错误示例：内置函数拼写错误
violation[{"msg": "invalid image"}] {
    not regex.mach(`^[a-z]+$`, input.image)  # 应为 regex.match
}

# 正确示例
violation[{"msg": "invalid image"}] {
    not regex.match(`^[a-z]+$`, input.image)
}

4.4 三类错误对比与调试策略

4.5 综合调试示例：Rego 策略中的三类错误

以下示例展示了一个包含三类错误的 Gatekeeper ConstraintTemplate 片段，以及对应的修复方案。

# 错误版本（包含三类错误）
package k8srequiredlabels

violation[{"msg": msg}] {
    # 错误1：变量未定义 - msg 未赋值
    # 错误2：类型不匹配 - input.review.object.metadata.labels 是对象，却用数组索引
    label := input.review.object.metadata.labels[0]
    # 错误3：函数调用错误 - 拼写错误
    not regex.mach(`^[a-z]+$`, label)
}

# 修复版本
package k8srequiredlabels

violation[{"msg": msg}] {
    labels := input.review.object.metadata.labels
    # 修复2：使用对象遍历
    label := labels[_]
    # 修复3：正确函数名
    not regex.match(`^[a-z]+$`, label)
    # 修复1：显式赋值 msg
    msg := sprintf("label '%v' does not match pattern", [label])
}