每天学点 Go 规范 - context 类型的 key 有什么讲究？

现在团队里几乎所有的代码都需要经过 Code Review（代码审查）之后，才允许合入主分支。作为 CR 负责人之一，在 CR 中看到了不少不适合的问题，也看到了不少值得学习的点。笔者决定从今天开始，一点一滴地记录这些做法、经验、教训，以飨读者。

这系列文章，我都会先抛出一句话规范说明，然后解释问题的背景，最后再给出正确的规范。

一句话规范

当使用 context.Context 类型保存 KV 对时, key 不能使用原生类型，而应该使用派生类型

问题背景

我们知道，可以利用 context.Context 类型来存一些自定义的键值对——当然了，需要保存新的 context 对象：

ctx = context.WithValue(ctx, someKey, someValue)

很快就可以注意到 key 的参数类型是 any，也就是 Go 1.17 之前的 interface{}。“可能是为了能够使用 int 吧？” ——初学者很可能会这么想。

在实际的 CR 中，可以看到很多人都使用 string 类型作为 key，比如这是一个非常典型的例子：

ctx = context.WithValue(ctx, "openid", userOpenID)

存在问题

如果你使用了 VSCode，并且一键安装了 Go 开发工具包，那么 VSCode 大概率也安装了 golangci-lint 工具。此时，上面的这段代码会喜提一个 warning：

SA1029: should not use built-in type string as key for value; define your own type to avoid collisions (staticcheck)

告警信息虽然是英文，但很容易理解：

不应该使用内建类型作为 KV 中 key 的类型，而应该使用自定义的类型来避免冲突。

为什么要这么做呢？很简单，现代软件都是团队开发的，多模块相互耦合，互相协作。在一个 ctx 对象的整个生命周期中，它需要经过多个逻辑 / 模块的洗礼，每一个模块都可能使用 ctx 来存储相应信息。

假设 user 模块，它使用 ctx 类型缓存了用户的 openid 字段。这个逻辑没什么问题。然后这个 ctx（和代码逻辑）继续往后走，大家约定，就使用这个 "openid" 来存储。

有一天，来了一个紧急需求，比如说要做一个群聊功能，尽可能复用老代码减少开发。或许 group 模块就利用了 user 模块的代码。好巧不巧，从其他团队过来支援的开发同学，也使用了 "openid" 这个 key，来存储群主的 openid。结果绕了一圈，这位同学发现：咦怎么这群主的 openid 老变成别人的 openid？搁这群主轮流做是吧？

解决方法

可能有人觉得：那我把 key 的定义统一收集起来规定不就行了？解决一个问题总有上中下策，这是个办法，但是一个下下下策。软件工程主打一个分而治之，在没有必要的情况下，尽可能避免集中式的管理。

最上策的解决方法简单而言，就是使用自定义的类型作为 key 的类型。我们看看下面的代码：

type myString string

func main() {
    ctx := context.Background()
    ctx = context.WithValue(ctx, "openid", "不是群主")
    ctx = context.WithValue(ctx, myString("openid"), "群主")

    fmt.Println(ctx.Value("openid"))
    fmt.Println(ctx.Value(myString("openid")))
}

两行输出：

不是群主
群主

这就非常清晰了，尽管底层类型相同（都是 string 类型），但是经过 type 定义之后，Go 是作为完全不同的 key 来处理的。针对具体类型自定义 key 类型之后，很好地解决了同名 key 冲突的问题。

不过呢，如果你并不需要使用同一个 key 类型，存储多个不同 value，那么上面的模式还只能说是中策，真正的上策是这么做的：

type myString struct{}

func main() {
    ctx := context.Background()
    ctx = context.WithValue(ctx, "openid", "不是群主")
    ctx = context.WithValue(ctx, myString{}, "群主")

    fmt.Println(ctx.Value("openid"))
    fmt.Println(ctx.Value(myString{}))
}

我还记得我当年第一次看到这个模式的时候，我就是上图的这个表情。是的，struct{} 类型也可以作为 KV 的 key 类型——当然了，也应该定义为自定义类型。

使用 struct{} 的好处可是大大的多：首先，这个类型在 Go 中原则上是不占内存空间和 gc 开销的，可以提升性能；其次，这少了开发者额外 “写一个 key” 的时间（类型往往可以通过 IDE 快速补全），大大提高了敲代码的速度呀。

典型例子

使用 context WithValue 方法，有一个很典型的例子，就是在 ctx 中存入一个 trace ID，用于跟踪整个调用链。那么，我们可以包装一个 traceid 包，比较规范的写法是这样的：

// Package traceid 用于在 context 中维护 trace ID
package traceid

import "context"

// WithTraceID 往 context 中存入 trace ID
func WithTraceID(ctx context.Context, traceID string) context.Context {
    return context.WithValue(ctx, traceIDKey{}, traceID)
}

// TraceID 从 context 中提取 trace ID
func TraceID(ctx context.Context) string {
    v := context.Value(ctx, traceIDKey{})
    id, _ := v.(string)
    return id
}

type traceIDKey struct{}

本文章采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。

原作者： amc，原文发布于腾讯云开发者社区，也是本人的博客。欢迎转载，但请注明出处。

原作者： amc，欢迎转载，但请注明出处。

原文标题：《每天学点 Go 规范 - context 类型的 key 有什么讲究？》

发布日期：2023-08-16

原文链接：https://cloud.tencent.com/developer/article/2313242。