Go Expr 怎样用 Env 为表达式声明结构化输入

在 Go Expr 里，expr.Env 的职责不是保存一次运行时数据，而是告诉编译器：表达式将会看到哪些字段、这些字段是什么类型。比较稳定的写法是用同一个结构体作为环境样本和运行值：编译时传入 expr.Env(Input{})，运行时再把填好数据的 Input 传给 expr.Run。这样字段拼写和类型变化会尽早暴露。

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

本文只讨论结构化输入这一条链路。Expr 官方仓库的示例同时展示了用 map 或结构体声明环境，官方语言文档还说明 $env 可以访问传入表达式的变量集合。

影响面：为什么表达式能编译但运行时拿不到业务字段

这类问题通常出现在规则配置刚接入服务时：表达式写成 Order.Total > Limit，调用方却只在运行时传了一个 map，或者编译时用的环境字段和运行时对象已经不是同一套。故障表面是“字段不存在”“类型不匹配”，根因是两个边界被混在了一起。

expr.Compile 需要知道表达式的输入形状；expr.Run 才接收本次请求的数据。前者像接口声明，后者像接口调用。只把数据传给 Run，并不会替代编译阶段的环境声明。

触发条件：用结构体声明 Expr 的输入形状

假设规则要判断订单金额和地区，先把表达式需要的字段收敛到一个小结构体。编译阶段传入零值结构体即可，重点是让 Expr 获得字段名与类型。

package main

import (
    "fmt"

    "github.com/expr-lang/expr"
)

type Input struct {
    Total  int
    Region string
}

func main() {
    // 表达式只依赖这两个字段，环境结构体就是它的输入契约。
    code := `Total >= 1000 and Region == "华东"`

    // 零值样本用于编译期字段和类型检查，不代表一次真实请求。
    program, err := expr.Compile(code, expr.Env(Input{}))
    if err != nil {
        // 编译错误应在配置加载阶段返回，避免错误规则进入运行期。
        panic(err)
    }

    input := Input{Total: 1280, Region: "华东"}
    // 运行时传入同形状的业务数据，Expr 才能读取字段值。
    output, err := expr.Run(program, input)
    if err != nil {
        // 运行错误仍要保留，便于区分数据问题和表达式编译问题。
        panic(err)
    }

    fmt.Println(output)
}

这里的关键不是把结构体写得多大，而是让它只包含规则真正需要的字段。结构体字段改名、类型改动或表达式引用了不存在的字段时，问题会集中出现在编译边界，而不是散落到业务请求中。

根因：Env 与 Run 使用了不同的数据形状

最容易误判的一点是：expr.Env(Input{}) 只描述环境形状，不会把这个零值对象自动带到执行阶段。执行时仍要传入真实的 Input。反过来，如果编译时声明了结构体，运行时却传入字段名相似但类型不同的 map，也会让问题变得难以追踪。

建议把“表达式文本、编译环境、运行值”放在同一条调用链上，至少固定三件事：

• 表达式里使用的字段必须属于输入结构体；
• 编译样本和运行值使用同一种结构体定义；
• 编译错误与运行错误分开记录，不要只返回一个笼统的“规则失败”。

如果表达式确实需要动态变量，可以使用 map，但仍然要明确它的字段集合和值类型。官方语言文档中的 $env 是表达式可见变量的集合视图，适合处理变量名需要动态判断的场景；它不能替代对核心业务字段的建模。

修复动作：把结构化环境接入完整调用链

在服务中可以把编译动作放到配置加载阶段，把运行动作留在请求路径。下面的函数把编译错误和执行错误保留在不同出口，调用方只负责传入一个已经填好的结构体。

import (
    "fmt"

    "github.com/expr-lang/expr"
    "github.com/expr-lang/expr/vm"
)

type RuleInput struct {
    Total  int
    Region string
}

func compileRule(code string) (*vm.Program, error) {
    // 用零值结构体声明稳定的字段和类型，不在这里读取请求数据。
    return expr.Compile(code, expr.Env(RuleInput{}))
}

func evaluateRule(program *expr.Program, input RuleInput) (bool, error) {
    // Run 只接收当前请求的结构化数据，保持与 Compile 的环境形状一致。
    value, err := expr.Run(program, input)
    if err != nil {
        // 运行错误通常与数据值或表达式函数有关，单独向上层返回。
        return false, fmt.Errorf("run expr rule: %w", err)
    }

    result, ok := value.(bool)
    if !ok {
        // 规则约定返回布尔值，避免把字符串或数字悄悄当成通过。
        return false, fmt.Errorf("expr rule returned %T, want bool", value)
    }
    return result, nil
}

这段组织方式的价值在于：规则编译失败不会等到请求到来才暴露，运行结果也不会因为类型断言缺失而被静默接受。它适合把表达式当成一个有明确输入输出的配置接口。

防复发：让表达式环境成为稳定接口

第一，把输入结构体当成版本化接口。新增字段通常是兼容扩展，但删除字段或改变类型会直接影响已有表达式，应该和配置变更一起评审。第二，集中编译规则，不要在每个请求中重复编译相同文本。第三，给规则配置准备一条加载期错误日志，记录规则标识和编译错误，避免线上只看到业务请求失败。

如果使用 map，建议在进入 Expr 前完成字段命名和类型整理；如果使用结构体，建议为表达式专门定义小型输入类型，不要把整个数据库模型或请求对象直接暴露出去。这样既减少规则与业务对象的耦合，也能让结构化输入的边界更容易维护。

常见问题

expr.Env(Input{}) 会把 Input 的零值传给 expr.Run 吗？

不会。它只是编译时的环境声明，真实请求仍需把具体的 Input 传给 expr.Run。

编译时用结构体，运行时能换成 map 吗？

不建议这样做。即使部分字段碰巧能解析，字段类型和嵌套结构也可能产生运行期差异。更稳妥的方式是编译和运行都使用同一个输入结构体。

为什么要单独检查结果是不是 bool？

因为业务规则通常需要明确的通过或拒绝。显式断言能把表达式作者误写成数字、字符串等问题尽快暴露，而不是让调用方自行猜测含义。