Go Starlark Go 怎样向脚本注册宿主函数

在 Go Starlark Go 中，先用 starlark.NewBuiltin 包装符合接口签名的 Go 函数，再把它放进 starlark.StringDict，作为 ExecFile 的预声明环境传入。脚本使用字典中的名称调用它；回调里用 UnpackArgs 处理参数，再返回合法的 Starlark 值。

项目官方地址：https://github.com/google/starlark-go

先定义功能基线与测量口径

我倾向先做一个没有外部依赖的宿主函数，再讨论注册是否足够快。本文选择 label：接收名称和可选前缀，拼成标签。这样可以把“脚本能否找到函数”“参数是否符合约定”和“宿主业务是否耗时”分开讨论。

这里不提供未经测量的吞吐量或性能提升比例。示例是集成写法，没有在本文中运行。功能基线是正常输入产生约定字符串，错误输入以错误结束，而不是继续返回半成品。

用NewBuiltin和预声明字典注册函数

下面是独立 Go 模块内的完整入口示例。先在项目中添加 go.starlark.net/starlark 依赖并固定适合项目的模块版本；不要把未固定的开发分支当作生产依赖约束。

package main

import (
    "fmt"
    "os"
    "strings"
    "go.starlark.net/starlark"
)

// label只负责字符串组合，不开放文件或网络访问。
func label(_ *starlark.Thread, fn *starlark.Builtin,
    args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
    var name string
    prefix := "item"
    // 必填name与可选prefix同时支持位置参数和关键字参数。
    if err := starlark.UnpackArgs(fn.Name(), args, kwargs,
        "name", &name, "prefix?", &prefix); err != nil {
        return nil, err
    }
    // 类型正确后，继续检查本业务允许的输入范围。
    if strings.TrimSpace(name) == "" {
        return nil, fmt.Errorf("%s: name不能为空", fn.Name())
    }
    return starlark.String(prefix + ":" + name), nil
}

func main() {
    predeclared := starlark.StringDict{
        "label": starlark.NewBuiltin("label", label),
    }
    thread := &starlark.Thread{Name: "labels"}
    // 使用内存脚本，示例不读取用户文件。
    source := `# 脚本通过预声明名称调用Go宿主函数。
result = label(name="sensor", prefix="asset")
`
    globals, err := starlark.ExecFile(thread, "labels.star", source, predeclared)
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    // String会保留Starlark字符串的显示引号。
    fmt.Println(globals["result"].String())
}

字典键 label 决定脚本可见的名称；传给 NewBuiltin 的名称用于函数自身标识和诊断。让两处一致，可以减少报错时的理解成本。单独创建一个 Builtin 对象不会自动让所有脚本认识它，执行入口还必须接到这份预声明环境。

解析参数并返回Starlark值

回调接到的 args 是位置参数，kwargs 保存关键字参数。例子把 name 解包到 Go 字符串，把 prefix? 标为可选；缺省值来自调用前初始化的 prefix := "item"。

因此，脚本可以写 label("sensor")，也可以写 label(name="sensor", prefix="asset")。按示例中的纯字符串拼接规则，后一种调用的字符串内容应为 asset:sensor；入口使用 String() 打印时会带显示引号。这是代码推导的预期，不是运行日志。

把数字传给名称参数或漏传必填参数时，应直接返回解包错误。类型合格也不代表业务合格，所以示例另外拒绝全空白名称。这里故意不自动修剪最终名称：是否保留用户输入的空格，应由业务接口约定决定。

成功时返回 starlark.String。如果业务没有返回内容，应该返回 starlark.None, nil，不能用 nil, nil 冒充脚本的 None。

拆分性能测量而不混入编译成本

如果后续发现调用频繁，我会先分开测三组：直接调用 Go 的字符串组合逻辑；经解释器调用已经准备好的宿主函数；完整执行一份脚本。前两组帮助判断跨解释器接口的额外成本，第三组才反映当前执行方式的总体代价。

测量时保持输入内容、调用次数和宿主业务一致，记录 Go 版本、模块提交、处理器与并发设置。使用 Go benchmark 时记录 ns/op、B/op 和 allocs/op，多轮观察波动。需要测调用成本，就把脚本准备工作放在计时区外；需要测完整入口，就明确把它放在计时区内。

改动前后应使用同一口径比较。把“每次重新解析脚本”的旧方案与“只测现成函数调用”的新方案直接相除，会把不同工作量写成性能提升。本文没有执行这些测量，所以结果栏应保持待测，不能根据函数很短就声称零开销。

处理错误与宿主能力边界

宿主函数最好只开放脚本完成任务需要的能力。本文没有把任意文件路径、网络地址或命令执行接口交给脚本。如果未来增加外部访问，应在宿主服务里落实授权、超时与输入限制，而不是把解释器当作这些措施的替代品。

参数错误和业务错误都通过回调的 error 返回，让执行入口决定如何展示或记录。若宿主函数捕获可变 Go 状态，并发安全也由宿主负责。取消脚本执行可能要等正在运行的宿主回调返回才能被观察到；耗时外部操作需要自己的取消机制。

为什么脚本提示找不到label？

先看名称是否放进当前这次执行所用的预声明字典，再看脚本拼写是否一致。只定义Go函数或只创建Builtin都不等于完成名称绑定。

可选参数为什么没有默认值？

问号表示允许省略，默认值仍由Go变量初始化提供。不要期待参数名自动生成业务默认值。

什么时候值得优化注册方式？

当测量显示重复准备环境确实占据明显成本时，再考虑环境或编译产物复用。先把可见名称、输入契约和宿主状态所有权说清楚，通常比过早追求更少一层包装更实用。

技术依据：Starlark Go接口文档、官方参数解析实现、官方执行与取消接口。