This resume is also available in English.

一、Go 地基第 4 / 4 篇 · 全部目錄

專欄 › 一、Go 地基 › 第 4 篇

context:取消、逾時與資料傳遞

Go context: Cancellation, Timeouts and Request-Scoped Values

說明 context 如何形成一棵取消樹,怎麼用 WithCancel、WithTimeout 把取消與逾時從 HTTP 處理器傳到每個 goroutine 與下游,並介紹 WithCancelCause、AfterFunc、WithoutCancel 與 WithValue 的正確用法。

  • Go
  • Context
  • Concurrency
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:認識 Context 介面與基本規則
  3. 第 2 步:WithCancel 與取消樹
  4. 第 3 步:WithTimeout、WithDeadline 與逾時預算
  5. 第 4 步:用 WithCancelCause 說明為什麼取消
  6. 第 5 步:AfterFunc:取消時執行清理
  7. 第 6 步:WithValue:只放請求範圍的資料
  8. 第 7 步:WithoutCancel:請求結束後還要繼續的工作
  9. 常見陷阱
  10. 重點整理
  11. 下一篇

上一篇〈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 有幾條社群普遍遵守的規則,標準函式庫與大部分程式庫都依此設計:

  1. context 是函式的第一個參數,名稱叫 ctx:func (s *Service) Create(ctx context.Context, o Order) error。
  2. 不要把 context 存在結構欄位裡,而是每次呼叫時傳入。context 代表的是「這一次呼叫」的生命週期,存在結構中會讓它活得比請求還久。
  3. 不要傳 nil context。不知道該用什麼時,用 context.TODO() 標記「之後要補」;真正的根節點用 context.Background(),通常只出現在 main、初始化與測試中。
  4. 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 也會跟著被取消。反過來則不成立:取消子節點不會影響父節點與兄弟節點。

r.Context() 請求的根節點 查價 WithTimeout 保留庫存 cancel() 在這裡 book pen lamp 後代全部收到 Done() 兄弟節點不受影響 取消只往下傳;根節點被取消時,整棵樹一起結束

圖:取消「保留庫存」節點時,它底下的三個品項查詢一起結束;「查價」與根節點不受影響。根節點被取消時,整棵樹都會結束。

下面的程式建立一棵小樹,觀察取消如何往下傳遞。注意每個長時間執行的 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 傳下去;訂單服務呼叫付款服務時,可以再設一個更短的上限,確保自己有時間處理失敗並回應,而不是和上游同時逾時。

0 秒 3 秒 api-gateway WithTimeout(3s):整個請求的預算 order r.Context():繼承剩餘時間 資料庫 500ms payment WithTimeout(1s) 失敗後仍有時間 回應上游 子節點的截止時間只會更早,不會晚於父節點

圖:閘道給 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 就回傳。

Background 伺服器根節點 WithValue requestID=req-abc WithValue userID=u-1 WithTimeout 處理器拿到的 ctx 每個節點只記得自己的父節點 ctx.Value(requestIDKey):由內往外找,第一個相符就停 找不到時回傳 nil;查找成本與鏈長成正比,不適合放大量資料

圖:處理器呼叫 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。