Go Starlark 的 Freeze 为什么会禁止后续修改集合

如果 Go 代码把一个 *starlark.List 或 *starlark.Dict 交给多个 Starlark 解释器读取，之后又尝试调用 Append、SetIndex 或 SetKey，修改失败并不是集合“突然坏了”，而是它已经进入了冻结状态。

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

Freeze 的核心不是只给外层集合加一个只读开关，而是把根值通过集合和闭包可达的对象一起标记为 frozen。后续通过 Starlark API 进行的变更会动态失败，这样同一份数据才能安全发布给并发运行的解释器。

修改失败现场：为什么只是追加一个元素也会报错

排查时最容易忽略的是调用顺序。集合通常先由 Go 代码构造、填充默认值，再调用 Freeze()，最后作为全局值或内置函数返回值交给解释器。若初始化逻辑仍在冻结之后运行，Append、Clear、SetIndex、SetKey 等修改方法就会返回错误。

因此，看到修改失败时先记录三件事：修改对象的实际类型、最近一次调用 Freeze() 的位置，以及这次写入是否发生在发布之后。不要先把问题归因于 Go 指针或垃圾回收。

Freeze 到底冻结了什么

官方 Value 接口的语义是：Freeze 会把当前值，以及通过集合和闭包传递可达的值，都标记为 frozen。之后通过这套 API 修改数据结构会动态失败，结果是数据结构不可变，并且可以安全地发布给并发运行的 Starlark 解释器。

这解释了两个常见现象：

• 冻结外层 Dict 后，里面的 List 也不能再通过 API 修改；不能只检查外层指针是否变化。
• 冻结并不会复制一份新对象。原来的对象仍然被引用，只是进入了不允许变更的生命周期阶段。

List、Dict 和 Set 都提供 Freeze()；它们的修改操作仍然通过返回值报告错误。普通不可变值调用冻结通常没有可见变化，但自定义 Value 必须实现自己的冻结策略。

构造阶段和发布阶段要分开

最稳妥的做法是把共享值分成两个阶段：构造阶段允许填充和校正，发布阶段只读。下面的代码只展示 API 关系，错误分支用于说明冻结后写入应如何被保留和处理；它不是本机运行截图。

package main

import (
    "fmt"

    "go.starlark.net/starlark"
)

func buildGlobals() (starlark.StringDict, error) {
    // 先在可变阶段准备嵌套集合，避免发布后再补数据。
    flags := starlark.NewList([]starlark.Value{
        starlark.String("safe"),
    })
    globals := starlark.StringDict{
        "flags": flags,
    }

    // 根字典冻结后，可达的 flags 也进入只读发布阶段。
    globals.Freeze()

    // 这里故意保留错误处理，说明冻结后不能再原地追加。
    if err := flags.Append(starlark.String("late")); err != nil {
        return nil, fmt.Errorf("冻结后的集合不能修改: %w", err)
    }
    return globals, nil
}

生产代码不会真的在成功路径里追加 late；这个片段把错误边界放在眼前，便于检查初始化函数是否误把“发布后的补丁”混进来。真正需要新增值时，重新构造一份新的集合，填充完成后再冻结新根对象。

嵌套值和引用环为什么需要额外小心

嵌套对象让“我只改内部集合”这个想法失效：外层字典持有列表，列表又持有字典时，根对象的冻结会把这条可达链纳入保护范围。对于实现 Value 的自定义类型，官方还特别要求 Freeze 对引用环保持防御性。

实现自定义值时，正确顺序是先检查自己是否已经 frozen，再立刻设置 frozen 标志，最后访问其他引用的值。如果先递归访问子对象、最后才设置标志，环形引用就可能让冻结逻辑无限递归。这个约束属于实现者责任，调用方不能靠重复调用 Freeze 修复。

错误定位：复制、重建还是延后冻结

如果业务确实需要更新配置，不要尝试绕过集合的修改错误。先判断它属于哪一种生命周期：

尤其不要把集合转换成 Go 原生 map 或 slice 后直接暴露给 Starlark，再指望 Freeze() 替你管理这些外部别名。Starlark 值的冻结语义只覆盖实现遵守 Value 契约的对象；外部共享状态仍需要由应用自己设计并发边界。

发布前检查：冻结时点是否唯一

可以用一份小清单收尾：所有默认值是否已经填完；嵌套集合是否还被其他初始化代码持有；冻结调用是否发生在交给解释器之前；修改方法的 error 是否被处理；需要更新时是否生成了新快照；自定义值是否先标记自身再遍历引用。

一句话总结：Go Starlark 的 Freeze 是“构造完成后发布不可变快照”的生命周期动作，不是临时暂停某一次写入。先完成构造，再冻结根对象；需要变更时构造新对象，才能同时满足可更新配置和并发只读执行。

常见问题：Freeze 与集合修改

Freeze 会不会复制集合？

不会。它是在现有值上标记冻结状态，后续通过 Starlark API 的修改会失败。

只冻结 List，里面的 Dict 也安全吗？

冻结语义沿集合和闭包的可达关系传播，但自定义值是否正确实现 Freeze 仍取决于它自己的实现。不要把第三方自定义值当作自动安全。

冻结后想改一个字段怎么办？

不要原地修改已发布快照；创建新集合或新根字典，完成填充后重新 Freeze，再把新快照交给后续解释器。