头图

现在团队里几乎所有的代码都需要经过 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)

230816_每天学点Go规范_context_key.01.png

告警信息虽然是英文,但很容易理解:

  • 不应该使用内建类型作为 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


amc
908 声望217 粉丝

电子和互联网深耕多年,拥有丰富的嵌入式和服务器开发经验。现负责腾讯心悦俱乐部后台开发