錯誤處理:包裝、哨兵、自訂型別
Error Handling in Go: Wrapping, Sentinels and Custom Types
從 error 只是一個介面講起,逐步加上 %w 包裝、哨兵錯誤、自訂錯誤型別、errors.Join 與邊界轉換,建立一套在服務裡能判斷、能記錄、也不洩漏內部細節的錯誤處理方式。
這篇的步驟
上一篇〈工程結構與 Go Modules〉我們建立了 example.com/shop 這個模組,排好 cmd/order 與 internal/order 的骨架,也定義了 Order 與 pending、paid、cancelled 三種狀態;這篇接著處理骨架一長出功能就會遇到的問題:失敗的時候怎麼回報、怎麼判斷、怎麼不把內部細節洩漏出去。
這篇要解決什麼
Go 沒有例外(exception),錯誤是函式的一般回傳值。初學者最常見的兩種反應,一種是「到處都是 if err != nil,好囉嗦」,另一種是把錯誤一路 return err 原封不動往上丟,最後在日誌裡看到一行孤零零的 sql: no rows in result set,完全不知道是哪個請求、哪個查詢、哪一層出的事。
在單體程式裡這還能靠除錯器追;到了微服務,一個請求會穿過 HTTP 處理器、業務邏輯、資料庫、下游服務,錯誤處理就變成三個具體問題:
- 能判斷:呼叫端要能分辨「找不到」、「權限不足」、「暫時性失敗可以重試」,並據此走不同的流程。
- 能追查:日誌裡的錯誤訊息要帶著足夠的上下文,看一眼就知道是哪條路徑出錯。
- 能安全對外:回給客戶端的訊息不能洩漏 SQL、內部主機名稱或堆疊。
這篇會用訂單服務「查詢一筆訂單」的情境,從最基本的錯誤值開始,依序加上包裝、哨兵錯誤、自訂型別、多重錯誤,最後在服務邊界把錯誤轉成 HTTP 狀態碼。讀完之後,你會知道在每一層該「處理」、「包裝」還是「原樣傳遞」錯誤,以及該用 errors.Is 還是 errors.As。
第 1 步:error 只是一個介面
Go 的 error 是內建的介面,定義只有一行:type error interface { Error() string }。任何實作了 Error() string 的型別都是錯誤。這個設計帶來幾個重要的觀念:
- 錯誤是值。它可以被存進變數、放進切片、比較、包裝、當成參數傳遞。處理錯誤就是在寫一般的程式邏輯,而不是特殊的控制流程。
nil代表沒有錯誤。慣例是函式的最後一個回傳值是error,成功時回傳nil。呼叫端拿到非nil的錯誤時,其他回傳值通常不可信,除非文件特別說明(例如io.Reader.Read可能同時回傳 n > 0 與io.EOF)。- 錯誤要立刻處理。
if err != nil緊跟在呼叫之後,讀者不需要去猜錯誤會在哪裡被捕捉。
建立錯誤最簡單的方式是 errors.New("訊息") 或 fmt.Errorf("格式", 參數...)。錯誤訊息的慣例是:小寫開頭、不加句號、不換行,因為它常常會被串接在其他訊息後面,例如 load order 42: query: connection refused。
「處理」一個錯誤只有三種選擇,這篇其餘的內容都是在幫你做這個選擇:
| 選擇 | 什麼時候用 | 範例 |
|---|---|---|
| 在這裡處理掉 | 你知道怎麼補救:有預設值、可以重試、可以改走另一條路 | 快取讀取失敗就改查資料庫 |
| 加上上下文後回傳 | 你無法補救,但知道「當時在做什麼」 | fmt.Errorf("load order %s: %w", id, err) |
| 原樣回傳 | 你這層沒有新增任何有用的資訊 | 很薄的轉接函式 |
最不該做的是第四種:記錄日誌之後又回傳。這會讓同一個錯誤在日誌裡出現好幾次,每一層各記一次,反而更難追。原則是:一個錯誤只在最後真正處理它的地方記錄一次。
第 2 步:用 %w 包裝,保留錯誤鏈
假設訂單服務的資料存取層查不到資料時,資料庫驅動回傳 sql.ErrNoRows。如果業務層用 fmt.Errorf("load order: %v", err) 把它變成字串,原本的錯誤就消失了,上層只能用字串比對來判斷,非常脆弱。
Go 1.13 起,fmt.Errorf 支援 %w 動詞:它產生的新錯誤會「包住」原本的錯誤,形成一條錯誤鏈。errors.Unwrap 可以取出下一層,而 errors.Is 與 errors.As 會沿著整條鏈往下找。
圖:處理器與服務層各包一層,最內層是業務層的 ErrNotFound;資料層的 sql.ErrNoRows 在服務層被轉換而不是往上包。訊息由外往內串接,判斷時也由外往內比對。
包裝時要加的上下文,是呼叫端不知道、而你這一層知道的事情:查的是哪一筆、在做哪個步驟。不要重複函式名稱以外沒有資訊量的文字,例如「error occurred」、「failed to」這類詞每一層都加,最後訊息會變成 failed to handle: failed to load: failed to query: ...。比較好的寫法是用動詞片語描述這一層的動作:get order 42: query orders: connection refused。
%w 與 %v 的選擇
用 %w 等於把內層錯誤變成你的 API 的一部分:呼叫端可以 errors.Is(err, sql.ErrNoRows),之後你就不能把資料庫換成別的東西而不影響他們。因此常見的原則是:
- 套件內部的層與層之間,用
%w保留完整的鏈,方便判斷與除錯。 - 跨越抽象邊界時(例如資料存取層要對業務層隱藏「底層是 SQL」這件事),把底層錯誤轉成自己定義的錯誤(下一步的哨兵錯誤),或用
%v只保留訊息、切斷鏈。
一次包多個錯誤
Go 1.20 起,fmt.Errorf 可以有多個 %w,errors.Join 也可以把多個錯誤合成一個。這時錯誤鏈不再是一條線,而是一棵樹,errors.Is / errors.As 會用深度優先走訪整棵樹。第 5 步會實際用到。
第 3 步:哨兵錯誤與 errors.Is
「哨兵錯誤」(sentinel error)是在套件層級宣告、可以被比較的錯誤值。標準函式庫裡到處都是:io.EOF、sql.ErrNoRows、os.ErrNotExist、context.Canceled。它們用來表達「某種可預期的狀況」,讓呼叫端可以依此分支。
訂單服務的業務層可以宣告自己的哨兵錯誤,把資料存取層的細節轉成業務語意:
// 片段:internal/order/service.go 的開頭
package order
import "errors"
var (
ErrNotFound = errors.New("order: not found")
ErrAlreadyPaid = errors.New("order: already paid")
ErrInvalidAmount = errors.New("order: invalid amount")
)判斷時一律用 errors.Is(err, order.ErrNotFound),而不是 err == order.ErrNotFound。原因是錯誤一旦被任何一層用 %w 包裝過,== 就不成立了,而 errors.Is 會沿著鏈逐層比對(如果某層實作了 Is(error) bool 方法,也會呼叫它)。
哨兵錯誤的優點是簡單、比較便宜;缺點是它只能攜帶固定的訊息,沒辦法告訴你「哪一筆訂單找不到」。這個資訊應該由包裝它的那一層用 %w 補上:fmt.Errorf("get order %s: %w", id, ErrNotFound)。
狀態轉換錯誤也是哨兵的好用途
訂單有 pending、paid、cancelled 三種狀態,並不是任意兩種之間都能轉換:已取消的訂單不能付款,已付款的訂單不能再付一次。這類「狀態不允許這個操作」的錯誤非常適合用哨兵表達,例如 ErrAlreadyPaid。呼叫端看到它時,可以回應「訂單已付款」而不是當成系統錯誤;到了後面處理重複請求與冪等的時候,ErrAlreadyPaid 甚至可以被視為「操作其實已經成功」,直接回傳原本的結果。這也說明了為什麼哨兵錯誤的命名要描述「狀況」而不是「出錯的地方」:同一個狀況在不同呼叫端可能有完全不同的處理方式,錯誤本身不應該替呼叫端決定該怎麼辦。
提示:哨兵錯誤一旦匯出,就是套件 API 的一部分,改名或刪除都會破壞呼叫端。只匯出呼叫端真的需要分辨的狀況;如果只是想讓訊息比較清楚,用
fmt.Errorf就夠了。
第 4 步:自訂錯誤型別與 errors.As
當錯誤需要攜帶結構化資料時,哨兵錯誤就不夠了。例如驗證失敗時,呼叫端想知道是哪個欄位、什麼原因,才能回給前端對應的提示;呼叫下游服務失敗時,想知道 HTTP 狀態碼與是否可以重試。這時就定義一個實作 error 介面的型別。
取出自訂型別要用 errors.As:它沿著錯誤鏈找第一個「可以指派給目標型別」的錯誤,找到就填進目標並回傳 true。Go 1.26 起還有泛型版本 errors.AsType,不需要先宣告一個變數,寫起來更直接。
下面是一個完整的範例,把前三步串起來:資料層回傳底層錯誤,業務層轉成哨兵錯誤或自訂型別並包上上下文,最上層用 errors.Is 與 errors.As 判斷。
package main
import (
"errors"
"fmt"
"strings"
)
// ErrNotFound 是業務層的哨兵錯誤。
var ErrNotFound = errors.New("order: not found")
// ValidationError 攜帶結構化資訊:哪個欄位、為什麼。
type ValidationError struct {
Field string
Reason string
}
func (e *ValidationError) Error() string {
return fmt.Sprintf("invalid %s: %s", e.Field, e.Reason)
}
// errNoRows 模擬資料庫驅動的錯誤(例如 sql.ErrNoRows)。
var errNoRows = errors.New("no rows in result set")
// Order 沿用系列的領域模型;Total 以「分」為單位。
type Order struct {
ID string
UserID string
Total int64
Status string // pending / paid / cancelled
}
// findOrder 是資料存取層(repository.go):只回報底層發生了什麼。
func findOrder(id string) (Order, error) {
if id == "404" {
return Order{}, errNoRows
}
return Order{ID: id, UserID: "u-1", Total: 12900, Status: "pending"}, nil
}
// GetOrder 是業務層(service.go):驗證輸入,並把底層錯誤轉成業務語意。
func GetOrder(id string) (Order, error) {
if strings.TrimSpace(id) == "" {
return Order{}, &ValidationError{Field: "id", Reason: "must not be empty"}
}
o, err := findOrder(id)
if errors.Is(err, errNoRows) {
// 對上層隱藏「底層是 SQL」:轉成自己的哨兵錯誤,並補上是哪一筆。
return Order{}, fmt.Errorf("get order %s: %w", id, ErrNotFound)
}
if err != nil {
return Order{}, fmt.Errorf("get order %s: %w", id, err)
}
return o, nil
}
func main() {
for _, id := range []string{"42", "404", " "} {
o, err := GetOrder(id)
// Go 1.26+:泛型版本,不必先宣告目標變數。
if ve, ok := errors.AsType[*ValidationError](err); ok {
fmt.Printf("%q -> 400 Bad Request(欄位 %s)\n", id, ve.Field)
continue
}
// 傳統寫法:宣告目標變數再傳指標,效果相同。
var ve *ValidationError
switch {
case errors.As(err, &ve):
fmt.Printf("%q -> 400(不會走到這裡)\n", id)
case errors.Is(err, ErrNotFound):
fmt.Printf("%q -> 404 Not Found:%v\n", id, err)
case err != nil:
fmt.Printf("%q -> 500:%v\n", id, err)
default:
fmt.Printf("%q -> 200 OK:%+v\n", id, o)
}
}
}執行結果大致是:"42" 得到 200,"404" 得到 404 並印出 get order 404: order: not found,空白 ID 得到 400 並指出欄位 id。
指標接收者與 errors.As 的目標型別
自訂錯誤型別通常用指標接收者實作 Error(),並以指標回傳(&ValidationError{...})。這時 errors.As 的目標必須是 **ValidationError(也就是 var ve *ValidationError 再傳 &ve)。如果目標寫成值型別,errors.As 會找不到;如果目標根本不是指向「實作 error 的型別或介面」的指標,errors.As 會直接 panic,go vet 也會幫你抓出這類錯誤。
用介面判斷「行為」而不是「型別」
有時候呼叫端在意的不是具體型別,而是某種性質,例如「這個錯誤能不能重試」。這時可以定義一個小介面,讓 errors.As 去找實作它的錯誤:
// 片段:用行為介面判斷是否可重試
type retryable interface {
Retryable() bool
}
func shouldRetry(err error) bool {
var r retryable
return errors.As(err, &r) && r.Retryable()
}這樣不同套件(HTTP 客戶端、資料庫、訊息佇列)的錯誤,只要實作 Retryable(),就能被同一段重試邏輯處理,彼此不需要互相匯入。後面〈逾時、重試與熔斷〉會用到這個技巧。
三種做法怎麼選
| 做法 | 攜帶資訊 | 判斷方式 | 適合情境 |
|---|---|---|---|
| 不匯出的一般錯誤 | 只有訊息 | 不讓呼叫端判斷 | 呼叫端只需要知道「失敗了」 |
| 哨兵錯誤 | 固定訊息 | errors.Is | 可預期、需分支的狀況:找不到、已存在、已取消 |
| 自訂型別 | 任意結構化欄位 | errors.As / errors.AsType | 需要欄位、狀態碼、重試資訊 |
| 行為介面 | 由實作決定 | errors.As 到介面 | 跨套件判斷共通性質,例如可重試、暫時性 |
第 5 步:多個錯誤:errors.Join
有些操作會同時產生多個錯誤,而且你希望全部回報,而不是只回報第一個:驗證一張表單的所有欄位、關閉多個資源、平行呼叫多個下游。Go 1.20 加入的 errors.Join 就是為此設計的:
// 片段:驗證多個欄位,把所有錯誤一起回傳
func (r CreateOrderRequest) Validate() error {
var errs []error
if r.UserID == "" {
errs = append(errs, &ValidationError{Field: "user_id", Reason: "required"})
}
if len(r.Items) == 0 {
errs = append(errs, &ValidationError{Field: "items", Reason: "must not be empty"})
}
for i, it := range r.Items {
if it.Qty <= 0 {
errs = append(errs, &ValidationError{Field: fmt.Sprintf("items[%d].qty", i), Reason: "must be positive"})
}
}
return errors.Join(errs...) // 全部是 nil 或切片為空時回傳 nil
}
// 關閉資源時常見的寫法:把關閉錯誤併進原本的錯誤
func process(path string) (err error) {
f, err := os.Open(path)
if err != nil {
return err
}
defer func() { err = errors.Join(err, f.Close()) }()
// ... 讀取 f ...
return nil
}errors.Join 的幾個特性要記住:
- 引數中的
nil會被忽略;全部都是nil時回傳nil,所以可以放心地直接回傳它。 - 合併後的
Error()是各錯誤訊息以換行串接。如果你的日誌格式是一行一筆,要注意換行字元;結構化日誌(log/slog的 JSON 輸出)會自動跳脫,不會有問題。 errors.Is與errors.As會檢查裡面的每一個錯誤,只要有一個符合就成立。errors.Unwrap對它回傳nil,因為它實作的是Unwrap() []error,不是單一的Unwrap() error。
圖:外層的 %w 包住一個 Join,Join 底下有三個驗證錯誤;errors.As 會依序檢查每一個分支,找到第一個符合的就停。
第 6 步:在服務邊界轉換錯誤
錯誤在服務內部要盡量保留細節,但跨出服務時要反過來:對外只說必要的事。客戶端需要的是狀態碼和一段可以顯示或據以處理的訊息,不需要知道 SQL 語句、內部主機名稱、檔案路徑;這些資訊洩漏出去,輕則讓 API 的行為被底層實作綁死,重則成為攻擊者的情報。
常見的做法是在最外層(HTTP 處理器或 gRPC 攔截器)集中做一次轉換:
圖:處理器拿到錯誤後分成兩條路:完整的錯誤鏈進日誌,對外只回狀態碼與固定的訊息。
package main
import (
"errors"
"fmt"
"log/slog"
"net/http"
"net/http/httptest"
"os"
)
var (
ErrNotFound = errors.New("not found")
ErrForbidden = errors.New("forbidden")
)
type ValidationError struct{ Field, Reason string }
func (e *ValidationError) Error() string { return e.Field + ": " + e.Reason }
// apiError 是對外的錯誤格式:只有狀態碼與安全的訊息。
type apiError struct {
Status int
Message string
}
// toAPIError 是唯一一個把內部錯誤翻譯成對外錯誤的地方。
func toAPIError(err error) apiError {
if ve, ok := errors.AsType[*ValidationError](err); ok {
return apiError{http.StatusBadRequest, "invalid field: " + ve.Field}
}
switch {
case errors.Is(err, ErrNotFound):
return apiError{http.StatusNotFound, "resource not found"}
case errors.Is(err, ErrForbidden):
return apiError{http.StatusForbidden, "forbidden"}
default:
// 未知錯誤:對外不透露任何細節。
return apiError{http.StatusInternalServerError, "internal error"}
}
}
// handlerFunc 讓處理器可以直接回傳 error,轉換集中在 wrap 裡做一次。
type handlerFunc func(w http.ResponseWriter, r *http.Request) error
func wrap(log *slog.Logger, h handlerFunc) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
err := h(w, r)
if err == nil {
return
}
ae := toAPIError(err)
level := slog.LevelInfo
if ae.Status >= 500 {
level = slog.LevelError
}
// 完整的錯誤鏈只進日誌,只記這一次。
log.Log(r.Context(), level, "request failed",
"method", r.Method, "path", r.URL.Path, "status", ae.Status, "err", err)
http.Error(w, ae.Message, ae.Status)
})
}
func getOrder(w http.ResponseWriter, r *http.Request) error {
id := r.PathValue("id")
if id == "0" {
return &ValidationError{Field: "id", Reason: "must be positive"}
}
if id == "404" {
return fmt.Errorf("get order %s: %w", id, ErrNotFound)
}
if id == "500" {
return fmt.Errorf("get order %s: query: dial tcp 10.0.0.5:5432: connection refused", id)
}
_, err := fmt.Fprintf(w, "order %s\n", id)
return err
}
func main() {
log := slog.New(slog.NewJSONHandler(os.Stderr, nil))
mux := http.NewServeMux()
mux.Handle("GET /orders/{id}", wrap(log, getOrder))
for _, id := range []string{"7", "0", "404", "500"} {
rec := httptest.NewRecorder()
mux.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/orders/"+id, nil))
fmt.Printf("GET /orders/%s -> %d %s", id, rec.Code, rec.Body.String())
}
}這段程式的重點:
- 轉換只寫一次。所有處理器回傳
error,由wrap統一翻譯與記錄,不會有某個處理器忘了設定狀態碼、或把內部訊息直接寫給客戶端。 - 日誌等級依嚴重程度決定。4xx 是客戶端的問題,通常記成 Info 或 Warn;5xx 才是需要告警的 Error。全部記成 Error 會讓告警失去意義。
id == "500"的例子刻意在錯誤訊息裡放了內部 IP,你會看到它只出現在 stderr 的日誌中,HTTP 回應只有internal error。
後面的〈net/http 與中介層〉會把 wrap 發展成真正的中介層;〈gRPC 與 Protocol Buffers〉則是把錯誤轉成 status.Error(codes.NotFound, ...),概念完全相同。
第 7 步:panic 只留給真正的程式錯誤
Go 也有 panic 與 recover,但它們不是用來做一般錯誤處理的。panic 代表「程式本身有 bug,或處於無法繼續的狀態」:索引越界、對 nil map 寫入、啟動時必要的設定缺失。可預期的失敗(找不到資料、網路斷線、輸入不合法)一律用 error 回傳。
實務上的規則:
- 函式庫不要 panic 給呼叫端。即使內部用 panic 簡化遞迴邏輯(例如解析器),也要在公開 API 的邊界
recover並轉成error。 - 啟動階段可以「Must」。像
regexp.MustCompile、template.Must這種只在初始化時用、輸入是程式設計師寫死的值,失敗就代表程式寫錯,panic 是合理的。 - 伺服器要在請求邊界 recover。
net/http的伺服器已經會 recover 處理器中的 panic 並記錄(只會中斷那一個連線),但它不會幫你回傳 500,也不會記錄你需要的上下文;常見做法是加一個 recover 中介層,記錄堆疊後回 500。要注意:另外啟動的 goroutine 裡的 panic 不會被任何人 recover,會讓整個程序結束,所以背景工作需要在 goroutine 內部自己處理。
常見陷阱
- 回傳型別為具體指標的 nil 錯誤:函式宣告回傳
error,內部卻var e *MyError; return e,呼叫端拿到的介面值不是nil(型別不為空、值為 nil),err != nil會成立。沒有錯誤時一律直接return nil。 - 記錄後又回傳:同一個錯誤在日誌出現多次。只在最終處理的地方記錄一次。
- 用
err.Error()做字串比對:訊息一改判斷就壞。用哨兵錯誤配errors.Is,或自訂型別配errors.As。 - 用
==比較被包裝過的錯誤:包一層之後就不相等了,一律用errors.Is。 - 對外洩漏內部錯誤訊息:
http.Error(w, err.Error(), 500)會把 SQL、主機位址送給客戶端。在邊界統一翻譯。 - 每層都加「failed to」:訊息冗長而沒有資訊量。用簡短的動作片語,並帶上識別資訊(ID、名稱)。
- 忽略錯誤:
_ = f.Close()或乾脆不接回傳值。寫入檔案時Close的錯誤可能代表資料沒寫完整,要檢查;真的要忽略時,加註解說明為什麼。 - 跨抽象邊界仍用
%w暴露底層錯誤:上層開始依賴sql.ErrNoRows,之後換掉資料庫就會牽一髮動全身。在邊界轉成自己的錯誤。 - 在 goroutine 裡 panic:沒有 recover 會讓整個服務結束。背景工作要自己 recover,或把錯誤透過 channel 回報。
重點整理
error是只有Error() string的介面;錯誤是值,要在呼叫後立刻處理:補救、加上下文回傳,或原樣回傳,三選一。- 用
fmt.Errorf("動作 %s: %w", id, err)包裝,加上這一層才知道的資訊;%w會讓內層錯誤成為 API 的一部分,跨抽象邊界時改用自己的錯誤。 - 哨兵錯誤表達可預期的狀況,用
errors.Is判斷;自訂型別攜帶結構化資料,用errors.As或 Go 1.26 的errors.AsType取出。 - 想判斷共通性質(例如可重試)時,用小介面配
errors.As,避免套件互相匯入。 errors.Join與多個%w會形成錯誤樹,Is/As會檢查每個分支;defer中常用它併入Close的錯誤。- 在服務邊界集中把錯誤翻譯成狀態碼與安全訊息,完整錯誤只記錄一次;4xx 與 5xx 用不同日誌等級。
panic只用於程式錯誤與初始化失敗;伺服器在請求邊界 recover,自己啟動的 goroutine 要自己處理。
下一篇
到目前為止,訂單服務的每一段程式都是一步接一步執行的;但真實的服務要同時處理很多請求、同時呼叫好幾個下游,錯誤也會從好幾個 goroutine 同時冒出來。下一篇〈Goroutine、Channel 與並發模式〉會說明 Go 怎麼表達並發,以及怎麼把並發中的錯誤收回來。