Exception on Tarragon

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、預設值）
寫一個裝飾器，自動捕獲異常並轉換為返回值

下一章：返回值設計

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 與測試隔離 相關：作用域迴歸案例研究 — 這套機制如何在一次重構中暴露出潛在問題

Exception on Tarragon

5.1 異常處理策略

基本語法

try-except

完整結構

常見異常類型

實際範例：Git 命令執行

設計分析

Hook 系統的異常哲學

為什麼不直接拋出異常？

(bool, str) 返回值模式

實際應用

異常處理策略

策略 1：捕獲並轉換

策略 2：捕獲並記錄

策略 3：捕獲並重新拋出

策略 4：使用預設值

最佳實踐

1. 具體優於籠統

2. 保留原始異常資訊

3. 使用 finally 清理資源

4. 不要靜默忽略異常

自訂異常

思考題

實作練習

5.5 頂層例外處理機制

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

解決方案：run_hook_safely

每個 Hook 的使用方式

設計解析

為什麼用 Callable 包裝？

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

返回值型別驗證

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

實際案例

日誌系統配置

Fallback 策略

統一前後的對比

思考題

實作練習

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

解決方案：`run_hook_safely`

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