模組五：錯誤處理與測試 on Tarragon

5.1 錯誤回傳與早期返回

Wed, 22 Apr 2026 00:00:00 +0000

Go 把錯誤當成回傳值。這讓失敗路徑直接出現在程式碼裡，也讓呼叫者必須明確決定如何處理失敗。

本章目標

學完本章後，你將能夠：

理解 error 回傳值的設計目的
用 early return 保持控制流程扁平
為錯誤加上足夠脈絡
在 HTTP handler 中對應不同錯誤情境

【觀察】Go 錯誤處理很顯式

Go 錯誤處理的核心規則是：可能失敗的函式用 error 回傳失敗，呼叫者在呼叫點立即處理。常見寫法如下：

1data, err := os.ReadFile("config.json")
2if err != nil {
3 return err
4}

這段程式很直接：讀檔可能失敗，失敗就回傳錯誤。

對剛接觸 Go 的人來說，if err != nil 可能看起來重複。但這個重複有明確目的：失敗路徑不被隱藏，讀者可以逐步看見每個操作失敗時會發生什麼事。

【判讀】錯誤是控制流程的一部分

Go 的錯誤模型把失敗視為控制流程的一部分。很多語言用 exception 讓錯誤跳出目前流程；Go 則偏好讓錯誤留在函式簽名和呼叫點：

 1func LoadConfig(path string) (Config, error) {
 2 data, err := os.ReadFile(path)
 3 if err != nil {
 4 return Config{}, fmt.Errorf("read config: %w", err)
 5 }
 6
 7 var cfg Config
 8 if err := json.Unmarshal(data, &cfg); err != nil {
 9 return Config{}, fmt.Errorf("parse config: %w", err)
10 }
11
12 if err := validateConfig(cfg); err != nil {
13 return Config{}, fmt.Errorf("validate config: %w", err)
14 }
15
16 return cfg, nil
17}

錯誤脈絡的核心規則是：越靠近失敗來源，越應補上「正在做什麼」的資訊。這裡每個錯誤都被加上脈絡：

read config
parse config
validate config

當錯誤出現在 log 裡時，讀者不只知道失敗了，也知道失敗在哪個階段。

【策略】用 early return 避免巢狀

early return 的核心規則是：失敗路徑就地返回，成功路徑保持在左側。不要把成功路徑包在很多層 else 裡：

 1// 不佳：成功路徑被包在巢狀中
 2func Load(path string) (Config, error) {
 3 data, err := os.ReadFile(path)
 4 if err == nil {
 5 var cfg Config
 6 err = json.Unmarshal(data, &cfg)
 7 if err == nil {
 8 return cfg, nil
 9 } else {
10 return Config{}, err
11 }
12 } else {
13 return Config{}, err
14 }
15}

Go 更常用 early return：

 1func Load(path string) (Config, error) {
 2 data, err := os.ReadFile(path)
 3 if err != nil {
 4 return Config{}, err
 5 }
 6
 7 var cfg Config
 8 if err := json.Unmarshal(data, &cfg); err != nil {
 9 return Config{}, err
10 }
11
12 return cfg, nil
13}

成功路徑保持在左側，失敗路徑就地處理。這是 Go 可讀性的重要風格。

【執行】HTTP handler 中的錯誤路徑

邊界層錯誤處理的核心規則是：內部錯誤要轉成呼叫者能理解的回應。HTTP handler 要把 Go 的錯誤轉成 HTTP response：

 1func handleCreateUser(w http.ResponseWriter, r *http.Request) {
 2 var req CreateUserRequest
 3 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 4 writeJSONError(w, http.StatusBadRequest, "invalid JSON")
 5 return
 6 }
 7
 8 if req.Name == "" {
 9 writeJSONError(w, http.StatusBadRequest, "name is required")
10 return
11 }
12
13 user, err := createUser(req)
14 if err != nil {
15 writeJSONError(w, http.StatusInternalServerError, "create user failed")
16 return
17 }
18
19 writeJSON(w, http.StatusCreated, user)
20}

這段程式的層次很清楚：

JSON 格式錯誤 → 400
欄位驗證錯誤 → 400
內部建立失敗 → 500
成功 → 201

每個錯誤路徑都結束於 return，後面的成功流程不需要被 else 包住。

5.2 testing 基礎

Wed, 22 Apr 2026 00:00:00 +0000

Go 測試的核心規則是：測試檔以 _test.go 結尾，測試函式以 Test 開頭並接收 *testing.T。本章將說明如何建立第一個單元測試、檢查結果與回報失敗。

測試是同一個 package 的行為說明

Go 測試的核心目標是驗證可觀察行為。測試用輸入、輸出與錯誤條件說明這段程式應該如何運作。

1func NormalizeName(input string) string {
2 input = strings.TrimSpace(input)
3 return strings.ToLower(input)
4}

這個函式的可觀察行為是：移除前後空白，並轉成小寫。測試應該檢查這個行為，而不是檢查函式內部是否真的先呼叫 TrimSpace 再呼叫 ToLower。

1func TestNormalizeName(t *testing.T) {
2 got := NormalizeName(" Alice ")
3 want := "alice"
4
5 if got != want {
6 t.Fatalf("NormalizeName() = %q, want %q", got, want)
7 }
8}

這就是最小的 Go 單元測試：準備輸入，呼叫函式，比對結果，失敗時回報清楚訊息。

測試檔命名有固定規則

Go 測試檔的核心規則是檔名必須以 _test.go 結尾。測試函式必須以 Test 開頭，接收一個 *testing.T 參數，且沒有回傳值。

1// normalize_test.go
2func TestNormalizeName(t *testing.T) {
3 // ...
4}

go test 會自動找到這些檔案與函式。測試檔可以和被測程式放在同一個 package，也可以使用 package xxx_test 建立外部測試 package。

同 package 測試可以存取未匯出的函式與型別，外部測試只能使用匯出的 API。入門階段可以先用同 package 測試，等到需要從使用者視角驗證 public API 時，再使用外部測試。

失敗訊息要說明 got 與 want

測試失敗訊息的核心責任是幫助讀者快速定位差異。Go 社群常用 got 與 want 表示實際結果與預期結果。

1if got != want {
2 t.Fatalf("NormalizeName() = %q, want %q", got, want)
3}

這個訊息包含函式名稱、實際結果與預期結果。當測試失敗時，讀者不需要再打開測試檔猜哪個值錯了。

t.Fatal 與 t.Fatalf 會立刻中止目前測試；t.Error 與 t.Errorf 會記錄失敗但繼續執行。若後續檢查依賴目前結果，使用 Fatalf 比較安全。

1got, err := ParsePort("8080")
2if err != nil {
3 t.Fatalf("ParsePort() error = %v", err)
4}
5
6if got != 8080 {
7 t.Fatalf("ParsePort() = %d, want %d", got, 8080)
8}

如果解析已經失敗，後面再檢查數值沒有意義，所以先用 Fatalf 結束測試。

測試錯誤要明確檢查錯誤存在

錯誤情境測試的核心原則是同時檢查「是否有錯」與「錯誤是否符合預期」。只檢查回傳值常常不足以描述失敗行為。

 1func ParsePort(input string) (int, error) {
 2 port, err := strconv.Atoi(input)
 3 if err != nil {
 4 return 0, fmt.Errorf("parse port %q: %w", input, err)
 5 }
 6
 7 if port <= 0 {
 8 return 0, fmt.Errorf("port must be positive")
 9 }
10
11 return port, nil
12}

測試成功情境時，應確認沒有錯誤；測試失敗情境時，應確認錯誤確實發生。

1func TestParsePortInvalid(t *testing.T) {
2 _, err := ParsePort("abc")
3 if err == nil {
4 t.Fatalf("ParsePort() error = nil, want error")
5 }
6}

若程式使用 sentinel error 或可辨識的錯誤型別，可以再用 errors.Is 或 errors.As 檢查錯誤種類。不要只比對完整錯誤字串，除非錯誤訊息本身就是公開合約。

helper 函式可以降低重複

測試 helper 的核心用途是隱藏準備資料的細節，而不是隱藏真正的驗證邏輯。helper 應該讓測試主體更接近「這個行為應該成立」。

 1func mustParsePort(t *testing.T, input string) int {
 2 t.Helper()
 3
 4 port, err := ParsePort(input)
 5 if err != nil {
 6 t.Fatalf("ParsePort(%q) error = %v", input, err)
 7 }
 8
 9 return port
10}

t.Helper() 會讓失敗行號指向呼叫 helper 的測試，而不是 helper 內部。這能讓測試失敗時更快找到真正的案例位置。

helper 不應該把測試意圖藏起來。若 helper 名稱太抽象，或讀者必須跳進 helper 才知道測試在驗證什麼，這個 helper 可能反而降低可讀性。

測試要避免依賴不穩定環境

可靠測試的核心規則是讓輸入可控制、輸出可觀察。時間、隨機數、檔案系統、網路與全域狀態都可能讓測試不穩定。

1func IsExpired(now time.Time, deadline time.Time) bool {
2 return now.After(deadline)
3}

這個函式把 now 當成參數，因此測試可以傳入固定時間。

5.3 table-driven test

Wed, 22 Apr 2026 00:00:00 +0000

table-driven test 的核心規則是：同一個行為的多組案例放進表格，測試流程只寫一次。本章將說明如何設計案例欄位、命名子測試，並避免把太多不同行為塞進同一張表。

table-driven test 解決重複案例

table-driven test 的核心目標是把「案例資料」和「測試流程」分開。當同一個函式需要測多組輸入與預期結果時，表格能讓案例集中呈現，測試流程只保留一次。

1func NormalizeName(input string) string {
2    input = strings.TrimSpace(input)
3    return strings.ToLower(input)
4}

這個函式有多個值得驗證的案例：一般字串、前後空白、已經是小寫、空字串。若每個案例都寫一個完整測試，程式會很快重複。

 1func TestNormalizeName(t *testing.T) {
 2    tests := []struct {
 3        name  string
 4        input string
 5        want  string
 6    }{
 7        {name: "lowercase", input: "alice", want: "alice"},
 8        {name: "trim spaces", input: "  Alice  ", want: "alice"},
 9        {name: "empty", input: "", want: ""},
10    }
11
12    for _, tt := range tests {
13        t.Run(tt.name, func(t *testing.T) {
14            got := NormalizeName(tt.input)
15            if got != tt.want {
16                t.Fatalf("NormalizeName(%q) = %q, want %q", tt.input, got, tt.want)
17            }
18        })
19    }
20}

表格中的每一列是一個案例，迴圈中的程式是共同驗證流程。新增案例時，只要新增一列，不必複製整個測試函式。

案例欄位要對應行為

測試表格欄位的核心原則是只放描述案例所需的資料。常見欄位包括 name、輸入值、預期輸出與是否預期錯誤。

 1tests := []struct {
 2    name    string
 3    input   string
 4    want    int
 5    wantErr bool
 6}{
 7    {name: "valid", input: "8080", want: 8080},
 8    {name: "not number", input: "abc", wantErr: true},
 9    {name: "zero", input: "0", wantErr: true},
10}

wantErr 表示這個案例預期出錯。它比把錯誤訊息塞進 want 更清楚，因為成功結果與錯誤結果是兩種不同觀察。

 1for _, tt := range tests {
 2    t.Run(tt.name, func(t *testing.T) {
 3        got, err := ParsePort(tt.input)
 4        if tt.wantErr {
 5            if err == nil {
 6                t.Fatalf("ParsePort(%q) error = nil, want error", tt.input)
 7            }
 8            return
 9        }
10
11        if err != nil {
12            t.Fatalf("ParsePort(%q) error = %v", tt.input, err)
13        }
14
15        if got != tt.want {
16            t.Fatalf("ParsePort(%q) = %d, want %d", tt.input, got, tt.want)
17        }
18    })
19}

錯誤案例先處理並 return，成功案例再繼續檢查輸出。這讓測試流程和函式行為一樣清楚：失敗時不應再比較正常結果。

`t.Run` 讓案例有名字

t.Run 的核心作用是建立子測試，讓每個案例在測試輸出中有獨立名稱。當某個案例失敗時，工程師可以直接看到是哪一列資料出問題。

1t.Run(tt.name, func(t *testing.T) {
2    // case assertion
3})

案例名稱應該描述情境，而不是描述編號。"empty input"、"negative port"、"trim spaces" 比 "case 1" 更有定位價值。

1tests := []struct {
2    name  string
3    input string
4    want  string
5}{
6    {name: "trim spaces", input: "  Alice  ", want: "alice"},
7    {name: "preserve hyphen", input: "Mary-Jane", want: "mary-jane"},
8}

當測試失敗時，名稱會出現在 go test 輸出中。好的案例名稱能讓讀者先理解失敗情境，再去看 got/want 差異。

表格應集中在單一行為

table-driven test 的邊界是「同一個測試流程是否能自然描述所有案例」。如果某些案例需要完全不同的準備、執行或驗證方式，通常應該拆成不同測試。

1func TestParsePort(t *testing.T) {
2    // 測 ParsePort 的輸入輸出規則
3}
4
5func TestLoadConfig(t *testing.T) {
6    // 測 LoadConfig 的檔案讀取與解析流程
7}

把不同行為硬塞進同一張表，會讓欄位越來越多，最後出現大量只在少數案例使用的欄位。這種表格看起來少了重複，實際上讓讀者更難理解每個案例。

好的表格應該短而集中。若你需要在測試迴圈裡寫很多 if tt.someMode，這通常是拆分測試的訊號。

比較複雜資料時使用合適工具

比較結果的核心原則是選擇能清楚表達差異的方式。基本型別可以直接用 !=，slice、map、struct 則常用 reflect.DeepEqual 或專門的比較工具。

 1func SplitCSV(input string) []string {
 2    if input == "" {
 3        return nil
 4    }
 5
 6    parts := strings.Split(input, ",")
 7    for i := range parts {
 8        parts[i] = strings.TrimSpace(parts[i])
 9    }
10
11    return parts
12}

測試 slice 時，不能直接用 got != want。

 1func TestSplitCSV(t *testing.T) {
 2    tests := []struct {
 3        name  string
 4        input string
 5        want  []string
 6    }{
 7        {name: "empty", input: "", want: nil},
 8        {name: "two values", input: "a, b", want: []string{"a", "b"}},
 9    }
10
11    for _, tt := range tests {
12        t.Run(tt.name, func(t *testing.T) {
13            got := SplitCSV(tt.input)
14            if !reflect.DeepEqual(got, tt.want) {
15                t.Fatalf("SplitCSV(%q) = %#v, want %#v", tt.input, got, tt.want)
16            }
17        })
18    }
19}

reflect.DeepEqual 適合入門與標準庫範例。大型專案可能使用第三方比較工具產生更好的 diff，但核心原則不變：失敗訊息要讓差異容易看懂。

下一章會把測試方法套到 HTTP handler，說明如何不用啟動真實 server 也能驗證請求與回應。

5.4 HTTP handler 測試

Wed, 22 Apr 2026 00:00:00 +0000

HTTP handler 測試的核心規則是不用啟動真實 server，也能驗證 request 進入 handler 後產生的 response。net/http/httptest 提供 request builder 與 response recorder，讓 handler 可以像普通函式一樣被測試。

`httptest` 把 HTTP 測試變成函式呼叫

httptest 的核心用途是建立測試用 request 與 response writer。handler 本來就是 func(http.ResponseWriter, *http.Request)，所以測試可以直接呼叫 handler。

1func handleHealth(w http.ResponseWriter, r *http.Request) {
2    if r.Method != http.MethodGet {
3        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
4        return
5    }
6
7    w.Header().Set("Content-Type", "application/json")
8    fmt.Fprint(w, `{"status":"ok"}`)
9}

這個 handler 可以不用啟動 port，也不用發出真實網路請求。

 1func TestHandleHealth(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodGet, "/health", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handleHealth(rec, req)
 6
 7    res := rec.Result()
 8    defer res.Body.Close()
 9
10    if res.StatusCode != http.StatusOK {
11        t.Fatalf("status = %d, want %d", res.StatusCode, http.StatusOK)
12    }
13}

httptest.NewRequest 建立 request，httptest.NewRecorder 記錄 response。測試直接呼叫 handleHealth(rec, req)，再檢查 recorder 產生的結果。

status code 是第一個行為合約

HTTP response 的核心合約通常先看 status code。成功、輸入錯誤、方法不允許與伺服器錯誤，都應該有明確狀態碼。

 1func TestHandleHealthMethodNotAllowed(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodPost, "/health", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handleHealth(rec, req)
 6
 7    if rec.Code != http.StatusMethodNotAllowed {
 8        t.Fatalf("status = %d, want %d", rec.Code, http.StatusMethodNotAllowed)
 9    }
10}

rec.Code 可以直接取得 handler 寫出的狀態碼。若 handler 沒有呼叫 WriteHeader，但有寫 body，狀態碼通常會是 200。

測試狀態碼時，不要只檢查 body 字串。body 可能改文案，但 status code 才是呼叫端最依賴的協定訊號。

body 檢查要符合輸出格式

response body 的核心檢查方式應該配合輸出格式。純文字可以比對字串；JSON 應該解析成 struct 或 map 後再比對欄位。

 1func TestHandleHealthBody(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodGet, "/health", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handleHealth(rec, req)
 6
 7    var body struct {
 8        Status string `json:"status"`
 9    }
10
11    if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
12        t.Fatalf("decode response body: %v", err)
13    }
14
15    if body.Status != "ok" {
16        t.Fatalf("status field = %q, want %q", body.Status, "ok")
17    }
18}

解析 JSON 後檢查欄位，比直接比對 {"status":"ok"} 更穩定。JSON 欄位順序、空白與換行不應該讓測試失敗。

request body 可以用 `strings.NewReader`

測試 JSON request 的核心做法是把字串或 bytes 包成 reader。handler 看到的是 io.Reader，不需要知道資料來自檔案、網路或測試字串。

 1func TestHandleCreateUser(t *testing.T) {
 2    body := strings.NewReader(`{"name":"Alice","email":"alice@example.com"}`)
 3    req := httptest.NewRequest(http.MethodPost, "/users", body)
 4    req.Header.Set("Content-Type", "application/json")
 5
 6    rec := httptest.NewRecorder()
 7    handler := newCreateUserHandler(fakeUserCreator{})
 8
 9    handler.ServeHTTP(rec, req)
10
11    if rec.Code != http.StatusCreated {
12        t.Fatalf("status = %d, want %d", rec.Code, http.StatusCreated)
13    }
14}

strings.NewReader 讓測試資料留在測試檔中，適合小型 JSON。若 request 很大或要重複使用，可以把測試資料放在 testdata 目錄。

依賴應該用 fake 隔離

handler 測試的核心邊界是 HTTP 行為，不是資料庫或外部服務。若 handler 需要呼叫內部服務，可以提供 fake 實作，讓測試專注於 request/response。

 1type fakeUserCreator struct {
 2    id  string
 3    err error
 4}
 5
 6func (f fakeUserCreator) CreateUser(ctx context.Context, name string, email string) (string, error) {
 7    if f.err != nil {
 8        return "", f.err
 9    }
10    return f.id, nil
11}

成功案例可以讓 fake 回傳 id，失敗案例可以讓 fake 回傳錯誤。這樣測試可以分別驗證 201 Created 與 500 Internal Server Error。

 1func TestHandleCreateUserServiceError(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodPost, "/users", strings.NewReader(`{"name":"Alice","email":"alice@example.com"}`))
 3    rec := httptest.NewRecorder()
 4
 5    handler := newCreateUserHandler(fakeUserCreator{err: errors.New("database unavailable")})
 6    handler.ServeHTTP(rec, req)
 7
 8    if rec.Code != http.StatusInternalServerError {
 9        t.Fatalf("status = %d, want %d", rec.Code, http.StatusInternalServerError)
10    }
11}

這是 handler 單元測試。資料庫連線、migration、真實網路等行為應該放在更高層級的整合測試處理。

下一章會處理時間注入，說明如何避免測試依賴真實現在時間。

5.5 時間注入與 deterministic test

Wed, 22 Apr 2026 00:00:00 +0000

時間注入的核心目標是讓測試可以控制「現在時間」。只要函式內部直接呼叫 time.Now()，測試結果就可能受執行時間影響；把時間來源改成參數或小介面後，測試就能重現固定情境。

真實時間會讓測試不穩定

測試不穩定的核心原因是輸入不完全由測試控制。時間是最常見的隱性輸入，因為 time.Now() 每次呼叫都會得到不同結果。

1func IsExpired(deadline time.Time) bool {
2 return time.Now().After(deadline)
3}

這個函式看起來只有一個參數，但實際上還依賴目前時間。測試如果用 time.Now().Add(...) 組 deadline，可能因為執行延遲、時區或邊界條件而變得脆弱。

更好的做法是把現在時間傳進去。

1func IsExpired(now time.Time, deadline time.Time) bool {
2 return now.After(deadline)
3}

函式的所有重要輸入都變成參數後，測試可以完全控制情境。

參數注入適合純邏輯

參數注入的核心用途是處理單次計算。當函式只是判斷過期、計算剩餘時間或產生 timestamp，直接把 now time.Time 傳入通常最簡單。

1func Remaining(now time.Time, deadline time.Time) time.Duration {
2 if now.After(deadline) {
3 return 0
4 }
5 return deadline.Sub(now)
6}

測試可以建立固定時間點。

 1func TestRemaining(t *testing.T) {
 2 now := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 3 deadline := time.Date(2026, 4, 22, 10, 5, 0, 0, time.UTC)
 4
 5 got := Remaining(now, deadline)
 6 want := 5 * time.Minute
 7
 8 if got != want {
 9 t.Fatalf("Remaining() = %v, want %v", got, want)
10 }
11}

這個測試不會因為今天是哪一天、測試跑得快或慢而改變結果。參數注入也讓函式更容易理解，因為時間依賴直接出現在函式簽名中。

provider 函式適合需要多次取時間的元件

時間 provider 的核心用途是讓長生命週期元件可以取得目前時間，但測試仍能替換時間來源。最簡單的 provider 是 func() time.Time。

 1type TokenGenerator struct {
 2 now func() time.Time
 3}
 4
 5func NewTokenGenerator(now func() time.Time) TokenGenerator {
 6 return TokenGenerator{now: now}
 7}
 8
 9func (g TokenGenerator) NewToken(userID string) Token {
10 return Token{
11 UserID: userID,
12 CreatedAt: g.now(),
13 }
14}

正式環境可以傳入 time.Now。

1generator := NewTokenGenerator(time.Now)

測試可以傳入固定時間。

 1func TestTokenGenerator(t *testing.T) {
 2 fixedNow := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 3 generator := NewTokenGenerator(func() time.Time {
 4 return fixedNow
 5 })
 6
 7 token := generator.NewToken("user_123")
 8 if !token.CreatedAt.Equal(fixedNow) {
 9 t.Fatalf("CreatedAt = %v, want %v", token.CreatedAt, fixedNow)
10 }
11}

func() time.Time 比完整介面更輕量，適合只需要目前時間的情境。若元件還需要 timer、ticker 或 sleep，才需要更完整的 clock abstraction。

duration 測試應控制時間

測試 timeout 的核心原則是驗證邏輯，不是讓測試真的睡很久。time.Sleep 會讓測試慢，也會讓測試受排程影響。

1func RetryDelay(attempt int) time.Duration {
2 if attempt <= 0 {
3 return 0
4 }
5
6 return time.Duration(attempt) * 100 * time.Millisecond
7}

這種邏輯應該直接測回傳的 duration。

1func TestRetryDelay(t *testing.T) {
2 got := RetryDelay(3)
3 want := 300 * time.Millisecond
4
5 if got != want {
6 t.Fatalf("RetryDelay() = %v, want %v", got, want)
7 }
8}

若真的要測等待行為，應把等待機制包成可替換依賴，讓測試使用 fake sleeper，而不是呼叫真實 time.Sleep。

1type Sleeper interface {
2 Sleep(time.Duration)
3}
4
5type realSleeper struct{}
6
7func (realSleeper) Sleep(d time.Duration) {
8 time.Sleep(d)
9}

這種抽象只有在等待行為本身需要測試時才值得加入。不要為了形式而把所有 time API 都包起來。

時區要明確

時間測試的核心規則是使用明確時區。測試資料若依賴本機時區，可能在不同開發機或 CI 環境得到不同結果。

1createdAt := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)

使用 time.UTC 能讓測試在不同環境保持一致。若功能本來就和特定時區有關，應用 time.LoadLocation 明確載入。

1loc, err := time.LoadLocation("Asia/Taipei")
2if err != nil {
3 t.Fatalf("load location: %v", err)
4}
5
6localTime := time.Date(2026, 4, 22, 18, 0, 0, 0, loc)

不要讓測試默默依賴 time.Local，除非測試目的就是驗證本機時區設定。

下一章會進入並發行為測試，說明如何驗證 goroutine、channel 與共享狀態。

延伸閱讀

本章處理入門測試中的時間依賴。若要測長時間 worker、ticker 排程、WebSocket cleanup 或 deadline，可以接著閱讀 Go 進階：時間注入與狀態轉移測試；若 timeout 來自部署平台或 load balancer，則閱讀 Go 進階：Kubernetes、systemd 與 load balancer 合約。

5.6 並發行為測試

Wed, 22 Apr 2026 00:00:00 +0000

並發測試的核心目標是驗證可觀察的同步行為，而不是猜測 goroutine 的執行順序。Go 的 goroutine 由 scheduler 安排，測試應該用 channel、context、WaitGroup 與 timeout 表達「什麼結果必須發生」。

並發測試應等待明確訊號

並發程式的核心限制是執行順序不穩定。測試如果假設某個 goroutine 一定先跑，通常會變成偶發失敗。

1func sendAsync(ch chan<- string) {
2    go func() {
3        ch <- "ready"
4    }()
5}

測試不應該在呼叫後立刻假設資料已經送出，而應該等待明確訊號。

 1func TestSendAsync(t *testing.T) {
 2    ch := make(chan string, 1)
 3
 4    sendAsync(ch)
 5
 6    select {
 7    case got := <-ch:
 8        if got != "ready" {
 9            t.Fatalf("message = %q, want %q", got, "ready")
10        }
11    case <-time.After(time.Second):
12        t.Fatalf("timeout waiting for message")
13    }
14}

select 加 timeout 可以避免測試永久卡住。timeout 不應該用來證明程式正確，只是測試失敗時的保護機制。

channel 測試要驗證傳遞結果

channel 測試的核心問題是資料是否被送到預期位置。測試應該觀察 channel 收到的值，或觀察 channel 關閉後的狀態。

 1func Produce(ids []string) <-chan string {
 2    out := make(chan string)
 3
 4    go func() {
 5        defer close(out)
 6        for _, id := range ids {
 7            out <- id
 8        }
 9    }()
10
11    return out
12}

這個函式回傳只讀 channel，呼叫端可以 range 讀取直到 channel 關閉。

 1func TestProduce(t *testing.T) {
 2    out := Produce([]string{"a", "b"})
 3
 4    var got []string
 5    for id := range out {
 6        got = append(got, id)
 7    }
 8
 9    want := []string{"a", "b"}
10    if !reflect.DeepEqual(got, want) {
11        t.Fatalf("Produce() = %#v, want %#v", got, want)
12    }
13}

這個測試沒有使用 sleep。channel 關閉就是明確完成訊號，測試可以自然結束。

context 用來測試退出

goroutine 退出測試的核心做法是提供可取消的 context.Context，再等待函式發出完成訊號。沒有退出訊號的 goroutine 很難可靠測試。

 1func RunWorker(ctx context.Context, jobs <-chan string, done chan<- struct{}) {
 2    defer close(done)
 3
 4    for {
 5        select {
 6        case <-ctx.Done():
 7            return
 8        case <-jobs:
 9            // process job
10        }
11    }
12}

測試可以取消 context，然後確認 done 被關閉。

 1func TestRunWorkerStops(t *testing.T) {
 2    ctx, cancel := context.WithCancel(context.Background())
 3    jobs := make(chan string)
 4    done := make(chan struct{})
 5
 6    go RunWorker(ctx, jobs, done)
 7    cancel()
 8
 9    select {
10    case <-done:
11    case <-time.After(time.Second):
12        t.Fatalf("worker did not stop")
13    }
14}

done channel 是測試與 goroutine 之間的完成協定。若程式沒有這種協定，測試只能猜測 goroutine 是否已經退出。

`sync.WaitGroup` 適合等待一組工作完成

WaitGroup 的核心用途是等待已知數量的 goroutine 完成。它適合 fan-out 工作、批次處理與測試中需要等多個背景任務結束的情境。

 1func ProcessAll(items []string, process func(string)) {
 2    var wg sync.WaitGroup
 3
 4    for _, item := range items {
 5        item := item
 6        wg.Add(1)
 7        go func() {
 8            defer wg.Done()
 9            process(item)
10        }()
11    }
12
13    wg.Wait()
14}

測試可以用 mutex 保護共享 slice，並在函式回傳後檢查結果。

 1func TestProcessAll(t *testing.T) {
 2    var mu sync.Mutex
 3    var got []string
 4
 5    ProcessAll([]string{"a", "b"}, func(item string) {
 6        mu.Lock()
 7        defer mu.Unlock()
 8        got = append(got, item)
 9    })
10
11    sort.Strings(got)
12    want := []string{"a", "b"}
13    if !reflect.DeepEqual(got, want) {
14        t.Fatalf("processed = %#v, want %#v", got, want)
15    }
16}

因為 goroutine 執行順序不固定，測試先排序再比較。這表示測試關心「所有項目都有被處理」，不關心處理順序。

race detector 檢查共享狀態

共享狀態測試的核心風險是 data race。Go 提供 race detector，可以在測試時檢查多個 goroutine 是否未同步讀寫同一份資料。

1go test -race ./...

-race 會讓測試變慢，但能抓出許多一般斷言看不見的並發錯誤。只要程式有 goroutine 與共享資料，定期跑 race test 就很有價值。

race detector 不是邏輯正確性的完整證明。它能檢查資料競爭，但不能保證事件順序、buffer 策略或 timeout 行為都符合需求；這些仍然要靠明確測試案例。

5.7 錯誤處理與測試在高併發服務中的角色

Thu, 23 Apr 2026 00:00:00 +0000

高併發服務的可靠性來自錯誤處理與測試共同形成的保護機制。錯誤處理讓失敗路徑可見，測試讓失敗路徑可重現；兩者一起決定系統在壓力下是否仍能被理解、修復與持續交付。

本章目標

學完本章後，你將能夠：

把錯誤處理看成可靠性的一部分
區分可恢復錯誤與不可恢復錯誤
用測試保護失敗路徑與並發路徑
讓 timeout、取消與 race condition 能被提早發現
理解為什麼高併發服務更需要明確的測試邊界

【觀察】錯誤是服務常態

在高併發服務裡，錯誤是日常情況的一部分。網路會失敗、下游會超時、資料會不完整、狀態會競爭；這些情境都應進入系統設計，而不是只留給事故發生後人工排查。

Go 把錯誤放在回傳值中，就是要讓這些常態能被直接看見。

【判讀】測試要先保護脆弱邊界

高併發服務最容易出問題的地方，通常是：

HTTP handler 與外部輸入邊界
goroutine 之間的共享狀態
timeout 與 cancellation
event / queue 的重複或漏處理

這些邊界都應該有測試。人工驗證可以輔助檢查流程，但它無法穩定重現 timeout、取消、race condition 與高併發失敗路徑。

【策略】錯誤路徑也要被測

服務測試需要同時覆蓋成功路徑與失敗路徑。只驗證成功路徑會讓 timeout、下游錯誤、取消與狀態競爭在壓力下才暴露，修復成本會更高。

你至少應該測：

參數不合法時是否回傳穩定錯誤
下游失敗時是否有正確的包裝錯誤
timeout 是否真的會停止工作
取消 context 後 goroutine 是否退出

【執行】並發測試要看資源是否被正確回收

高併發測試的核心目標是確認資源會被正確回收。跑很多 goroutine 只是製造壓力；真正需要驗證的是：

goroutine 會不會 leak
channel 會不會卡住
鎖的範圍是否合理
資源關閉後流程是否停止

可靠性測試至少要證明流程能正確結束。只證明「看起來可以跑」會漏掉 goroutine leak、channel 卡住、鎖範圍過大與資源未釋放等問題。

模組五：錯誤處理與測試 on Tarragon

5.1 錯誤回傳與早期返回

本章目標

【觀察】Go 錯誤處理很顯式

【判讀】錯誤是控制流程的一部分

【策略】用 early return 避免巢狀

【執行】HTTP handler 中的錯誤路徑

5.2 testing 基礎

測試是同一個 package 的行為說明

測試檔命名有固定規則

失敗訊息要說明 got 與 want

測試錯誤要明確檢查錯誤存在

helper 函式可以降低重複

測試要避免依賴不穩定環境

5.3 table-driven test

table-driven test 解決重複案例

案例欄位要對應行為

t.Run 讓案例有名字

表格應集中在單一行為

比較複雜資料時使用合適工具

下一章

5.4 HTTP handler 測試

httptest 把 HTTP 測試變成函式呼叫

status code 是第一個行為合約

body 檢查要符合輸出格式

request body 可以用 strings.NewReader

依賴應該用 fake 隔離

下一章

5.5 時間注入與 deterministic test

真實時間會讓測試不穩定

參數注入適合純邏輯

provider 函式適合需要多次取時間的元件

duration 測試應控制時間

時區要明確

下一章

延伸閱讀

5.6 並發行為測試

並發測試應等待明確訊號

channel 測試要驗證傳遞結果

context 用來測試退出

sync.WaitGroup 適合等待一組工作完成

race detector 檢查共享狀態

5.7 錯誤處理與測試在高併發服務中的角色

本章目標

【觀察】錯誤是服務常態

【判讀】測試要先保護脆弱邊界

【策略】錯誤路徑也要被測

【執行】並發測試要看資源是否被正確回收

`t.Run` 讓案例有名字

`httptest` 把 HTTP 測試變成函式呼叫

request body 可以用 `strings.NewReader`

`sync.WaitGroup` 適合等待一組工作完成