Stdlib on Tarragon

9.1 用 stdlib flag 寫 subcommand CLI

Fri, 24 Apr 2026 00:00:00 +0000

Subcommand CLI 的核心結構是 _{[flags] [args]}，每層各自承擔獨立決策：dispatcher 決定走到哪個子命令、flag parser 只認該子命令的旗標命名空間、positional args 交給業務邏輯。flag.NewFlagSet 為每個子命令建立獨立 flag 命名空間，讓三層以內的 CLI 用 stdlib 就能乾淨解析；cobra 的說服點在 tab completion、generated help、hierarchical commands 等超出 flag 解析本身的領域，三層內走 stdlib 成本最低。

本章以 scripts/mdtools（blog 自己的 markdown 工具鏈，repo 內檔案）作為 concrete instance。讀者不需要事先熟悉 mdtools — 每段會先講通用 pattern，再用對應 code 示範一種可行實作。

基礎：為什麼需要 `flag.NewFlagSet` 而非 `flag.Parse()`

flag.Parse() 只解析一次全域 flag set。對只有一個命令的小工具（如 tool --input foo）夠用；但一旦進入 tool fmt --fix 這種 [flags] 結構，全域 flag set 就擋路：

--fix 對 fmt 命令有意義，對 lint 命令沒有。
各子命令可能共享 name（例如 --verbose）但預設值或語意不同。
help 輸出需要分子命令各自列自己的 flags。

flag.NewFlagSet 讓每個子命令擁有獨立的 flag 命名空間：

1fs := flag.NewFlagSet("fmt", flag.ExitOnError)
2fix := fs.Bool("fix", false, "apply fixes in place")
3check := fs.Bool("check", false, "report-only")
4_ = fs.Parse(args) // args = os.Args[2:]，已經跳過了子命令本身

fs.Parse(args) 只看傳進去的片段，不碰 os.Args 全域。這是撐起 subcommand CLI 的核心 API。

專案 Layout：main → cmd/ → internal/

Go 慣例的 CLI 專案結構是三層，對應三種責任：

 1scripts/mdtools/
 2├── main.go             ← 層 1：dispatcher，只做「看第一個參數分派到哪裡」
 3├── cmd/
 4│   ├── fmt.go          ← 層 2：每個子命令一個檔案，負責 flag 解析與呼叫 internal
 5│   ├── lint.go
 6│   ├── cards.go
 7│   └── migrate.go
 8└── internal/
 9    ├── mdfmt/          ← 層 3：純邏輯，不碰 flag、os.Args、os.Exit
10    ├── mdlint/
11    └── mdcards/

分層的目的是支援每層獨立的測試策略：

layer 1：幾乎不測，因為只是 switch。
layer 2：integration test（給定 argv、確認 exit code 與 stdout）。
layer 3：unit test，純函式輸入輸出。後續模組的所有實作技術 — AST 整合、idempotent 改寫、graph 分析 — 都落在這層。

把 os.Exit / os.Args / os.Stderr 都擋在 layer 1-2，layer 3 就能用一般 table-driven test 測，不用起 subprocess。

Layer 1：main.go dispatcher

 1// scripts/mdtools/main.go
 2package main
 3
 4import (
 5	"fmt"
 6	"os"
 7
 8	"blog/scripts/mdtools/cmd"
 9)
10
11func main() {
12	if len(os.Args) < 2 {
13		usage()
14		os.Exit(2)
15	}
16
17	sub := os.Args[1]
18	args := os.Args[2:]
19
20	var exitCode int
21	switch sub {
22	case "fmt":
23		exitCode = cmd.Fmt(args)
24	case "lint":
25		exitCode = cmd.Lint(args)
26	case "cards":
27		exitCode = cmd.Cards(args)
28	case "migrate":
29		exitCode = cmd.Migrate(args)
30	case "-h", "--help", "help":
31		usage()
32	case "version":
33		fmt.Println("mdtools 0.1.0-dev")
34	default:
35		fmt.Fprintf(os.Stderr, "unknown subcommand: %q\n\n", sub)
36		usage()
37		exitCode = 2
38	}
39
40	os.Exit(exitCode)
41}

注意幾個 pattern：

dispatcher 不做 flag 解析。args := os.Args[2:] 把剩下交給子命令。
每個子命令回傳 int，dispatcher 統一呼叫 os.Exit。這讓子命令本身容易測（不會直接 kill 測試 process）。
-h / --help / help 三種寫法都接受。Unix 慣例。
unknown subcommand 進 exit code 2，保留 exit 1 給「有違規」的語義。

Layer 2：子命令入口

每個子命令一個檔案，結構類似：

 1// scripts/mdtools/cmd/fmt.go
 2package cmd
 3
 4import (
 5	"flag"
 6	"fmt"
 7	"os"
 8
 9	"blog/scripts/mdtools/internal/files"
10	"blog/scripts/mdtools/internal/mdfmt"
11	"blog/scripts/mdtools/internal/rules"
12)
13
14func Fmt(args []string) int {
15	fs := flag.NewFlagSet("fmt", flag.ExitOnError)
16	fix := fs.Bool("fix", false, "apply fixes in place")
17	check := fs.Bool("check", false, "report-only; non-zero on pending changes")
18	_ = fs.Parse(args)
19
20	if *check && *fix {
21		fmt.Fprintln(os.Stderr, "mdtools fmt: --fix and --check are mutually exclusive")
22		return 2
23	}
24	if !*check && !*fix {
25		*check = true // safe default
26	}
27
28	paths := fs.Args()
29	if len(paths) == 0 {
30		paths = []string{"content"}
31	}
32
33	cfg := rules.Default()
34	mdFiles, err := files.WalkMarkdown(paths)
35	if err != nil {
36		fmt.Fprintf(os.Stderr, "mdtools fmt: walk error: %v\n", err)
37		return 2
38	}
39
40	changed := 0
41	for _, path := range mdFiles {
42		result, err := mdfmt.FormatFile(path, cfg)
43		if err != nil {
44			fmt.Fprintf(os.Stderr, "mdtools fmt: %s: %v\n", path, err)
45			return 2
46		}
47		if !result.Changed() {
48			continue
49		}
50		changed++
51		if *fix {
52			if err := os.WriteFile(path, result.Fixed, 0o644); err != nil {
53				fmt.Fprintf(os.Stderr, "write %s: %v\n", path, err)
54				return 2
55			}
56			fmt.Printf("fixed: %s\n", path)
57		} else {
58			fmt.Printf("would fix: %s\n", path)
59		}
60	}
61
62	if *check && changed > 0 {
63		return 1 // CI-friendly: exit 1 means "things need fixing"
64	}
65	return 0
66}

要注意幾個設計決策：

flag 定義就在入口函式裡，不抽成 package 常數。每個子命令的 flag 獨立演化。
ExitOnError 讓 fs.Parse 遇到不合法 flag 直接 exit — 對 CLI 工具 OK，因為 parse 失敗本來就無法繼續。測試時要用 ContinueOnError 避免殺測試。
positional args 從 fs.Args() 取，不是 os.Args。fs.Parse 會把非 flag 的留在 fs.Args()。
預設值走安全側（*check = true when neither given）— 防止使用者意外執行破壞性動作。
exit code 分層語意：0 = 成功、1 = 有違規、2 = 工具本身失敗。CI script 能用 [[ $? -eq 1 ]] 區分。

Layer 3：internal 實作

Layer 3 是純邏輯，不知道任何 os / flag 的存在。這讓它能被 layer 2 呼叫、被 test 呼叫、也能在未來被其他 binary 或 library 重用：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2package mdfmt
 3
 4import (
 5	"bytes"
 6	"os"
 7
 8	"blog/scripts/mdtools/internal/rules"
 9)
10
11type FixResult struct {
12	Path     string
13	Original []byte
14	Fixed    []byte
15}
16
17func (r FixResult) Changed() bool {
18	return !bytes.Equal(r.Original, r.Fixed)
19}
20
21func FormatFile(path string, cfg rules.Config) (FixResult, error) {
22	data, err := os.ReadFile(path)
23	if err != nil {
24		return FixResult{}, err
25	}
26	fixed := applyAll(data, cfg)
27	return FixResult{Path: path, Original: data, Fixed: fixed}, nil
28}

FormatFile 回傳 (FixResult, error)，不 os.Exit、不印訊息、不碰全域狀態。Test 可以直接給一個記憶體 []byte 跑 applyAll 驗結果。

什麼時候該上 cobra

升級到 cobra 的判準是stdlib 能處理的負面複雜度已經超過 cobra 的學習成本。下表列五個實際觸發過團隊升級的訊號，每個都附展開說明。

訊號	為什麼 stdlib 處理不好
命令層級超過 3 層（`tool sub1 sub2 sub3 --flag`）	dispatcher 變成多層 nested switch，flag 繼承需要手動維護
需要自動 shell completion（bash / zsh / fish）	手寫 completion 腳本成本高；cobra / urfave-cli 有 generator
需要 markdown / man-page 形式的 help 輸出	stdlib 只有基本 `flag.Usage`；cobra 有 `doc` package 能渲染
有多個 end-user 要閱讀 help（非開發者）	stdlib 的 `flag.Usage` 格式樸素，降低使用者可讀性
大量共用 flag（–verbose / –log-level 每個命令都要）	cobra 的 PersistentFlags 比手工在每個子命令重複宣告乾淨

命令層級超過 3 層：kubectl get pods 只有兩層還撐得住；到 gh api repos owner/repo/pulls list --limit 10 就是四層（含 api 這個 namespace），dispatcher 裡巢狀 switch 開始難讀。信號：dispatcher 的 switch case 超過十個，或 case 裡面又呼叫另一個 switch。反例：即使只有兩層，若每層未來會繼續加，早上 cobra 可省後來重構。

需要自動 shell completion：end-user 會反覆打命令、需要 tab 補齊子命令與 flag 名稱時，這功能差很多。手寫 completion 腳本要處理三種 shell 的語法差異，成本高；cobra 一行 cobra.GenBashCompletion 就產生。信號：工具有外部使用者、或團隊已經裝 shell completion。反例：只在 CI 跑、人不會互動輸入。

man-page 形式的 help 輸出：Unix 社群期待工具有 man tool 級的文件。stdlib 只輸出簡單的 usage 字串，排版樸素；cobra 的 doc package 能生成 markdown / reStructuredText / man。信號：工具要 package 進系統（Homebrew、apt），或對外發佈。反例：公司內部用、README 夠用。

多 end-user 讀 help：工程師忍受樸素的 -h 輸出，但產品經理、SRE on-call 看不下。cobra 有明確的 long description、example 欄位，排版比 stdlib 好。信號：使用者包含非程式設計角色。反例：user 是同團隊工程師。

大量共用 flag：--verbose、--log-level、--config 這類 flag 每個子命令都要用。stdlib 要在每個子命令重複 fs.Bool("verbose", ...)；cobra 的 PersistentFlags 能繼承到所有 subcommand。信號：重複 flag 超過三個、或要 enforce 某個 flag 在所有 subcommand 都有。反例：flag 在每個子命令語意不同，共用反而製造混淆。

以上五個訊號在 mdtools 都沒命中（內部工具、單層 subcommand、工程師使用者），所以繼續走 stdlib。若未來 mdtools 對外釋出給讀者下載，就值得重新評估。判讀時機是設計當下，不是感覺「stdlib 開始髒」時 — 髒時通常已經晚。

常見陷阱

在 layer 3 直接呼叫 `os.Exit`

會破壞 test：test runner 呼叫 TestXxx 時，如果 subject code 裡 os.Exit(1)，整個 test process 退出，其他 test 不跑。Layer 3 應回傳 error，讓 layer 2 決定怎麼退出。

用全域 `var fs = flag.NewFlagSet(...)` 宣告 flag

每次呼叫會累積狀態（flag 已經被定義過會 panic），並且兩個 test 同時跑會 race。定義 flag 要在函式裡。

忘記 `ContinueOnError` 就跑 test

ExitOnError 是 production 預設，但測試時會讓測試 process 整個退出。Table-driven test 要用：

1fs := flag.NewFlagSet(name, flag.ContinueOnError)
2fs.SetOutput(io.Discard) // 測試時不要印 usage 到 stderr

太早抽出「所有子命令共用的 flag」

PersistentFlags 概念在 stdlib 沒有，手動在每個子命令重複 fs.Bool("verbose", false, ...) 看似重複但其實可讀。一旦抽成共用 helper，就開始維護一個小框架 — 這時候用 cobra 反而更乾淨。

擴充路徑

命令太多時分組：tool fmt check、tool fmt fix 的兩層 subcommand 可以用「每層一個 switch」展開，main → cmd.Fmt → cmd.FmtCheck。mdtools 的 migrate fix-links 就是這個模式（見 cmd/migrate.go）。
共用 config loading：rules.Default() 這類邏輯放在 internal 裡，每個子命令呼叫；不要每個子命令自己 parse 配置檔。
測試 layer 2：用 buffer 捕獲 stdout/stderr，傳入自定 args。參考 Go stdlib 的 testing/iotest 跟 bytes.Buffer。

下一步

9.2 goldmark AST 入門會看 mdtools 怎麼把 markdown 解析成可操作的結構，layer 3 內部怎麼組織 parser 整合。

3.1 fmt、strings 與基本文字處理

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

文字處理的核心規則是：格式化輸出交給 fmt，字串查找、裁切、替換與組合交給 strings。本章將用 CLI 輸出、設定值清理與簡單 parser 建立標準庫文字處理基礎。

`fmt` 負責格式化

fmt 的核心責任是把資料轉成可閱讀的文字。它可以輸出到標準輸出，也可以把格式化結果組成字串，常用於 CLI 訊息、錯誤訊息與簡單除錯。

1name := "worker"
2count := 3
3
4fmt.Printf("%s handled %d jobs\n", name, count)
5message := fmt.Sprintf("%s handled %d jobs", name, count)
6
7fmt.Println(message)

Printf 會直接輸出，Sprintf 會回傳字串。這個差異很重要：函式內部如果只是要建立訊息，通常應該用 Sprintf 回傳字串，而不是直接印出。

格式動詞描述輸出形狀

格式動詞的核心作用是告訴 fmt 如何呈現資料。常見動詞包括 %s 表示字串，%d 表示十進位整數，%v 表示一般值，%+v 顯示 struct 欄位名稱，%#v 顯示更接近 Go 語法的表示。

 1type User struct {
 2 ID int
 3 Name string
 4}
 5
 6user := User{ID: 7, Name: "alice"}
 7
 8fmt.Printf("%v\n", user) // {7 alice}
 9fmt.Printf("%+v\n", user) // {ID:7 Name:alice}
10fmt.Printf("%#v\n", user) // main.User{ID:7, Name:"alice"}

%v 適合一般輸出，%+v 適合快速檢查 struct 欄位，%#v 適合除錯或理解實際型別。正式 log 通常應該使用結構化 log，而不是把所有資料塞進格式化字串。

錯誤訊息要包含可行動資訊

錯誤訊息的核心原則是描述失敗的操作與關鍵資料。fmt.Errorf 可以建立帶格式的 error，也可以用 %w 包裝原始錯誤，保留錯誤鏈。

1func loadUser(id string) error {
2 if id == "" {
3 return fmt.Errorf("load user: id is required")
4 }
5
6 return nil
7}

錯誤訊息是給工程師定位問題的線索。像 "failed" 這類訊息太籠統，讀者無法知道是哪個操作失敗。

1if err := saveConfig(path, config); err != nil {
2 return fmt.Errorf("save config %q: %w", path, err)
3}

這裡的訊息包含操作 save config、目標 path 與原始錯誤。呼叫端可以顯示完整錯誤，也可以用 errors.Is 或 errors.As 檢查被包裝的錯誤。

`strings` 負責字串操作

strings 的核心責任是提供不需要正規表示式的常見字串操作。裁切空白、檢查前後綴、切割、替換、大小寫轉換，都應該先考慮 strings。

1raw := " api,worker,admin "
2raw = strings.TrimSpace(raw)
3
4parts := strings.Split(raw, ",")
5for _, part := range parts {
6 fmt.Println(strings.TrimSpace(part))
7}

這段程式先移除整體前後空白，再用逗號切割，最後清理每個片段。這種處理很常見於環境變數、設定檔與簡單文字輸入。

查找與判斷應該直接表達意圖

字串判斷的核心原則是使用最貼近意圖的函式。檢查包含關係用 Contains，檢查開頭用 HasPrefix，檢查結尾用 HasSuffix。

1path := "/api/users"
2
3if strings.HasPrefix(path, "/api/") {
4 fmt.Println("api route")
5}
6
7if strings.Contains(path, "users") {
8 fmt.Println("user resource")
9}

用 Index 判斷是否存在也是可行的，但意圖比較間接。

1if strings.Index(path, "/api/") == 0 {
2 fmt.Println("api route")
3}

這段程式需要讀者理解 Index 回傳 0 表示出現在開頭；HasPrefix 則直接說出規則。入門階段應優先選擇語意清楚的 API。

組合字串要看資料量

組合少量字串時，+ 與 fmt.Sprintf 通常足夠；大量或迴圈內組合字串時，strings.Builder 更適合。核心判斷是：資料量小時重視可讀性，資料量大時避免反覆建立中間字串。

1name := "alice"
2message := "hello, " + name
3fmt.Println(message)

少量字串串接很直覺，不需要過度設計。當你在迴圈中累積文字，strings.Builder 能更明確地表達「正在逐步建構一段文字」。

1var builder strings.Builder
2
3for _, name := range []string{"alice", "bob", "carol"} {
4 builder.WriteString("- ")
5 builder.WriteString(name)
6 builder.WriteString("\n")
7}
8
9fmt.Print(builder.String())

strings.Builder 不是每次組字串都必須使用。若資料量小、流程簡單，普通串接往往更好讀。

簡單 parser 可以先用標準庫

簡單文字解析的核心策略是先用清楚的步驟切割資料，再逐步驗證格式。只有當格式本身複雜到難以維護時，才需要引入 parser 或正規表示式。

 1func parsePair(input string) (string, string, error) {
 2 parts := strings.SplitN(input, "=", 2)
 3 if len(parts) != 2 {
 4 return "", "", fmt.Errorf("parse pair %q: missing =", input)
 5 }
 6
 7 key := strings.TrimSpace(parts[0])
 8 value := strings.TrimSpace(parts[1])
 9 if key == "" {
10 return "", "", fmt.Errorf("parse pair %q: empty key", input)
11 }
12
13 return key, value, nil
14}

SplitN 限制最多切成兩段，避免 value 裡再次出現 = 時被過度切割。這個例子也先處理格式錯誤，再回傳正常結果，讓流程保持清楚。

3.1 pathlib - 路徑操作

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

pathlib 是 Python 3.4+ 引入的現代路徑處理模組，提供物件導向的 API 來處理檔案系統路徑。在 Hook 系統中，幾乎每個檔案都使用 pathlib。

為什麼使用 pathlib？

傳統 os.path 方式

 1import os
 2
 3# 組合路徑
 4config_path = os.path.join(project_root, ".claude", "config.json")
 5
 6# 取得父目錄
 7parent = os.path.dirname(file_path)
 8
 9# 取得檔名
10filename = os.path.basename(file_path)
11
12# 檢查存在
13if os.path.exists(config_path):
14    ...

現代 pathlib 方式

 1from pathlib import Path
 2
 3# 組合路徑
 4config_path = project_root / ".claude" / "config.json"
 5
 6# 取得父目錄
 7parent = file_path.parent
 8
 9# 取得檔名
10filename = file_path.name
11
12# 檢查存在
13if config_path.exists():
14    ...

基本操作

建立 Path 物件

 1from pathlib import Path
 2
 3# 從字串建立
 4p = Path("/home/user/project")
 5
 6# 當前目錄
 7cwd = Path.cwd()
 8
 9# 使用者目錄
10home = Path.home()
11
12# 從 __file__ 建立
13current_file = Path(__file__)

路徑組合

使用 / 運算子組合路徑（非常直觀）：

1from pathlib import Path
2
3project = Path("/home/user/project")
4config = project / ".claude" / "config.json"
5
6# 等同於
7config = project.joinpath(".claude", "config.json")

取得路徑部分

1p = Path("/home/user/project/file.txt")
2
3p.name        # "file.txt"
4p.stem        # "file"（不含副檔名）
5p.suffix      # ".txt"
6p.parent      # Path("/home/user/project")
7p.parents[0]  # Path("/home/user/project")
8p.parents[1]  # Path("/home/user")
9p.parts       # ('/', 'home', 'user', 'project', 'file.txt')

實際範例：Hook 系統

日誌目錄建立

來自 .claude/lib/hook_logging.py：

 1from pathlib import Path
 2
 3def setup_hook_logging(hook_name: str) -> logging.Logger:
 4    # 建立日誌目錄
 5    project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
 6    log_dir = Path(project_root) / ".claude" / "hook-logs" / hook_name
 7
 8    # mkdir 的 parents=True 會建立所有不存在的父目錄
 9    # exist_ok=True 表示如果目錄已存在不會報錯
10    log_dir.mkdir(parents=True, exist_ok=True)
11
12    # 日誌檔案路徑
13    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
14    log_file = log_dir / f"{hook_name}-{timestamp}.log"
15
16    # ...

設定檔案搜尋

來自 .claude/lib/config_loader.py：

 1def load_config(config_name: str) -> dict:
 2    config_dir = get_config_dir()
 3
 4    # 優先嘗試不同副檔名
 5    yaml_path = config_dir / f"{config_name}.yaml"
 6    yml_path = config_dir / f"{config_name}.yml"
 7    json_path = config_dir / f"{config_name}.json"
 8
 9    if yaml_path.exists():
10        return _load_yaml_file(yaml_path)
11    elif yml_path.exists():
12        return _load_yaml_file(yml_path)
13    elif json_path.exists():
14        return _load_json_file(json_path)
15
16    raise FileNotFoundError(f"Configuration not found: {config_name}")

檔案操作

讀取檔案

1from pathlib import Path
2
3p = Path("config.json")
4
5# 讀取文字
6content = p.read_text(encoding="utf-8")
7
8# 讀取位元組
9data = p.read_bytes()

寫入檔案

1from pathlib import Path
2
3p = Path("output.txt")
4
5# 寫入文字
6p.write_text("Hello, World!", encoding="utf-8")
7
8# 寫入位元組
9p.write_bytes(b"binary data")

檢查檔案類型

1p = Path("/some/path")
2
3p.exists()      # 是否存在
4p.is_file()     # 是否為檔案
5p.is_dir()      # 是否為目錄
6p.is_symlink()  # 是否為符號連結

目錄操作

建立目錄

1from pathlib import Path
2
3p = Path("new_dir/sub_dir")
4
5# 建立目錄（包含父目錄）
6p.mkdir(parents=True, exist_ok=True)

列出目錄內容

 1from pathlib import Path
 2
 3p = Path(".")
 4
 5# 列出所有項目
 6for item in p.iterdir():
 7    print(item)
 8
 9# 使用 glob 模式
10for py_file in p.glob("*.py"):
11    print(py_file)
12
13# 遞迴搜尋
14for md_file in p.rglob("*.md"):
15    print(md_file)

實際範例：驗證所有 Hook

來自 .claude/lib/hook_validator.py：

 1def validate_all_hooks(self, hooks_dir: Optional[str] = None):
 2    if hooks_dir is None:
 3        hooks_dir = str(self.project_root / ".claude" / "hooks")
 4
 5    hooks_dir = self._resolve_path(hooks_dir)
 6
 7    # 找出所有 .py 檔案
 8    results = []
 9    for hook_file in sorted(hooks_dir.glob("*.py")):
10        if hook_file.name.startswith("_"):
11            continue  # 跳過 __init__.py 等
12        results.append(self.validate_hook(str(hook_file)))
13
14    return results

路徑解析

相對路徑與絕對路徑

1from pathlib import Path
2
3p = Path("./relative/path")
4
5# 轉換為絕對路徑
6absolute = p.resolve()
7
8# 相對於某個目錄
9relative = p.relative_to(Path.cwd())

實際範例：解析路徑

1def _resolve_path(self, path: str) -> Path:
2    """解析路徑為絕對路徑"""
3    p = Path(path)
4    if p.is_absolute():
5        return p
6    return self.project_root / p

常用模式

計算腳本所在目錄

1# 在 .claude/hooks/my_hook.py 中
2from pathlib import Path
3
4# 取得 lib 目錄
5lib_path = Path(__file__).parent.parent / "lib"
6# __file__ = .claude/hooks/my_hook.py
7# parent = .claude/hooks/
8# parent.parent = .claude/
9# / "lib" = .claude/lib/

確保檔案副檔名

1def ensure_extension(path: Path, ext: str) -> Path:
2    """確保檔案有指定的副檔名"""
3    if path.suffix != ext:
4        return path.with_suffix(ext)
5    return path
6
7# 使用
8p = Path("config")
9p = ensure_extension(p, ".json")  # Path("config.json")

安全的檔案讀取

1def safe_read_file(path: Path) -> Optional[str]:
2    """安全讀取檔案，不存在時返回 None"""
3    if not path.exists():
4        return None
5    try:
6        return path.read_text(encoding="utf-8")
7    except Exception:
8        return None

思考題

Path("/a/b") / "c" 和 Path("/a/b").joinpath("c") 有什麼區別？
為什麼 mkdir(parents=True, exist_ok=True) 是常見的組合？
glob("**/*.py") 和 rglob("*.py") 有什麼區別？

實作練習

寫一個函式，找出目錄中所有超過 1MB 的檔案
寫一個函式，將所有 .txt 檔案重命名為 .md
實作一個函式，計算目錄中所有 Python 檔案的總行數

下一章：json - 序列化

3.2 time：時間與 duration

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

時間處理的核心規則是：時間點使用 time.Time，時間長度使用 time.Duration。本章將說明 now、parse、format、duration、timer 與 ticker 的基本用法。

`time.Time` 表示時間點

time.Time 的核心意義是一個具體時間點。它可以代表現在、某個解析出來的時間、資料庫中的時間戳，或 API 回傳的建立時間。

1now := time.Now()
2fmt.Println(now)

time.Now() 會取得目前時間。它很方便，但也會讓測試變得不穩定；需要可測試的邏輯時，通常會把時間來源包成參數或介面。

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

這個函式不自己呼叫 time.Now()，而是由呼叫端傳入現在時間。測試時就能提供固定時間點，避免測試結果受執行時間影響。

`time.Duration` 表示時間長度

time.Duration 的核心意義是一段時間長度，不是某個時間點。它常用於 timeout、interval、重試等待與效能測量。

1timeout := 5 * time.Second
2interval := 200 * time.Millisecond
3
4fmt.Println(timeout)
5fmt.Println(interval)

time.Second、time.Millisecond 這些常數本身是 Duration，可以用乘法組出可讀的時間長度。這比直接寫奈秒數清楚很多。

1// 可讀性差：
2timeout := time.Duration(5000000000)
3
4// 可讀性好：
5timeout := 5 * time.Second

直接寫數字會讓讀者無法立即看出單位。Go 的時間 API 以奈秒為底層單位，但程式碼應該使用明確單位表達意圖。

時間加減要區分時間點與長度

時間運算的核心規則是：時間點加上 duration 會得到另一個時間點，兩個時間點相減會得到 duration。

1start := time.Now()
2deadline := start.Add(30 * time.Second)
3elapsed := time.Since(start)
4
5fmt.Println(deadline)
6fmt.Println(elapsed)

Add 適合計算截止時間，Since 適合計算從某個時間點到現在經過多久。time.Until(deadline) 則可以計算距離某個未來時間還有多久。

1remaining := time.Until(deadline)
2if remaining <= 0 {
3 fmt.Println("expired")
4}

這些 API 讓程式直接表達時間語意，而不是把時間轉成數字後自行相減。

parse 與 format 使用 layout

Go 時間格式化的核心規則是使用固定參考時間 2006-01-02 15:04:05 作為 layout。layout 用這個參考時間的各個部分代表輸出形狀。

1now := time.Date(2026, 4, 22, 9, 30, 0, 0, time.UTC)
2
3fmt.Println(now.Format("2006-01-02"))
4fmt.Println(now.Format("2006-01-02 15:04:05"))

如果你想輸出年月日，就在 layout 裡寫 2006-01-02；如果想輸出 24 小時制時間，就寫 15:04:05。這和許多語言使用 YYYY-MM-DD 的方式不同，是 Go 時間 API 最容易混淆的地方。

解析時間也使用同一套 layout。

1input := "2026-04-22 09:30:00"
2
3createdAt, err := time.Parse("2006-01-02 15:04:05", input)
4if err != nil {
5 return err
6}
7
8fmt.Println(createdAt)

time.Parse 預設會以 UTC 解讀不含時區的時間。若資料代表某個本地時區，應使用 time.ParseInLocation。

timer 表示一次性的未來事件

time.Timer 的核心用途是在一段時間後發出一次訊號。它常用於 timeout、延遲執行與 select 控制。

1timer := time.NewTimer(2 * time.Second)
2defer timer.Stop()
3
4select {
5case <-timer.C:
6 fmt.Println("timeout")
7}

timer.C 是一個 channel，到時間後會收到一個時間值。若 timer 可能提前不再使用，應呼叫 Stop 釋放資源。

在很多簡單情境中，time.After 更短。

1select {
2case <-time.After(2 * time.Second):
3 fmt.Println("timeout")
4}

time.After 適合一次性的簡單 timeout；在高頻迴圈或需要取消、重設的情境中，time.NewTimer 通常比較適合。

ticker 表示週期性事件

time.Ticker 的核心用途是固定間隔發出訊號。它常用於定期清理、輪詢、健康檢查與背景工作。

1ticker := time.NewTicker(1 * time.Second)
2defer ticker.Stop()
3
4for i := 0; i < 3; i++ {
5 <-ticker.C
6 fmt.Println("tick")
7}

ticker.C 每隔指定 duration 會收到一次訊號。只要不再使用 ticker，就應呼叫 Stop，避免背景資源持續運作。

週期性工作要有明確的退出條件。實務上常搭配 context.Context。

 1func run(ctx context.Context) {
 2 ticker := time.NewTicker(1 * time.Second)
 3 defer ticker.Stop()
 4
 5 for {
 6 select {
 7 case <-ctx.Done():
 8 return
 9 case <-ticker.C:
10 fmt.Println("work")
11 }
12 }
13}

這段程式每秒執行一次工作，直到 context 被取消。時間控制與生命週期控制分開後，程式會比較容易測試與關閉。

小結

下一章會進入 os 與 io，說明檔案、輸入輸出與 streaming API 的共同抽象。

3.2 json - 序列化

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

JSON（JavaScript Object Notation）是現代應用程式中最常用的資料交換格式。Python 的 json 模組提供了簡單的 API 來處理 JSON 資料。

基本操作

序列化（Python 物件 → JSON 字串）

 1import json
 2
 3# 字典轉 JSON 字串
 4data = {"name": "Python", "version": 3.11}
 5json_str = json.dumps(data)
 6# '{"name": "Python", "version": 3.11}'
 7
 8# 格式化輸出
 9json_str = json.dumps(data, indent=2)
10# {
11#   "name": "Python",
12#   "version": 3.11
13# }

反序列化（JSON 字串 → Python 物件）

1import json
2
3json_str = '{"name": "Python", "version": 3.11}'
4data = json.loads(json_str)
5# {'name': 'Python', 'version': 3.11}

檔案讀寫

1import json
2
3# 寫入檔案
4with open("config.json", "w", encoding="utf-8") as f:
5    json.dump(data, f, indent=2)
6
7# 讀取檔案
8with open("config.json", "r", encoding="utf-8") as f:
9    data = json.load(f)

實際範例：Hook 系統

Hook 輸入讀取

來自 .claude/lib/hook_io.py：

 1import json
 2import sys
 3
 4def read_hook_input() -> dict:
 5    """
 6    從 stdin 讀取 Hook 輸入
 7
 8    Returns:
 9        dict: 解析後的 JSON 資料，解析失敗時返回空字典
10    """
11    try:
12        return json.load(sys.stdin)
13    except json.JSONDecodeError:
14        return {}
15    except Exception:
16        return {}

Hook 輸出寫入

 1def write_hook_output(
 2    output: dict,
 3    ensure_ascii: bool = False,
 4    indent: int = 2
 5) -> None:
 6    """
 7    輸出 Hook 結果到 stdout
 8
 9    Args:
10        output: 要輸出的字典
11        ensure_ascii: 是否確保 ASCII 編碼
12        indent: JSON 縮排空格數
13    """
14    print(json.dumps(output, ensure_ascii=ensure_ascii, indent=indent))

重要參數

ensure_ascii

控制是否將非 ASCII 字元轉換為跳脫序列：

 1import json
 2
 3data = {"message": "你好"}
 4
 5# ensure_ascii=True（預設）
 6json.dumps(data)
 7# '{"message": "\\u4f60\\u597d"}'
 8
 9# ensure_ascii=False（保留原字元）
10json.dumps(data, ensure_ascii=False)
11# '{"message": "你好"}'

在 Hook 系統中，我們使用 ensure_ascii=False 來保留中文字元。

indent

控制輸出的縮排：

 1data = {"name": "Python", "features": ["simple", "readable"]}
 2
 3# 無縮排
 4json.dumps(data)
 5# '{"name": "Python", "features": ["simple", "readable"]}'
 6
 7# 有縮排
 8json.dumps(data, indent=2)
 9# {
10#   "name": "Python",
11#   "features": [
12#     "simple",
13#     "readable"
14#   ]
15# }

sort_keys

按鍵名排序輸出：

1data = {"z": 1, "a": 2, "m": 3}
2
3json.dumps(data, sort_keys=True)
4# '{"a": 2, "m": 3, "z": 1}'

default

處理無法序列化的物件：

 1from datetime import datetime
 2import json
 3
 4def json_serializer(obj):
 5    if isinstance(obj, datetime):
 6        return obj.isoformat()
 7    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
 8
 9data = {"timestamp": datetime.now()}
10json.dumps(data, default=json_serializer)
11# '{"timestamp": "2024-01-20T15:30:00"}'

型別對應

Python 型別	JSON 型別
dict	object
list, tuple	array
str	string
int, float	number
True	true
False	false
None	null

常見錯誤處理

JSONDecodeError

1import json
2
3def safe_parse_json(json_str: str) -> dict:
4    """安全解析 JSON，失敗時返回空字典"""
5    try:
6        return json.loads(json_str)
7    except json.JSONDecodeError as e:
8        print(f"JSON 解析錯誤: {e}")
9        return {}

無法序列化的物件

 1import json
 2from dataclasses import dataclass, asdict
 3
 4@dataclass
 5class Config:
 6    name: str
 7    timeout: int
 8
 9config = Config("test", 30)
10
11# 錯誤：dataclass 無法直接序列化
12# json.dumps(config)  # TypeError
13
14# 正確：轉換為字典
15json.dumps(asdict(config))
16# '{"name": "test", "timeout": 30}'

實際應用：配置檔案載入

來自 .claude/lib/config_loader.py：

1def _load_json_file(file_path: Path) -> dict:
2    """載入 JSON 檔案"""
3    import json
4    with open(file_path, "r", encoding="utf-8") as f:
5        return json.load(f)

與 YAML 的比較

Hook 系統同時支援 JSON 和 YAML：

 1# 嘗試導入 PyYAML，如果失敗則使用 JSON 作為備案
 2try:
 3    import yaml
 4    HAS_YAML = True
 5except ImportError:
 6    HAS_YAML = False
 7    import json
 8
 9def load_config(config_name: str) -> dict:
10    if yaml_path.exists() and HAS_YAML:
11        return _load_yaml_file(yaml_path)
12    elif json_path.exists():
13        return _load_json_file(json_path)

最佳實踐

1. 總是指定編碼

1# 好
2with open("data.json", "w", encoding="utf-8") as f:
3    json.dump(data, f)
4
5# 不好（可能在不同系統有不同行為）
6with open("data.json", "w") as f:
7    json.dump(data, f)

2. 處理解析錯誤

1def read_config(path: str) -> dict:
2    try:
3        with open(path, "r", encoding="utf-8") as f:
4            return json.load(f)
5    except FileNotFoundError:
6        return {}
7    except json.JSONDecodeError:
8        return {}

3. 使用 ensure_ascii=False 處理中文

1# 輸出中文友好的 JSON
2json.dumps(data, ensure_ascii=False, indent=2)

思考題

json.dump() 和 json.dumps() 有什麼區別？
為什麼 Hook 系統的 read_hook_input() 捕獲 JSONDecodeError 後返回空字典而不是拋出異常？
如何將包含 datetime 物件的字典序列化為 JSON？

實作練習

寫一個函式，合併多個 JSON 檔案
實作一個支援註解的 JSON 讀取器（移除 // 開頭的行）
寫一個函式，比較兩個 JSON 檔案的差異

上一章：pathlib - 路徑操作 下一章：subprocess - 執行外部命令

3.3 os/io：檔案與輸入輸出

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

Go I/O 的核心規則是：資料來源抽象成 io.Reader，資料目的地抽象成 io.Writer。本章將從檔案讀寫開始，建立 os、io 與 streaming API 的基本模型。

檔案操作從 `os` 開始

os package 的核心責任是處理作業系統層級的資源，例如檔案、目錄、環境變數與 process 相關資訊。入門階段最常用的是讀檔、寫檔與建立檔案。

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

os.ReadFile 會一次把整個檔案讀進記憶體，適合設定檔、小型文字檔與測試資料。若檔案可能很大，就應改用 streaming 方式逐步讀取。

寫入小檔案也可以使用 os.WriteFile。

1data := []byte("name=demo\n")
2
3if err := os.WriteFile("app.env", data, 0644); err != nil {
4 return err
5}

最後的 0644 是檔案權限。它表示檔案擁有者可讀寫，其他人可讀。權限是 Unix 檔案權限慣例。

開啟檔案後要關閉

檔案是作業系統資源，開啟後應在不使用時關閉。Go 常用 defer file.Close() 放在成功開啟檔案後，確保函式結束時釋放資源。

 1file, err := os.Open("data.txt")
 2if err != nil {
 3 return err
 4}
 5defer file.Close()
 6
 7data, err := io.ReadAll(file)
 8if err != nil {
 9 return err
10}
11
12fmt.Println(string(data))

defer 應該放在確認 err == nil 之後，因為開啟失敗時 file 可能是 nil。這是 Go I/O 程式很重要的基本順序：先檢查錯誤，再使用資源。

`io.Reader` 表示可讀來源

io.Reader 的核心意義是「可以讀出 bytes 的來源」。檔案、網路連線、HTTP request body、字串 reader 都可以是 reader。

1func countBytes(r io.Reader) (int, error) {
2 data, err := io.ReadAll(r)
3 if err != nil {
4 return 0, err
5 }
6
7 return len(data), nil
8}

這個函式不關心資料來自檔案、記憶體或網路，只要求呼叫端提供一個 io.Reader。這就是 Go 介面設計的典型風格：用小介面描述能力，而不是描述具體來源。

1count, err := countBytes(strings.NewReader("hello"))
2if err != nil {
3 return err
4}
5
6fmt.Println(count)

strings.NewReader 可以把字串包成 reader，常用於測試與範例。因為函式依賴 io.Reader，測試時不需要真的建立檔案。

`io.Writer` 表示可寫目的地

io.Writer 的核心意義是「可以接收 bytes 的目的地」。檔案、網路連線、HTTP response、記憶體 buffer 都可以是 writer。

1func writeGreeting(w io.Writer, name string) error {
2 _, err := fmt.Fprintf(w, "hello, %s\n", name)
3 return err
4}

這個函式不決定輸出位置，只決定輸出內容。呼叫端可以把內容寫到標準輸出、檔案或 buffer。

1var buffer bytes.Buffer
2
3if err := writeGreeting(&buffer, "alice"); err != nil {
4 return err
5}
6
7fmt.Println(buffer.String())

bytes.Buffer 同時實作 reader 與 writer，適合用來累積輸出或測試寫入結果。

streaming 適合大資料或長連線

streaming 的核心策略是分段處理資料，而不是一次把全部資料載入記憶體。當檔案很大、資料來自網路，或你只需要逐步轉送資料時，streaming 會比 ReadAll 更適合。

 1func copyFile(dstPath string, srcPath string) error {
 2 src, err := os.Open(srcPath)
 3 if err != nil {
 4 return err
 5 }
 6 defer src.Close()
 7
 8 dst, err := os.Create(dstPath)
 9 if err != nil {
10 return err
11 }
12 defer dst.Close()
13
14 _, err = io.Copy(dst, src)
15 return err
16}

io.Copy 從 reader 讀資料並寫到 writer。這段程式沒有手動配置完整檔案大小的 byte slice，因此可以處理比記憶體更大的檔案。

`bufio.Scanner` 適合逐行讀取

逐行處理文字的核心工具是 bufio.Scanner。它會把 reader 切成一個個 token，預設 token 是一行文字。

1func printLines(r io.Reader) error {
2 scanner := bufio.NewScanner(r)
3 for scanner.Scan() {
4 fmt.Println(scanner.Text())
5 }
6
7 return scanner.Err()
8}

scanner.Scan() 每次成功讀到一行就回傳 true，讀完或遇到錯誤時回傳 false。迴圈結束後要檢查 scanner.Err()，因為讀取錯誤不會在迴圈內直接回傳。

Scanner 適合一般文字行，但它有預設 token 大小限制。若要處理非常長的行或大型二進位資料，應改用 bufio.Reader 或其他 streaming API。

模組三：標準庫實戰

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

Go 的標準庫是理解 Go 精神的重要入口。它偏好清楚的小 API、明確錯誤處理與組合式設計。本模組從常見任務出發：格式化輸出、時間處理、JSON 編解碼、HTTP handler、結構化日誌、生命週期控制、資源清理與設定讀取。

章節列表

章節	主題	關鍵收穫
3.1	fmt、strings 與基本文字處理	處理輸出、格式化與字串轉換
3.2	time：時間與 duration	表達時間點、時間差與 timeout
3.3	os/io：檔案與輸入輸出	讀寫檔案與理解 `io.Reader`
3.4	encoding/json：資料交換	在檔案、API 與訊息中使用 JSON
3.5	net/http 與 handler 設計	用 `http.HandlerFunc` 理解 Go 的組合風格
3.6	log/slog：結構化日誌	用欄位支援除錯與 grep
3.7	context：取消、逾時與生命週期	讓長時間工作可以停止
3.8	defer 與資源清理	用 `defer` 管理 close、unlock、recover 邊界
3.9	flag、os/env 與設定邊界	用標準庫讀取設定，並把設定轉成 config struct
3.10	標準庫如何支撐服務型 Go	把 `context`、`net/http` 與 `log/slog` 串成底座

本模組使用的範例主題

格式化輸出與錯誤訊息
字串處理與時間處理
檔案讀寫與 I/O 介面
JSON 檔案與 API 資料
HTTP handler
結構化日誌欄位
資源清理與基本設定讀取

學習時間

預計 3-4 小時

3.3 subprocess - 執行外部命令

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

subprocess 模組讓你從 Python 程式中執行外部命令。在 Hook 系統中，主要用於執行 Git 命令。

基本用法

subprocess.run()

最推薦的方式，Python 3.5+ 引入：

 1import subprocess
 2
 3# 基本執行
 4result = subprocess.run(["ls", "-la"])
 5
 6# 捕獲輸出
 7result = subprocess.run(
 8    ["ls", "-la"],
 9    capture_output=True,
10    text=True
11)
12print(result.stdout)  # 標準輸出
13print(result.stderr)  # 錯誤輸出
14print(result.returncode)  # 返回碼

實際範例：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    Args:
13        args: git 命令參數列表（不含 'git'）
14        cwd: 執行目錄，預設為當前目錄
15        timeout: 命令超時時間（秒）
16
17    Returns:
18        tuple[bool, str]: (是否成功, 輸出內容或錯誤訊息)
19    """
20    try:
21        result = subprocess.run(
22            ["git"] + args,
23            cwd=cwd,
24            capture_output=True,
25            text=True,
26            timeout=timeout
27        )
28        if result.returncode == 0:
29            return True, result.stdout.strip()
30        else:
31            return False, result.stderr.strip()
32    except subprocess.TimeoutExpired:
33        return False, f"Command timed out after {timeout}s"
34    except FileNotFoundError:
35        return False, "git command not found"
36    except Exception as e:
37        return False, str(e)

使用範例：

 1# 取得當前分支
 2success, output = run_git_command(["branch", "--show-current"])
 3if success:
 4    print(f"Current branch: {output}")
 5
 6# 取得專案根目錄
 7success, output = run_git_command(["rev-parse", "--show-toplevel"])
 8
 9# 取得 worktree 列表
10success, output = run_git_command(["worktree", "list", "--porcelain"])

重要參數

capture_output

捕獲標準輸出和錯誤輸出：

 1# 捕獲輸出
 2result = subprocess.run(
 3    ["git", "status"],
 4    capture_output=True,  # 等同於 stdout=PIPE, stderr=PIPE
 5    text=True
 6)
 7
 8# 等價寫法
 9result = subprocess.run(
10    ["git", "status"],
11    stdout=subprocess.PIPE,
12    stderr=subprocess.PIPE,
13    text=True
14)

text

將輸出解碼為字串（而非 bytes）：

1# text=False（預設）
2result = subprocess.run(["echo", "hello"], capture_output=True)
3print(result.stdout)  # b'hello\n'（bytes）
4
5# text=True
6result = subprocess.run(["echo", "hello"], capture_output=True, text=True)
7print(result.stdout)  # 'hello\n'（str）

cwd

指定工作目錄：

1result = subprocess.run(
2    ["git", "status"],
3    cwd="/path/to/repo",
4    capture_output=True,
5    text=True
6)

timeout

設定超時時間（秒）：

1try:
2    result = subprocess.run(
3        ["long_running_command"],
4        timeout=10,
5        capture_output=True
6    )
7except subprocess.TimeoutExpired:
8    print("Command timed out!")

check

自動檢查返回碼：

 1try:
 2    # 如果返回碼非零，拋出 CalledProcessError
 3    result = subprocess.run(
 4        ["git", "status"],
 5        check=True,
 6        capture_output=True,
 7        text=True
 8    )
 9except subprocess.CalledProcessError as e:
10    print(f"Command failed with return code {e.returncode}")
11    print(f"Error output: {e.stderr}")

錯誤處理

常見異常

 1import subprocess
 2
 3def safe_run_command(args: list[str]) -> tuple[bool, str]:
 4    try:
 5        result = subprocess.run(
 6            args,
 7            capture_output=True,
 8            text=True,
 9            timeout=30
10        )
11        if result.returncode == 0:
12            return True, result.stdout.strip()
13        return False, result.stderr.strip()
14
15    except subprocess.TimeoutExpired:
16        return False, "Command timed out"
17
18    except FileNotFoundError:
19        return False, f"Command not found: {args[0]}"
20
21    except PermissionError:
22        return False, f"Permission denied: {args[0]}"
23
24    except Exception as e:
25        return False, str(e)

安全考量

避免 shell=True

1# 危險：使用者輸入可能導致命令注入
2user_input = "file.txt; rm -rf /"
3subprocess.run(f"cat {user_input}", shell=True)  # 危險！
4
5# 安全：使用列表傳遞參數
6subprocess.run(["cat", user_input])  # 安全

驗證輸入

1def run_git_command(args: list[str]) -> tuple[bool, str]:
2    # 驗證第一個參數是否為有效的 git 子命令
3    valid_commands = ["status", "branch", "log", "diff", "rev-parse"]
4    if args and args[0] not in valid_commands:
5        return False, f"Invalid git command: {args[0]}"
6    # ...

進階用法

管道（Pipe）

 1# 模擬 "ls -la | grep .py"
 2ls_process = subprocess.run(
 3    ["ls", "-la"],
 4    capture_output=True,
 5    text=True
 6)
 7
 8grep_process = subprocess.run(
 9    ["grep", ".py"],
10    input=ls_process.stdout,
11    capture_output=True,
12    text=True
13)

環境變數

 1import os
 2
 3# 自訂環境變數
 4env = os.environ.copy()
 5env["MY_VAR"] = "value"
 6
 7result = subprocess.run(
 8    ["my_script.sh"],
 9    env=env,
10    capture_output=True
11)

實際應用：分支資訊

 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()
10
11def get_worktree_list() -> list[dict]:
12    """獲取所有 worktree 列表"""
13    success, output = run_git_command(["worktree", "list", "--porcelain"])
14    if not success:
15        return []
16
17    worktrees = []
18    current_worktree = {}
19
20    for line in output.split("\n"):
21        if line.startswith("worktree "):
22            if current_worktree:
23                worktrees.append(current_worktree)
24            current_worktree = {"path": line[9:]}  # 移除 "worktree " 前綴
25        elif line.startswith("branch "):
26            branch_ref = line[7:]  # 移除 "branch " 前綴
27            if branch_ref.startswith("refs/heads/"):
28                branch_ref = branch_ref[11:]
29            current_worktree["branch"] = branch_ref
30
31    if current_worktree:
32        worktrees.append(current_worktree)
33
34    return worktrees

最佳實踐

1. 使用列表而非字串

1# 好
2subprocess.run(["git", "commit", "-m", "Fix bug"])
3
4# 不好
5subprocess.run("git commit -m 'Fix bug'", shell=True)

2. 設定合理的超時

1# 為長時間運行的命令設定超時
2subprocess.run(["long_task"], timeout=300)  # 5 分鐘

3. 處理所有可能的錯誤

 1def robust_run(args):
 2    try:
 3        result = subprocess.run(args, ...)
 4        return True, result.stdout
 5    except subprocess.TimeoutExpired:
 6        return False, "Timeout"
 7    except FileNotFoundError:
 8        return False, "Command not found"
 9    except Exception as e:
10        return False, str(e)

思考題

為什麼 run_git_command 返回 tuple[bool, str] 而不是直接拋出異常？
shell=True 有什麼風險？什麼情況下必須使用？
如何實作一個可以同時執行多個命令的函式？

實作練習

寫一個函式，執行命令並即時顯示輸出（不等待完成）
實作一個命令重試機制（失敗時自動重試 N 次）
寫一個函式，執行多個命令並收集所有結果

上一章：json - 序列化 下一章：re - 正規表達式

模組三：標準庫實戰

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

Python 的「電池內建」哲學意味著標準庫提供了豐富的工具。本模組介紹 Hook 系統中最常用的標準庫模組。

章節列表

章節	主題	關鍵收穫
3.1	pathlib - 路徑操作	物件導向的路徑處理
3.2	json - 序列化	資料的讀寫與轉換
3.3	subprocess - 執行外部命令	呼叫系統命令
3.4	re - 正規表達式	文字模式匹配
3.5	logging - 日誌系統	結構化日誌輸出
3.6	argparse - CLI 介面	命令列參數解析
3.7	並行處理	threading、multiprocessing、concurrent.futures
3.8	效能迷思與優化	效能測量、優化策略

實際範例來源

模組	範例來源
pathlib	全部 Hook 檔案
json	`hook_io.py`
subprocess	`git_utils.py`
re	`markdown_link_checker.py`
logging	`hook_logging.py`
argparse	`hook_validator.py`

學習建議

這些模組可以獨立學習，建議按實際需求選擇閱讀順序：

處理檔案 → 先讀 pathlib
呼叫 Git → 先讀 subprocess
解析文字 → 先讀 re
建立 CLI → 先讀 argparse
並行處理 → 先讀 concurrency
效能問題 → 先讀 performance

學習時間

每章節約 15-20 分鐘，全模組約 120-150 分鐘

新增章節說明（2026-01）

3.7-3.8 章節涵蓋實用的並行處理與效能優化：

並行處理基礎：傳統的 threading 和 multiprocessing
效能優化：常見效能迷思與實用優化策略

進階內容：Free-Threading（Python 3.13+ 無 GIL）已移至進階系列

3.4 encoding/json：資料交換

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

encoding/json 是 Go 標準庫中負責 JSON 編碼與解碼的 package。它的核心用途是把 Go struct 轉成 JSON，或把 JSON 轉回 Go struct，讓程式能和設定檔、HTTP API、message queue 等外部格式交換資料。

本章目標

學完本章後，你將能夠：

用 json.Unmarshal 解析 JSON bytes
用 json.Marshal 輸出 JSON bytes
用 json.NewDecoder 解析 stream
用 json.NewEncoder 寫出 response
正確處理 JSON 解析錯誤

【觀察】JSON 解碼是外部資料進入 Go 型別的邊界

JSON 解碼的核心規則是：外部資料必須先進入明確的 Go struct，後續程式才應依賴型別欄位。以下範例把設定檔 JSON 解析成 Config：

 1type Config struct {
 2 AppName string `json:"appName"`
 3 Port int `json:"port"`
 4 Debug bool `json:"debug"`
 5}
 6
 7func LoadConfig(data []byte) (Config, error) {
 8 var cfg Config
 9 if err := json.Unmarshal(data, &cfg); err != nil {
10 return Config{}, fmt.Errorf("parse config JSON: %w", err)
11 }
12 return cfg, nil
13}

json.Unmarshal 需要接收 pointer，因為它要把解析結果寫入 cfg。若傳入 cfg 而不是 &cfg，解碼結果無法寫回呼叫端變數。

【判讀】JSON tag 是解碼與編碼的欄位對照表

JSON tag 的核心規則是：Go 欄位名稱和 JSON 欄位名稱可以不同，但必須在 struct tag 中明確對應。

1type User struct {
2 ID string `json:"id"`
3 Name string `json:"name"`
4 CreatedAt string `json:"createdAt"`
5}

這個 struct 對應的 JSON 是：

1{
2 "id": "u_1",
3 "name": "Alice",
4 "createdAt": "2026-04-22T10:00:00Z"
5}

Go 欄位必須 exported，encoding/json 才能讀寫。小寫開頭欄位是 unexported，JSON package 不會填入。

【策略】bytes 用 Marshal/Unmarshal，stream 用 Encoder/Decoder

JSON API 選擇的核心規則是：資料已經在記憶體中用 Marshal / Unmarshal，資料來自 stream 用 Encoder / Decoder。

情境	適合 API
`[]byte` 解析成 struct	`json.Unmarshal`
struct 轉成 `[]byte`	`json.Marshal`
從 `io.Reader` 讀 JSON	`json.NewDecoder`
寫 JSON 到 `io.Writer`	`json.NewEncoder`

HTTP request body 是 stream，適合用 decoder：

1func decodeCreateUser(r *http.Request) (CreateUserRequest, error) {
2 var req CreateUserRequest
3 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
4 return CreateUserRequest{}, fmt.Errorf("decode request JSON: %w", err)
5 }
6 return req, nil
7}

HTTP response writer 也是 stream，適合用 encoder：

1func writeJSON(w http.ResponseWriter, status int, data any) {
2 w.Header().Set("Content-Type", "application/json")
3 w.WriteHeader(status)
4 _ = json.NewEncoder(w).Encode(data)
5}

【執行】在 HTTP handler 中處理 JSON

HTTP JSON handler 的核心規則是：解析錯誤屬於 client input 問題，通常回 400；內部處理錯誤屬於 server 問題，通常回 500。

 1type CreateUserRequest struct {
 2 Name string `json:"name"`
 3}
 4
 5type CreateUserResponse struct {
 6 ID string `json:"id"`
 7 Name string `json:"name"`
 8}
 9
10func handleCreateUser(w http.ResponseWriter, r *http.Request) {
11 var req CreateUserRequest
12 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
13 writeJSON(w, http.StatusBadRequest, map[string]string{
14 "error": "invalid JSON",
15 })
16 return
17 }
18
19 if req.Name == "" {
20 writeJSON(w, http.StatusBadRequest, map[string]string{
21 "error": "name is required",
22 })
23 return
24 }
25
26 resp := CreateUserResponse{
27 ID: "u_1",
28 Name: req.Name,
29 }
30 writeJSON(w, http.StatusCreated, resp)
31}

這個 handler 把 JSON 邊界處理清楚：先解碼，再驗證，再執行核心邏輯，最後輸出 JSON。

3.4 re - 正規表達式

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

正規表達式（Regular Expression，簡稱 regex 或 re）是一種強大的文字模式匹配工具。在 Hook 系統中，主要用於解析 Markdown 連結和驗證輸入格式。

基本用法

re.search() - 搜尋匹配

1import re
2
3text = "Hello, Python 3.11!"
4
5# 搜尋數字
6match = re.search(r'\d+\.\d+', text)
7if match:
8    print(match.group())  # "3.11"

re.match() - 從開頭匹配

1import re
2
3text = "Python is great"
4
5# 只從字串開頭匹配
6match = re.match(r'Python', text)  # 成功
7match = re.match(r'great', text)   # None（不是從開頭開始）

re.findall() - 找出所有匹配

1import re
2
3text = "Call 123-456-7890 or 098-765-4321"
4
5# 找出所有電話號碼
6phones = re.findall(r'\d{3}-\d{3}-\d{4}', text)
7# ['123-456-7890', '098-765-4321']

re.sub() - 替換

1import re
2
3text = "Hello   World"
4
5# 將多個空格替換為單個
6result = re.sub(r'\s+', ' ', text)
7# "Hello World"

正規表達式語法

基本字元

模式	說明	範例
`.`	任意字元（除換行）	`a.c` 匹配 “abc”, “a1c”
`\d`	數字 [0-9]	`\d+` 匹配 “123”
`\w`	單字字元 [a-zA-Z0-9_]	`\w+` 匹配 “hello”
`\s`	空白字元	`\s+` 匹配空格、tab
`^`	字串開頭	`^Hello`
`$`	字串結尾	`World$`

數量詞

模式	說明	範例
`*`	0 或多次	`a*` 匹配 “”, “a”, “aaa”
`+`	1 或多次	`a+` 匹配 “a”, “aaa”
`?`	0 或 1 次	`a?` 匹配 “”, “a”
`{n}`	恰好 n 次	`a{3}` 匹配 “aaa”
`{n,m}`	n 到 m 次	`a{2,4}` 匹配 “aa”, “aaa”, “aaaa”

群組與擷取

1import re
2
3text = "[Link Text](https://example.com)"
4
5# 使用群組擷取
6match = re.search(r'\[([^\]]+)\]\(([^)]+)\)', text)
7if match:
8    link_text = match.group(1)  # "Link Text"
9    link_url = match.group(2)   # "https://example.com"

實際範例：Markdown 連結檢查

來自 .claude/lib/markdown_link_checker.py：

 1import re
 2
 3class MarkdownLinkChecker:
 4    # Markdown 連結正則表達式
 5    # 匹配 [text](/python/03-stdlib/regex/target) 格式，排除圖片 ![alt](/python/03-stdlib/regex/src)
 6    INLINE_LINK_PATTERN = re.compile(
 7        r'(?
 8    )
 9
10    # 引用式連結定義 [ref]: target
11    REFERENCE_DEF_PATTERN = re.compile(
12        r'^\s*\[([^\]]+)\]:\s*(.+)$',
13        re.MULTILINE
14    )
15
16    # 引用式連結使用 [text][ref]
17    REFERENCE_USE_PATTERN = re.compile(
18        r'\[([^\]]+)\]\[([^\]]+)\]'
19    )

模式解析

r'(? 解析：



  
      
          部分
          說明
      
  
  
      
          (?
          負向前瞻，確保前面不是 !（排除圖片）
      
      
          \[
          匹配字面 [
      
      
          ([^\]]+)
          群組 1：擷取連結文字（一個或多個非 ] 字元）
      
      
          \]
          匹配字面 ]
      
      
          \(
          匹配字面 (
      
      
          ([^)]+)
          群組 2：擷取連結目標（一個或多個非 ) 字元）
      
      
          \)
          匹配字面 )
      
  

使用範例





 1def parse_markdown_links(self, content: str) -> list[dict]:
 2    """解析 Markdown 內容中的所有連結"""
 3    links = []
 4    lines = content.split('\n')
 5
 6    for line_num, line in enumerate(lines, start=1):
 7        # 行內連結 [text](/python/03-stdlib/regex/target)
 8        for match in self.INLINE_LINK_PATTERN.finditer(line):
 9            links.append({
10                "text": match.group(1),
11                "target": match.group(2),
12                "line": line_num
13            })
14
15    return links
編譯正規表達式
對於重複使用的模式，預先編譯可提升效能：





1import re
2
3# 編譯模式
4pattern = re.compile(r'\d+')
5
6# 重複使用
7pattern.search(text1)
8pattern.findall(text2)
9pattern.sub('X', text3)
實際應用：Hook 驗證
來自 .claude/lib/hook_validator.py：





 1class HookValidator:
 2    # 共用模組導入模式
 3    HOOK_IO_PATTERNS = [
 4        r"from\s+hook_io\s+import",
 5        r"from\s+lib\.hook_io\s+import",
 6    ]
 7
 8    # 命名規範模式
 9    VALID_NAME_PATTERNS = [
10        r"^[a-z0-9](/python/03-stdlib/regex/[a-z0-9\-_]*[a-z0-9])?\.py$",
11    ]
12
13    def _has_import(self, content: str, patterns: list[str]) -> bool:
14        """檢查是否有符合任一模式的導入"""
15        return any(
16            re.search(pattern, content)
17            for pattern in patterns
18        )
19
20    def check_naming_convention(self, hook_path: Path) -> list:
21        """檢查命名規範"""
22        filename = hook_path.name
23
24        valid_name = any(
25            re.match(pattern, filename)
26            for pattern in self.VALID_NAME_PATTERNS
27        )
28        # ...
常用旗標
re.IGNORECASE（忽略大小寫）





1import re
2
3re.search(r'hello', 'Hello World', re.IGNORECASE)  # 匹配
re.MULTILINE（多行模式）





1import re
2
3text = """line 1
4line 2
5line 3"""
6
7# 每行開頭的 "line"
8matches = re.findall(r'^line', text, re.MULTILINE)
9# ['line', 'line', 'line']
re.DOTALL（點號匹配換行）





1import re
2
3text = "start\nmiddle\nend"
4
5# 無 DOTALL：. 不匹配換行
6re.search(r'start.*end', text)  # None
7
8# 有 DOTALL：. 匹配換行
9re.search(r'start.*end', text, re.DOTALL)  # 匹配
外部連結判斷





 1class MarkdownLinkChecker:
 2    EXTERNAL_PATTERNS = [
 3        r'^https?://',
 4        r'^mailto:',
 5        r'^tel:',
 6        r'^ftp://',
 7    ]
 8
 9    def _is_external_link(self, target: str) -> bool:
10        """檢查是否為外部連結"""
11        return any(
12            re.match(pattern, target)
13            for pattern in self.EXTERNAL_PATTERNS
14        )
最佳實踐
1. 使用原始字串





1# 好：使用 r'' 避免跳脫問題
2pattern = r'\d+\.\d+'
3
4# 不好：需要雙重跳脫
5pattern = '\\d+\\.\\d+'
2. 預編譯重複使用的模式





1# 好：編譯後重複使用
2pattern = re.compile(r'\d+')
3for text in texts:
4    pattern.findall(text)
5
6# 不好：每次都重新編譯
7for text in texts:
8    re.findall(r'\d+', text)
3. 使用命名群組





1# 有命名群組：更易讀
2pattern = re.compile(r'(?P\d{4})-(?P\d{2})-(?P\d{2})')
3match = pattern.search("2024-01-20")
4if match:
5    print(match.group('year'))   # "2024"
6    print(match.group('month'))  # "01"
思考題

re.search() 和 re.match() 有什麼區別？
為什麼 Markdown 連結模式使用 (? 負向前瞻？

re.compile() 的好處是什麼？

實作練習

寫一個正規表達式，驗證電子郵件格式
從 Python 原始碼中擷取所有函式定義（def function_name(）
實作一個函式，將 Markdown 標題（# Title）轉換為 HTML（Title）


上一章：subprocess - 執行外部命令
下一章：logging - 日誌系統

部分	說明
`(?`	負向前瞻，確保前面不是 `!`（排除圖片）
`\[`	匹配字面 `[`
`([^\]]+)`	群組 1：擷取連結文字（一個或多個非 `]` 字元）
`\]`	匹配字面 `]`
`\(`	匹配字面 `(`
`([^)]+)`	群組 2：擷取連結目標（一個或多個非 `)` 字元）
`\)`	匹配字面 `)`



3.5 net/http 與 handler 設計
Wed, 22 Apr 2026 00:00:00 +0000
Go 的 net/http 把 HTTP endpoint 簡化成一個核心模型：handler 接收 request，然後寫出 response。後端服務可以有複雜的資料庫、queue、背景工作或即時連線，但 HTTP 入口本身應該先保持清楚。
handler 是 HTTP 邊界
HTTP handler 的核心責任是處理協定邊界。它應該讀取 request、驗證輸入、呼叫內部邏輯，最後寫出 status code、header 與 body。





 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    w.WriteHeader(http.StatusOK)
 9    fmt.Fprint(w, `{"status":"ok"}`)
10}
這個 handler 只處理健康檢查：確認 HTTP method，設定回應格式，寫出 JSON。它沒有讀取資料庫，也沒有啟動背景工作，因為健康檢查的責任就是讓呼叫者知道服務是否能回應。
handler 可以呼叫內部服務，但不應該把所有業務規則都塞在 HTTP 層。HTTP 層越薄，測試越容易，未來改成 CLI、queue consumer 或其他入口時也比較不會重寫核心邏輯。
http.HandlerFunc 是函式轉接器
http.HandlerFunc 的核心意義是讓普通函式符合 http.Handler 介面。只要函式形狀是 func(http.ResponseWriter, *http.Request)，就能成為 HTTP handler。





1func hello(w http.ResponseWriter, r *http.Request) {
2    fmt.Fprint(w, "hello")
3}
4
5func main() {
6    http.HandleFunc("/hello", hello)
7    http.ListenAndServe(":8080", nil)
8}
http.HandleFunc 會把 hello 轉成 handler 並註冊到預設 mux。小範例可以這樣寫，但實際應用通常會建立自己的 ServeMux，避免全域註冊讓測試與組裝變得不清楚。





1func newRouter() http.Handler {
2    mux := http.NewServeMux()
3    mux.HandleFunc("/health", handleHealth)
4    mux.HandleFunc("/users", handleUsers)
5    return mux
6}
回傳 http.Handler 可以隱藏路由實作，呼叫端只需要知道這是一個可被 server 使用的 handler。
ServeMux 負責路由分派
ServeMux 的核心責任是把 request path 對應到 handler。標準庫的 http.NewServeMux 足以建立許多小型服務與教學範例。





 1func main() {
 2    mux := http.NewServeMux()
 3    mux.HandleFunc("GET /health", handleHealth)
 4    mux.HandleFunc("POST /users", handleCreateUser)
 5
 6    server := &http.Server{
 7        Addr:    ":8080",
 8        Handler: mux,
 9    }
10
11    if err := server.ListenAndServe(); err != nil {
12        log.Fatal(err)
13    }
14}
新版 Go 的 ServeMux 支援在 pattern 裡寫 HTTP method，例如 GET /health。這能讓 method 與 path 在註冊處一起呈現。
若你的專案需要 middleware group、path parameter 或更完整的路由功能，可以使用第三方 router。入門階段先理解標準庫模型，會更容易看懂任何 router 的抽象。
request 讀取要有明確限制
讀取 request 的核心原則是只接受你預期的內容。handler 應該檢查 method、content type、body 大小與 JSON 格式，避免把任意輸入直接交給內部邏輯。





 1type createUserRequest struct {
 2    Name  string `json:"name"`
 3    Email string `json:"email"`
 4}
 5
 6func handleCreateUser(w http.ResponseWriter, r *http.Request) {
 7    if r.Method != http.MethodPost {
 8        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 9        return
10    }
11
12    defer r.Body.Close()
13    r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
14
15    var req createUserRequest
16    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
17        http.Error(w, "invalid json", http.StatusBadRequest)
18        return
19    }
20
21    if req.Email == "" {
22        http.Error(w, "email is required", http.StatusBadRequest)
23        return
24    }
25
26    w.WriteHeader(http.StatusCreated)
27}
http.MaxBytesReader 限制 body 大小，避免大型輸入消耗過多記憶體。json.Decoder 解析 body，失敗時回傳 400 Bad Request。欄位驗證通過後，handler 才進入真正的建立流程。
這段範例省略了資料儲存，因為本章重點是 HTTP 邊界。實務上通常會把建立使用者的規則放到 service 函式，handler 只負責轉換 request 與 response。
response 要先決定狀態碼
寫 response 的核心規則是先決定 status code，再寫 header 與 body。只要 body 開始寫出，Go 就會送出預設或目前設定的 status code。





1func writeJSON(w http.ResponseWriter, status int, value any) {
2    w.Header().Set("Content-Type", "application/json")
3    w.WriteHeader(status)
4
5    if err := json.NewEncoder(w).Encode(value); err != nil {
6        // response 已經開始寫出，這裡通常只能記錄錯誤。
7        log.Printf("write json response: %v", err)
8    }
9}
WriteHeader 應該在 Encode 之前呼叫。若先寫 body，再呼叫 WriteHeader，狀態碼可能已經固定為 200 OK。





1writeJSON(w, http.StatusCreated, map[string]string{
2    "id": "user_123",
3})
小型範例可以直接在 handler 裡寫 response；當多個 handler 都要輸出 JSON 時，抽出 writeJSON 這類 helper 可以減少重複。
handler 可以依賴介面
handler 依賴介面的核心好處是測試與替換更容易。HTTP 層不需要知道資料來自資料庫、記憶體或遠端 API，只需要知道它可以呼叫某個能力。





 1type UserCreator interface {
 2    CreateUser(ctx context.Context, name string, email string) (string, error)
 3}
 4
 5type UserHandler struct {
 6    creator UserCreator
 7}
 8
 9func (h UserHandler) Create(w http.ResponseWriter, r *http.Request) {
10    // 解析與驗證 request 後：
11    id, err := h.creator.CreateUser(r.Context(), "alice", "alice@example.com")
12    if err != nil {
13        http.Error(w, "create user", http.StatusInternalServerError)
14        return
15    }
16
17    writeJSON(w, http.StatusCreated, map[string]string{"id": id})
18}
這裡的 UserHandler 不知道使用者如何被建立，只知道有一個 UserCreator。測試時可以提供假的 creator，正式環境再接上真正實作。
介面不需要一開始就為所有東西建立。當 handler 真的需要隔離外部依賴，或測試需要替換依賴時，再抽出小介面會更自然。
小結
下一章會回到 logging，說明如何用 slog 讓服務輸出可搜尋、可關聯的結構化資訊。



3.5 logging - 日誌系統
Tue, 20 Jan 2026 00:00:00 +0000
logging 模組提供了靈活的日誌記錄功能。相較於 print()，日誌系統提供了等級控制、格式化和輸出目標管理等功能。
為什麼用 logging 而非 print？





 1# 使用 print 的問題
 2print("Processing started")        # 無法控制輸出等級
 3print(f"Error: {error}")          # 無法區分一般訊息和錯誤
 4print("Debug: x =", x)            # 生產環境也會輸出
 5
 6# 使用 logging 的好處
 7import logging
 8logger = logging.getLogger(__name__)
 9
10logger.info("Processing started")   # 可以控制等級
11logger.error(f"Error: {error}")    # 明確標示為錯誤
12logger.debug(f"x = {x}")           # 只在 DEBUG 模式輸出
日誌等級

  
      
          等級
          數值
          使用時機
      
  
  
      
          DEBUG
          10
          詳細的除錯資訊
      
      
          INFO
          20
          一般的操作資訊
      
      
          WARNING
          30
          警告但程式仍可運行
      
      
          ERROR
          40
          錯誤但程式仍可運行
      
      
          CRITICAL
          50
          嚴重錯誤，程式可能無法繼續
      
  

實際範例：Hook 日誌系統
來自 .claude/lib/hook_logging.py：





 1import logging
 2import os
 3from datetime import datetime
 4from pathlib import Path
 5from typing import Optional
 6
 7
 8def setup_hook_logging(
 9    hook_name: str,
10    log_subdir: Optional[str] = None,
11    log_level: Optional[int] = None,
12    include_stderr: bool = False
13) -> logging.Logger:
14    """
15    設定 Hook 日誌系統
16
17    Args:
18        hook_name: Hook 名稱，用於識別日誌來源
19        log_subdir: 日誌子目錄，預設為 hook_name
20        log_level: 日誌等級，預設根據環境變數決定
21        include_stderr: 是否同時輸出到 stderr
22
23    Returns:
24        logging.Logger: 配置好的 Logger 實例
25    """
26    # 決定日誌等級
27    if log_level is None:
28        debug_mode = os.getenv("HOOK_DEBUG", "").lower() == "true"
29        log_level = logging.DEBUG if debug_mode else logging.INFO
30
31    # 建立 Logger
32    logger = logging.getLogger(hook_name)
33    logger.setLevel(log_level)
34
35    # 避免重複添加 handler
36    if logger.handlers:
37        return logger
38
39    # 建立日誌目錄
40    project_root = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
41    subdir = log_subdir or hook_name
42    log_dir = Path(project_root) / ".claude" / "hook-logs" / subdir
43    log_dir.mkdir(parents=True, exist_ok=True)
44
45    # 日誌檔案路徑
46    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
47    log_file = log_dir / f"{hook_name}-{timestamp}.log"
48
49    # 設定 formatter
50    formatter = logging.Formatter(
51        "[%(asctime)s] %(levelname)s - %(message)s",
52        datefmt="%Y-%m-%d %H:%M:%S"
53    )
54
55    # 檔案 handler
56    file_handler = logging.FileHandler(log_file, encoding="utf-8")
57    file_handler.setFormatter(formatter)
58    logger.addHandler(file_handler)
59
60    # 可選的 stderr handler
61    if include_stderr:
62        import sys
63        stderr_handler = logging.StreamHandler(sys.stderr)
64        stderr_handler.setFormatter(formatter)
65        logger.addHandler(stderr_handler)
66
67    return logger
使用 Logger
在 Hook 腳本中使用





 1#!/usr/bin/env python3
 2from hook_logging import setup_hook_logging
 3
 4# 初始化 logger
 5logger = setup_hook_logging("branch-verify")
 6
 7def main():
 8    logger.info("Hook started")
 9
10    branch = get_current_branch()
11    logger.debug(f"Current branch: {branch}")
12
13    if is_protected_branch(branch):
14        logger.warning(f"Operating on protected branch: {branch}")
15
16    try:
17        # 執行操作
18        result = do_something()
19        logger.info(f"Operation completed: {result}")
20    except Exception as e:
21        logger.error(f"Operation failed: {e}")
22        raise
23
24if __name__ == "__main__":
25    main()
核心概念
Logger
日誌記錄器，用於發送日誌訊息：





1import logging
2
3# 取得 logger（使用模組名稱作為標識）
4logger = logging.getLogger(__name__)
5
6# 或使用自訂名稱
7logger = logging.getLogger("my_app")
Handler
決定日誌輸出到哪裡：





 1import logging
 2
 3logger = logging.getLogger("my_app")
 4
 5# 輸出到檔案
 6file_handler = logging.FileHandler("app.log", encoding="utf-8")
 7logger.addHandler(file_handler)
 8
 9# 輸出到控制台
10console_handler = logging.StreamHandler()
11logger.addHandler(console_handler)
Formatter
決定日誌的格式：





1import logging
2
3formatter = logging.Formatter(
4    "[%(asctime)s] %(levelname)s - %(name)s - %(message)s",
5    datefmt="%Y-%m-%d %H:%M:%S"
6)
7
8handler = logging.FileHandler("app.log")
9handler.setFormatter(formatter)
格式化字串變數

  
      
          變數
          說明
      
  
  
      
          %(asctime)s
          時間戳
      
      
          %(levelname)s
          日誌等級名稱
      
      
          %(name)s
          Logger 名稱
      
      
          %(message)s
          日誌訊息
      
      
          %(filename)s
          檔案名稱
      
      
          %(lineno)d
          行號
      
      
          %(funcName)s
          函式名稱
      
  

實用技巧
避免重複 Handler





 1def setup_logger(name: str) -> logging.Logger:
 2    logger = logging.getLogger(name)
 3    logger.setLevel(logging.INFO)
 4
 5    # 重要：檢查是否已有 handler
 6    if logger.handlers:
 7        return logger
 8
 9    handler = logging.FileHandler("app.log")
10    logger.addHandler(handler)
11    return logger
環境變數控制日誌等級





 1import os
 2import logging
 3
 4def get_log_level() -> int:
 5    """從環境變數取得日誌等級"""
 6    level_name = os.getenv("LOG_LEVEL", "INFO").upper()
 7    return getattr(logging, level_name, logging.INFO)
 8
 9logger = logging.getLogger(__name__)
10logger.setLevel(get_log_level())
日誌輪替





1from logging.handlers import RotatingFileHandler
2
3handler = RotatingFileHandler(
4    "app.log",
5    maxBytes=10*1024*1024,  # 10MB
6    backupCount=5           # 保留 5 個備份
7)
日誌檔案結構
Hook 系統的日誌結構：





1.claude/hook-logs/
2├── branch-verify/
3│   ├── branch-verify-20240120-153000.log
4│   └── branch-verify-20240120-160000.log
5├── ticket-quality-gate/
6│   └── ticket-quality-gate-20240120-155000.log
7└── ...
最佳實踐
1. 使用 __name__ 作為 Logger 名稱





1import logging
2
3# 好：使用模組名稱，便於追蹤
4logger = logging.getLogger(__name__)
5
6# 不好：使用固定字串，難以區分來源
7logger = logging.getLogger("my_logger")
2. 在適當的等級記錄訊息





1logger.debug("Variable x = %s", x)           # 詳細除錯
2logger.info("Processing file %s", filename)  # 一般操作
3logger.warning("Config not found, using default")  # 警告
4logger.error("Failed to connect: %s", error)  # 錯誤
3. 使用延遲格式化





1# 好：使用 % 格式化（只在需要時才格式化）
2logger.debug("Data: %s", expensive_function())
3
4# 不好：f-string 總是會執行
5logger.debug(f"Data: {expensive_function()}")
思考題

為什麼 setup_hook_logging 要檢查 logger.handlers？
logging.DEBUG 和 logging.INFO 的差別是什麼？什麼時候用哪個？
如何讓日誌同時輸出到檔案和控制台？

實作練習

修改 setup_hook_logging，添加日誌輪替功能
實作一個裝飾器，自動記錄函式的進入和離開
建立一個日誌分析腳本，統計各等級日誌的數量


上一章：re - 正規表達式
下一章：argparse - CLI 介面



3.6 log/slog：結構化日誌
Wed, 22 Apr 2026 00:00:00 +0000
log/slog 是 Go 標準庫提供的結構化日誌 package。它的核心用途是把 log 寫成「訊息 + key-value 欄位」，讓人類能讀，也讓工具能搜尋、過濾與聚合。
本章目標
學完本章後，你將能夠：

建立 text 或 JSON logger
使用 log level 區分訊號重要性
用 key-value 欄位保存可查詢資訊
設計穩定的 log 欄位名稱
避免把所有資訊塞進自由文字


【觀察】結構化日誌把資訊放進欄位
結構化日誌的核心規則是：穩定資訊放欄位，敘述文字只描述事件。以下範例記錄一筆 user 建立事件：





1logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
2
3logger.Info(
4 "user created",
5 "userID", "u_1",
6 "email", "alice@example.com",
7)
JSON handler 會輸出類似：





1{
2 "time": "2026-04-22T10:00:00Z",
3 "level": "INFO",
4 "msg": "user created",
5 "userID": "u_1",
6 "email": "alice@example.com"
7}
這比 fmt.Printf("user u_1 alice@example.com created") 更容易被查詢。
【判讀】level 表示事件嚴重度
log level 的核心規則是：level 表示事件需要多少注意力，不表示程式碼所在位置。

 
 
 level
 適用情境
 
 
 
 
 Debug
 開發或診斷細節
 
 
 Info
 正常但重要的狀態變化
 
 
 Warn
 可恢復但需要注意的異常
 
 
 Error
 操作失敗或需要處理的錯誤
 
 

範例：





1logger.Debug("cache miss", "key", key)
2logger.Info("server started", "addr", addr)
3logger.Warn("queue full", "dropped", count)
4logger.Error("write file failed", "path", path, "error", err)
Error log 應該包含 error 欄位，讓讀者知道失敗原因。
【策略】欄位名稱要穩定
log 欄位設計的核心規則是：同一個概念使用同一個欄位名稱，不要在不同地方混用別名。

 
 
 概念
 建議欄位
 
 
 
 
 使用者 ID
 userID
 
 
 request ID
 requestID
 
 
 工作 ID
 jobID
 
 
 元件名稱
 component
 
 
 錯誤
 error
 
 

不要這樣混用：





1logger.Info("job queued", "id", job.ID)
2logger.Info("job started", "job_id", job.ID)
3logger.Info("job done", "jobID", job.ID)
應該統一：





1logger.Info("job queued", "jobID", job.ID)
2logger.Info("job started", "jobID", job.ID)
3logger.Info("job done", "jobID", job.ID)
欄位穩定後，grep、log query、dashboard 才能可靠。
【執行】建立帶預設欄位的 logger
預設欄位的核心規則是：每筆 log 都需要的上下文，應該掛在 logger 上，而不是每次手動重複。





 1base := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
 2 Level: slog.LevelInfo,
 3}))
 4
 5logger := base.With(
 6 "component", "worker",
 7 "version", "1.0.0",
 8)
 9
10logger.Info("job started", "jobID", "j_1")
11logger.Info("job finished", "jobID", "j_1")
With 會回傳帶有固定欄位的新 logger。這適合 component、version、requestID 這類上下文。
設計檢查
把所有資訊塞進 msg
不佳：





1logger.Info("job j_1 for user u_1 started")
較佳：





1logger.Info("job started", "jobID", "j_1", "userID", "u_1")
第二種寫法可以直接查 jobID=j_1 或 userID=u_1。
欄位名稱不穩定
欄位名稱不穩定會讓查詢失效。選定 userID 就一路使用 userID，不要混用 uid、user_id、user。
忽略敏感資訊
log 會被保存與轉發。密碼、token、完整信用卡號等敏感資訊不應寫入 log。
延伸閱讀
本章只介紹標準庫 log/slog 的基本用法。服務開始有 domain event、state repository 或查詢需求時，可以接著閱讀 如何新增結構化記錄欄位；進入生產操作後，再閱讀 Go 進階：結構化日誌欄位設計 與 Observability pipeline、metrics 與 tracing。


3.6 argparse - CLI 介面
Tue, 20 Jan 2026 00:00:00 +0000
argparse 是 Python 標準庫中用於建立命令列介面（CLI）的模組。它能自動生成幫助訊息、處理各種參數類型，並進行輸入驗證。
基本用法
最簡單的 CLI





1import argparse
2
3parser = argparse.ArgumentParser(description="我的程式")
4parser.add_argument("filename", help="要處理的檔案")
5args = parser.parse_args()
6
7print(f"處理檔案: {args.filename}")
執行：





 1$ python script.py myfile.txt
 2處理檔案: myfile.txt
 3
 4$ python script.py --help
 5usage: script.py [-h] filename
 6
 7我的程式
 8
 9positional arguments:
10  filename    要處理的檔案
11
12options:
13  -h, --help  show this help message and exit
參數類型
位置參數（Positional Arguments）
必須提供的參數：





1parser.add_argument("filename")
2# 使用: python script.py myfile.txt
可選參數（Optional Arguments）
使用 - 或 -- 開頭：





1parser.add_argument("-v", "--verbose", action="store_true")
2parser.add_argument("-o", "--output", default="output.txt")
3# 使用: python script.py -v -o result.txt
布林旗標





1# store_true：出現時為 True
2parser.add_argument("--debug", action="store_true")
3
4# store_false：出現時為 False
5parser.add_argument("--no-cache", action="store_false", dest="cache")
實際範例：Hook 驗證器
來自 .claude/lib/hook_validator.py：





 1def main():
 2    """命令行介面"""
 3    parser = argparse.ArgumentParser(
 4        description="Hook 合規性驗證工具",
 5        formatter_class=argparse.RawDescriptionHelpFormatter,
 6        epilog="""
 7使用範例:
 8  # 驗證單一 Hook
 9  python hook_validator.py .claude/hooks/my-hook.py
10
11  # 驗證所有 Hook
12  python hook_validator.py --all
13
14  # 輸出 JSON 格式
15  python hook_validator.py --all --json
16
17  # 自訂 Hook 目錄
18  python hook_validator.py --all --dir .claude/hooks
19        """
20    )
21
22    parser.add_argument(
23        "hook_path",
24        nargs="?",
25        help="Hook 檔案路徑（相對或絕對）"
26    )
27    parser.add_argument(
28        "--all",
29        action="store_true",
30        help="驗證所有 Hook 檔案"
31    )
32    parser.add_argument(
33        "--dir",
34        help="自訂 Hook 目錄路徑（預設 .claude/hooks）"
35    )
36    parser.add_argument(
37        "--json",
38        action="store_true",
39        help="輸出 JSON 格式"
40    )
41    parser.add_argument(
42        "--strict",
43        action="store_true",
44        help="嚴格模式：將 warning 視為 error"
45    )
46
47    args = parser.parse_args()
48
49    # 根據參數執行不同邏輯
50    if args.all:
51        results = validate_all_hooks(hooks_dir=args.dir)
52    elif args.hook_path:
53        results = [validate_hook(args.hook_path)]
54    else:
55        parser.print_help()
56        sys.exit(1)
57
58    # 輸出結果
59    if args.json:
60        print(json.dumps(output, ensure_ascii=False, indent=2))
61    else:
62        print(format_validation_report(results))
常用參數選項
nargs - 參數數量





 1# 單一值（預設）
 2parser.add_argument("filename")
 3
 4# 可選（0 或 1）
 5parser.add_argument("output", nargs="?", default="out.txt")
 6
 7# 零或多個
 8parser.add_argument("files", nargs="*")
 9
10# 一或多個
11parser.add_argument("files", nargs="+")
12
13# 固定數量
14parser.add_argument("point", nargs=2, type=int)  # 需要兩個整數
type - 型別轉換





1# 整數
2parser.add_argument("--count", type=int, default=10)
3
4# 浮點數
5parser.add_argument("--ratio", type=float)
6
7# 檔案路徑
8from pathlib import Path
9parser.add_argument("--config", type=Path)
choices - 限制選項





1parser.add_argument(
2    "--format",
3    choices=["json", "yaml", "text"],
4    default="text",
5    help="輸出格式"
6)
default - 預設值





1parser.add_argument("--timeout", type=int, default=30)
2parser.add_argument("--verbose", action="store_true")  # 預設 False
required - 強制必填





1parser.add_argument("--config", required=True)
dest - 屬性名稱





1parser.add_argument("--no-cache", action="store_false", dest="use_cache")
2# args.use_cache 而非 args.no_cache
實際範例：Markdown 連結檢查器
來自 .claude/lib/markdown_link_checker.py：





 1def main():
 2    """命令行介面"""
 3    parser = argparse.ArgumentParser(
 4        description="Markdown 連結檢查工具",
 5        formatter_class=argparse.RawDescriptionHelpFormatter,
 6        epilog="""
 7使用範例:
 8  # 檢查單一文件
 9  python markdown_link_checker.py docs/README.md
10
11  # 檢查整個目錄
12  python markdown_link_checker.py --dir .claude/methodologies/
13
14  # JSON 輸出
15  python markdown_link_checker.py --dir docs/ --json
16
17  # 只檢查當前目錄（不遞迴）
18  python markdown_link_checker.py --dir docs/ --no-recursive
19        """
20    )
21
22    parser.add_argument(
23        "file_path",
24        nargs="?",
25        help="Markdown 檔案路徑"
26    )
27    parser.add_argument(
28        "--dir",
29        help="要檢查的目錄路徑"
30    )
31    parser.add_argument(
32        "--json",
33        action="store_true",
34        help="輸出 JSON 格式"
35    )
36    parser.add_argument(
37        "--no-recursive",
38        action="store_true",
39        help="不遞迴檢查子目錄"
40    )
41
42    args = parser.parse_args()
43
44    # 決定工作模式
45    if args.dir:
46        results = checker.check_directory(
47            args.dir,
48            recursive=not args.no_recursive
49        )
50    elif args.file_path:
51        results = [checker.check_file(args.file_path)]
52    else:
53        parser.print_help()
54        sys.exit(1)
進階技巧
參數群組





1parser = argparse.ArgumentParser()
2
3# 必要參數群組
4required = parser.add_argument_group("required arguments")
5required.add_argument("--config", required=True)
6
7# 可選參數群組
8optional = parser.add_argument_group("optional arguments")
9optional.add_argument("--verbose", action="store_true")
互斥參數





1group = parser.add_mutually_exclusive_group()
2group.add_argument("--json", action="store_true")
3group.add_argument("--yaml", action="store_true")
4# 只能選擇其中一個
子命令





 1parser = argparse.ArgumentParser()
 2subparsers = parser.add_subparsers(dest="command")
 3
 4# add 子命令
 5add_parser = subparsers.add_parser("add", help="新增項目")
 6add_parser.add_argument("name")
 7
 8# list 子命令
 9list_parser = subparsers.add_parser("list", help="列出項目")
10list_parser.add_argument("--all", action="store_true")
11
12args = parser.parse_args()
13if args.command == "add":
14    # 處理 add
15    pass
16elif args.command == "list":
17    # 處理 list
18    pass
完整範例模板





 1#!/usr/bin/env python3
 2"""
 3我的 CLI 工具
 4
 5使用方式:
 6    python my_tool.py input.txt -o output.txt --verbose
 7"""
 8
 9import argparse
10import sys
11
12
13def create_parser() -> argparse.ArgumentParser:
14    """建立參數解析器"""
15    parser = argparse.ArgumentParser(
16        description="我的 CLI 工具",
17        formatter_class=argparse.RawDescriptionHelpFormatter,
18        epilog="範例: python my_tool.py input.txt -o output.txt"
19    )
20
21    parser.add_argument(
22        "input",
23        help="輸入檔案"
24    )
25    parser.add_argument(
26        "-o", "--output",
27        default="output.txt",
28        help="輸出檔案 (預設: output.txt)"
29    )
30    parser.add_argument(
31        "-v", "--verbose",
32        action="store_true",
33        help="詳細輸出"
34    )
35    parser.add_argument(
36        "--version",
37        action="version",
38        version="%(prog)s 1.0.0"
39    )
40
41    return parser
42
43
44def main():
45    parser = create_parser()
46    args = parser.parse_args()
47
48    if args.verbose:
49        print(f"Input: {args.input}")
50        print(f"Output: {args.output}")
51
52    # 主要邏輯
53    process(args.input, args.output)
54
55
56if __name__ == "__main__":
57    main()
最佳實踐
1. 提供有意義的 help 訊息





1parser.add_argument(
2    "--timeout",
3    type=int,
4    default=30,
5    help="超時時間（秒），預設 30"  # 說明用途和預設值
6)
2. 使用 epilog 提供使用範例





1parser = argparse.ArgumentParser(
2    epilog="""
3範例:
4  %(prog)s file.txt                    # 處理單一檔案
5  %(prog)s -d ./data --recursive       # 遞迴處理目錄
6    """
7)
3. 合理的 exit code





1if not results:
2    sys.exit(0)  # 成功
3else:
4    sys.exit(1)  # 失敗
思考題

nargs="?" 和 nargs="*" 有什麼區別？
為什麼 --no-recursive 使用 action="store_true" 而不是 store_false？
如何實作一個同時支援 --verbose 和 -v 的參數？

實作練習

為現有的 Python 腳本添加 CLI 介面
實作一個支援子命令的 CLI 工具
建立一個參數驗證函式，檢查檔案是否存在


上一章：logging - 日誌系統
下一模組：物件導向設計



3.7 context：取消、逾時與生命週期
Wed, 22 Apr 2026 00:00:00 +0000
context.Context 是 Go 用來傳遞取消訊號、逾時與 request-scoped 資訊的標準機制。它的核心用途是讓一串呼叫知道「這件工作是否應該停止」。
本章目標
學完本章後，你將能夠：

理解 context 的取消語義
使用 context.WithCancel
使用 context.WithTimeout
在 goroutine 和函式呼叫鏈中傳遞 context
避免把 context 當成一般資料容器


【觀察】context 表示工作生命週期
context 的核心規則是：被取消的 context 代表這件工作不應繼續進行。長時間工作應定期檢查 ctx.Done()：





 1func Run(ctx context.Context) error {
 2 for {
 3 select {
 4 case <-ctx.Done():
 5 return ctx.Err()
 6 default:
 7 doOneStep()
 8 }
 9 }
10}
ctx.Done() 是一個 channel。當 context 被取消或逾時，這個 channel 會被關閉。
【判讀】取消是由上層傳給下層
context 的方向規則是：上層建立 context，下層接收 context；下層不應保存 context，也不應自行決定整個系統的生命週期。





1func main() {
2 ctx, cancel := context.WithCancel(context.Background())
3 defer cancel()
4
5 go worker(ctx)
6
7 waitForSignal()
8 cancel()
9}
context.Background() 是根 context。context.WithCancel 回傳子 context 和 cancel 函式。當 cancel() 被呼叫，所有使用該 context 的下層工作都會收到停止訊號。
【策略】逾時用 WithTimeout，主動停止用 WithCancel
context 建立方式的核心規則是：不知道何時停止但需要手動停止，用 WithCancel；有明確時間限制，用 WithTimeout。





1ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
2defer cancel()
3
4if err := fetchData(ctx); err != nil {
5 return err
6}
下層函式應該接收 context：





 1func fetchData(ctx context.Context) error {
 2 req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.com", nil)
 3 if err != nil {
 4 return err
 5 }
 6
 7 resp, err := http.DefaultClient.Do(req)
 8 if err != nil {
 9 return err
10 }
11 defer resp.Body.Close()
12 return nil
13}
當 timeout 到達，HTTP request 會被取消。
【執行】讓背景 goroutine 有序退出
背景 goroutine 的核心規則是：啟動時接收 context，迴圈中用 select 同時等待工作與取消訊號。





 1func worker(ctx context.Context, jobs <-chan Job) {
 2 for {
 3 select {
 4 case <-ctx.Done():
 5 return
 6 case job, ok := <-jobs:
 7 if !ok {
 8 return
 9 }
10 handleJob(job)
11 }
12 }
13}
這個 worker 有兩種退出路徑：

 
 
 退出原因
 對應 case
 
 
 
 
 上層取消
 <-ctx.Done()
 
 
 job channel 關閉
 ok == false
 
 

這比讓 goroutine 無限跑更安全，也比較容易測試。
設計檢查
把 context 存進 struct
context 的生命週期屬於單次操作，不應長期存在 struct 裡。通常把 context 作為函式第一個參數：





1func (s *Service) Do(ctx context.Context, input Input) error
忘記呼叫 cancel
WithCancel、WithTimeout、WithDeadline 回傳的 cancel 應該被呼叫，釋放相關資源：





1ctx, cancel := context.WithTimeout(parent, time.Second)
2defer cancel()
用 context 傳一般參數
context value 適合 request-scoped metadata，例如 request ID。一般業務參數應放在函式參數或 struct 裡。


3.7 並行處理 - threading、multiprocessing、concurrent.futures
Tue, 20 Jan 2026 00:00:00 +0000
Python 提供了多種並行處理的方式。本章介紹三個核心模組，幫助你根據任務特性選擇合適的方案。
為什麼需要並行處理？
在實際開發中，我們常遇到需要同時處理多個任務的情況：





1# 情境 1：批次下載多個檔案（I/O 密集）
2urls = ["https://example.com/file1", "https://example.com/file2", ...]
3# 一個一個下載太慢了！
4
5# 情境 2：處理大量資料（CPU 密集）
6data_chunks = [chunk1, chunk2, chunk3, ...]
7# 能不能同時處理多個資料區塊？
並行處理可以顯著提升這類任務的效率。
I/O 密集 vs CPU 密集
在選擇並行方案之前，首先要判斷你的任務類型：
I/O 密集任務
程式大部分時間在「等待」外部資源：

網路請求（HTTP、API 呼叫）
檔案讀寫
資料庫查詢






1# I/O 密集的特徵：大部分時間在等待
2def fetch_data():
3    response = requests.get(url)  # 等待網路回應
4    return response.json()
CPU 密集任務
程式大部分時間在「計算」：

數學運算
資料處理與轉換
圖像處理






1# CPU 密集的特徵：大部分時間在計算
2def compute_heavy(n):
3    return sum(i * i for i in range(n))  # 純計算
GIL（全域直譯器鎖）
在深入各模組之前，需要先了解 Python 的一個重要機制。
什麼是 GIL？
GIL（Global Interpreter Lock）是 CPython 直譯器的一個機制，它確保同一時間只有一個執行緒能執行 Python bytecode。





 1┌─────────────────────────────────────────┐
 2│              Python 直譯器                │
 3│  ┌─────┐  ┌─────┐  ┌─────┐              │
 4│  │執行緒1│  │執行緒2│  │執行緒3│              │
 5│  └──┬──┘  └──┬──┘  └──┬──┘              │
 6│     │        │        │                 │
 7│     └────────┼────────┘                 │
 8│              ▼                          │
 9│         ┌───────┐                       │
10│         │  GIL  │ ← 同時只有一個能執行      │
11│         └───────┘                       │
12└─────────────────────────────────────────┘
GIL 的影響

  
      
          任務類型
          GIL 影響
          原因
      
  
  
      
          I/O 密集
          影響小
          等待 I/O 時會釋放 GIL
      
      
          CPU 密集
          影響大
          多執行緒無法真正並行計算
      
  

這就是為什麼：

I/O 密集：使用 threading 即可
CPU 密集：需要使用 multiprocessing 繞過 GIL


注意：Python 3.13+ 推出了 Free-threading（無 GIL）版本，詳見 3.8 Free-Threading
threading 模組
threading 模組提供執行緒級別的並行，適合 I/O 密集任務。
基本用法





 1import threading
 2import time
 3
 4def worker(name, delay):
 5    print(f"{name} 開始工作")
 6    time.sleep(delay)  # 模擬 I/O 等待
 7    print(f"{name} 完成工作")
 8
 9# 建立執行緒
10t1 = threading.Thread(target=worker, args=("Worker-1", 2))
11t2 = threading.Thread(target=worker, args=("Worker-2", 1))
12
13# 啟動執行緒
14t1.start()
15t2.start()
16
17# 等待執行緒完成
18t1.join()
19t2.join()
20
21print("所有工作完成")
執行緒安全與 Lock
當多個執行緒存取共享資源時，需要使用鎖來避免競爭條件：





 1import threading
 2
 3counter = 0
 4lock = threading.Lock()
 5
 6def increment():
 7    global counter
 8    for _ in range(100000):
 9        with lock:  # 使用 context manager 自動獲取和釋放鎖
10            counter += 1
11
12# 建立多個執行緒
13threads = [threading.Thread(target=increment) for _ in range(5)]
14
15for t in threads:
16    t.start()
17for t in threads:
18    t.join()
19
20print(f"Counter: {counter}")  # 應該是 500000
何時使用 threading

網路請求（HTTP、API）
檔案讀寫
資料庫操作
任何需要等待外部資源的任務

multiprocessing 模組
multiprocessing 模組使用多個進程來實現真正的並行，繞過 GIL 限制。
基本用法





 1from multiprocessing import Process
 2
 3def cpu_intensive(n):
 4    """CPU 密集計算"""
 5    result = sum(i * i for i in range(n))
 6    print(f"計算完成: {result}")
 7
 8if __name__ == "__main__":  # 在 Windows 上必須使用這個保護
 9    processes = []
10    for i in range(4):
11        p = Process(target=cpu_intensive, args=(10_000_000,))
12        processes.append(p)
13        p.start()
14
15    for p in processes:
16        p.join()
17
18    print("所有計算完成")
進程間通訊
進程之間不共享記憶體，需要使用 Queue 或 Pipe 來通訊：





 1from multiprocessing import Process, Queue
 2
 3def worker(queue, n):
 4    result = sum(i * i for i in range(n))
 5    queue.put(result)  # 將結果放入佇列
 6
 7if __name__ == "__main__":
 8    queue = Queue()
 9    processes = []
10
11    for i in range(4):
12        p = Process(target=worker, args=(queue, 5_000_000))
13        processes.append(p)
14        p.start()
15
16    for p in processes:
17        p.join()
18
19    # 收集結果
20    results = [queue.get() for _ in range(4)]
21    print(f"結果: {results}")
何時使用 multiprocessing

CPU 密集計算
資料處理與轉換
需要真正並行執行的任務

concurrent.futures（推薦入門）
concurrent.futures 提供了更高階、更簡潔的 API，統一了執行緒和進程的使用方式。
ThreadPoolExecutor
適合 I/O 密集任務：





 1from concurrent.futures import ThreadPoolExecutor
 2import urllib.request
 3
 4def fetch_url(url):
 5    """下載網頁並返回大小"""
 6    try:
 7        with urllib.request.urlopen(url, timeout=10) as response:
 8            return url, len(response.read())
 9    except Exception as e:
10        return url, f"Error: {e}"
11
12urls = [
13    "https://www.python.org",
14    "https://docs.python.org",
15    "https://pypi.org",
16]
17
18# 使用執行緒池並行下載
19with ThreadPoolExecutor(max_workers=3) as executor:
20    results = list(executor.map(fetch_url, urls))
21
22for url, size in results:
23    print(f"{url}: {size}")
ProcessPoolExecutor
適合 CPU 密集任務：





 1from concurrent.futures import ProcessPoolExecutor, as_completed
 2
 3def compute_heavy(n):
 4    """CPU 密集計算"""
 5    return n, sum(i * i for i in range(n))
 6
 7if __name__ == "__main__":
 8    numbers = [10_000_000, 20_000_000, 15_000_000, 5_000_000]
 9
10    with ProcessPoolExecutor() as executor:
11        # 方法 1：使用 map（保持順序）
12        results = list(executor.map(compute_heavy, numbers))
13
14        # 方法 2：使用 submit + as_completed（先完成先處理）
15        futures = {executor.submit(compute_heavy, n): n for n in numbers}
16        for future in as_completed(futures):
17            n, result = future.result()
18            print(f"n={n}: {result}")
處理異常





 1from concurrent.futures import ThreadPoolExecutor, as_completed
 2
 3def risky_task(n):
 4    if n == 3:
 5        raise ValueError("不喜歡 3！")
 6    return n * 2
 7
 8with ThreadPoolExecutor(max_workers=4) as executor:
 9    futures = {executor.submit(risky_task, i): i for i in range(5)}
10
11    for future in as_completed(futures):
12        n = futures[future]
13        try:
14            result = future.result()
15            print(f"任務 {n} 完成: {result}")
16        except Exception as e:
17            print(f"任務 {n} 失敗: {e}")
選擇指南

  
      
          任務類型
          推薦方案
          原因
      
  
  
      
          I/O 密集
          ThreadPoolExecutor
          輕量、共享記憶體、GIL 影響小
      
      
          CPU 密集
          ProcessPoolExecutor
          繞過 GIL、真正並行
      
      
          需要細控制
          threading/multiprocessing
          底層 API、更多控制
      
      
          Python 3.14+ CPU 密集
          threading + Free-threading
          真正的多執行緒並行
      
  

決策流程





 1任務類型是什麼？
 2    │
 3    ├─→ I/O 密集（網路、檔案、DB）
 4    │       │
 5    │       └─→ 使用 ThreadPoolExecutor
 6    │
 7    └─→ CPU 密集（計算、處理）
 8            │
 9            ├─→ Python 3.14+ Free-threaded
10            │       │
11            │       └─→ 可以使用 threading
12            │
13            └─→ 傳統 Python
14                    │
15                    └─→ 使用 ProcessPoolExecutor
常見陷阱與最佳實踐
1. 設定合理的 worker 數量





1import os
2
3# I/O 密集：可以設定較多的 worker
4io_workers = min(32, os.cpu_count() + 4)
5
6# CPU 密集：不要超過 CPU 核心數
7cpu_workers = os.cpu_count()
2. 避免共享可變狀態





 1# 不好：共享可變狀態
 2results = []
 3
 4def bad_worker(n):
 5    results.append(n * 2)  # 危險！多執行緒存取
 6
 7# 好：返回結果，由主執行緒收集
 8def good_worker(n):
 9    return n * 2
10
11with ThreadPoolExecutor() as executor:
12    results = list(executor.map(good_worker, range(10)))
3. 使用 context manager





1# 好：使用 with 語句自動管理資源
2with ThreadPoolExecutor(max_workers=4) as executor:
3    results = executor.map(task, items)
4
5# 不好：手動管理
6executor = ThreadPoolExecutor(max_workers=4)
7results = executor.map(task, items)
8executor.shutdown(wait=True)  # 容易忘記
4. multiprocessing 的 if __name__ == "__main__" 保護





 1from multiprocessing import Process
 2
 3def worker():
 4    print("Working...")
 5
 6# Windows 上必須使用這個保護，否則會無限遞迴
 7if __name__ == "__main__":
 8    p = Process(target=worker)
 9    p.start()
10    p.join()
思考題

為什麼 I/O 密集任務使用 threading 就夠了，而 CPU 密集任務需要 multiprocessing？
ThreadPoolExecutor 和手動建立 Thread 有什麼優缺點？
在什麼情況下，並行處理反而會比序列處理更慢？

實作練習

寫一個函式，使用 ThreadPoolExecutor 同時檢查多個網址是否可以連線
使用 ProcessPoolExecutor 計算一組大數字的質因數分解
實作一個進度顯示器，顯示多個任務的完成進度

延伸閱讀（進階系列）

實戰效能優化：並行處理 - 真實案例的並行化改造
asyncio 非同步程式設計 - 學習協程與事件迴圈
GIL 與執行緒模型 - 深入理解 GIL 的設計與實現
Free-Threading - Python 3.13+ 無 GIL 多執行緒


上一章：argparse - CLI 介面
下一章：效能迷思與優化策略



3.8 defer 與資源清理
Wed, 22 Apr 2026 00:00:00 +0000
defer 的核心用途是把資源清理放在取得資源的附近。檔案、鎖、response body、temporary resource 與測試 cleanup 都適合用 defer 表達「離開這個 scope 前要完成的事」。
預計補充內容
這些資源清理邊界會在下列章節展開：

Go 進階：select loop 的生命週期設計：長生命週期的 goroutine 會怎麼收尾，和 defer 的 scope 觀念直接相關。
Go 進階：graceful shutdown 與 signal handling：當 process 要停下來時，defer 常常是 cleanup 的最後一道保險。
Go 入門：testing 基礎：測試裡的資源回收與 t.Cleanup，會比單純 close 更能說清楚責任。

與 Go 進階的關係
本章建立基本資源清理語感。長時間 worker、WebSocket pump 與 graceful shutdown 會在 Go 進階：select loop 的生命週期設計 與 graceful shutdown 與 signal handling 中延伸。
和 Go 教材的關係
這一章承接的是資源生命週期、goroutine 停止與 shutdown；如果你要先回看語言教材，可以讀：

Go：goroutine：輕量並發工作
Go：select：同時等待多種事件
Go 進階：goroutine leak 偵測
Go 進階：graceful shutdown 與 signal handling



3.8 效能迷思與優化策略
Tue, 20 Jan 2026 00:00:00 +0000
「Python 很慢」是程式設計社群中最常見的說法之一。本章將探討這個說法的真相、何時效能真的重要，以及如何有效地優化 Python 程式。
Python「慢」的真相
直譯語言 vs 編譯語言
Python 是直譯語言，程式碼在執行時才被轉換成機器碼：





1編譯語言（C/C++/Rust）：
2原始碼 → 編譯器 → 機器碼 → 執行
3                    ↑
4              一次編譯，多次執行
5
6直譯語言（Python）：
7原始碼 → 直譯器 → 逐行執行
8              ↑
9         每次執行都要解釋
這意味著 Python 在純計算任務上確實比編譯語言慢，通常是 10-100 倍的差距。
但這重要嗎？
讓我們看一個來自 Reddit 社群的經典回答：

「如果你要問 Python 是不是太慢，那就不關你的事。」
— Reddit 用戶 scandii
這聽起來很直接，但背後有深刻的道理：





 1# 情境 1：網頁後端
 2# Python 處理請求：50ms
 3# 網路延遲：200ms
 4# 資料庫查詢：100ms
 5# 總計：350ms
 6#
 7# 就算 Python 快 10 倍（5ms），總時間也只變成 305ms
 8# 用戶感受差異：幾乎沒有
 9
10# 情境 2：命令列工具
11# 執行時間：0.5 秒
12# 用戶可接受？當然可以
設計哲學的取捨
Python 的設計哲學是「開發速度 > 執行速度」：

  
      
          面向
          Python
          C++
      
  
  
      
          開發時間
          短
          長
      
      
          執行速度
          慢
          快
      
      
          程式碼可讀性
          高
          中
      
      
          除錯難度
          低
          高
      
      
          學習曲線
          緩
          陡
      
  

對於大多數應用來說，開發效率和維護成本遠比執行速度重要。
真正的瓶頸在哪裡？
在優化之前，你需要先找出真正的瓶頸。以下是常見的效能瓶頸排名：
1. I/O 操作





 1import time
 2import requests
 3
 4# 網路請求：通常是最大的瓶頸
 5start = time.perf_counter()
 6response = requests.get("https://api.example.com/data")  # 50-500ms
 7print(f"網路請求: {time.perf_counter() - start:.3f}s")
 8
 9# 檔案讀寫
10start = time.perf_counter()
11with open("large_file.txt", "r") as f:
12    content = f.read()  # 取決於檔案大小和硬碟速度
13print(f"檔案讀取: {time.perf_counter() - start:.3f}s")
2. 資料庫查詢





 1# 一個沒有索引的查詢可能需要幾秒鐘
 2# SELECT * FROM users WHERE email = '...'  # 無索引：慢
 3# SELECT * FROM users WHERE id = 123       # 有索引：快
 4
 5# N+1 查詢問題
 6for user in users:
 7    orders = get_orders(user.id)  # 每個用戶一次查詢 → 很慢
 8
 9# 應該改成
10orders = get_orders_for_users([u.id for u in users])  # 一次查詢
3. 演算法複雜度





 1# O(n²) vs O(n) 的差異遠大於語言差異
 2
 3# O(n²) - 10000 個元素需要 100,000,000 次操作
 4def find_duplicates_slow(items):
 5    duplicates = []
 6    for i, item in enumerate(items):
 7        for j, other in enumerate(items):
 8            if i != j and item == other:
 9                duplicates.append(item)
10    return duplicates
11
12# O(n) - 10000 個元素只需要 10000 次操作
13def find_duplicates_fast(items):
14    seen = set()
15    duplicates = []
16    for item in items:
17        if item in seen:
18            duplicates.append(item)
19        seen.add(item)
20    return duplicates
瓶頸排名





1通常的效能瓶頸（由大到小）：
21. 網路延遲         100-1000ms
32. 資料庫查詢        10-1000ms
43. 檔案 I/O          1-100ms
54. 演算法複雜度      視情況
65. Python 本身        0.001-1ms
優化方案總覽

  
      
          方案
          適用場景
          學習成本
          效果
      
  
  
      
          演算法優化
          通用
          中
          最高
      
      
          NumPy/Pandas
          數值計算
          低
          高
      
      
          concurrent.futures
          並行任務
          低
          中-高
      
      
          Free-threading
          CPU 並行
          中
          高
      
      
          Cython
          熱點程式碼
          高
          高
      
      
          PyPy
          通用加速
          低
          中
      
      
          asyncio
          I/O 並發
          中
          中-高
      
  

1. 演算法優化
永遠是第一優先：





1# 用合適的資料結構
2items_list = [1, 2, 3, ...]    # 查找 O(n)
3items_set = {1, 2, 3, ...}     # 查找 O(1)
4
5# 用合適的演算法
6sorted(items)                   # O(n log n)
7items.sort()                    # O(n log n)，但原地排序更省記憶體
2. 使用 NumPy/Pandas
把計算交給 C 實現的函式庫：





 1import numpy as np
 2
 3# 純 Python：慢
 4def sum_squares_python(n):
 5    return sum(i * i for i in range(n))
 6
 7# NumPy：快 10-100 倍
 8def sum_squares_numpy(n):
 9    arr = np.arange(n)
10    return np.sum(arr * arr)
11
12# 向量化操作是關鍵
13# 不好：Python 迴圈
14result = []
15for x in data:
16    result.append(x * 2 + 1)
17
18# 好：NumPy 向量化
19result = data * 2 + 1
3. 並行處理
見 3.7 並行處理 和 3.8 Free-Threading





1from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
2
3# I/O 密集：使用執行緒
4with ThreadPoolExecutor(max_workers=10) as executor:
5    results = executor.map(fetch_url, urls)
6
7# CPU 密集：使用進程（或 Free-threading）
8with ProcessPoolExecutor() as executor:
9    results = executor.map(compute_heavy, data_chunks)
4. PyPy
PyPy 是 Python 的另一個實現，使用 JIT 編譯：





1# 安裝 PyPy
2# macOS: brew install pypy3
3# Ubuntu: apt install pypy3
4
5# 執行
6pypy3 your_script.py
PyPy 對於迴圈密集的程式碼特別有效：





1# 這種程式碼在 PyPy 上可能快 10-50 倍
2def compute():
3    total = 0
4    for i in range(10_000_000):
5        total += i * i
6    return total
Python 3.13-3.14 效能改進
新的直譯器
Python 3.14 引入了使用尾調用的新直譯器，在支援的編譯器上快 3-5%：





1# 需要使用 Clang 19+ 編譯，並啟用配置選項
2./configure --with-tail-call-interp
增量垃圾回收
循環垃圾回收現在是增量式的，減少了長時間停頓：





1import gc
2
3# 舊版：可能造成明顯停頓
4gc.collect()
5
6# 3.14：增量回收，影響更平滑
7gc.collect(1)
Free-Threading
詳見 3.8 Free-Threading。
什麼時候該優化？
「過早優化是萬惡之源」
Donald Knuth 的這句名言經常被誤解。完整的引言是：

「程式設計師花費了大量時間思考或擔心程式非關鍵部分的速度，而當考慮到除錯和維護時，這些效率的嘗試實際上會產生強烈的負面影響。我們應該忘記小的效率問題，比如說 97% 的時間：過早優化是萬惡之源。然而，我們不應該放棄那關鍵的 3% 的機會。」
優化的正確流程





 11. 讓程式正確運作
 2      ↓
 32. 讓程式碼可讀、可維護
 4      ↓
 53. 測量效能（profiling）
 6      ↓
 74. 找出瓶頸（通常是 20% 的程式碼佔 80% 的時間）
 8      ↓
 95. 只優化瓶頸
10      ↓
116. 再次測量，確認改善
80/20 法則
在大多數程式中：

20% 的程式碼佔用 80% 的執行時間
優化錯誤的地方不會有任何效果

效能測量工具
簡單計時





 1import time
 2
 3def measure_time(func, *args, **kwargs):
 4    """測量函式執行時間"""
 5    start = time.perf_counter()
 6    result = func(*args, **kwargs)
 7    elapsed = time.perf_counter() - start
 8    print(f"{func.__name__}: {elapsed:.6f}s")
 9    return result
10
11# 使用
12result = measure_time(my_function, arg1, arg2)
使用 timeit





 1import timeit
 2
 3# 測量小段程式碼
 4time_taken = timeit.timeit(
 5    'sum(range(1000))',
 6    number=10000
 7)
 8print(f"平均執行時間: {time_taken / 10000:.6f}s")
 9
10# 比較兩種實現
11setup = "data = list(range(1000))"
12
13time1 = timeit.timeit('sum(data)', setup=setup, number=10000)
14time2 = timeit.timeit('sum(x for x in data)', setup=setup, number=10000)
15
16print(f"直接 sum: {time1:.4f}s")
17print(f"生成器 sum: {time2:.4f}s")
使用 cProfile





 1import cProfile
 2import pstats
 3
 4# 基本用法
 5cProfile.run('my_function()')
 6
 7# 詳細分析
 8profiler = cProfile.Profile()
 9profiler.enable()
10
11# 執行你的程式碼
12result = my_function()
13
14profiler.disable()
15stats = pstats.Stats(profiler)
16stats.sort_stats('cumulative')
17stats.print_stats(20)  # 顯示前 20 個
使用 line_profiler（逐行分析）





1pip install line_profiler




1# 在函式上加上 @profile 裝飾器
2@profile
3def slow_function():
4    total = 0
5    for i in range(1000):
6        total += i * i
7    return total




1kernprof -l -v your_script.py
使用 memory_profiler（記憶體分析）





1pip install memory_profiler




1from memory_profiler import profile
2
3@profile
4def memory_hungry_function():
5    big_list = [i for i in range(1000000)]
6    return sum(big_list)
實際案例
案例 1：優化資料處理





 1# 原始版本：慢
 2def process_data_slow(data):
 3    result = []
 4    for item in data:
 5        if item > 0:
 6            result.append(item * 2)
 7    return result
 8
 9# 優化版本 1：列表推導式（快 20-30%）
10def process_data_v1(data):
11    return [item * 2 for item in data if item > 0]
12
13# 優化版本 2：NumPy（大數據時快 10-100 倍）
14import numpy as np
15
16def process_data_v2(data):
17    arr = np.array(data)
18    return arr[arr > 0] * 2
案例 2：快取昂貴的計算





 1from functools import lru_cache
 2
 3# 沒有快取：每次都重新計算
 4def fibonacci_slow(n):
 5    if n < 2:
 6        return n
 7    return fibonacci_slow(n - 1) + fibonacci_slow(n - 2)
 8
 9# 有快取：已計算的結果會被記住
10@lru_cache(maxsize=None)
11def fibonacci_fast(n):
12    if n < 2:
13        return n
14    return fibonacci_fast(n - 1) + fibonacci_fast(n - 2)
15
16# fibonacci_slow(35) 需要幾秒鐘
17# fibonacci_fast(35) 幾乎瞬間完成
案例 3：選擇正確的資料結構





 1import time
 2
 3# 用 list 查找（O(n)）
 4def find_in_list(items, target):
 5    return target in items
 6
 7# 用 set 查找（O(1)）
 8def find_in_set(items, target):
 9    return target in items
10
11# 測試
12data_list = list(range(1_000_000))
13data_set = set(range(1_000_000))
14target = 999_999
15
16start = time.perf_counter()
17find_in_list(data_list, target)
18print(f"List 查找: {time.perf_counter() - start:.6f}s")
19
20start = time.perf_counter()
21find_in_set(data_set, target)
22print(f"Set 查找: {time.perf_counter() - start:.6f}s")
23
24# List 查找: 0.015000s（取決於位置）
25# Set 查找:  0.000001s（幾乎瞬間）
思考題

為什麼「過早優化是萬惡之源」？什麼時候優化才是適當的？
在什麼情況下，Python 的「慢」確實是個問題？
NumPy 為什麼比純 Python 迴圈快這麼多？

實作練習

使用 cProfile 分析一個現有的 Python 程式，找出效能瓶頸
將一個使用 Python 迴圈的數值計算程式改寫成 NumPy 版本，比較效能差異
實作一個帶有快取的 API 客戶端，避免重複請求相同的資料

延伸閱讀

Python 官方效能提示
High Performance Python, 2nd Edition
NumPy 官方文件 - 效能

延伸閱讀（進階系列）

實戰效能優化 - 真實案例的效能調優實戰
CPython 內部機制 - 理解 Python 的運作原理以優化效能
Free-Threading - Python 3.13+ 無 GIL 多執行緒
用 C 擴展 Python - 使用 ctypes、Cython、pybind11 提升效能
用 Rust 擴展 Python - 使用 PyO3 建立高效能安全的擴展


上一章：並行處理



3.9 flag、os/env 與設定邊界
Wed, 22 Apr 2026 00:00:00 +0000
設定讀取的核心責任是把外部字串轉成程式內部的 typed config。環境變數、命令列 flag、設定檔與預設值都只是輸入來源；application 應依賴已驗證的 config struct。
預計補充內容
這些設定邊界會在下列章節展開：

Go 進階：composition root 與依賴組裝：設定讀取的真正用途，是在啟動層把外部輸入轉成可驗證的依賴。
Go 入門：從入口程式看應用啟動流程：先看主程式怎麼啟動，才知道設定應該在哪裡完成驗證。
Backend：部署平台與網路入口：像 secret manager、ConfigMap 與 rollout 這類平台責任應該留給 Backend。

與 Backend 教材的分工
本章只處理 Go 程式內的設定邊界。secret manager、Kubernetes ConfigMap、container environment、遠端動態設定與部署平台 rollout 會放在 Backend：部署平台與網路入口。
和 Go 教材的關係
這一章承接的是入口流程與 composition root；如果你要先回看語言教材，可以讀：

Go：從入口程式看應用啟動流程
Go：composition root 與依賴組裝
Go：testing 基礎
Go：flag、os/env 與設定邊界



3.10 標準庫如何支撐服務型 Go
Thu, 23 Apr 2026 00:00:00 +0000
Go 標準庫的服務價值在於它直接提供 HTTP、timeout、取消、日誌與資源管理的基本能力。這一章把前面學過的工具串成服務底座，讓讀者理解標準庫如何支撐後端程式，而不只是個別 API 的使用方式。
本章目標
學完本章後，你將能夠：

看出標準庫為什麼是 Go 服務的底座
把 context、net/http、log/slog、defer 與 time 串成一個服務模型
理解為什麼這些工具會讓服務更可維護
把標準庫能力轉成實際服務邊界
知道何時標準庫已足夠，何時才需要外部框架


【觀察】標準庫本身就能做服務
Go 的標準庫已經包含服務程式需要的主要基礎能力。net/http 可以直接建立服務，context 可以控制取消與 timeout，log/slog 可以支援結構化日誌，defer 可以整理資源釋放，time 可以處理期限與排程。
這些能力拼在一起，就是一個後端服務最基本的底盤。
【判讀】context 是服務生命週期的中心
在服務型 Go 裡，context 是請求、取消與 deadline 的共同語言。當 handler、worker、DB、Redis 都接受 context 時，整個流程就能在同一個生命週期邊界內運作；缺少 context 的長時間流程會讓取消與逾時難以傳遞。
【判讀】net/http 讓入口保持簡單
net/http 的 handler 模型很薄，這是優點。它讓你能快速建立路由、驗證 request、回傳 response，而不需要先學一大套框架約定。對服務型 Go 來說，這種簡單性會直接降低協作成本。
【策略】log 與 defer 讓邊界更完整
log/slog 提供結構化日誌，讓高併發服務的診斷更容易；defer 則讓 close、unlock、cancel 等收尾操作更安全。這兩個工具都是 Go 在長時間運行服務中很重要的可靠性支撐。
小結
標準庫是 Go 成為服務語言的核心原因之一。當你把 context、net/http、log/slog、defer 與 time 看成一組工具時，就更容易理解 Go 為什麼適合做後端服務。

等級	數值	使用時機
DEBUG	10	詳細的除錯資訊
INFO	20	一般的操作資訊
WARNING	30	警告但程式仍可運行
ERROR	40	錯誤但程式仍可運行
CRITICAL	50	嚴重錯誤，程式可能無法繼續

變數	說明
`%(asctime)s`	時間戳
`%(levelname)s`	日誌等級名稱
`%(name)s`	Logger 名稱
`%(message)s`	日誌訊息
`%(filename)s`	檔案名稱
`%(lineno)d`	行號
`%(funcName)s`	函式名稱

level	適用情境
Debug	開發或診斷細節
Info	正常但重要的狀態變化
Warn	可恢復但需要注意的異常
Error	操作失敗或需要處理的錯誤

概念	建議欄位
使用者 ID	`userID`
request ID	`requestID`
工作 ID	`jobID`
元件名稱	`component`
錯誤	`error`

任務類型	GIL 影響	原因
I/O 密集	影響小	等待 I/O 時會釋放 GIL
CPU 密集	影響大	多執行緒無法真正並行計算

任務類型	推薦方案	原因
I/O 密集	`ThreadPoolExecutor`	輕量、共享記憶體、GIL 影響小
CPU 密集	`ProcessPoolExecutor`	繞過 GIL、真正並行
需要細控制	`threading`/`multiprocessing`	底層 API、更多控制
Python 3.14+ CPU 密集	`threading` + Free-threading	真正的多執行緒並行

面向	Python	C++
開發時間	短	長
執行速度	慢	快
程式碼可讀性	高	中
除錯難度	低	高
學習曲線	緩	陡

方案	適用場景	學習成本	效果
演算法優化	通用	中	最高
NumPy/Pandas	數值計算	低	高
concurrent.futures	並行任務	低	中-高
Free-threading	CPU 並行	中	高
Cython	熱點程式碼	高	高
PyPy	通用加速	低	中
asyncio	I/O 並發	中	中-高

Stdlib on Tarragon

9.1 用 stdlib flag 寫 subcommand CLI

基礎：為什麼需要 flag.NewFlagSet 而非 flag.Parse()

專案 Layout：main → cmd/ → internal/

Layer 1：main.go dispatcher

Layer 2：子命令入口

Layer 3：internal 實作

什麼時候該上 cobra

常見陷阱

在 layer 3 直接呼叫 os.Exit

用全域 var fs = flag.NewFlagSet(...) 宣告 flag

忘記 ContinueOnError 就跑 test

太早抽出「所有子命令共用的 flag」

擴充路徑

下一步

3.1 fmt、strings 與基本文字處理

fmt 負責格式化

格式動詞描述輸出形狀

錯誤訊息要包含可行動資訊

strings 負責字串操作

查找與判斷應該直接表達意圖

組合字串要看資料量

簡單 parser 可以先用標準庫

3.1 pathlib - 路徑操作

為什麼使用 pathlib？

傳統 os.path 方式

現代 pathlib 方式

基本操作

建立 Path 物件

路徑組合

取得路徑部分

實際範例：Hook 系統

日誌目錄建立

設定檔案搜尋

檔案操作

讀取檔案

寫入檔案

檢查檔案類型

目錄操作

建立目錄

列出目錄內容

實際範例：驗證所有 Hook

路徑解析

相對路徑與絕對路徑

實際範例：解析路徑

常用模式

計算腳本所在目錄

確保檔案副檔名

安全的檔案讀取

思考題

實作練習

3.2 time：時間與 duration

time.Time 表示時間點

time.Duration 表示時間長度

時間加減要區分時間點與長度

parse 與 format 使用 layout

timer 表示一次性的未來事件

ticker 表示週期性事件

小結

3.2 json - 序列化

基本操作

序列化（Python 物件 → JSON 字串）

反序列化（JSON 字串 → Python 物件）

檔案讀寫

實際範例：Hook 系統

Hook 輸入讀取

Hook 輸出寫入

重要參數

ensure_ascii

indent

sort_keys

default

型別對應

常見錯誤處理

JSONDecodeError

無法序列化的物件

實際應用：配置檔案載入

與 YAML 的比較

最佳實踐

1. 總是指定編碼

基礎：為什麼需要 `flag.NewFlagSet` 而非 `flag.Parse()`

在 layer 3 直接呼叫 `os.Exit`

用全域 `var fs = flag.NewFlagSet(...)` 宣告 flag

忘記 `ContinueOnError` 就跑 test

`fmt` 負責格式化

`strings` 負責字串操作

`time.Time` 表示時間點

`time.Duration` 表示時間長度

檔案操作從 `os` 開始

`io.Reader` 表示可讀來源

`io.Writer` 表示可寫目的地

`bufio.Scanner` 適合逐行讀取