Go Expr 怎么为表达式注册带类型约束的函数

Go Expr 注册自定义函数时，真正需要分开的有两件事：一份是运行时执行的函数实现，另一份是告诉编译器“这个函数接受什么参数、返回什么类型”的函数签名。只传实现回调，表达式很容易把错误拖到运行阶段；给 expr.Function 追加函数类型，才能把类型约束前移到 expr.Compile。

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

稳定的做法是用 expr.Function 注册 func(params ...any) (any, error) 实现，再用 new(func(...)) 提供表达式侧的静态签名。编译错误在规则构建阶段处理，运行时的业务失败仍由函数返回 error 或业务值表达。

下面以一个“按用户等级计算折扣”的规则为例。文章中的数字是示例契约，不把它们描述为本机运行结果；重点是注册入口、类型检查和错误边界。

先把函数实现和表达式签名分开

expr.Function 的第二个参数是通用实现回调。它接收 ...any，因此可以统一处理参数数量、断言具体类型和业务错误。后面的 types ...any 不是第二份实现，而是给 Expr 编译器看的函数类型描述。

这两个层次对应不同指标：没有类型签名时，表达式调用的参数问题可能在规则运行时才暴露；有了签名后，参数个数、参数类型以及返回值类型可以在编译阶段进入契约。它不会改变实现回调仍然要做的运行时错误处理。

用函数类型声明参数与返回值

最小的注册方式可以把表达式函数设计成 discount(int, string) float64。实现回调仍然从 params 读取值，但额外的函数类型让表达式知道第一个参数必须是整数、第二个参数必须是字符串，并且结果应当是 float64。

package main

import (
    "fmt"
    "github.com/expr-lang/expr"
)

// discountImpl 负责运行时取参和业务判断，错误不能静默变成零值。
func discountImpl(params ...any) (any, error) {
    if len(params) != 2 {
        return nil, fmt.Errorf("discount 参数数量错误：%d", len(params))
    }

    // 类型签名会先帮助 Compile 检查，但实现仍需保护运行时入口。
    level, ok := params[0].(int)
    if !ok {
        return nil, fmt.Errorf("discount 第一个参数不是 int：%T", params[0])
    }
    role, ok := params[1].(string)
    if !ok {
        return nil, fmt.Errorf("discount 第二个参数不是 string：%T", params[1])
    }

    if level >= 3 && role == "member" {
        return 0.90, nil
    }
    return 1.00, nil
}

func main() {
    // 函数类型只描述表达式契约，不会替代上面的实现回调。
    option := expr.Function(
        "discount",
        discountImpl,
        new(func(int, string) float64),
    )

    program, err := expr.Compile(
        `discount(Level, Role) 

这里使用 new(func(int, string) float64)，是因为 expr.Function 会读取这个值的反射类型；库内部会去掉指针层，并要求最终得到的类型确实是函数类型。new 只是构造类型载体，不会被当成运行时参数传入表达式。

如果表达式写成 discount("3", Role)，或者把结果拿去和字符串比较，编译阶段就应当指出契约不匹配。这个前移动作比等到某个请求才触发实现回调更容易定位。

把注册函数放进可复用的编译入口

生产代码通常不会在每次请求里重新注册和编译函数。可以把自定义函数选项和环境类型放到一个构建函数中，规则文本保持不变时复用返回的程序。这样“注册能力”和“当前请求数据”不会混在一起。

type RuleEnv struct {
    Level   int
    Role    string
    MaxRate float64
}

func compileRule() (any, error) {
    // 空值环境只用于声明字段和类型，实际值在 expr.Run 时提供。
    return expr.Compile(
        `discount(Level, Role) 

如果要采用上面的完整写法，需要在代码文件的导入区增加 github.com/expr-lang/expr/vm，并把 compileRule 的返回类型改成 *vm.Program；这里保留 any 是为了突出“程序对象与运行环境分离”的边界。实际项目应选择明确的公开类型，而不是用空接口掩盖契约。

一个简单的基线对比是：把注册、编译和运行全部放进请求路径，会重复承担规则准备成本；将函数注册和编译移到规则加载边界后，请求路径只剩 Run 与当前环境。不要把这个结构性判断写成未经测量的固定百分比，实际收益要用项目自己的规则数量、输入规模和基准方法测量。

区分编译错误、函数错误和业务 false

这三种结果的语义不同。表达式调用与函数签名冲突，属于 Compile 阶段的规则错误；函数实现发现参数值不满足业务约束，属于 Run 阶段的运行错误；函数正常返回 1.00，随后规则判断为 false，则是一次成功求值后的业务拒绝。

这种分层也方便缓存。只有编译成功的程序才能进入缓存；某次输入导致的业务错误不应让所有相同规则都重新编译。反过来，如果自定义函数的签名、环境字段或编译选项改变，旧程序就不再代表当前契约。

多签名和动态参数应该怎么选

expr.Function 的 types ...any 可以承载多个函数类型，适合一个名字对应若干明确签名的场景。不过“能列出多个签名”不等于实现回调可以完全不做判断；实现仍然要根据收到的参数做安全分支，调用方也应为每种签名写清结果类型。

// 只在确实需要两个固定签名时注册多种类型，避免扩大表达式契约。
option := expr.Function(
    "label",
    func(params ...any) (any, error) {
        // 运行时仍要检查参数数量，并把不支持的组合返回为错误。
        switch len(params) {
        case 1:
            value, ok := params[0].(int)
            if !ok {
                return nil, fmt.Errorf("label 参数不是 int：%T", params[0])
            }
            return fmt.Sprintf("等级-%d", value), nil
        case 2:
            prefix, ok := params[0].(string)
            if !ok {
                return nil, fmt.Errorf("label 前缀不是 string：%T", params[0])
            }
            value, ok := params[1].(int)
            if !ok {
                return nil, fmt.Errorf("label 等级不是 int：%T", params[1])
            }
            return fmt.Sprintf("%s-%d", prefix, value), nil
        default:
            return nil, fmt.Errorf("label 不支持 %d 个参数", len(params))
        }
    },
    new(func(int) string),
    new(func(string, int) string),
)

如果参数类型只有在表达式内容或运行时上下文中才能决定，就不要把一个“看起来灵活”的 any 函数伪装成固定签名。Expr 的 builtin.Function 还提供 Validate 这类按 []reflect.Type 动态返回结果类型的能力，但它更适合确实需要动态类型规则的底层扩展；普通业务函数优先使用一到两个清晰的固定签名。

只传函数实现，不传类型签名可以吗？

可以注册，但放弃了表达式侧的静态参数与返回值约束。除非函数本身就是刻意设计的动态入口，否则建议把可确定的签名补上。

类型签名会替代实现里的类型断言吗？

不会。签名服务于编译阶段，类型断言服务于运行边界；配置、接口或其他代码仍可能把不符合约定的值送到实现回调，因此实现应保留错误处理。

什么时候应该重新编译？

表达式文本、环境字段类型、自定义函数签名或相关编译选项变化时重新编译。只有当前环境的字段值变化时，继续复用已有程序即可。

小结

Go Expr 自定义函数的关键不在于把所有参数都塞进 ...any，而在于同时维护两份清晰契约：用回调处理运行时值和业务错误，用 new(func(...)) 声明表达式侧的参数与返回类型。将注册和编译放在规则构建边界，能让类型问题更早暴露；将 Run 的错误与业务 false 分开，才能让缓存、排错和调用方决策保持稳定。