Go Starlark Go 怎样为 load 语句提供模块加载器

在 Go 里嵌入 Starlark 后，脚本中的 load("math.star", "double") 不会自动去读磁盘。真正决定“模块名对应什么内容”的，是宿主程序放进 starlark.Thread 的 Load 回调。它接收模块名，返回一个 starlark.StringDict，或者返回错误。

官方包地址：https://pkg.go.dev/go.starlark.net/starlark

这篇文章用一个小型内存模块表说明接口设计：先让重复加载复用同一个模块环境，再用加载中占位识别循环依赖；模块执行放到新线程，但新线程继续使用同一个加载器。这样 load 的职责、缓存职责和错误职责不会混在一起。

先把 load 语句翻译成 Thread.Load 合同

先抓住一个容易误解的点：load 是 Starlark 语言里的语句，不是需要我们额外注册的 Go 内置函数。解释器遇到它时，会读取当前线程的 Load 字段，并把模块字符串交给宿主。

这个回调的最小合同可以写成下面这样：

type Load func(thread *starlark.Thread, module string) (starlark.StringDict, error)

返回值里的 StringDict 就是被加载模块对外暴露的全局环境。脚本方可以通过第二个参数拿到其中的名字；宿主方则要保证同一个模块名的重复请求不会每次都重新执行。

用模块缓存保证重复加载的一致性

一个可维护的加载器至少要区分三种状态：模块从未请求过、模块正在加载、模块已经完成。把这三种状态压缩成一个普通的 map[string]StringDict 会丢失“正在加载”这个关键信号，也就无法识别 a.star 间接再次加载自己的情况。

顺序执行时，可以用 map 中的 nil 占位表示“加载中”，用结构体保存最终的环境和错误：

type moduleEntry struct {
	globals starlark.StringDict
	err     error
}

type loader struct {
	sources map[string]string
	cache   map[string]*moduleEntry // nil 表示该模块正在加载
}

func (l *loader) Load(_ *starlark.Thread, module string) (starlark.StringDict, error) {
	if entry, ok := l.cache[module]; ok {
		if entry == nil {
			// 再次遇到加载中的模块，说明依赖图出现了环。
			return nil, fmt.Errorf("cycle in load graph: %s", module)
		}
		// 成功和失败都缓存，保证重复请求得到同一结果。
		return entry.globals, entry.err
	}

	source, ok := l.sources[module]
	if !ok {
		// 缺失模块也写入结果，避免每次请求都重复查找。
		err := fmt.Errorf("module %q not found", module)
		l.cache[module] = &moduleEntry{err: err}
		return nil, err
	}

	// 先放占位，再解析模块内部可能出现的 load。
	l.cache[module] = nil
	child := &starlark.Thread{Name: "exec " + module, Load: l.Load}
	globals, err := starlark.ExecFile(child, module, source, nil)
	l.cache[module] = &moduleEntry{globals: globals, err: err}
	return globals, err
}

这里的关键不是 map 本身，而是状态转换顺序：先占位，后执行，最后写入结果。如果先执行再写缓存，模块内部的递归 load 看不到“正在加载”，循环就可能变成死递归或重复执行。

在新线程执行模块并继续传递加载器

每个模块都应在自己的 Thread 中执行。这样错误回溯里的文件名和调用边界更清楚，也不会把一个模块的线程局部状态误当成另一个模块的状态。但“新线程”不意味着“新加载器”：子线程的 Load 仍应指向同一个 loader.Load。

根脚本也要绑定这个回调，否则根脚本里的第一条 load 没有宿主入口：

root := &starlark.Thread{
	Name: "root",
	Load: modules.Load, // 根脚本和子模块共用同一份缓存
}

globals, err := starlark.ExecFile(root, "main.star", mainSource, nil)
if err != nil {
	if evalErr, ok := err.(*starlark.EvalError); ok {
		// EvalError 的回溯能指出脚本调用链中的失败位置。
		log.Print(evalErr.Backtrace())
	}
	log.Fatal(err)
}
fmt.Println(globals["result"])

子模块返回的环境不是根环境的副本。调用方只应通过 load 的名字使用它提供的值；如果业务需要共享可变状态，应显式设计宿主对象，而不是偷偷依赖多个模块反复执行的副作用。

把缺失模块、脚本错误和循环依赖分开

这三类错误的处理动作不同：

不要把所有失败都改写成“模块加载失败”。调用方通常需要知道是路径错、脚本错，还是依赖图错；保留原始错误并在外层补充模块名，定位成本会低很多。

另外，官方约定要求相同模块名的重复调用返回同一个模块环境或同一个错误。这个约定使脚本行为具有稳定性，也意味着缓存 key 必须在入口处统一规范化，例如统一相对路径规则，而不是让不同调用方各自拼接字符串。

缓存、并发和循环依赖要一起设计

上面的顺序版本适合一个根脚本串行加载模块。如果宿主会在多个 goroutine 中并行执行脚本，单纯给 map 加一把锁还不够：不能持锁执行整个 ExecFile，否则模块之间的互相等待会把锁变成新的死锁点。

并发版通常把缓存条目拆成四部分：模块 key、加载中的占位、完成通知 ready、最终的 globals/error。第一次请求创建条目并负责加载；后续请求释放互斥锁后等待 ready，再读取同一个结果。

如果允许并发加载，还要考虑“等待图”：A 等 B，B 又等 A 时，两个 goroutine 都在等待 ready，程序不会自然恢复。可以像官方示例那样给一次顶层加载分配一个 cycle checker，把当前加载者和等待对象串起来；发现新增等待边会形成环时，直接返回错误。

最后把 API 取舍收束成一张清单

• 入口：根线程和每个子模块线程都设置 Load，不要把模块解析逻辑藏在脚本内置函数里。
• 返回值：成功返回模块的 StringDict，失败保留原始 error，必要时在外层补充模块名。
• 缓存：相同模块名复用同一环境或同一错误；加载中要有独立状态，不能与“空模块”混淆。
• 线程：模块可以在新线程执行，但所有线程应共享同一个加载器和模块缓存。
• 并发：锁只保护缓存状态，不要在锁内运行 ExecFile；用 ready 交付已完成结果。
• 循环：顺序场景用占位检测，真正并行时再增加等待图检测，避免把死锁留给线上。

这样实现后，load 的 API 设计就清楚了：Starlark 只提出模块名和需要的符号，Go 宿主负责定位、缓存、执行和错误模型。先把这四个职责分开，再决定是否加入磁盘读取、模块路径规范化或并发加载，后续扩展会比直接在回调里堆逻辑稳定得多。

相关问题

Thread.Load 返回 nil 的 StringDict 可以吗？

成功路径不建议返回 nil，因为脚本方需要从模块环境中读取名称。没有可导出的值时，也应返回一个明确的空 StringDict；失败路径则返回 error。

为什么不在每次 load 时重新执行文件？

重复执行会破坏官方约定，还可能重复触发模块初始化副作用。用模块名缓存最终环境或错误，脚本行为更稳定。

顺序缓存能直接用于并发脚本吗？

不能直接照搬。并发场景需要互斥保护、完成通知和等待图循环检测，并且不能在持锁期间执行模块代码。