3. 常见语法错误类型（一）：括号不匹配、引号缺失、缩进错误

在云原生安全策略（如 OPA/Gatekeeper、Kyverno、OPA-Envoy 或自定义准入控制器策略）的编写与核验过程中，语法错误是最常见且最容易被忽视的问题。这类错误通常不会触发运行时安全告警，而是直接导致策略加载失败、策略不生效或产生非预期的拒绝行为。本章聚焦于三类最基础的语法错误：括号不匹配、引号缺失 与 缩进错误，通过典型场景与调试方法帮助学习者建立快速定位问题的能力。

3.1 括号不匹配

括号不匹配是 Rego、YAML 或 JSON 策略中最容易出现的结构性错误。在 Rego 策略中，括号用于定义规则体、函数参数、集合与数组；在 YAML/JSON 中，花括号与方括号用于定义对象与数组结构。一旦括号数量不对等，解析器将无法正确识别作用域边界，导致策略整体失效。

3.1.1 常见括号类型与匹配规则

3.1.2 错误示例与修正

# 错误示例：花括号不匹配
violation[{"msg": "container image must not be latest"
    # 缺少右花括号
]

# 正确示例
violation[{"msg": "container image must not be latest"}]

3.2 引号缺失

引号用于定义字符串常量、键名（在 JSON 中强制要求）以及某些 Rego 内置函数的参数。引号缺失会导致解析器将字符串误识别为变量名或关键字，从而引发 rego_type_error 或 syntax_error。

3.2.1 引号缺失的典型表现

• JSON 策略中键名未加引号： {name: "test"} 应写为 {"name": "test"}
• Rego 字符串常量未加引号： input.request.kind = Deployment 应写为 input.request.kind = "Deployment"
• YAML 多行字符串中引号不闭合： 导致后续内容被错误解析为字符串的一部分

3.2.2 错误示例与修正

# 错误示例：引号缺失
deny[msg] {
    input.request.operation = CREATE    # "CREATE" 缺少引号
    msg = "operation not allowed"
}

# 正确示例
deny[msg] {
    input.request.operation = "CREATE"
    msg = "operation not allowed"
}

3.3 缩进错误

缩进在 YAML 和 Rego 中具有语义含义。YAML 使用缩进表示层级关系；Rego 虽然不强制缩进，但社区规范与可读性要求一致缩进。缩进错误会导致策略结构错乱、规则体意外闭合或条件判断失效。

3.3.1 YAML 缩进规则

• 使用空格缩进，禁止使用 Tab 键（不同编辑器对 Tab 解释不一致）
• 同一层级必须保持相同缩进空格数（通常为 2 或 4 个空格）
• 列表项（-）与其父级缩进对齐，列表项内容再缩进一级

3.3.2 Rego 缩进规范

• 规则体内部语句缩进 2 或 4 个空格
• 嵌套条件（some、every、not）应比外层多缩进一级
• 多行表达式换行时，续行应与上一行表达式对齐

3.3.3 错误示例与修正

# 错误示例：YAML 缩进不一致
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: require-labels
spec:
  match:
    kinds:
      - apiGroups: [""]
  kinds: ["Pod"]    # 缩进错误，与上方 kinds 层级混乱

# 正确示例
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: require-labels
spec:
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Pod"]    # 正确缩进，作为 apiGroups 的子级

3.4 三类错误对比与快速定位

3.5 语法错误调试流程

下图展示了从发现错误到修复验证的标准调试流程，适用于括号不匹配、引号缺失与缩进错误三类场景。