Error-Handling 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.1 異常處理策略

Tue, 20 Jan 2026 00:00:00 +0000

異常處理是撰寫穩健程式碼的關鍵。本章介紹 Python 的異常處理機制，以及 Hook 系統中採用的設計策略。

基本語法

try-except

1try:
2    result = risky_operation()
3except SomeException as e:
4    handle_error(e)

完整結構

 1try:
 2    result = risky_operation()
 3except SpecificError as e:
 4    # 處理特定錯誤
 5    handle_specific_error(e)
 6except (TypeError, ValueError) as e:
 7    # 處理多種錯誤
 8    handle_type_error(e)
 9except Exception as e:
10    # 處理其他所有錯誤
11    handle_unknown_error(e)
12else:
13    # 沒有錯誤時執行
14    process_result(result)
15finally:
16    # 無論如何都執行
17    cleanup()

常見異常類型

異常	發生時機
`FileNotFoundError`	檔案不存在
`PermissionError`	權限不足
`ValueError`	值不合法
`TypeError`	型別不正確
`KeyError`	字典鍵不存在
`IndexError`	索引超出範圍
`JSONDecodeError`	JSON 解析失敗
`TimeoutError`	操作超時

實際範例：Git 命令執行

來自 .claude/lib/git_utils.py：

 1import subprocess
 2from typing import Optional
 3
 4def run_git_command(
 5    args: list[str],
 6    cwd: Optional[str] = None,
 7    timeout: int = 10
 8) -> tuple[bool, str]:
 9    """
10    執行 git 命令並返回結果
11
12    Returns:
13        tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
14    """
15    try:
16        result = subprocess.run(
17            ["git"] + args,
18            cwd=cwd,
19            capture_output=True,
20            text=True,
21            timeout=timeout
22        )
23        if result.returncode == 0:
24            return True, result.stdout.strip()
25        else:
26            return False, result.stderr.strip()
27
28    except subprocess.TimeoutExpired:
29        # 命令超時
30        return False, f"Command timed out after {timeout}s"
31
32    except FileNotFoundError:
33        # git 命令不存在
34        return False, "git command not found"
35
36    except Exception as e:
37        # 其他未預期的錯誤
38        return False, str(e)

設計分析

這個函式展示了 Hook 系統的異常處理策略：

不拋出異常：返回 (bool, str) 元組
捕獲特定異常：分別處理 TimeoutExpired 和 FileNotFoundError
兜底處理：except Exception 捕獲其他錯誤
提供有意義的錯誤訊息：讓呼叫者知道發生了什麼

Hook 系統的異常哲學

為什麼不直接拋出異常？

Hook 腳本需要穩定運行，即使遇到錯誤也要：

給出有意義的反饋
不中斷整個 Claude 工作流程
讓主程式能夠決定如何處理

`(bool, str)` 返回值模式

 1# 函式簽名
 2def validate_something() -> tuple[bool, str]:
 3    """
 4    Returns:
 5        tuple[bool, str]: (成功與否, 訊息)
 6    """
 7    pass
 8
 9# 使用方式
10success, message = validate_something()
11if success:
12    print(f"成功: {message}")
13else:
14    print(f"失敗: {message}")

實際應用

 1def read_hook_input() -> dict:
 2    """
 3    從 stdin 讀取 Hook 輸入
 4
 5    Returns:
 6        dict: 解析後的 JSON 資料，解析失敗時返回空字典
 7    """
 8    try:
 9        return json.load(sys.stdin)
10    except json.JSONDecodeError:
11        return {}  # 不拋出異常，返回安全的預設值
12    except Exception:
13        return {}

異常處理策略

策略 1：捕獲並轉換

將異常轉換為返回值：

1def safe_divide(a: float, b: float) -> tuple[bool, float]:
2    try:
3        return True, a / b
4    except ZeroDivisionError:
5        return False, 0.0

策略 2：捕獲並記錄

記錄後繼續執行：

 1def process_files(files: list[str]) -> list[str]:
 2    results = []
 3    for file in files:
 4        try:
 5            result = process_file(file)
 6            results.append(result)
 7        except Exception as e:
 8            logger.error(f"Failed to process {file}: {e}")
 9            # 繼續處理其他檔案
10    return results

策略 3：捕獲並重新拋出

添加上下文後重新拋出：

1def load_config(path: str) -> dict:
2    try:
3        with open(path) as f:
4            return json.load(f)
5    except FileNotFoundError:
6        raise FileNotFoundError(f"Config file not found: {path}")
7    except json.JSONDecodeError as e:
8        raise ValueError(f"Invalid JSON in {path}: {e}")

策略 4：使用預設值

提供安全的預設值：

1def get_config_value(config: dict, key: str, default: str = "") -> str:
2    try:
3        return config[key]
4    except KeyError:
5        return default

最佳實踐

1. 具體優於籠統

 1# 好：捕獲具體異常
 2try:
 3    data = json.load(f)
 4except json.JSONDecodeError:
 5    data = {}
 6
 7# 不好：捕獲所有異常
 8try:
 9    data = json.load(f)
10except Exception:  # 可能隱藏其他問題
11    data = {}

2. 保留原始異常資訊

 1# 好：保留原始異常
 2try:
 3    process()
 4except ValueError as e:
 5    raise RuntimeError(f"Processing failed: {e}") from e
 6
 7# 不好：丟失原始資訊
 8try:
 9    process()
10except ValueError:
11    raise RuntimeError("Processing failed")

3. 使用 finally 清理資源

 1f = None
 2try:
 3    f = open("file.txt")
 4    process(f)
 5except IOError:
 6    handle_error()
 7finally:
 8    if f:
 9        f.close()  # 確保關閉檔案
10
11# 更好：使用 with 語句
12with open("file.txt") as f:
13    process(f)  # 自動關閉

4. 不要靜默忽略異常

 1# 不好：完全忽略錯誤
 2try:
 3    risky_operation()
 4except Exception:
 5    pass  # 什麼都不做
 6
 7# 好：至少記錄一下
 8try:
 9    risky_operation()
10except Exception as e:
11    logger.warning(f"Operation failed (ignored): {e}")

自訂異常

 1class HookError(Exception):
 2    """Hook 基礎異常"""
 3    pass
 4
 5class ValidationError(HookError):
 6    """驗證錯誤"""
 7    pass
 8
 9class ConfigurationError(HookError):
10    """配置錯誤"""
11    pass
12
13# 使用
14def validate_hook(path: str) -> None:
15    if not path.endswith(".py"):
16        raise ValidationError(f"Invalid hook file: {path}")

思考題

為什麼 run_git_command 不直接拋出異常？
什麼情況下應該使用 except Exception？
from e 在 raise ... from e 中的作用是什麼？

實作練習

重構一個使用異常的函式，改為返回 (bool, str) 模式
實作一個函式，嘗試多種方式載入配置（JSON、YAML、預設值）
寫一個裝飾器，自動捕獲異常並轉換為返回值

下一章：返回值設計

自動攔截機制

Fri, 19 Jun 2026 00:00:00 +0000

自動攔截機制讓 SDK 在開發者不寫任何 error 上報程式碼的情況下，自動捕獲未處理的例外並記錄為 error 事件。每個平台有各自的全域錯誤處理器，SDK 在 init 時註冊攔截器，捕獲後轉換為統一的 error 事件格式送出。

各平台的攔截點

JavaScript / TypeScript

JS 環境有兩個全域錯誤攔截點：

window.onerror 捕獲同步程式碼中未處理的例外。回呼函式收到 error message、來源 URL、行號、列號和 Error 物件。

window.onunhandledrejection 捕獲未處理的 Promise rejection。回呼函式收到 PromiseRejectionEvent，包含 rejection reason。

SDK 在 init 時註冊這兩個處理器。註冊前先保存原有的處理器（如果有），攔截後先呼叫原有處理器再執行 SDK 的記錄邏輯 — 避免覆蓋應用程式已有的錯誤處理。

限制：onerror 對跨域腳本的錯誤只收到 Script error. 訊息，沒有 stack trace。需要在 <script> 標籤加 crossorigin 屬性，server 端的 CORS header 加 Access-Control-Allow-Origin。

Flutter

Flutter 有兩個攔截層：

FlutterError.onError 捕獲 widget build / layout / paint 過程中的例外。預設行為是在 console 印出錯誤，SDK 替換為記錄 error 事件後再呼叫預設處理器。

PlatformDispatcher.instance.onError 捕獲其他非同步區域的未處理例外（Dart 2.15+）。包含 Isolate 內的未捕獲例外。

runZonedGuarded 是另一個選項 — 在指定的 Zone 內捕獲所有未處理例外。SDK 可以用 runZonedGuarded 包住整個 runApp()，但這和 PlatformDispatcher.onError 有重疊，需要避免同一個例外被記錄兩次。

限制：Flutter 的 release mode 會移除 stack trace 的符號資訊（obfuscation）。需要保留 debug symbols 檔案（.dSYM / mapping.txt），在 collector 端做 symbolication。

Python

sys.excepthook 處理主執行緒的未捕獲例外。回呼函式收到 exception type、value 和 traceback。

threading.excepthook（Python 3.8+）處理子執行緒的未捕獲例外。

atexit.register 用於在 Python 程序退出時 flush 剩餘的 buffer。但 atexit 在 os._exit() 或 SIGKILL 時不會執行。

限制：Python 的 GIL 讓 SDK 的網路操作可能阻塞主執行緒。SDK 的 flush 應該在獨立的 daemon thread 中執行，主執行緒只負責把事件放入 buffer。

攔截後的統一處理

不同平台的錯誤物件格式不同（JS 的 Error、Flutter 的 FlutterErrorDetails、Python 的 sys.exc_info tuple）。SDK 在攔截後把平台特定的錯誤物件轉換為統一的 error 事件格式：

type: "error"
name: 從 error class name 推導（TypeError → error.TypeError）
data: 包含 message、stack trace（字串化）、觸發位置

轉換層是每個平台 SDK 唯一的平台特定程式碼。轉換完成後，事件進入和手動上報相同的 buffer → flush 管線。

和手動上報的分工

自動攔截處理「開發者沒有預期到的錯誤」— 未捕獲的例外、未處理的 rejection。手動上報（Monitor.error()）處理「開發者知道可能發生但想記錄的錯誤」— 已捕獲的例外、業務邏輯的異常狀態。

兩者進入同一個 buffer 和 flush 管線，在 collector 端可以用 data 中的 source: "auto" / source: "manual" 欄位區分。

下一步路由

SDK 公開 API → SDK 公開 API 設計
各平台的深入適配問題 → 模組五平台適配
Buffer 和 flush → 攢批送出策略
主動感測器設計（和被動攔截互補）→ 前端感測器設計

5.2 返回值設計

Tue, 20 Jan 2026 00:00:00 +0000

Hook 系統採用 (bool, str) 返回值模式，這是一種替代異常處理的設計策略。本章深入探討這個模式的設計理念和最佳實踐。

(bool, str) 模式

基本形式

 1def validate_something() -> tuple[bool, str]:
 2 """
 3 Returns:
 4 tuple[bool, str]:
 5 - (True, "成功訊息") - 操作成功
 6 - (False, "錯誤訊息") - 操作失敗
 7 """
 8 if some_condition:
 9 return True, "驗證通過"
10 return False, "驗證失敗：原因說明"

使用方式

1success, message = validate_something()
2if success:
3 print(f"成功: {message}")
4else:
5 print(f"失敗: {message}")
6 # 決定如何處理錯誤

實際範例：Git 命令

來自 .claude/lib/git_utils.py：

 1def run_git_command(
 2 args: list[str],
 3 cwd: Optional[str] = None,
 4 timeout: int = 10
 5) -> tuple[bool, str]:
 6 """
 7 執行 git 命令並返回結果
 8
 9 Args:
10 args: git 命令參數列表
11 cwd: 執行目錄
12 timeout: 超時時間（秒）
13
14 Returns:
15 tuple[bool, str]: (是否成功, 輸出或錯誤訊息)
16 """
17 try:
18 result = subprocess.run(
19 ["git"] + args,
20 cwd=cwd,
21 capture_output=True,
22 text=True,
23 timeout=timeout
24 )
25 if result.returncode == 0:
26 return True, result.stdout.strip()
27 else:
28 return False, result.stderr.strip()
29 except subprocess.TimeoutExpired:
30 return False, f"Command timed out after {timeout}s"
31 except FileNotFoundError:
32 return False, "git command not found"

使用這個函式

1def get_current_branch() -> Optional[str]:
2 """獲取當前分支名稱"""
3 success, output = run_git_command(["branch", "--show-current"])
4 return output if success and output else None
5
6def get_project_root() -> str:
7 """獲取專案根目錄"""
8 success, output = run_git_command(["rev-parse", "--show-toplevel"])
9 return output if success else os.getcwd()

為什麼選擇這個模式？

優點

明確的錯誤處理

1# 呼叫者必須處理兩種情況
2success, message = validate()
3if not success:
4 # 必須處理錯誤
5 pass

錯誤訊息保留

1# 錯誤訊息可以傳遞給使用者
2success, error = run_command()
3if not success:
4 logger.error(error)
5 return create_error_response(error)

不中斷執行流程

1# 可以收集所有錯誤
2errors = []
3for file in files:
4 success, message = process(file)
5 if not success:
6 errors.append(message)

與異常的比較

特性	(bool, str)	異常
強制處理	是（需要解包）	否（可能被忽略）
控制流程	不中斷	中斷
效能	較好	較差（stack trace）
適合場景	預期的錯誤	非預期的錯誤

設計變體

(bool, T) - 通用型別

1from typing import TypeVar, Tuple
2
3T = TypeVar("T")
4
5def parse_json(text: str) -> Tuple[bool, dict]:
6 try:
7 return True, json.loads(text)
8 except json.JSONDecodeError as e:
9 return False, {"error": str(e)}

(T | None) - 成功返回值，失敗返回 None

1def find_config(name: str) -> Optional[dict]:
2 """找不到時返回 None"""
3 path = get_config_path(name)
4 if not path.exists():
5 return None
6 return load_config(path)

Result 類別（進階）

 1from dataclasses import dataclass
 2from typing import Generic, TypeVar
 3
 4T = TypeVar("T")
 5
 6@dataclass
 7class Result(Generic[T]):
 8 success: bool
 9 value: Optional[T] = None
10 error: Optional[str] = None
11
12 @classmethod
13 def ok(cls, value: T) -> "Result[T]":
14 return cls(success=True, value=value)
15
16 @classmethod
17 def fail(cls, error: str) -> "Result[T]":
18 return cls(success=False, error=error)
19
20# 使用
21def divide(a: int, b: int) -> Result[float]:
22 if b == 0:
23 return Result.fail("Division by zero")
24 return Result.ok(a / b)
25
26result = divide(10, 2)
27if result.success:
28 print(result.value) # 5.0
29else:
30 print(result.error)

實際應用模式

鏈式操作

 1def process_pipeline(data: str) -> Tuple[bool, str]:
 2 # 第一步
 3 success, result = step_one(data)
 4 if not success:
 5 return False, f"Step 1 failed: {result}"
 6
 7 # 第二步
 8 success, result = step_two(result)
 9 if not success:
10 return False, f"Step 2 failed: {result}"
11
12 # 第三步
13 success, result = step_three(result)
14 if not success:
15 return False, f"Step 3 failed: {result}"
16
17 return True, result

收集多個錯誤

 1def validate_all(items: list[str]) -> Tuple[bool, list[str]]:
 2 errors = []
 3 for item in items:
 4 success, message = validate_item(item)
 5 if not success:
 6 errors.append(message)
 7
 8 if errors:
 9 return False, errors
10 return True, []

帶上下文的錯誤

 1def run_with_context(
 2 command: str
 3) -> Tuple[bool, str]:
 4 """執行命令並提供上下文"""
 5 try:
 6 result = execute(command)
 7 return True, result
 8 except Exception as e:
 9 context = f"Command: {command}\nError: {e}"
10 return False, context

Hook 系統的應用

Hook 輸入讀取

1def read_hook_input() -> dict:
2 """
3 從 stdin 讀取輸入
4 失敗時返回空字典（而非拋出異常）
5 """
6 try:
7 return json.load(sys.stdin)
8 except json.JSONDecodeError:
9 return {}

分支驗證

1def validate_branch(branch: str) -> Tuple[bool, str]:
2 """驗證分支是否可以編輯"""
3 if is_protected_branch(branch):
4 return False, f"Cannot edit protected branch: {branch}"
5 if not is_allowed_branch(branch):
6 return False, f"Branch not in allowed list: {branch}"
7 return True, f"Branch {branch} is valid"

最佳實踐

1. 訊息要有意義

1# 好：提供具體資訊
2return False, f"Config file not found: {path}"
3
4# 不好：模糊的訊息
5return False, "Error"

2. 保持一致性

1# 好：整個模組使用相同模式
2def func_a() -> Tuple[bool, str]: ...
3def func_b() -> Tuple[bool, str]: ...
4def func_c() -> Tuple[bool, str]: ...
5
6# 不好：混合使用
7def func_a() -> Tuple[bool, str]: ...
8def func_b() -> Optional[str]: ... # 不一致
9def func_c(): ... # 可能拋出異常

3. 文檔說明返回值

 1def validate(data: str) -> Tuple[bool, str]:
 2 """
 3 驗證資料格式
 4
 5 Returns:
 6 tuple[bool, str]:
 7 - (True, "Validation passed") - 驗證成功
 8 - (False, error_message) - 驗證失敗，包含原因
 9 """
10 ...

思考題

什麼情況下應該使用 (bool, str) 而不是異常？
如何處理需要返回多種錯誤類型的情況？
(bool, str) 模式如何與型別檢查工具配合？

實作練習

重構一個使用異常的函式，改為 (bool, str) 模式
實作一個 Result 類別，支援 map 和 flat_map 操作
寫一個函式，執行多個驗證並收集所有錯誤

上一章：異常處理策略 下一章：unittest 基礎

0.3 錯誤處理：把失敗路徑寫出來

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

Go 錯誤處理的核心原則是把失敗路徑明確寫在程式流程中。if err != nil 看起來重複，但它讓每一步可能失敗的地方都可見，也讓讀者能直接知道失敗時程式會怎麼結束。對需要長時間運行、並發處理、背景工作或即時請求回應的服務來說，這種顯式失敗路徑比隱式例外更容易維護。

為什麼這章在第零章

如果你的場景已經把 Go 推向服務型系統，錯誤處理就是維持服務穩定的核心能力。這一章要先建立的是：Go 會要求你把失敗說清楚，因為在高併發或長時間運行的情境下，模糊的失敗行為會比清楚的錯誤訊息更難排查。

error 是普通回傳值

Go 的 error 是一個普通介面值。函式若可能失敗，通常會把錯誤放在最後一個回傳值。

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

這段程式有兩個失敗點：讀檔失敗與 JSON 解析失敗。每個失敗點都立刻處理並回傳，正常流程則留在函式底部。

早期返回讓正常流程清楚

早期返回的核心目標是先排除不能繼續的情況。錯誤越早被處理，後續程式越能專注在成功路徑。

 1func CreateUser(email string) (User, error) {
 2 email = strings.TrimSpace(email)
 3 if email == "" {
 4 return User{}, fmt.Errorf("email is required")
 5 }
 6
 7 if !strings.Contains(email, "@") {
 8 return User{}, fmt.Errorf("invalid email")
 9 }
10
11 return User{Email: email}, nil
12}

這個函式先處理空字串與格式錯誤，最後才建立使用者。讀者不需要進入深層巢狀條件，就能知道哪些資料不能通過。

包裝錯誤要補上操作脈絡

錯誤包裝的核心責任是保留原始錯誤，同時補上當前操作脈絡。fmt.Errorf 搭配 %w 可以建立錯誤鏈。

1if err := repository.Save(ctx, user); err != nil {
2 return fmt.Errorf("save user %q: %w", user.Email, err)
3}

save user "alice@example.com" 是當前操作脈絡，原始錯誤則被 %w 保留下來。呼叫端可以印出完整錯誤，也可以用 errors.Is 或 errors.As 檢查特定錯誤。

錯誤包裝應提供新的操作脈絡。fmt.Errorf("failed: %w", err) 這類包裝沒有資訊量；好的錯誤訊息應該回答「做什麼失敗」與「關鍵資料是什麼」。

HTTP handler 要把錯誤轉成協定語意

HTTP handler 的錯誤處理核心是把內部錯誤轉成明確 status code。輸入格式錯誤通常是 400，找不到資料是 404，不支援的方法是 405，未預期內部錯誤才是 500。

 1func handleCreateUser(w http.ResponseWriter, r *http.Request) {
 2 var req createUserRequest
 3 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 4 http.Error(w, "invalid json", http.StatusBadRequest)
 5 return
 6 }
 7
 8 user, err := CreateUser(req.Email)
 9 if err != nil {
10 http.Error(w, err.Error(), http.StatusBadRequest)
11 return
12 }
13
14 writeJSON(w, http.StatusCreated, user)
15}

handler 的錯誤對應應反映協定語意。錯誤來自呼叫端輸入時，回 400 才能讓 client 知道應該修正 request；未預期內部錯誤才應進入 500。

log 應該放在有處理責任的位置

錯誤記錄的核心規則是誰負責處理錯誤，誰才記錄錯誤。底層函式通常回傳錯誤，上層邊界再決定要 log、重試、轉成 HTTP response 或讓程式結束。

 1func run() error {
 2 config, err := LoadConfig("config.json")
 3 if err != nil {
 4 return err
 5 }
 6
 7 return StartServer(config)
 8}
 9
10func main() {
11 if err := run(); err != nil {
12 log.Fatal(err)
13 }
14}

LoadConfig 回傳錯誤比直接 log.Fatal 更符合責任邊界，因為它不知道呼叫端是否想重試、使用預設值或結束程式。main 是 process 邊界，才適合決定失敗時結束。

小結

Go 錯誤處理的價值是讓失敗路徑可讀、可測、可追蹤。每個 if err != nil 都是一個明確的決策點：是否補脈絡、是否轉成協定狀態、是否記錄、是否終止流程。這種顯式設計是 Go 長期維護性的核心之一。

模組五：錯誤處理與測試

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

Go 的錯誤處理偏向顯式：錯誤是回傳值，呼叫者要直接面對。Go 的測試也偏向直接：建立輸入、執行函式、檢查輸出。本模組把錯誤處理、單元測試、table-driven test、HTTP 測試與並發測試串成一組可落地的驗證方法。

章節列表

章節	主題	關鍵收穫
5.1	錯誤回傳與早期返回	寫出可追蹤的失敗路徑
5.2	testing 基礎	用 `testing` package 驗證函式行為
5.3	table-driven test	用表格整理多組輸入輸出
5.4	HTTP handler 測試	用 `httptest` 驗證 request/response
5.5	時間注入與 deterministic test	避免測試依賴真實時間
5.6	並發行為測試	測試 channel、goroutine 與狀態更新
5.7	錯誤處理與測試在高併發服務中的角色	把錯誤路徑與並發邊界納入可靠性觀點

本模組使用的範例主題

函式單元測試
table-driven test
HTTP handler 測試
時間相關測試
channel 與 goroutine 測試

學習時間

預計 2 小時

5.5 頂層例外處理機制

Wed, 04 Mar 2026 00:00:00 +0000

前面的章節介紹了異常處理的基本語法和 (bool, str) 返回值模式。本章進入實務層面：當你有 44 個 Hook 腳本，每個都可能在不同地方失敗時，如何建立一套統一的錯誤基礎設施？

這是 W22-W25 開發週期中建立的機制，解決的核心問題是：

Hook 失敗時，錯誤不能靜默消失，也不能讓整個工作流程崩潰。

問題：44 個 Hook，44 種錯誤處理方式

在統一之前，每個 Hook 腳本各自處理例外：

 1# hook_a.py — 用 try-except 包整個 main
 2def main():
 3    try:
 4        do_work()
 5    except Exception as e:
 6        print(f"Error: {e}")
 7        sys.exit(1)
 8
 9# hook_b.py — 完全沒有錯誤處理
10def main():
11    do_work()  # 任何異常直接讓腳本 crash
12
13# hook_c.py — 錯誤寫到檔案但用戶看不到
14def main():
15    try:
16        do_work()
17    except Exception as e:
18        with open("error.log", "a") as f:
19            f.write(str(e))
20        # 用戶完全不知道出錯了

這造成三個問題：

行為不一致：有的 Hook 失敗會中斷流程，有的靜默吞掉
重複程式碼：每個 Hook 各寫一套 try-except
錯誤不可見：某些 Hook 靜默失敗了好幾個 session 才被發現

解決方案：`run_hook_safely`

hook_utils.py 提供了一個頂層例外處理器，所有 Hook 統一使用：

 1def run_hook_safely(main_func: Callable[[], int], hook_name: str) -> int:
 2    """安全執行 Hook 函式，頂層例外處理
 3
 4    Args:
 5        main_func: Hook 主入口函式，必須返回 int
 6        hook_name: Hook 識別名稱
 7
 8    Returns:
 9        int: main_func 的返回值（正常），或 1（異常）
10    """
11    logger = setup_hook_logging(hook_name)
12
13    try:
14        exit_code = main_func()
15        # 驗證返回值是整數
16        if not isinstance(exit_code, int):
17            try:
18                exit_code = int(exit_code)
19            except (ValueError, TypeError):
20                exit_code = 0
21        return exit_code
22    except (KeyboardInterrupt, SystemExit):
23        raise  # 這兩個不攔截
24    except Exception:
25        tb_str = traceback.format_exc()
26        _log_exception(logger, hook_name, tb_str)
27        return EXIT_ERROR

每個 Hook 的使用方式

 1#!/usr/bin/env python3
 2import sys
 3sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
 4from hook_utils import run_hook_safely
 5
 6def main() -> int:
 7    # 專注於業務邏輯，不需要處理頂層例外
 8    data = json.load(sys.stdin)
 9    result = validate(data)
10    print(json.dumps(result))
11    return 0
12
13if __name__ == "__main__":
14    sys.exit(run_hook_safely(main, "my-hook-name"))

設計解析

為什麼用 Callable 包裝？

run_hook_safely 接收一個函式，而不是直接包裝程式碼區塊。這個設計有三個好處：

 1# 方式 A：直接包裝（不採用）
 2try:
 3    # 所有程式碼放在這裡
 4    data = read_input()
 5    result = process(data)
 6    output(result)
 7except Exception:
 8    handle_error()
 9
10# 方式 B：函式包裝（採用）
11def main() -> int:
12    data = read_input()
13    result = process(data)
14    output(result)
15    return 0
16
17run_hook_safely(main, "hook-name")

比較	方式 A	方式 B
可重用性	每個 Hook 各寫一次	`run_hook_safely` 寫一次，所有 Hook 共用
測試性	無法單獨測試錯誤處理	可以測試 `run_hook_safely` 的行為
關注點分離	業務邏輯和錯誤處理混在一起	Hook 只寫業務邏輯，錯誤處理交給框架

這就是高階函式在實務中的應用。

為什麼 `KeyboardInterrupt` 和 `SystemExit` 要特別處理？

1except (KeyboardInterrupt, SystemExit):
2    raise  # 不攔截，直接往上傳
3except Exception:
4    # 只攔截「普通」的程式錯誤

Python 的例外繼承結構：

1BaseException
2├── KeyboardInterrupt    ← Ctrl+C
3├── SystemExit           ← sys.exit()
4└── Exception            ← 所有「普通」例外的父類別
5    ├── ValueError
6    ├── TypeError
7    ├── FileNotFoundError
8    └── ...

KeyboardInterrupt 和 SystemExit 不是程式錯誤，它們是控制信號：

KeyboardInterrupt：用戶按了 Ctrl+C，意圖是終止程式
SystemExit：程式碼呼叫了 sys.exit()，意圖是正常退出

如果攔截了這兩個，用戶按 Ctrl+C 程式不會停，sys.exit(0) 也不會退出。這違反了「最小驚訝原則」。

返回值型別驗證

1if not isinstance(exit_code, int):
2    try:
3        exit_code = int(exit_code)
4    except (ValueError, TypeError):
5        exit_code = 0

這段防護處理的是：萬一某個 Hook 的 main() 返回了非整數（例如 None 或字串）。

main() 返回值	處理結果	說明
`0`	`0`	正常
`1`	`1`	正常
`None`	`0`	忘記寫 return
`"0"`	`0`	字串轉整數
`"abc"`	`0`	無法轉換，視為成功

stderr vs stdout：Hook 系統的特殊規則

Claude Code 的 Hook 系統對輸出有特殊解讀：

輸出管道	Claude Code 的解讀
`stdout`	正常訊息，顯示為 `hook success`
`stderr`	錯誤訊息，顯示為 `hook error`

這個行為影響了 _log_exception 的設計：

 1def _log_exception(logger, hook_name, tb_str):
 2    # 1. 寫入日誌檔案（給開發者事後分析）
 3    try:
 4        logger.critical(f"Unhandled exception in {hook_name}")
 5        logger.critical(tb_str)
 6    except Exception as logging_error:
 7        print(f"Failed to log exception: {logging_error}", file=sys.stdout)
 8        print(tb_str, file=sys.stdout)
 9
10    # 2. 輸出到 stderr（讓用戶知道出錯了）
11    print(
12        f"[Hook Error] {hook_name} failed unexpectedly. "
13        f"Check hook logs for details.",
14        file=sys.stderr
15    )

第二行的 stderr 輸出是刻意的。在 W25-005 之前，所有錯誤只寫入日誌檔案，導致 7 個 Hook 靜默失敗了至少 2 個 session 才被發現。加入 stderr 輸出後，用戶會立刻看到 hook error 提示。

實際案例

1# 用戶看到的訊息（W25-005 之前）
2SessionStart:startup hook success: Success     ← 看起來正常
3SessionStart:startup hook success: Success
4# 實際上有 7 個 Hook 在靜默失敗
5
6# W25-005 之後
7SessionStart:startup hook success: Success
8SessionStart:startup hook error: [Hook Error] acceptance-gate-hook failed unexpectedly.
9# 用戶立刻知道有問題

這個教訓的完整記錄在 IMP-003 錯誤模式中，模組七的作用域迴歸案例研究有詳細分析。

日誌系統配置

run_hook_safely 背後依賴 setup_hook_logging 建立日誌系統：

 1def setup_hook_logging(hook_name: str) -> logging.Logger:
 2    """建立並設定 Hook 日誌系統
 3
 4    功能：
 5    - 建立日誌目錄 .claude/hook-logs/{hook_name}/
 6    - 建立日誌檔案 {hook_name}-{YYYYMMDD-HHMMSS}.log
 7    - 配置 FileHandler + StreamHandler
 8    """
 9    sanitized_name = _sanitize_hook_name(hook_name)
10    root_dir = _find_project_root()
11    log_base_dir = root_dir / ".claude" / "hook-logs" / sanitized_name
12
13    try:
14        log_base_dir.mkdir(parents=True, exist_ok=True)
15    except OSError:
16        return _create_fallback_logger(hook_name)
17
18    logger = logging.getLogger(hook_name)
19    _clear_logger_handlers(logger)
20    logger.setLevel(logging.DEBUG)
21
22    is_debug = os.getenv("HOOK_DEBUG", "").lower() == "true"
23    _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug)
24    return logger

Fallback 策略

注意 except OSError 的處理：目錄建立失敗時不拋出異常，而是返回一個只有 StreamHandler 的 fallback logger。這確保即使檔案系統出問題，日誌功能仍然可用（只是沒有檔案記錄）。

這體現了 5.1 異常處理策略中「策略 4：使用預設值」的原則。

統一前後的對比

指標	統一前（v0.28.0）	統一後（v0.31.0）
錯誤處理方式	44 種不同實作	1 個 `run_hook_safely`
靜默失敗風險	高（多個 Hook 實際靜默失敗中）	低（stderr 強制可見）
日誌格式	不一致	統一時間戳、格式、目錄結構
新增 Hook 所需程式碼	~15 行錯誤處理	1 行 `run_hook_safely` 呼叫

思考題

run_hook_safely 為什麼選擇返回 EXIT_ERROR（整數 1）而不是拋出異常？
如果 _log_exception 本身也拋出異常（例如磁碟已滿），會發生什麼？
為什麼 _create_fallback_logger 只配 StreamHandler 而不是直接返回 None？

實作練習

寫一個類似 run_hook_safely 的裝飾器版本，讓 @safe_hook 就能保護函式
擴展 _log_exception，讓它在記錄日誌的同時發送通知（例如寫入一個 .alert 檔案）
修改 setup_hook_logging，加入日誌檔案大小限制（使用 RotatingFileHandler）

上一章：Mock 與測試隔離 相關：作用域迴歸案例研究 — 這套機制如何在一次重構中暴露出潛在問題

模組五：錯誤處理與測試

Tue, 20 Jan 2026 00:00:00 +0000

穩健的程式碼需要妥善處理錯誤情況，並透過測試確保品質。本模組介紹 Python 的異常處理策略和測試技巧。

章節列表

章節	主題	關鍵收穫
5.1	異常處理策略	何時捕獲、何時拋出
5.2	返回值設計	`(bool, str)` 模式的應用
5.3	unittest 基礎	撰寫第一個測試
5.4	Mock 與測試隔離	隔離外部依賴
5.5	頂層例外處理機制	`run_hook_safely` 與統一錯誤基礎設施
5.6	Hook 系統可觀測性設計	日誌架構、錯誤可見性、健康監控

實際範例來源

主題	範例來源
異常處理	`git_utils.py`
返回值設計	Hook 系統的 `(bool, str)` 模式
unittest	`tests/` 目錄
Mock	`test_hook_io.py`
頂層例外處理	`hook_utils.py`（W22-W25）
可觀測性設計	`hook_utils.py` 日誌架構 + IMP-003/005/006 錯誤模式

核心理念

 1# Hook 系統的返回值設計模式
 2def validate_something() -> tuple[bool, str]:
 3 """
 4 返回 (成功與否, 訊息)
 5 - True, "成功訊息" - 驗證通過
 6 - False, "錯誤訊息" - 驗證失敗
 7 """
 8 if some_condition:
 9 return True, "驗證通過"
10 return False, "驗證失敗：原因說明"

學習路徑

1異常處理 → 返回值設計 → unittest 基礎 → Mock 技巧 → 頂層例外處理機制 → 可觀測性設計

學習時間

預計 90-110 分鐘

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 卡住、鎖範圍過大與資源未釋放等問題。

Error-Handling on Tarragon

5.1 錯誤回傳與早期返回

本章目標

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

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

【策略】用 early return 避免巢狀

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

5.1 異常處理策略

基本語法

try-except

完整結構

常見異常類型

實際範例：Git 命令執行

設計分析

Hook 系統的異常哲學

為什麼不直接拋出異常？

(bool, str) 返回值模式

實際應用

異常處理策略

策略 1：捕獲並轉換

策略 2：捕獲並記錄

策略 3：捕獲並重新拋出

策略 4：使用預設值

最佳實踐

1. 具體優於籠統

2. 保留原始異常資訊

3. 使用 finally 清理資源

4. 不要靜默忽略異常

自訂異常

思考題

實作練習

自動攔截機制

各平台的攔截點

JavaScript / TypeScript

Flutter

Python

攔截後的統一處理

和手動上報的分工

下一步路由

5.2 返回值設計

(bool, str) 模式

基本形式

使用方式

實際範例：Git 命令

使用這個函式

為什麼選擇這個模式？

優點

明確的錯誤處理

錯誤訊息保留

不中斷執行流程

與異常的比較

設計變體

(bool, T) - 通用型別

(T | None) - 成功返回值，失敗返回 None

Result 類別（進階）

實際應用模式

鏈式操作

收集多個錯誤

帶上下文的錯誤

Hook 系統的應用

Hook 輸入讀取

分支驗證

最佳實踐

1. 訊息要有意義

2. 保持一致性

3. 文檔說明返回值

思考題

實作練習

0.3 錯誤處理：把失敗路徑寫出來

為什麼這章在第零章

error 是普通回傳值

早期返回讓正常流程清楚

包裝錯誤要補上操作脈絡

HTTP handler 要把錯誤轉成協定語意

log 應該放在有處理責任的位置

小結

模組五：錯誤處理與測試

章節列表

本模組使用的範例主題

學習時間

`(bool, str)` 返回值模式

解決方案：`run_hook_safely`

為什麼 `KeyboardInterrupt` 和 `SystemExit` 要特別處理？