Request-scoped context

在 Go 服务中，每个传入的请求都在其自己的goroutine 中处理。请求处理程序通常启动额外的 goroutine 来访问其他后端，如数据库和 RPC服务。处理请求的 goroutine 通常需要访问特定于请求(request-specific context)的值，例如最终用户的身份、授权令牌和请求的截止日期(deadline)。当一个请求被取消或超时时，处理该请求的所有 goroutine 都应该快速退出(fail fast)，这样系统就可以回收它们正在使用的任何资源。

Go 1.7 引入一个 context 包，它使得跨 API 边界的请求范围元数据、取消信号和截止日期很容易传递给处理请求所涉及的所有 goroutine(显示传递)。

核心接口：

如何将 context 集成到 API 中

在将 context 集成到 API 中时，要记住的最重要的一点是，它的作用域是请求级别 的。例如，沿单个数据库查询存在是有意义的，但沿数据库对象存在则没有意义。

目前有两种方法可以将 context 对象集成到 API 中：

• The first parameter of a function call：首参数传递 context 对象，比如，参考 net 包 Dialer.DialContext。此函数执行正常的 Dial 操作，但可以通过 context 对象取消函数调用。
• Optional config on a request structure：在第一个 request 对象中携带一个可选的 context 对象。例如 net/http 库的 Request.WithContext，通过携带给定的 context 对象，返回一个新的 Request 对象。

Do not store Contexts inside a struct type

使用 context 的一个很好的心智模型是它应该在程序中流动，应该贯穿你的代码。这通常意味着您不希望将其存储在结构体之中。它从一个函数传递到另一个函数，并根据需要进行扩展。理想情况下，每个请求都会创建一个 context 对象，并在请求结束时过期。

不存储上下文的一个例外是，当您需要将它放入一个结构中时，该结构纯粹用作通过通道传递的消息。如下例所示。

type message struct {
	responseChan chan<- int
	parameter string
	ctx context.Context
}

context.WithValue

context.WithValue 内部基于 valueCtx 实现：

type valueCtx struct {
	Context
	key, val interface{}
}

为了实现不断的 WithValue，构建新的 context，内部在查找 key 时候，使用递归方式不断从当前，从父节点寻找匹配的 key，直到 root context(Backgrond 和 TODO Value 函数会返回 nil)。

func (c *valueCtx) Value(key interface{}) interface{} {
	if c.key == key {
		return v.val
	}
	return c.Context.Value(key)
}

Debugging or tracing data is safe to pass in a Context

context.WithValue 方法允许上下文携带请求范围的数据。这些数据必须是安全的，以便多个 goroutine 同时使用。这里的数据，更多是面向请求的元数据，不应该作为函数的可选参数来使用(比如 context 里面挂了一个sql.Tx 对象，传递到 Dao 层使用)，因为元数据相对函数参数更加是隐含的，面向请求的。而参数是更加显示的。

•同一个 context 对象可以传递给在不同 goroutine 中运行的函数；上下文对于多个 goroutine 同时使用是安全的。对于值类型最容易犯错的地方，在于 context value 应该是 immutable 的，每次重新赋值应该是新的 context，即: context.WithValue(ctx, oldvalue)

https://pkg.go.dev/google.golang.org/grpc/metadata

Context.Value should inform, not control

func WithValue(parent Context, key, val interface{}) Context {
	if parent == nil {
		panic("cannot create context from nil parent")
	}
	if key = nil {
		panic("nil key")
	}
	if !reflectlite.TypeOf(key).Comparable() {
		panic("key is not comparable")
	}
	return &valueCtx{parent, key, val}
}

type valueCtx struct {
	Context
	key, val interface{}
}

Use context values only for request-scoped data that transits processes and APIs, not for passing optional parameters to functions.

比如 染色，API 重要性，Trace

https://github.com/go-kratos/kratos/blob/master/pkg/net/metadata/key.go

比如我们新建了一个基于 context.Background() 的 ctx1，携带了一个 map 的数据，map 中包含了 “k1”: “v1” 的一个键值对，ctx1 被两个 goroutine 同时使用作为函数签名传入，如果我们修改了 这个map，会导致另外进行读 context.Value 的 goroutine 和修改 map 的 goroutine，在 map 对象上产生 data race。因此我们要使用 copy-on-write 的思路，解决跨多个 goroutine 使用数据、修改数据的场景。

Replace a Context using WithCancel, WithDeadline, WithTimeout, or WithValue.

COW: 从 ctx1 中获取 map1(可以理解为 v1 版本的 map 数据)。构建一个新的 map 对象 map2，复制所有 map1 数据，同时追加新的数据 “k2”: “v2” 键值对，使用 context.WithValue 创建新的 ctx2，ctx2 会传递到其他的 goroutine 中。这样各自读取的副本都是自己的数据，写行为追加的数据，在 ctx2 中也能完整读取到，同时也不会污染 ctx1 中的数据。

The chain of function calls between them must propagate the Context.

When a Context is canceled, all Contexts derived from it are also canceled

当一个 context 被取消时，从它派生的所有 context 也将被取消。WithCancel(ctx) 参数 ctx 认为是 parent ctx，在内部会进行一个传播关系链的关联。Done() 返回 一个 chan，当我们取消某个parent context, 实际上上会递归层层 cancel 掉自己的 child context 的 done chan 从而让整个调用链中所有监听 cancel 的 goroutine退出。

package main

import (
	"context"
	"fmt"
)

func main() {
	gen := func(ctx context.Context) <-chan int {
		dst := make(chan int)
		n := 1
		go func() {
			for {
				select {
				case <- ctx.Done():
					return
				case dst <- n:
					n++
				}
			}
		}()
		return dst
	}

	ctx, cancel := context.WithCancel(context.Backgroud())
	defer cancel()

	for n := range gen(ctx) {
		fmt.PrintIn(n)
		if n==5 {
			break
		}
	}
}

All blocking/long operations should be cancelable

如果要实现一个超时控制，通过上面的context 的parent/child 机制，其实我们只需要启动一个定时器，然后在超时的时候，直接将当前的 context 给 cancel 掉，就可以实现监听在当前和下层的额context.Done() 的 goroutine 的退出。

package main

import (
	"context"
	"fmt"
	"time"
)

const shorDuration = 1 * time.Millisecond

func main() {
	d := time.Now().Add(shorDuration)
	ctx, cancel := context.WithDeadline(context.Backgroud())
	defer cancel()

	select {
	case <- time.After(1* time.Second):
		fmt.PrintIn("overslept")
	case <- ctx.Done():
		fmt.PrintIn(ctx.Err())
	}
}