Go CEL 怎样声明输入变量并编译筛选表达式

Go 中使用 CEL 编写筛选规则时，关键不是把表达式当成字符串直接执行，而是先在环境里声明变量类型，再完成解析和类型检查。最小流程是：cel.Variable 定义输入契约，env.Compile 编译表达式，env.Program 生成可复用程序，最后把业务数据作为输入求值。

官方地址：https://github.com/cel-expr/cel-go

如果筛选条件会被重复使用，应在配置加载或初始化阶段编译一次；请求处理阶段只绑定输入并调用 Eval。这样既能提前发现变量类型错误，也避免每次请求重复解析。

一、先把 CEL 输入变量声明成明确类型

本文用一个具体筛选条件作为例子：名称以 go- 开头，并且分数不低于 80。表达式需要两个外部输入：name 是字符串，score 是整数。它们不是 Go 代码中的局部变量，而是 CEL 环境公开给表达式的变量名。

package main

import (
    "fmt"

    "cel.dev/cel-go/cel"
)

func main() {
    // 用 CEL 类型声明输入契约，表达式里的 name 和 score 才能参与类型检查。
    env, err := cel.NewEnv(
        cel.Variable("name", cel.StringType),
        cel.Variable("score", cel.IntType),
    )
    if err != nil {
        // 环境配置失败时不应继续编译，否则后续错误会失去上下文。
        panic(err)
    }

    fmt.Println(env)
}

cel.StringType 和 cel.IntType 让 CEL 知道可用的操作：name.startsWith(...) 只能用于字符串，score >= 80 则要求整数语义。若把 score 声明成字符串，比较表达式会在编译阶段暴露问题，而不是等到线上输入才发现。

二、用 Compile 同时完成解析与类型检查

环境准备好后，把筛选表达式交给 Compile。它返回 AST 和 issues；只要 issues.Err() 非空，就应该把它当作编译失败处理。CEL 官方示例也建议把解析和检查提前完成，因为这一步比后续求值更适合放在初始化阶段。

// 只编译规则，不在这里绑定某一条业务数据。
ast, issues := env.Compile(`name.startsWith("go-") && score >= 80`)
if issues != nil && issues.Err() != nil {
    // 这里同时覆盖语法错误和类型检查错误。
    return fmt.Errorf("compile CEL expression: %w", issues.Err())
}

// AST 通过检查后再构造成可执行程序。
prg, err := env.Program(ast)
if err != nil {
    // 程序构造错误与表达式本身的 issues 分开处理，便于定位配置问题。
    return fmt.Errorf("build CEL program: %w", err)
}

这里的两个错误出口不要合并成“执行失败”：Compile 失败说明表达式与声明的环境不匹配；Program 失败说明 AST 到可执行程序的构造没有完成。只有得到 prg 后，才进入运行时输入绑定。

三、把 Program 复用到多次筛选

cel.Program 不携带某一次请求的输入，可以在初始化时创建后交给多个请求使用。每次求值只提供与声明同名的键，下面的 int64 对应 CEL 的整数类型：

func match(prg cel.Program, name string, score int64) (bool, error) {
    // 输入键必须与 cel.Variable 的名字一致，值的类型也要与声明匹配。
    input := map[string]any{
        "name":  name,
        "score": score,
    }

    // Program 可复用；每次调用只替换本次筛选的输入。
    out, _, err := prg.Eval(input)
    if err != nil {
        // 输入缺失或运行时类型不匹配会在求值阶段返回错误。
        return false, fmt.Errorf("evaluate CEL expression: %w", err)
    }

    accepted, ok := out.Value().(bool)
    if !ok {
        // 筛选条件应返回布尔值，避免把其它结果类型默认为通过。
        return false, fmt.Errorf("CEL result is %T, want bool", out.Value())
    }
    return accepted, nil
}

完整的初始化代码可以把上面的环境、编译和程序构造放进一个工厂函数：

func buildFilter() (cel.Program, error) {
    // 环境固定后只构建一次，后续请求共享同一个规则程序。
    env, err := cel.NewEnv(
        cel.Variable("name", cel.StringType),
        cel.Variable("score", cel.IntType),
    )
    if err != nil {
        return nil, err
    }

    ast, issues := env.Compile(`name.startsWith("go-") && score >= 80`)
    if issues != nil && issues.Err() != nil {
        return nil, issues.Err()
    }
    return env.Program(ast)
}

四、常见问题：变量声明与求值为什么容易混淆

1. 只在 Eval 时传入变量，为什么仍然编译失败？
因为 Eval 提供的是运行时值，不能替代编译阶段的类型声明。先用 cel.Variable 声明名称和类型，CEL 才能检查成员方法与比较运算。

2. 表达式编译成功，Eval 仍可能失败吗？
可能。编译检查的是表达式与环境的静态关系；运行时仍要保证输入键存在、值能映射到声明类型，并且表达式返回的是业务需要的布尔结果。

3. 每次请求重新 Compile 可以吗？
技术上可以，但会重复解析和类型检查。固定规则应缓存 cel.Program；只有表达式文本或变量声明确实变化时，才重新构建环境和程序。

因此，Go CEL 的筛选规则可以稳定地拆成三层：环境定义输入类型，编译阶段拒绝不合法表达式，求值阶段只处理具体数据。把这三层分开，错误处理和程序复用都会更清楚。