Go 語言 context 都能做什麼？

很多 Go 項目的源碼，在讀的過程中會發現一個很常見的參數 ctx，而且基本都是作爲函數的第一個參數。

爲什麼要這麼寫呢？這個參數到底有什麼用呢？帶着這樣的疑問，我研究了這個參數背後的故事。

開局一張圖：

核心是 Context 接口：

// A Context carries a deadline, cancelation signal, and request-scoped values
// across API boundaries. Its methods are safe for simultaneous use by multiple
// goroutines.
type Context interface {
    // Done returns a channel that is closed when this Context is canceled
    // or times out.
    Done() <-chan struct{}

    // Err indicates why this context was canceled, after the Done channel
    // is closed.
    Err() error

    // Deadline returns the time when this Context will be canceled, if any.
    Deadline() (deadline time.Time, ok bool)

    // Value returns the value associated with key or nil if none.
    Value(key interface{}) interface{}
}

包含四個方法：

有四個結構體實現了這個接口，分別是：emptyCtx, cancelCtx, timerCtx 和 valueCtx。

其中 emptyCtx 是空類型，暴露了兩個方法：

func Background() Context
func TODO() Context

一般情況下，會使用 Background() 作爲根 ctx，然後在其基礎上再派生出子 ctx。要是不確定使用哪個 ctx，就使用 TODO()。

另外三個也分別暴露了對應的方法：

func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc)
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
func WithValue(parent Context, key, val interface{}) Context

遵循規則

在使用 Context 時，要遵循以下四點規則：

  1. 不要將 Context 放入結構體，而是應該作爲第一個參數傳入，命名爲 ctx。

  2. 即使函數允許，也不要傳入 nil 的 Context。如果不知道用哪種 Context，可以使用 context.TODO()。

  3. 使用 Context 的 Value 相關方法只應該用於在程序和接口中傳遞和請求相關的元數據，不要用它來傳遞一些可選的參數。

  4. 相同的 Context 可以傳遞給不同的 goroutine；Context 是併發安全的。

WithCancel

func WithCancel(parent Context) (ctx Context, cancel CancelFunc)

WithCancel 返回帶有新 Done 通道的父級副本。當調用返回的 cancel 函數或關閉父上下文的 Done 通道時，返回的 ctx 的 Done 通道將關閉。

取消此上下文會釋放與其關聯的資源，因此在此上下文中運行的操作完成後，代碼應立即調用 cancel。

舉個例子：

這段代碼演示瞭如何使用可取消上下文來防止 goroutine 泄漏。在函數結束時，由 gen 啓動的 goroutine 將返回而不會泄漏。

package main

import (
    "context"
    "fmt"
)

func main() {
    // gen generates integers in a separate goroutine and
    // sends them to the returned channel.
    // The callers of gen need to cancel the context once
    // they are done consuming generated integers not to leak
    // the internal goroutine started by gen.
    gen := func(ctx context.Context) <-chan int {
        dst := make(chan int)
        n := 1
        go func() {
            for {
                select {
                case <-ctx.Done():
                    return // returning not to leak the goroutine
                case dst <- n:
                    n++
                }
            }
        }()
        return dst
    }

    ctx, cancel := context.WithCancel(context.Background())
    defer cancel() // cancel when we are finished consuming integers

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

輸出：

1
2
3
4
5

WithDeadline

func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)

WithDeadline 返回父上下文的副本，並將截止日期調整爲不晚於 d。如果父級的截止日期已經早於 d，則 WithDeadline(parent, d) 在語義上等同於 parent。

當截止時間到期、調用返回的取消函數時或當父上下文的 Done 通道關閉時，返回的上下文的 Done 通道將關閉。

取消此上下文會釋放與其關聯的資源，因此在此上下文中運行的操作完成後，代碼應立即調用取消。

舉個例子：

這段代碼傳遞具有截止時間的上下文，來告訴阻塞函數，它應該在到達截止時間時立刻退出。

package main

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

const shortDuration = 1 * time.Millisecond

func main() {
    d := time.Now().Add(shortDuration)
    ctx, cancel := context.WithDeadline(context.Background(), d)

    // Even though ctx will be expired, it is good practice to call its
    // cancellation function in any case. Failure to do so may keep the
    // context and its parent alive longer than necessary.
    defer cancel()

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

輸出：

context deadline exceeded

WithTimeout

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

WithTimeout 返回 WithDeadline(parent, time.Now().Add(timeout))。

取消此上下文會釋放與其關聯的資源，因此在此上下文中運行的操作完成後，代碼應立即調用取消。

舉個例子：

這段代碼傳遞帶有超時的上下文，以告訴阻塞函數應在超時後退出。

package main

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

const shortDuration = 1 * time.Millisecond

func main() {
    // Pass a context with a timeout to tell a blocking function that it
    // should abandon its work after the timeout elapses.
    ctx, cancel := context.WithTimeout(context.Background(), shortDuration)
    defer cancel()

    select {
    case <-time.After(1 * time.Second):
        fmt.Println("overslept")
    case <-ctx.Done():
        fmt.Println(ctx.Err()) // prints "context deadline exceeded"
    }

}

輸出：

context deadline exceeded

WithValue

func WithValue(parent Context, key, val any) Context

WithValue 返回父級的副本，其中與 key 關聯的值爲 val。

其中鍵必須是可比較的，並且不應是字符串類型或任何其他內置類型，以避免使用上下文的包之間發生衝突。 WithValue 的用戶應該定義自己的鍵類型。

爲了避免分配給 interface{}，上下文鍵通常具有具體的 struct{} 類型。或者，導出的上下文鍵變量的靜態類型應該是指針或接口。

舉個例子：

這段代碼演示瞭如何將值傳遞到上下文以及如何檢索它（如果存在）。

package main

import (
    "context"
    "fmt"
)

func main() {
    type favContextKey string

    f := func(ctx context.Context, k favContextKey) {
        if v := ctx.Value(k); v != nil {
            fmt.Println("found value:", v)
            return
        }
        fmt.Println("key not found:", k)
    }

    k := favContextKey("language")
    ctx := context.WithValue(context.Background(), k, "Go")

    f(ctx, k)
    f(ctx, favContextKey("color"))
}

輸出：

found value: Go
key not found: color

本文的大部分內容，包括代碼示例都是翻譯自官方文檔，代碼都是經過驗證可以執行的。如果有不是特別清晰的地方，可以直接去讀官方文檔。

官方文檔：

源碼分析：

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/7IliODEUt3JpEuzL8K_sOg

猜你喜歡