context:取消、逾時與資料傳遞
Go context: Cancellation, Timeouts and Request-Scoped Values
說明 context 如何形成一棵取消樹,怎麼用 WithCancel、WithTimeout 把取消與逾時從 HTTP 處理器傳到每個 goroutine 與下游,並介紹 WithCancelCause、AfterFunc、WithoutCancel 與 WithValue 的正確用法。
這篇的步驟
上一篇〈Goroutine、Channel 與並發模式〉我們讓訂單服務能並發查價、用 worker pool 處理大量工作,也用號誌限制並發數並以 errors.Join 收集錯誤;但當時留下一個缺口:沒有標準方式通知其他 goroutine「不用做了」,也無法替整條呼叫鏈設定時間上限。這篇接著用 context 補上這塊,它也是之後所有 HTTP、資料庫、gRPC 篇章都會出現在第一個參數的東西。
這篇要解決什麼
想像使用者在結帳頁按下「送出訂單」。訂單服務收到請求後要查價、檢查庫存、呼叫付款服務,每一步又可能在背後開幾個 goroutine 或發出資料庫查詢。這時候可能發生幾種狀況:
- 使用者等不及,關掉了分頁。連線斷了,但伺服器還在認真查庫存、呼叫付款,白白消耗資源。
- 付款服務變慢,一個請求卡了三十秒。上游的閘道早在五秒時就放棄了,訂單服務卻還在等。
- 並發保留三個品項的庫存,第一個就失敗了,另外兩個還在跑,最後還得一個一個回滾。
- 想在每一行日誌帶上請求 ID,但不想讓每個函式的參數都多一個
requestID string。
這四個問題的共同點是:它們都跟「一個請求的生命週期」有關。context.Context 就是 Go 用來表達請求生命週期的標準介面,它攜帶三樣東西:取消訊號、截止時間、請求範圍的值。標準函式庫裡所有可能阻塞的 API(net/http、database/sql、net.Dialer、os/exec)都接受 context,所以只要你把它一路往下傳,取消與逾時就能自動傳遞到每個角落。
這篇會從 context 的介面講起,依序介紹取消樹、逾時、取消原因、AfterFunc、值的傳遞,最後是「請求結束後仍要繼續的背景工作」該怎麼處理。
第 1 步:認識 Context 介面與基本規則
context.Context 是一個只有四個方法的介面:
| 方法 | 回傳 | 用途 |
|---|---|---|
Done() | <-chan struct{} | 被取消或逾時時會被關閉的 channel,用在 select 中 |
Err() | error | 尚未結束時為 nil;結束後是 context.Canceled 或 context.DeadlineExceeded |
Deadline() | time.Time, bool | 若有截止時間,回傳它與 true |
Value(key) | any | 取出請求範圍的值,找不到時回傳 nil |
Done() 就是上一篇自製 done channel 的標準化版本:被關閉時,所有等待它的 goroutine 會同時被喚醒。差別在於 context 可以一層一層衍生,形成一棵樹,取消會從上往下傳遞。
使用 context 有幾條社群普遍遵守的規則,標準函式庫與大部分程式庫都依此設計:
- context 是函式的第一個參數,名稱叫
ctx:func (s *Service) Create(ctx context.Context, o Order) error。 - 不要把 context 存在結構欄位裡,而是每次呼叫時傳入。context 代表的是「這一次呼叫」的生命週期,存在結構中會讓它活得比請求還久。
- 不要傳
nilcontext。不知道該用什麼時,用context.TODO()標記「之後要補」;真正的根節點用context.Background(),通常只出現在main、初始化與測試中。 - context 是不可變的。所有
With...函式都回傳一個新的子 context,不會改動父 context,所以同一個 context 可以安全地被多個 goroutine 同時使用。
在 HTTP 伺服器中,你幾乎不需要自己建立根 context:r.Context() 已經是 net/http 為每個請求建立好的 context,客戶端斷線或 HTTP/2 串流被重設時,它會被自動取消。
第 2 步:WithCancel 與取消樹
context.WithCancel(parent) 回傳一個子 context 和一個 cancel 函式。呼叫 cancel() 會取消這個子 context 以及它衍生出的所有後代;父 context 被取消時,子 context 也會跟著被取消。反過來則不成立:取消子節點不會影響父節點與兄弟節點。
圖:取消「保留庫存」節點時,它底下的三個品項查詢一起結束;「查價」與根節點不受影響。根節點被取消時,整棵樹都會結束。
下面的程式建立一棵小樹,觀察取消如何往下傳遞。注意每個長時間執行的 goroutine 都用 select 同時監聽 ctx.Done(),這是讓 goroutine「可被取消」的唯一方式:context 只是發出訊號,goroutine 必須主動檢查並自己結束。
package main
import (
"context"
"fmt"
"sync"
"time"
)
// work 模擬一個會定期檢查取消訊號的長時間工作。
func work(ctx context.Context, name string, wg *sync.WaitGroup) {
defer wg.Done()
ticker := time.NewTicker(50 * time.Millisecond)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
fmt.Printf("%-10s stopped: %v\n", name, ctx.Err())
return
case <-ticker.C:
// 做一小段工作
}
}
}
func main() {
root, cancelRoot := context.WithCancel(context.Background())
defer cancelRoot()
pricing, cancelPricing := context.WithCancel(root)
defer cancelPricing()
stock, cancelStock := context.WithCancel(root)
var wg sync.WaitGroup
wg.Add(4)
go work(pricing, "pricing", &wg)
go work(stock, "stock-a", &wg)
go work(stock, "stock-b", &wg)
go work(root, "root-job", &wg)
time.Sleep(120 * time.Millisecond)
fmt.Println("-- cancel stock subtree")
cancelStock() // 只有 stock-a、stock-b 停止
time.Sleep(120 * time.Millisecond)
fmt.Println("-- cancel root")
cancelRoot() // 其餘的全部停止
wg.Wait()
}為什麼一定要呼叫 cancel
WithCancel、WithTimeout、WithDeadline 回傳的 cancel 一定要呼叫,即使工作已經正常完成。子 context 會把自己登記在父 context 底下,以便父節點取消時能通知它;不呼叫 cancel,這個登記與相關的計時器就要等到父節點結束才會被釋放。如果父節點是長壽的(例如服務層級的 context),每個請求都會留下一點殘骸,累積成記憶體洩漏。慣例是取得後立刻 defer cancel(),go vet 的 lostcancel 檢查也會抓出忘記呼叫的情況。重複呼叫 cancel 是安全的,第二次之後什麼都不做。
第 3 步:WithTimeout、WithDeadline 與逾時預算
context.WithTimeout(parent, d) 等於 WithDeadline(parent, time.Now().Add(d)):到了截止時間,context 會自動被取消,Err() 回傳 context.DeadlineExceeded。關鍵特性是:子 context 的截止時間不會晚於父 context。如果父節點只剩 2 秒,你對子節點設 5 秒的逾時,實際生效的仍然是 2 秒。
這讓「逾時預算」可以自然地沿著呼叫鏈傳遞。閘道對整個請求設 3 秒,訂單服務收到時已經用掉一些,剩下的時間會隨著 context 傳下去;訂單服務呼叫付款服務時,可以再設一個更短的上限,確保自己有時間處理失敗並回應,而不是和上游同時逾時。
圖:閘道給 3 秒;訂單服務對付款呼叫另設 1 秒上限,對資料庫查詢設 500 毫秒;任何一層到期,底下的呼叫都會被取消。
在程式中,只要把 context 傳給接受它的 API,逾時就會生效:
// 片段:在訂單服務中把 context 傳給資料庫與下游 HTTP 呼叫
func (s *Service) Create(ctx context.Context, o Order) error {
// 資料庫查詢最多 500ms,但不會超過請求本身剩下的時間。
dbCtx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)
defer cancel()
if err := s.repo.Insert(dbCtx, o); err != nil { // 內部用 db.ExecContext(dbCtx, ...)
return fmt.Errorf("create order %s: %w", o.ID, err)
}
// 呼叫付款服務最多 1 秒。
payCtx, cancelPay := context.WithTimeout(ctx, time.Second)
defer cancelPay()
req, err := http.NewRequestWithContext(payCtx, http.MethodPost, s.paymentURL, body(o))
if err != nil {
return err
}
resp, err := s.client.Do(req)
if errors.Is(err, context.DeadlineExceeded) {
return fmt.Errorf("charge order %s: payment timeout: %w", o.ID, err)
}
if err != nil {
return fmt.Errorf("charge order %s: %w", o.ID, err)
}
defer resp.Body.Close()
// ...
return nil
}判斷是誰造成的逾時
context.Canceled 與 context.DeadlineExceeded 都是上一篇介紹的哨兵錯誤,用 errors.Is 判斷。實務上它們的意義差很多:Canceled 通常代表呼叫端放棄了(客戶端斷線),不是服務本身的問題,記成 Info 即可,也不需要回應(對方已經收不到);DeadlineExceeded 則代表某處太慢,值得記錄與監控。在〈錯誤處理:包裝、哨兵、自訂型別〉的邊界轉換函式中,常見做法是把前者對應到 499(客戶端關閉請求,非標準但廣泛使用的狀態碼),後者對應到 504。
提示:逾時應該設在「最接近 I/O 的地方」與「整個請求的入口」兩處。只在入口設,下游一個慢呼叫就會吃光整個預算;只在 I/O 設,多個呼叫加總起來仍可能超過上游能等的時間。如何為每一層挑選數值,以及和重試的關係,在〈逾時、重試與熔斷〉會深入討論。
第 4 步:用 WithCancelCause 說明為什麼取消
ctx.Err() 只能告訴你「被取消了」或「逾時了」,卻不知道為什麼。在並發保留庫存的例子中,第一個品項庫存不足導致其他工作被取消,其他 goroutine 只看到 context canceled,日誌裡就失去了真正的原因。
Go 1.20 加入了 context.WithCancelCause:它的 cancel 函式接受一個 error 參數,之後任何人都可以用 context.Cause(ctx) 取回這個原因,而 ctx.Err() 仍然維持回傳 context.Canceled,不破壞既有的判斷邏輯。Go 1.21 再加入 WithTimeoutCause 與 WithDeadlineCause,可以為逾時指定原因。
把上一篇的「並發保留庫存」改寫成「第一個失敗就取消其他人,並保留原因」:
package main
import (
"context"
"errors"
"fmt"
"sync"
"time"
)
var ErrInsufficientStock = errors.New("inventory: insufficient stock")
// reserve 模擬呼叫庫存服務;會尊重 ctx 的取消。
func reserve(ctx context.Context, sku string, d time.Duration) error {
select {
case <-ctx.Done():
return fmt.Errorf("reserve %s: %w", sku, context.Cause(ctx))
case <-time.After(d):
}
if sku == "sold-out" {
return fmt.Errorf("reserve %s: %w", sku, ErrInsufficientStock)
}
return nil
}
// reserveAll 並發保留所有品項;第一個錯誤會取消其他工作,並以它作為取消原因。
func reserveAll(ctx context.Context, skus map[string]time.Duration) error {
ctx, cancel := context.WithCancelCause(ctx)
defer cancel(nil)
var (
wg sync.WaitGroup
once sync.Once
firstErr error
)
for sku, d := range skus {
wg.Go(func() {
if err := reserve(ctx, sku, d); err != nil {
once.Do(func() {
firstErr = err
cancel(err) // 原因會透過 context.Cause 傳給其他 goroutine
})
}
})
}
wg.Wait()
return firstErr
}
func main() {
// 整個操作最多 1 秒;逾時時的原因也可以自訂。
ctx, cancel := context.WithTimeoutCause(context.Background(), time.Second,
errors.New("checkout: reservation budget exceeded"))
defer cancel()
err := reserveAll(ctx, map[string]time.Duration{
"book": 300 * time.Millisecond,
"sold-out": 50 * time.Millisecond, // 很快就失敗
"lamp": 400 * time.Millisecond,
})
fmt.Println("result:", err)
fmt.Println("is insufficient stock:", errors.Is(err, ErrInsufficientStock))
}這段程式約 50 毫秒就會返回,而不是等最慢的 400 毫秒;被取消的 goroutine 回傳的錯誤會包著真正的原因(庫存不足),而不只是 context canceled。這正是 golang.org/x/sync/errgroup 的 WithContext 在做的事:它內部也使用 WithCancelCause,所以用 errgroup 時同樣可以透過 context.Cause 取得第一個錯誤。
第 5 步:AfterFunc:取消時執行清理
有些阻塞的操作不接受 context,例如舊式的網路協定程式庫、sync.Cond.Wait,或某個只提供 Close() 來中斷的連線。過去常見的寫法是另外開一個 goroutine 等 <-ctx.Done(),然後呼叫 Close(),但這個 goroutine 很容易在操作正常完成後忘記結束,變成洩漏。
Go 1.21 加入的 context.AfterFunc(ctx, f) 把這件事標準化:在 ctx 結束之後,於一個新的 goroutine 中執行 f;它回傳一個 stop 函式,在 f 還沒開始執行前呼叫 stop() 可以取消這個登記,並回傳 true 表示成功阻止。
// 片段:讓不支援 context 的讀取可以被取消
func readWithContext(ctx context.Context, conn net.Conn, buf []byte) (int, error) {
// ctx 結束時,把讀取期限設為過去,讓阻塞中的 Read 立即返回。
stop := context.AfterFunc(ctx, func() {
conn.SetReadDeadline(time.Unix(1, 0))
})
n, err := conn.Read(buf)
if !stop() {
// stop 回傳 false:AfterFunc 已經觸發(或正在執行),Read 是被我們中斷的。
return n, context.Cause(ctx)
}
return n, err
}AfterFunc 也常用來把「取消」轉接到其他通知機制,例如喚醒正在 sync.Cond 上等待的 goroutine,或在請求取消時從某個等待佇列中移除自己。它不會阻塞呼叫者,也不需要你自己管理那個 goroutine 的生命週期。
第 6 步:WithValue:只放請求範圍的資料
context.WithValue(parent, key, val) 讓你在 context 上附加一個值,ctx.Value(key) 會從目前節點往父節點一路找,找到第一個符合的 key 就回傳。
圖:處理器呼叫 ctx.Value(requestIDKey) 時,從最內層的逾時節點開始往上找,在中介層加入的節點找到請求 ID。
這個機制很方便,也很容易被濫用。判斷一個值該不該放進 context,可以用這張表:
| 適合放進 context | 不適合放進 context |
|---|---|
| 請求 ID、追蹤(trace)資訊 | 資料庫連線池、logger 實例、設定(應用依賴注入傳入) |
| 已驗證的使用者身分、租戶 | 函式的必要參數(例如要查詢的訂單 ID) |
| 請求的語系、來源 IP 等中介層解析出的資訊 | 可選參數、功能開關(讓函式簽章說謊) |
| 跨越 API 邊界、與請求生命週期一致的資料 | 會被修改的可變狀態 |
原則是:拿掉這個值,函式仍然應該能正確運作(只是少了一些日誌或追蹤資訊)。如果拿掉之後函式就無法運作,它就是必要的參數,應該寫在函式簽章上,讓編譯器幫你檢查。資料庫連線池這類依賴,應該透過建構函式傳進結構,這在〈分層架構與依賴注入〉會詳細說明。
key 要用未匯出的自訂型別
WithValue 用 == 比較 key。如果用字串 "requestID" 當 key,任何套件都可能用到同樣的字串,互相覆蓋。慣例是在套件內定義一個未匯出的型別當 key,並提供匯出的存取函式,這樣只有這個套件能讀寫這個值,型別也有保證。下一步的完整程式示範了這個寫法。
第 7 步:WithoutCancel:請求結束後還要繼續的工作
有時候請求處理完之後,還有一些工作要做,但不應該讓客戶端等:寫一筆稽核紀錄、送出「訂單已建立」的通知。如果直接用 r.Context() 啟動背景 goroutine,處理器一返回,這個 context 就被取消,背景工作會跟著失敗;如果改用 context.Background(),又會失去請求 ID 等值,日誌就對不起來。
Go 1.21 加入的 context.WithoutCancel(ctx) 解決的正是這個問題:它回傳的 context 保留父節點的所有值,但不會隨父節點取消,也沒有截止時間。要注意,脫離取消之後,這個工作就沒有任何時間上限了,所以通常會再包一層自己的逾時。
下面的完整程式把第 6、7 步串起來:中介層把請求 ID 放進 context,處理器與 slog 日誌讀出它,並在回應後以 WithoutCancel 加上自己的逾時寫稽核紀錄。
package main
import (
"context"
"fmt"
"log/slog"
"net/http"
"net/http/httptest"
"os"
"sync"
"time"
)
// ctxKey 是未匯出的型別,其他套件無法建立相同的 key。
type ctxKey int
const requestIDKey ctxKey = iota
func WithRequestID(ctx context.Context, id string) context.Context {
return context.WithValue(ctx, requestIDKey, id)
}
func RequestID(ctx context.Context) string {
id, _ := ctx.Value(requestIDKey).(string)
return id // 沒有時回傳空字串,呼叫端仍能正常運作
}
// requestIDMiddleware 是中介層:從標頭取得或產生請求 ID,放進 context。
func requestIDMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := r.Header.Get("X-Request-ID")
if id == "" {
id = fmt.Sprintf("req-%d", time.Now().UnixNano())
}
next.ServeHTTP(w, r.WithContext(WithRequestID(r.Context(), id)))
})
}
type server struct {
log *slog.Logger
bg sync.WaitGroup // 追蹤背景工作,關閉服務時要等它們結束
}
func (s *server) writeAudit(ctx context.Context, orderID string) {
select {
case <-time.After(50 * time.Millisecond): // 模擬寫入稽核資料表
s.log.InfoContext(ctx, "audit written", "request_id", RequestID(ctx), "order_id", orderID)
case <-ctx.Done():
s.log.WarnContext(ctx, "audit aborted", "request_id", RequestID(ctx), "cause", context.Cause(ctx))
}
}
func (s *server) createOrder(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
orderID := "o-1001"
s.log.InfoContext(ctx, "order created", "request_id", RequestID(ctx), "order_id", orderID)
// 背景工作:保留請求 ID 等值,但不隨請求取消;另設 2 秒上限。
bgCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 2*time.Second)
s.bg.Go(func() {
defer cancel()
s.writeAudit(bgCtx, orderID)
})
w.WriteHeader(http.StatusCreated)
fmt.Fprintln(w, orderID)
}
func main() {
s := &server{log: slog.New(slog.NewTextHandler(os.Stdout, nil))}
mux := http.NewServeMux()
mux.HandleFunc("POST /orders", s.createOrder)
h := requestIDMiddleware(mux)
req := httptest.NewRequest(http.MethodPost, "/orders", nil)
req.Header.Set("X-Request-ID", "req-abc")
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req) // 處理器返回後,r.Context() 在真實伺服器中會被取消
fmt.Print("response: ", rec.Code, " ", rec.Body.String())
s.bg.Wait() // 稽核仍會完成,並帶著同一個請求 ID
}幾個要點:
- 中介層用
r.WithContext產生帶有新 context 的請求副本往下傳,這是在 HTTP 處理鏈中附加值的標準做法,〈net/http 與中介層〉會把它擴充成完整的中介層鏈。 slog的InfoContext會把 context 傳給 handler;實務上常寫一個自訂的slog.Handler,自動從 context 取出請求 ID 與追蹤 ID 加到每一行日誌,就不必每次手動帶"request_id"。〈可觀測性:日誌、指標、追蹤〉會實作這個 handler。- 背景工作用
sync.WaitGroup追蹤。服務關閉時要等它們完成或逾時,否則稽核紀錄可能寫到一半就被中斷,這在〈設定與優雅關閉〉會接起來。 - 更可靠的做法是把這類「之後要做」的工作交給訊息佇列,而不是放在程序記憶體中,這是〈訊息佇列與事件驅動〉與〈分散式交易:Saga 與 Outbox〉要處理的問題。
常見陷阱
- 忘記呼叫
cancel:子 context 與計時器要等父節點結束才釋放,長壽的父節點會累積洩漏。取得後立即defer cancel()。 - goroutine 不檢查
ctx.Done():context 只是訊號,不會強制中斷任何東西。長迴圈與阻塞操作都要在select中監聽取消,或使用接受 context 的 API。 - 把 context 存進結構欄位:它的生命週期會和結構綁在一起,取消語意變得混亂。每次呼叫時以第一個參數傳入。
- 在處理器返回後繼續使用
r.Context():背景工作會立即被取消。用context.WithoutCancel並加上自己的逾時。 - 用
context.Background()啟動背景工作:失去請求 ID 與追蹤資訊,日誌對不起來;同時也沒有任何上限。 - 用字串或內建型別當 Value 的 key:不同套件可能互相覆蓋。用未匯出的自訂型別,並提供存取函式。
- 把依賴或必要參數塞進 context:函式簽章不再誠實,編譯器也無法幫你檢查。只放「拿掉也能運作」的請求範圍資料。
- 把
Canceled當成伺服器錯誤告警:客戶端放棄是常態,不該觸發告警;DeadlineExceeded才值得關注。用errors.Is區分兩者。 - 子節點設了比父節點更長的逾時,以為會生效:截止時間只會變短不會變長。需要更長時間的工作,應該脫離請求的生命週期(
WithoutCancel或訊息佇列)。
重點整理
context.Context攜帶取消訊號、截止時間與請求範圍的值;它是函式的第一個參數ctx,不存進結構,也不傳nil。With...函式衍生出子 context,形成取消樹:取消會往下傳遞,不會往上或往兄弟節點傳遞;回傳的cancel一定要呼叫。WithTimeout/WithDeadline讓逾時預算沿呼叫鏈傳遞,子節點的截止時間不會晚於父節點;用errors.Is區分Canceled與DeadlineExceeded。WithCancelCause、WithTimeoutCause與context.Cause保留取消的真正原因,適合「第一個錯誤取消其他工作」的情境,errgroup 內部也用它。AfterFunc在 context 結束時執行清理,讓不支援 context 的阻塞操作也能被取消,並以stop取消登記。WithValue只放請求範圍、拿掉也能運作的資料,key 用未匯出的自訂型別並提供存取函式。WithoutCancel讓背景工作保留值但脫離請求的取消,記得自己加上逾時並在關閉時等待它們。
下一篇
到這裡,一、Go 地基的四塊都齊了:模組與目錄、錯誤、並發、context。但訂單服務還沒有真正對外提供 HTTP API。下一篇〈net/http 與中介層〉會用標準函式庫的路由與中介層,把這四篇的內容組裝成一個能處理請求、記錄日誌、統一轉換錯誤的訂單 API。