Go Starlark 的列表为什么不能直接当字典键

在 Go 项目里接入 Starlark 后，下面这种写法很容易让人困惑：列表明明可以比较、可以打印，也可以放进变量，为什么一旦作为字典键传给 SetKey 就失败？答案是 Starlark 字典依赖的是键的哈希契约，而不是“这个值能不能放进 Go 变量”。Go Starlark 的 starlark.List.Hash() 明确返回不可哈希错误，所以列表不能直接当字典键。

官方资料：https://pkg.go.dev/go.starlark.net/starlark

把列表当作“值”保存没有问题；把列表当作“身份”使用就需要先改成可哈希的稳定表示。固定结构用 starlark.Tuple，开放结构通常用规范化字符串或业务 ID。

先用最小代码复现错误

先不要从 Go 原生 map 的规则推断 Starlark。直接创建一个 starlark.Dict，把列表传给 SetKey，就能看到错误发生在字典写入边界：

package main

import (
    "fmt"

    "go.starlark.net/starlark"
)

func main() {
    // 列表适合作为可变值，但不作为字典键表达身份。
    key := starlark.NewList([]starlark.Value{
        starlark.String("go"),
        starlark.MakeInt(1),
    })
    dict := starlark.NewDict(0)

    // SetKey 需要键能够提供稳定的 Hash 结果。
    err := dict.SetKey(key, starlark.String("配置"))
    fmt.Println(err)
}

unhashable type: list

这里的错误不是 NewList 创建失败，也不是字典值类型不对，而是 SetKey 无法为列表取得合法哈希。这个区分很重要：修复方向应该围绕“键的表示”展开，而不是给列表再包一层指针。

SetKey 为什么会关心 Hash

Starlark 的 Value 接口把 Hash() (uint32, error) 作为字典键所需的能力之一。字典需要用键建立稳定的查找关系，因此遇到无法提供哈希的值时，必须返回错误，而不是悄悄把列表内容转成字符串。

列表的问题在于它是可变容器：调用方可以追加、删除或替换元素。如果一个列表已经作为键存入字典，之后又改变了内容，那么“它应该落在哪个桶里”与“它当前看起来是什么内容”可能不一致。禁止列表作为键，能避免这种身份漂移。

Go Starlark 的实现更直接：*starlark.List 的 Hash 方法返回 unhashable type: list。因此，给列表调用 Freeze 主要是限制后续修改，并不等于把这个 Go 实现里的列表自动变成可用字典键。不要把“不可变”与“实现已经提供哈希”当成同一个条件。

固定结构的复合键改用 Tuple

如果列表只是为了把几个字段组合起来，例如“环境 + 版本”或“租户 + 资源名”，可以使用 starlark.Tuple。元组表达的是固定结构，字典键的语义也更清楚：

package main

import (
    "fmt"

    "go.starlark.net/starlark"
)

func main() {
    // 元组表示固定位置的复合键；其中每个元素都必须可哈希。
    key := starlark.Tuple{
        starlark.String("prod"),
        starlark.String("api"),
    }
    dict := starlark.NewDict(1)

    // 使用元组作为键，保留字段边界而不引入可变列表。
    if err := dict.SetKey(key, starlark.String("enabled")); err != nil {
        // 把错误留在调用边界，避免把失败伪装成空值。
        panic(err)
    }
    value, found, err := dict.Get(key)
    fmt.Println(value, found, err)
}

元组不是“任何元素都能装”的逃生通道。如果元组内部又放入列表、字典或其他不可哈希值，最终仍然会在哈希阶段失败。判断标准是递归的：元组本身要稳定，里面的每个元素也要能提供稳定哈希。

开放结构不要硬塞进复合键

当键来自用户配置、可选字段或数量不固定的列表时，直接把整个列表转换成元组可能会掩盖更大的设计问题：你到底想表达“这组字段的内容”，还是想表达“这个对象的业务身份”？先把键语义说清楚，再选择表示方式。

• 需要按固定字段组合查找时，用元组，并明确字段顺序。
• 需要跨进程、跨存储或跨语言复用时，用有明确规范的字符串；分隔符、转义和大小写规则要固定。
• 对象已有稳定身份时，优先使用业务 ID，而不是把全部可变属性拼进键。

package main

import "go.starlark.net/starlark"

func makeKeys() (*starlark.Dict, error) {
    dict := starlark.NewDict(2)

    // 固定结构键适合用 Tuple，字段顺序就是键协议的一部分。
    tupleKey := starlark.Tuple{
        starlark.String("tenant-a"),
        starlark.String("worker"),
    }
    if err := dict.SetKey(tupleKey, starlark.String("tuple-key")); err != nil {
        return nil, err
    }

    // 开放结构键先按约定规范化，再使用稳定字符串。
    stringKey := starlark.String("tenant-a|worker|v1")
    if err := dict.SetKey(stringKey, starlark.String("string-key")); err != nil {
        return nil, err
    }
    return dict, nil
}

字符串方案的关键不是“把列表打印一下”，而是定义稳定的序列化规则。若元素中可能出现分隔符、空值、不同类型或不同顺序的数据，应该使用明确的编码格式，或者回到业务 ID，避免两个不同对象被拼成同一个键。

几个容易误判的边界

第一，列表能不能放进字典值？可以。键和值经过的是不同路径，列表作为值保存并不会触发键的哈希要求。

第二，换成 Go 指针能不能绕过限制？不应该这样做。指针地址表达的是 Go 对象身份，不是 Starlark 数据语义，而且地址通常不能跨解释器、跨进程或跨持久化场景稳定复用。

第三，冻结后能不能直接当键？要看具体实现的哈希契约。Go Starlark 当前的 List.Hash 仍然返回不可哈希错误，因此冻结只能解决部分并发发布和修改边界，不能替代键类型设计。

第四，元组是否永远安全？不是。元组中的元素如果仍然不可哈希，字典写入仍会失败。把复合键构造集中在一个函数里，可以让类型检查、规范化和错误处理保持一致。

把排查结论落成一张键设计清单

遇到 unhashable type: list 时，可以按下面顺序处理：

1. 确认报错发生在 Dict.SetKey 或字典字面量，而不是列表创建。
2. 检查键是否承担了“可变数据值”和“稳定身份”两种职责。
3. 固定字段组合用 starlark.Tuple，同时检查每个元素的哈希能力。
4. 开放结构用规范化字符串或业务 ID，并写清排序、转义、大小写和版本规则。
5. 把键构造与字典写入放在同一层处理错误，避免失败后继续使用一个未写入的假设。

最终原则很简单：列表是适合表达内容的可变容器，字典键是需要稳定身份的索引。只要先分清这两个角色，Go Starlark 的列表不能直接当字典键就不再是一个令人意外的限制。

相关问题

starlark.Dict 的值可以是列表吗？

可以，列表作为值不需要提供字典键所需的哈希结果。只有把它放到键的位置时，才会触发不可哈希错误。

列表转换成 Tuple 就一定能成功吗？

不一定。转换后的元组元素仍需全部可哈希，嵌套列表或字典仍会使键失败。

什么时候更适合使用业务 ID？

当对象有稳定身份、属性会变化，或键需要跨进程和持久化边界复用时，业务 ID 通常比拼接全部属性更可靠。