Refactoring on Tarragon

7.1 把 handler 邏輯拆成可測單元

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

handler 重構的核心目標是把 transport concern 和 application concern 分開。handler 應處理 request/response，usecase 應處理行為規則，domain 應保存狀態語意。

本章目標

學完本章後，你將能夠：

辨識 handler 過重的訊號
把 request DTO 與 command 分開
把業務規則搬到 usecase
讓 handler 只做 request/response 轉換
分開撰寫 usecase test、handler test 與少量 integration test

【觀察】過重 handler 會混合三種責任

handler 過重的核心問題是 transport、application 與 state concern 混在同一個函式。當一個 handler 同時解析 JSON、驗證欄位、檢查重複、修改 map、組 response，它就很難測，也很難重用。

常見壞味道：

handler 超過一兩個螢幕。
測試核心規則必須透過 HTTP。
JSON tag 出現在 domain type 上。
handler 直接改 repository 的 map 或 slice。
多個 handler 重複同樣的驗證與錯誤 mapping。
想新增 CLI、worker 或 WebSocket action 時，只能複製 handler 內的邏輯。

以下是一個過重的建立通知 handler：

 1var notifications = map[string]Notification{}
 2
 3func handleCreateNotification(w http.ResponseWriter, r *http.Request) {
 4    if r.Method != http.MethodPost {
 5        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 6        return
 7    }
 8
 9    var req struct {
10        ID    string `json:"id"`
11        Topic string `json:"topic"`
12        Title string `json:"title"`
13    }
14    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
15        http.Error(w, "invalid json", http.StatusBadRequest)
16        return
17    }
18
19    if strings.TrimSpace(req.ID) == "" || strings.TrimSpace(req.Topic) == "" {
20        http.Error(w, "missing required field", http.StatusBadRequest)
21        return
22    }
23
24    if _, exists := notifications[req.ID]; exists {
25        http.Error(w, "notification already exists", http.StatusConflict)
26        return
27    }
28
29    notification := Notification{
30        ID:        req.ID,
31        Topic:     req.Topic,
32        Title:     req.Title,
33        CreatedAt: time.Now(),
34    }
35    notifications[notification.ID] = notification
36
37    w.Header().Set("Content-Type", "application/json")
38    w.WriteHeader(http.StatusCreated)
39    _ = json.NewEncoder(w).Encode(notification)
40}

這段程式可以跑，但它把太多責任放進 HTTP 邊界。只要要測「重複 ID 不可建立」，就必須走 HTTP；只要要改儲存方式，就必須改 handler。

【判讀】先拆 request DTO

request DTO 的核心責任是描述外部輸入格式。它可以有 JSON tag，但不應直接當成 domain model 或 repository model。

 1type createNotificationRequest struct {
 2    ID    string `json:"id"`
 3    Topic string `json:"topic"`
 4    Title string `json:"title"`
 5}
 6
 7func (r createNotificationRequest) validate() error {
 8    if strings.TrimSpace(r.ID) == "" {
 9        return ErrInvalidInput{Field: "id", Reason: "required"}
10    }
11    if strings.TrimSpace(r.Topic) == "" {
12        return ErrInvalidInput{Field: "topic", Reason: "required"}
13    }
14    return nil
15}

DTO 可以是 unexported，因為它只服務 HTTP handler。JSON tag 也停在 transport layer，不會污染 application command。

錯誤可以先用簡單型別表達：

1type ErrInvalidInput struct {
2    Field  string
3    Reason string
4}
5
6func (e ErrInvalidInput) Error() string {
7    return e.Field + ": " + e.Reason
8}

這個錯誤型別讓 handler 可以把輸入錯誤轉成 400 Bad Request，而不必靠字串比對。

【策略】command 表達 usecase 輸入

command 的核心責任是描述 application layer 要執行的行為。它不需要 JSON tag，也不需要知道 request body 來自 HTTP、WebSocket 或 CLI。

1type CreateNotificationCommand struct {
2    ID        string
3    Topic     string
4    Title     string
5    CreatedAt time.Time
6}

handler 負責 DTO -> command 的轉換：

1func (r createNotificationRequest) toCommand(now time.Time) CreateNotificationCommand {
2    return CreateNotificationCommand{
3        ID:        strings.TrimSpace(r.ID),
4        Topic:     strings.TrimSpace(r.Topic),
5        Title:     strings.TrimSpace(r.Title),
6        CreatedAt: now,
7    }
8}

CreatedAt 由 handler 或 usecase 決定都可以，但要一致。若時間是業務規則的一部分，通常由 usecase 注入 clock 會更穩；若只是 request 接收時間，handler 傳入也合理。重點是不要在測試中散落 time.Now()。

【執行】usecase 保存行為規則

usecase 的核心責任是處理行為規則與資料能力。重複檢查、儲存、事件發布或狀態轉移應該在 usecase，而不是 handler。

先定義 usecase 需要的 repository：

1type NotificationRepository interface {
2    Save(ctx context.Context, notification Notification) error
3    FindByID(ctx context.Context, id string) (Notification, bool, error)
4}

再定義 service：

1type CreateNotificationUsecase struct {
2    repository NotificationRepository
3}
4
5func NewCreateNotificationUsecase(repository NotificationRepository) *CreateNotificationUsecase {
6    return &CreateNotificationUsecase{repository: repository}
7}

執行 command：

 1func (u *CreateNotificationUsecase) Execute(ctx context.Context, cmd CreateNotificationCommand) (Notification, error) {
 2    if strings.TrimSpace(cmd.ID) == "" {
 3        return Notification{}, ErrInvalidInput{Field: "id", Reason: "required"}
 4    }
 5    if strings.TrimSpace(cmd.Topic) == "" {
 6        return Notification{}, ErrInvalidInput{Field: "topic", Reason: "required"}
 7    }
 8
 9    if _, exists, err := u.repository.FindByID(ctx, cmd.ID); err != nil {
10        return Notification{}, fmt.Errorf("find notification: %w", err)
11    } else if exists {
12        return Notification{}, ErrAlreadyExists{ID: cmd.ID}
13    }
14
15    notification := Notification{
16        ID:        cmd.ID,
17        Topic:     cmd.Topic,
18        Title:     cmd.Title,
19        CreatedAt: cmd.CreatedAt,
20    }
21
22    if err := u.repository.Save(ctx, notification); err != nil {
23        return Notification{}, fmt.Errorf("save notification: %w", err)
24    }
25
26    return notification, nil
27}

ErrAlreadyExists 可以是明確錯誤型別：

1type ErrAlreadyExists struct {
2    ID string
3}
4
5func (e ErrAlreadyExists) Error() string {
6    return "notification already exists: " + e.ID
7}

這樣 handler 可以用 errors.As 把它對應到 409 Conflict。

【執行】handler 只做轉換與 mapping

重構後 handler 的核心責任是 request -> command、result -> response、error -> HTTP status。它不直接碰 map，也不保存業務規則。

 1type NotificationCreator interface {
 2    Execute(ctx context.Context, cmd CreateNotificationCommand) (Notification, error)
 3}
 4
 5type NotificationHandler struct {
 6    creator NotificationCreator
 7    now     func() time.Time
 8}
 9
10func NewNotificationHandler(creator NotificationCreator, now func() time.Time) NotificationHandler {
11    return NotificationHandler{creator: creator, now: now}
12}

handler 實作：

 1func (h NotificationHandler) Create(w http.ResponseWriter, r *http.Request) {
 2    if r.Method != http.MethodPost {
 3        writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "method not allowed")
 4        return
 5    }
 6
 7    var req createNotificationRequest
 8    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 9        writeError(w, http.StatusBadRequest, "invalid_json", "request body must be valid JSON")
10        return
11    }
12
13    if err := req.validate(); err != nil {
14        writeError(w, http.StatusBadRequest, "invalid_input", err.Error())
15        return
16    }
17
18    notification, err := h.creator.Execute(r.Context(), req.toCommand(h.now()))
19    if err != nil {
20        writeUsecaseError(w, err)
21        return
22    }
23
24    writeJSON(w, http.StatusCreated, newNotificationResponse(notification))
25}

這個 handler 仍然有 HTTP 協定責任，但核心行為已經搬出去。未來 WebSocket action 或 worker 也可以建立 CreateNotificationCommand 呼叫同一個 usecase。

【策略】response struct 是對外 contract

response struct 的核心責任是描述 HTTP 回應格式。不要直接把 domain model 全部輸出，否則內部欄位會變成外部 API 承諾。

 1type notificationResponse struct {
 2    ID        string    `json:"id"`
 3    Topic     string    `json:"topic"`
 4    Title     string    `json:"title"`
 5    CreatedAt time.Time `json:"createdAt"`
 6}
 7
 8func newNotificationResponse(notification Notification) notificationResponse {
 9    return notificationResponse{
10        ID:        notification.ID,
11        Topic:     notification.Topic,
12        Title:     notification.Title,
13        CreatedAt: notification.CreatedAt,
14    }
15}

error response 也應該穩定：

 1type errorResponse struct {
 2    Code    string `json:"code"`
 3    Message string `json:"message"`
 4}
 5
 6func writeError(w http.ResponseWriter, status int, code string, message string) {
 7    writeJSON(w, status, errorResponse{
 8        Code:    code,
 9        Message: message,
10    })
11}

writeJSON 集中 JSON response 寫法：

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

這個 helper 可以忽略 encode error，因為 response 已經開始寫出；正式服務通常會記錄 log。

【判讀】error mapping 是 handler 邊界

error mapping 的核心責任是把 application error 轉成 HTTP status 與對外 code。usecase 不應知道 HTTP status；handler 不應靠錯誤字串猜狀態。

 1func writeUsecaseError(w http.ResponseWriter, err error) {
 2    var invalid ErrInvalidInput
 3    if errors.As(err, &invalid) {
 4        writeError(w, http.StatusBadRequest, "invalid_input", invalid.Error())
 5        return
 6    }
 7
 8    var alreadyExists ErrAlreadyExists
 9    if errors.As(err, &alreadyExists) {
10        writeError(w, http.StatusConflict, "already_exists", "notification already exists")
11        return
12    }
13
14    writeError(w, http.StatusInternalServerError, "internal_error", "internal server error")
15}

內部錯誤不要直接回給 client。對外 message 應該穩定且安全；詳細錯誤留給 log 與 error chain。

【執行】usecase 測試不需要 HTTP

usecase 測試的核心目標是驗證行為規則。它應該直接建立 command，使用 fake repository，不需要 httptest。

 1type fakeNotificationRepository struct {
 2    existing map[string]Notification
 3    saved    []Notification
 4}
 5
 6func (f *fakeNotificationRepository) Save(ctx context.Context, notification Notification) error {
 7    f.saved = append(f.saved, notification)
 8    return nil
 9}
10
11func (f *fakeNotificationRepository) FindByID(ctx context.Context, id string) (Notification, bool, error) {
12    notification, ok := f.existing[id]
13    return notification, ok, nil
14}

測試建立成功：

 1func TestCreateNotificationUsecaseExecute(t *testing.T) {
 2    repo := &fakeNotificationRepository{existing: map[string]Notification{}}
 3    usecase := NewCreateNotificationUsecase(repo)
 4
 5    _, err := usecase.Execute(context.Background(), CreateNotificationCommand{
 6        ID:        "ntf_1",
 7        Topic:     "deployments",
 8        Title:     "Deploy finished",
 9        CreatedAt: time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
10    })
11    if err != nil {
12        t.Fatalf("execute usecase: %v", err)
13    }
14
15    if len(repo.saved) != 1 {
16        t.Fatalf("saved notifications = %d, want 1", len(repo.saved))
17    }
18}

這個測試速度快、錯誤定位明確。若失敗，問題在 usecase，不在 HTTP parsing。

【執行】handler test 專注 request/response

handler test 的核心目標是驗證 HTTP 協定行為。它應該使用 fake usecase，而不是真 repository。

 1type fakeNotificationCreator struct {
 2    got CreateNotificationCommand
 3    out Notification
 4    err error
 5}
 6
 7func (f *fakeNotificationCreator) Execute(ctx context.Context, cmd CreateNotificationCommand) (Notification, error) {
 8    f.got = cmd
 9    if f.err != nil {
10        return Notification{}, f.err
11    }
12    return f.out, nil
13}

測試成功 response：

 1func TestNotificationHandlerCreate(t *testing.T) {
 2    creator := &fakeNotificationCreator{
 3        out: Notification{
 4            ID:        "ntf_1",
 5            Topic:     "deployments",
 6            Title:     "Deploy finished",
 7            CreatedAt: time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
 8        },
 9    }
10    handler := NewNotificationHandler(creator, func() time.Time {
11        return time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
12    })
13
14    req := httptest.NewRequest(http.MethodPost, "/notifications", strings.NewReader(`{
15        "id": "ntf_1",
16        "topic": "deployments",
17        "title": "Deploy finished"
18    }`))
19    rec := httptest.NewRecorder()
20
21    handler.Create(rec, req)
22
23    if rec.Code != http.StatusCreated {
24        t.Fatalf("status = %d, want %d", rec.Code, http.StatusCreated)
25    }
26    if creator.got.Topic != "deployments" {
27        t.Fatalf("topic = %q, want deployments", creator.got.Topic)
28    }
29}

這個測試確認 handler 能解析 JSON、建立 command、呼叫 usecase、寫出狀態碼。它不測重複 ID 的儲存規則，那已經是 usecase 測試的責任。

【策略】integration test 只保留少數端到端路徑

integration test 的核心用途是確認組裝正確，不是覆蓋所有規則。當 usecase 與 handler 都已有單元測試，端到端測試只需要保留代表性成功與失敗路徑。

例如：

POST /notifications 成功建立。
invalid JSON 回 400。
重複 ID 回 409。

不要把所有欄位驗證都只放在 integration test。那會讓測試慢、失敗定位模糊，也讓重構成本升高。

重構步驟

從過重 handler 重構時，可以按這個順序：

先補 handler 現有行為測試，鎖住 status code 與 response body。
抽出 request DTO，但暫時不改行為。
抽出 command 與 usecase，讓 handler 呼叫 usecase。
把 repository 或 map 寫入移到 usecase 後方。
抽出 response struct 與 error mapping helper。
補 usecase 單元測試。
縮減 handler 測試範圍，保留 request/response 行為。

每一步都應該讓程式可編譯、測試可跑。不要一次把 handler、repository、package 結構全部搬完。

設計檢查

檢查一：抽出真正的行為邊界

如果新函式仍然接收 http.ResponseWriter 和 *http.Request，那只是移動程式碼，還沒有分離 transport concern。

檢查二：domain model 和 response model 分開

JSON tag 是 transport contract。domain model 若直接承擔對外格式，未來內部欄位調整就會牽動 API 相容性。

檢查三：錯誤類型對應 HTTP 回應

輸入錯誤、重複資料、權限問題與內部錯誤應該對應不同 status code。錯誤型別與 error mapping helper 可以避免字串判斷。

檢查四：分層測試保護不同責任

端到端測試重要，但不應是唯一測試。usecase 規則越多，越需要直接測 command 與 fake repository。

本章不處理

本章先處理 HTTP handler 的轉換邊界；router、middleware 與 transaction，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 request DTO、command 與 usecase 分層；如果你要先回看語言教材，可以讀：

7.2 用 interface 隔離外部依賴

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

interface 邊界重構的核心規則是由使用端定義需要的能力。介面的目的是讓 usecase 不依賴外部技術細節。

本章目標

學完本章後，你將能夠：

辨識哪些依賴值得用 interface 隔離
讓 interface 由使用端定義
設計小而穩定的 port
分辨 fake test 與 contract test
避免過早抽象與巨大 interface

【觀察】interface 是依賴邊界

interface 重構的核心目標是讓高層邏輯只依賴需要的能力。Go 的 interface 讓呼叫端不必知道具體實作。

過重依賴常見在這些地方：

usecase 直接依賴 *sql.DB。
handler 直接依賴 concrete service，測試很難替換。
background worker 直接呼叫外部 API client。
processor 直接知道 WebSocket hub。
測試為了建一個 usecase，必須初始化真資料庫、真檔案或真網路。

interface 的價值是讓 usecase 可以說：「我只需要儲存 notification」、「我只需要 append event」、「我只需要 publish message」。至於能力怎麼實作，是 adapter 的責任。

【判讀】先辨識外部依賴

外部依賴的核心特徵是慢、不穩、難測或帶有技術細節。這些依賴通常適合被 interface 隔離。

依賴	隔離原因	可能 interface
clock	測試需要固定時間	`Clock` 或 `func() time.Time`
repository	儲存技術可替換	`NotificationRepository`
[event log](/go/backend/knowledge-cards/event-log)	記錄實作可替換	`EventLog`
publisher	WebSocket、queue、log 都可能是輸出	`Publisher`
external client	網路失敗與測試替身	`NotificationSource`
command runner	外部程序慢且不穩	`CommandRunner`

不是所有型別都需要 interface。純資料 struct、簡單 helper、沒有替換需求的內部物件，通常先保持 concrete type 更清楚。

【策略】interface 放在使用端

interface 位置的核心規則是：誰需要這個能力，誰定義 interface。這會讓 interface 保持小，也避免 implementation 暴露太多方法。

usecase 需要儲存通知，就在 usecase 附近定義：

1type NotificationRepository interface {
2    Save(ctx context.Context, notification Notification) error
3    FindByID(ctx context.Context, id string) (Notification, bool, error)
4}

in-memory adapter 只要方法集合符合，就自然實作這個 interface：

 1type InMemoryNotificationRepository struct {
 2    mu            sync.RWMutex
 3    notifications map[string]Notification
 4}
 5
 6func (r *InMemoryNotificationRepository) Save(ctx context.Context, notification Notification) error {
 7    r.mu.Lock()
 8    defer r.mu.Unlock()
 9    r.notifications[notification.ID] = notification
10    return nil
11}
12
13func (r *InMemoryNotificationRepository) FindByID(ctx context.Context, id string) (Notification, bool, error) {
14    r.mu.RLock()
15    defer r.mu.RUnlock()
16    notification, ok := r.notifications[id]
17    return notification, ok, nil
18}

InMemoryNotificationRepository 不需要宣告自己 implements 了什麼。Go 的 implicit interface 讓實作端保持乾淨。

【執行】用小 port 隔離 event log

event log port 的核心語意是「可以記錄已發生的事件」。usecase 或 processor 不需要知道事件記錄到 memory、檔案還是資料庫。

1type EventLog interface {
2    Append(ctx context.Context, event DomainEvent) error
3}

processor 依賴這個 port：

 1type EventProcessor struct {
 2    eventLog EventLog
 3}
 4
 5func NewEventProcessor(eventLog EventLog) *EventProcessor {
 6    return &EventProcessor{eventLog: eventLog}
 7}
 8
 9func (p *EventProcessor) Process(ctx context.Context, event DomainEvent) error {
10    if err := event.Validate(); err != nil {
11        return fmt.Errorf("validate event: %w", err)
12    }
13    if err := p.eventLog.Append(ctx, event); err != nil {
14        return fmt.Errorf("append event log: %w", err)
15    }
16    return nil
17}

這個 interface 很小，但它已經足夠讓 processor 測試脫離真正儲存實作。

【執行】publisher port 隔離輸出技術

publisher port 的核心語意是「把結果送出去」。即時推送可以用 WebSocket，非同步流程可以用 queue，測試可以用 recording fake。

1type Publisher interface {
2    Publish(ctx context.Context, event DomainEvent) error
3}

processor 可以同時依賴 event log 與 publisher：

 1type RecordingProcessor struct {
 2    eventLog  EventLog
 3    publisher Publisher
 4}
 5
 6func (p *RecordingProcessor) Process(ctx context.Context, event DomainEvent) error {
 7    if err := p.eventLog.Append(ctx, event); err != nil {
 8        return fmt.Errorf("append event: %w", err)
 9    }
10    if err := p.publisher.Publish(ctx, event); err != nil {
11        return fmt.Errorf("publish event: %w", err)
12    }
13    return nil
14}

這裡的 processor 不知道輸出是 WebSocket 還是 message queue。這就是 interface 邊界的目的。

【策略】clock 可以用函式，不一定要 interface

時間依賴的核心問題是測試需要固定現在時間。最小解法通常是注入函式，而不是建立完整 interface。

1type Clock func() time.Time
2
3type NotificationService struct {
4    now Clock
5}
6
7func NewNotificationService(now Clock) *NotificationService {
8    return &NotificationService{now: now}
9}

使用時：

1func (s *NotificationService) NewNotification(id string, topic string) Notification {
2    return Notification{
3        ID:        id,
4        Topic:     topic,
5        CreatedAt: s.now(),
6    }
7}

測試時傳固定時間：

1fixedNow := func() time.Time {
2    return time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
3}
4service := NewNotificationService(fixedNow)

若只需要「現在時間」，函式比 Clock interface { Now() time.Time } 更簡單。Go 的抽象不一定要用 interface。

【判讀】小 interface 比大 interface 更穩定

小 interface 的核心好處是測試替身容易寫，使用端只知道自己需要的能力。巨大 interface 會把不相關 usecase 綁在一起。

不佳：

1type ApplicationService interface {
2    CreateNotification(ctx context.Context, cmd CreateNotificationCommand) error
3    ListNotifications(ctx context.Context, topic string) ([]Notification, error)
4    AppendEvent(ctx context.Context, event DomainEvent) error
5    Publish(ctx context.Context, event DomainEvent) error
6    RunSync(ctx context.Context) error
7}

較佳：

 1type NotificationCreator interface {
 2    Create(ctx context.Context, cmd CreateNotificationCommand) error
 3}
 4
 5type EventLog interface {
 6    Append(ctx context.Context, event DomainEvent) error
 7}
 8
 9type Publisher interface {
10    Publish(ctx context.Context, event DomainEvent) error
11}

不同呼叫端依賴不同能力。handler 只依賴 creator，processor 只依賴 event log 與 publisher，worker 只依賴 source 與 processor。

【執行】fake test 驗證使用端行為

fake test 的核心目標是測使用端怎麼使用依賴。fake 可以很小，只實作測試需要的行為。

 1type fakeEventLog struct {
 2    appended []DomainEvent
 3    err      error
 4}
 5
 6func (f *fakeEventLog) Append(ctx context.Context, event DomainEvent) error {
 7    if f.err != nil {
 8        return f.err
 9    }
10    f.appended = append(f.appended, event)
11    return nil
12}

測 processor：

 1func TestEventProcessorAppendsEvent(t *testing.T) {
 2    eventLog := &fakeEventLog{}
 3    processor := NewEventProcessor(eventLog)
 4
 5    event := validDomainEvent()
 6    if err := processor.Process(context.Background(), event); err != nil {
 7        t.Fatalf("process event: %v", err)
 8    }
 9
10    if len(eventLog.appended) != 1 {
11        t.Fatalf("appended events = %d, want 1", len(eventLog.appended))
12    }
13}

這個測試不關心 event log 如何保存資料。它只驗證 processor 在正確情境下呼叫了 port。

【執行】contract test 驗證 adapter 行為

contract test 的核心目標是讓不同 adapter 都符合 port 行為。這類測試測 implementation，不測 usecase。

 1func runEventLogContract(t *testing.T, newLog func() EventLogWithList) {
 2    t.Helper()
 3
 4    log := newLog()
 5    event := validDomainEvent()
 6
 7    if err := log.Append(context.Background(), event); err != nil {
 8        t.Fatalf("append event: %v", err)
 9    }
10
11    events := log.List()
12    if len(events) != 1 {
13        t.Fatalf("events = %d, want 1", len(events))
14    }
15    if events[0].ID != event.ID {
16        t.Fatalf("event ID = %q, want %q", events[0].ID, event.ID)
17    }
18}
19
20type EventLogWithList interface {
21    EventLog
22    List() []DomainEvent
23}

List 不一定屬於 production port，它可以是測試用輔助介面。若未來有 SQLite event log，也可以跑同一套 contract test。

【策略】避免過早抽象

避免過早抽象的核心判斷是：沒有替換、測試或技術隔離需求時，先用 concrete type。interface 不是越多越好。

先不要抽 interface 的情境：

只有一個 implementation。
測試不需要 fake。
concrete type 很小，直接使用更清楚。
interface 只是完整複製 concrete type 的所有方法。
邊界還不穩，方法很快會變。

可以抽 interface 的情境：

usecase 不應依賴技術細節。
測試需要替換慢或不穩的依賴。
同一個能力有多種 implementation。
依賴跨越 package 邊界，使用端只需要小部分能力。

重構時可以先寫 concrete type，等第二個使用端或測試壓力出現，再抽出使用端 interface。

重構步驟

把 concrete dependency 改成 interface 時，可以按這個順序：

找出使用端真正呼叫的方法。
在使用端附近定義小 interface。
把 struct 欄位型別從 concrete type 改成 interface。
確認現有 concrete type 自然符合 interface。
在測試中建立 fake。
為 adapter 補 contract test。
移除不再需要的直接依賴。

不要先設計一個完美的全域介面。從使用端需要的最小方法開始，介面會更穩。

設計檢查

檢查一：interface 由使用端定義

implementation 定義的 interface 往往暴露太多方法。使用端定義 interface，才能只依賴自己真正需要的能力。

檢查二：有替換需求再建立 interface

Foo 搭配 FooInterface 不是 Go 的慣例。interface 應該來自使用需求，而不是來自型別存在。

檢查三：fake 服務當前測試行為

fake 是測試工具，不是真 adapter。它只需要支援測試情境，不需要重建資料庫、網路或完整狀態機。

檢查四：公開 interface 需要穩定承諾

一旦 interface 被多個 package 依賴，修改成本會提高。邊界還在探索時，保持 unexported 或使用 concrete type 更務實。

本章不處理

本章先處理 interface 如何讓使用端依賴能力；全專案 DI 框架與 mock generator，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 usecase、adapter 與測試替身邊界；如果你要先回看語言教材，可以讀：

7.3 事件去重邏輯的重構策略

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

事件去重重構的核心目標是把語義鍵、時間窗口與來源優先順序整理成可測規則。本章用一般事件處理流程說明如何降低重複邏輯，同時保留事件合併的判斷依據。

本章目標

學完本章後，你將能夠：

辨識 raw payload 去重的風險
用 domain dedup key 表達同一件事
把去重邏輯抽成 Deduper
設計時間窗口與 cleanup
測試同窗口、跨窗口、不同來源與過期清理

【觀察】重複事件通常先散落在入口層

去重邏輯重構的核心觸發點是多個入口開始各自判斷「這筆事件看過了嗎」。HTTP callback、queue consumer、background worker 或 WebSocket action 都可能收到同一件事，若每個入口各自去重，規則很快會不一致。

重構前常見寫法：

 1var seenHTTPEvents = map[string]bool{}
 2
 3func handleCallback(w http.ResponseWriter, r *http.Request) {
 4    var raw RawNotificationCallback
 5    _ = json.NewDecoder(r.Body).Decode(&raw)
 6
 7    key := raw.NotificationID + ":" + raw.EventName + ":" + raw.Timestamp
 8    if seenHTTPEvents[key] {
 9        w.WriteHeader(http.StatusOK)
10        return
11    }
12    seenHTTPEvents[key] = true
13
14    // update state...
15}

worker 裡又有另一套：

 1var seenWorkerEvents = map[string]time.Time{}
 2
 3func handleWorkerUpdate(update RawNotificationUpdate) {
 4    key := update.ID
 5    if _, ok := seenWorkerEvents[key]; ok {
 6        return
 7    }
 8    seenWorkerEvents[key] = time.Now()
 9
10    // update state...
11}

這兩段程式都在去重，但依據不同。一個用 notification ID、event name、timestamp；另一個用 raw event ID。當兩個來源描述同一件 domain event 時，它們無法互相辨識。

【判讀】raw payload 不適合當去重依據

raw payload 去重的核心問題是來源格式不是 domain 語意。不同來源可能使用不同欄位名稱、timestamp 精度、metadata 或 request ID，但仍然描述同一件事。

容易造成誤判的欄位：

欄位	問題
request ID	每次重送都可能不同
received timestamp	取決於系統收到時間，不是發生時間
raw payload hash	欄位順序或 metadata 變化會改變 hash
source-specific ID	不同來源可能沒有共同 ID
debug metadata	不代表事件語意

去重應該發生在 normalized DomainEvent 上，而不是 raw HTTP body、queue message 或 worker update 上。

【策略】domain dedup key 表達同一件事

domain dedup key 的核心責任是回答「哪兩筆事件應該被視為同一件 domain fact」。常見欄位是 subject kind、subject ID、event type 與時間窗口。

 1type DedupKey struct {
 2    SubjectKind SubjectKind
 3    SubjectID   string
 4    EventType   EventType
 5    Window      int64
 6}
 7
 8func NewDedupKey(event DomainEvent, window time.Duration) DedupKey {
 9    return DedupKey{
10        SubjectKind: event.SubjectKind,
11        SubjectID:   event.SubjectID,
12        EventType:   event.Type,
13        Window:      event.OccurredAt.UnixNano() / int64(window),
14    }
15}

這個 key 不包含 Source，因為不同來源可能送來同一件事。是否包含 source 是一個 domain 決策：如果不同來源代表不同事實，就包含；如果不同來源只是同一事實的不同通道，就不要包含。

時間窗口是容忍來源時間差的折衷。窗口太小會漏掉重複事件，窗口太大可能合併兩件獨立事件。

【執行】抽出 Deduper

Deduper 的核心責任是保存已看過的 key，並回報目前事件是否重複。它不應知道 HTTP、WebSocket 或 queue，也不應更新狀態。

 1type Deduper struct {
 2    mu      sync.Mutex
 3    seen    map[DedupKey]time.Time
 4    window  time.Duration
 5    expires time.Duration
 6}
 7
 8func NewDeduper(window time.Duration, expires time.Duration) *Deduper {
 9    return &Deduper{
10        seen:    make(map[DedupKey]time.Time),
11        window:  window,
12        expires: expires,
13    }
14}

Seen 判斷是否看過：

 1func (d *Deduper) Seen(event DomainEvent) bool {
 2    d.mu.Lock()
 3    defer d.mu.Unlock()
 4
 5    key := NewDedupKey(event, d.window)
 6    if _, ok := d.seen[key]; ok {
 7        return true
 8    }
 9
10    d.seen[key] = event.ReceivedAt
11    return false
12}

這裡用 ReceivedAt 作為清理基準，因為清理是系統內部記憶體管理問題；去重 key 則用 OccurredAt，因為那是事件發生語意。兩個時間各有用途，不應混用。

【執行】processor 使用 Deduper

重構後的核心方向是讓所有來源先 normalize 成 DomainEvent，再交給同一個 processor 去重與套用規則。

 1type EventProcessor struct {
 2    deduper    *Deduper
 3    repository EventRepository
 4    publisher  Publisher
 5}
 6
 7func (p *EventProcessor) Process(ctx context.Context, event DomainEvent) error {
 8    if err := event.Validate(); err != nil {
 9        return fmt.Errorf("validate event: %w", err)
10    }
11
12    if p.deduper.Seen(event) {
13        return nil
14    }
15
16    if err := p.repository.Apply(ctx, event); err != nil {
17        return fmt.Errorf("apply event: %w", err)
18    }
19
20    return p.publisher.Publish(ctx, event)
21}

這個位置比 handler 或 worker 更適合去重，因為 processor 已經面對 normalized domain event。新增事件來源時，只要它走同一個 processor，就自然共用同一套去重規則。

【策略】來源優先順序要顯式化

來源優先順序的核心問題是重複事件不一定完全相同。有些來源即時但資料少，有些來源延遲但資料完整。若需要合併資料，就要把 priority rule 寫成可測規則。

先定義 priority：

 1func SourcePriority(source EventSource) int {
 2    switch source {
 3    case SourceHTTPCallback:
 4        return 100
 5    case SourceClientCommand:
 6        return 80
 7    case SourceTimer:
 8        return 50
 9    default:
10        return 0
11    }
12}

若 deduper 只需要判斷 seen，就不處理 priority。若系統需要「較高 priority 事件可以取代較低 priority 事件」，應把 deduper 改成更明確的 result：

1type DedupDecision int
2
3const (
4    DedupAccept DedupDecision = iota
5    DedupDrop
6    DedupReplace
7)

不要把 priority 規則藏在 if 裡。它是 domain policy，應該可以被直接測試。

【執行】cleanup 防止去重表無限成長

cleanup 的核心責任是移除過期 key，防止去重表變成記憶體 leak。只要 seen 是 map，就必須設計生命週期。

 1func (d *Deduper) Cleanup(now time.Time) {
 2    d.mu.Lock()
 3    defer d.mu.Unlock()
 4
 5    for key, seenAt := range d.seen {
 6        if now.Sub(seenAt) > d.expires {
 7            delete(d.seen, key)
 8        }
 9    }
10}

cleanup 可以由 background worker 定期呼叫：

 1func RunDeduperCleanup(ctx context.Context, deduper *Deduper, interval time.Duration, now func() time.Time) {
 2    ticker := time.NewTicker(interval)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return
 9        case <-ticker.C:
10            deduper.Cleanup(now())
11        }
12    }
13}

這裡注入 now 是為了測試。清理策略不應依賴測試中的真實等待。

【執行】同窗口去重測試

同窗口測試的核心目標是確認兩筆語意相同、時間接近的事件會共用 key。

 1func TestDeduperSeenSameWindow(t *testing.T) {
 2    deduper := NewDeduper(time.Minute, time.Hour)
 3    base := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 4
 5    first := DomainEvent{
 6        ID:          "evt_1",
 7        Type:        EventNotificationCreated,
 8        SubjectKind: SubjectNotification,
 9        SubjectID:   "ntf_1",
10        OccurredAt:  base,
11        ReceivedAt:  base,
12    }
13    second := first
14    second.ID = "evt_2"
15    second.ReceivedAt = base.Add(5 * time.Second)
16
17    if deduper.Seen(first) {
18        t.Fatalf("first event should not be duplicate")
19    }
20    if !deduper.Seen(second) {
21        t.Fatalf("second event in same window should be duplicate")
22    }
23}

這個測試刻意讓 ID 不同，證明去重依賴 domain key。

【執行】跨窗口不去重測試

跨窗口測試的核心目標是確認兩件不同時間窗口的事件不會被誤合併。

 1func TestDeduperSeenDifferentWindow(t *testing.T) {
 2    deduper := NewDeduper(time.Minute, time.Hour)
 3    base := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 4
 5    first := DomainEvent{
 6        ID:          "evt_1",
 7        Type:        EventNotificationCreated,
 8        SubjectKind: SubjectNotification,
 9        SubjectID:   "ntf_1",
10        OccurredAt:  base,
11        ReceivedAt:  base,
12    }
13    second := first
14    second.ID = "evt_2"
15    second.OccurredAt = base.Add(2 * time.Minute)
16    second.ReceivedAt = base.Add(2 * time.Minute)
17
18    _ = deduper.Seen(first)
19    if deduper.Seen(second) {
20        t.Fatalf("event in different window should not be duplicate")
21    }
22}

窗口大小是一個業務取捨，測試可以讓這個取捨變成明確規格。

【執行】cleanup 測試不應 sleep

cleanup 測試的核心目標是確認過期 key 會被移除。測試應直接傳入時間，不要真的等待過期。

 1func TestDeduperCleanup(t *testing.T) {
 2    deduper := NewDeduper(time.Minute, time.Minute)
 3    base := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 4
 5    event := DomainEvent{
 6        ID:          "evt_1",
 7        Type:        EventNotificationCreated,
 8        SubjectKind: SubjectNotification,
 9        SubjectID:   "ntf_1",
10        OccurredAt:  base,
11        ReceivedAt:  base,
12    }
13
14    _ = deduper.Seen(event)
15    deduper.Cleanup(base.Add(2 * time.Minute))
16
17    if deduper.Seen(event) {
18        t.Fatalf("event should be accepted after cleanup")
19    }
20}

這個測試能快速完成，也不受機器速度影響。

重構步驟

把散落的去重邏輯收斂到 Deduper 時，可以按這個順序：

先列出所有入口目前的去重 key。
找出它們真正想表達的 domain 語意。
建立 DedupKey，使用 subject、event type 與時間窗口。
把 raw input 先 normalize 成 DomainEvent。
在 processor 中呼叫 Deduper.Seen。
移除 handler、worker 內的重複 map。
補同窗口、跨窗口、不同來源與 cleanup 測試。

不要一開始就把所有事件融合規則做完。先把「是否看過」集中，再處理 priority 或 replace policy。

設計檢查

檢查一：去重鍵使用 domain 語意

payload hash 對格式變化太敏感。欄位順序、metadata 或 timestamp 精度改變，都會讓同一件事看起來不同。

檢查二：事件順序使用 OccurredAt

ReceivedAt 是系統收到時間。事件是否同一件事，通常應看 OccurredAt 與 subject 語意。

檢查三：去重表需要 cleanup

任何「看過的 key」map 都會成長。沒有 cleanup 的 deduper 會在長時間服務中累積記憶體壓力。

檢查四：來源 priority 需要測試

若不同來源資料完整度不同，priority 是 domain policy。它應該有明確函式與測試，而不是散落在 processor 的條件判斷裡。

本章不處理

本章先處理單一服務內的去重規則如何集中；分散式去重與 idempotency store，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 event normalization、processor 與 source priority；如果你要先回看語言教材，可以讀：

7.4 狀態管理的安全邊界

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

狀態管理重構的核心目標是集中寫入、保護 map、回傳複製資料，並避免讓 handler、背景工作或即時連線直接操作內部狀態。本章用一般 repository 範例說明如何建立安全邊界。

本章目標

學完本章後，你將能夠：

辨識共享狀態外洩的程式碼壞味道
用 repository 或 state owner 集中寫入
用 sync.RWMutex 保護 map、slice 與狀態不變式
用 copy boundary 防止呼叫端修改內部資料
用行為測試與 go test -race 驗證並發狀態

【觀察】共享狀態外洩會讓規則分散

共享狀態外洩的核心問題是多個元件可以繞過同一套規則直接修改資料。當 handler、worker、WebSocket client manager 都能改同一個 map，狀態不一致與 data race 會變得很難追蹤。

重構前常見寫法：

 1type Server struct {
 2    jobs map[string]JobProjection
 3}
 4
 5func (s *Server) handleJobStarted(w http.ResponseWriter, r *http.Request) {
 6    id := r.URL.Query().Get("id")
 7    s.jobs[id] = JobProjection{
 8        ID:        id,
 9        Status:    JobStatusRunning,
10        UpdatedAt: time.Now(),
11    }
12    w.WriteHeader(http.StatusAccepted)
13}
14
15func (s *Server) handleJobList(w http.ResponseWriter, r *http.Request) {
16    _ = json.NewEncoder(w).Encode(s.jobs)
17}

這段程式有三個問題：handler 直接改 map，map 沒有 lock，查詢直接輸出內部資料。只要另一個 goroutine 同時讀寫 jobs，就可能產生 data race。

【判讀】state owner 是唯一寫入入口

state owner 的核心責任是擁有資料與狀態轉移規則。它可以叫 repository、store、manager；名稱不是重點，重點是所有寫入都經過同一組方法。

 1type JobRepository struct {
 2    mu   sync.RWMutex
 3    jobs map[string]JobProjection
 4}
 5
 6func NewJobRepository() *JobRepository {
 7    return &JobRepository{
 8        jobs: make(map[string]JobProjection),
 9    }
10}

handler 不再直接改 map，而是呼叫 repository 方法：

 1func (r *JobRepository) MarkRunning(id string, now time.Time) error {
 2    if strings.TrimSpace(id) == "" {
 3        return fmt.Errorf("job id is required")
 4    }
 5
 6    r.mu.Lock()
 7    defer r.mu.Unlock()
 8
 9    job := r.jobs[id]
10    job.ID = id
11    job.Status = JobStatusRunning
12    job.UpdatedAt = now
13    r.jobs[id] = job
14    return nil
15}

這個方法把「running 狀態怎麼寫入」集中起來。未來如果 running 只能從 pending 轉移，規則也加在這裡。

【策略】鎖保護的是不變式

lock 的核心責任是保護完整狀態不變式，不只是保護某一行 map assignment。若一次狀態轉移要同時更新 current、history、updated time，就要在同一把鎖內完成。

1type JobRecord struct {
2    Current JobProjection
3    History []JobProjection
4}
5
6type JobRepository struct {
7    mu      sync.RWMutex
8    records map[string]JobRecord
9}

寫入時同時更新 summary 與 history：

 1func (r *JobRepository) Apply(event JobEvent) error {
 2    r.mu.Lock()
 3    defer r.mu.Unlock()
 4
 5    record := r.records[event.JobID]
 6    next := record.Current
 7    next.ID = event.JobID
 8    next.UpdatedAt = event.OccurredAt
 9
10    switch event.Type {
11    case "job.started":
12        next.Status = JobStatusRunning
13    case "job.succeeded":
14        next.Status = JobStatusSucceeded
15        next.Progress = 100
16    case "job.failed":
17        next.Status = JobStatusFailed
18    default:
19        return fmt.Errorf("unsupported job event type %q", event.Type)
20    }
21
22    record.Current = next
23    record.History = append(record.History, next)
24    r.records[event.JobID] = record
25    return nil
26}

這段程式讓 current 與 history 保持一致。若分散在不同 handler 或不同鎖裡，就可能留下「current 已更新但 history 沒有記錄」的中間狀態。

【執行】讀取要回傳 copy

copy boundary 的核心目標是避免呼叫端拿到內部可變資料。鎖只保護鎖內操作；一旦把內部 slice 或 pointer 回傳出去，呼叫端就可以在鎖外修改資料。

單筆查詢：

 1func (r *JobRepository) Get(id string) (JobProjection, bool) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    record, ok := r.records[id]
 6    if !ok {
 7        return JobProjection{}, false
 8    }
 9    return cloneJobProjection(record.Current), true
10}

history 查詢：

 1func (r *JobRepository) History(id string) []JobProjection {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    history := r.records[id].History
 6    result := make([]JobProjection, len(history))
 7    for i, item := range history {
 8        result[i] = cloneJobProjection(item)
 9    }
10    return result
11}

clone 函式處理 pointer 欄位：

1func cloneJobProjection(job JobProjection) JobProjection {
2    cloned := job
3    if job.FinishedAt != nil {
4        finishedAt := *job.FinishedAt
5        cloned.FinishedAt = &finishedAt
6    }
7    return cloned
8}

如果 struct 未來新增 slice、map 或 pointer 欄位，clone 函式也要跟著更新。這是資料擁有權邊界的一部分。

【判讀】state 和 projection 要分清楚

state/projection 分離的核心原因是寫入規則與讀取需求不同。domain state 保存規則，projection 服務查詢與顯示。

 1type JobState struct {
 2    ID        string
 3    Status    JobStatus
 4    UpdatedAt time.Time
 5}
 6
 7type JobProjection struct {
 8    ID          string
 9    Status      JobStatus
10    Progress    int
11    UpdatedAt   time.Time
12    DisplayText string
13}

DisplayText 不應參與狀態轉移，它是 response 或 read model 的資料。若把顯示文字混進核心 state，前端文案改動就會牽動業務規則測試。

重構時不一定要一次拆出兩個 struct。可以先在程式碼中標記哪些欄位是 state，哪些欄位是 projection；等壓力變大，再正式拆型別。

【策略】handler 只請求狀態更新

handler 的核心責任是把 HTTP request 轉成狀態更新請求，而不是自己修改狀態。

重構後：

 1type JobStarter interface {
 2    MarkRunning(id string, now time.Time) error
 3}
 4
 5type JobHandler struct {
 6    jobs JobStarter
 7    now  func() time.Time
 8}
 9
10func (h JobHandler) Start(w http.ResponseWriter, r *http.Request) {
11    id := r.URL.Query().Get("id")
12    if err := h.jobs.MarkRunning(id, h.now()); err != nil {
13        http.Error(w, "start job", http.StatusBadRequest)
14        return
15    }
16    w.WriteHeader(http.StatusAccepted)
17}

handler 不知道 repository 內部用 map、slice、mutex 還是資料庫。它只知道「可以把 job 標記為 running」。

【策略】為未來資料庫保留邊界，但不提前綁死

database-ready 邊界的核心是 context、error 與一致性語意，不是提早引入 ORM。memory repository 可以先存在，但方法簽名可以保留未來 I/O 的可能。

1type JobRepositoryPort interface {
2    Apply(ctx context.Context, event JobEvent) error
3    Get(ctx context.Context, id string) (JobProjection, bool, error)
4}

memory implementation 可以忽略 context：

 1func (r *JobRepository) Get(ctx context.Context, id string) (JobProjection, bool, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    record, ok := r.records[id]
 6    if !ok {
 7        return JobProjection{}, false, nil
 8    }
 9    return cloneJobProjection(record.Current), true, nil
10}

未來換成資料庫時，context 可以傳給 query；error 可以包上資料庫錯誤。transaction 則等到一個 usecase 真的需要多筆寫入一致性時再設計。

【執行】state transition 測試鎖定規則

state transition 測試的核心目標是確認事件會產生正確狀態與 history。這類測試不需要 HTTP，也不需要 goroutine。

 1func TestJobRepositoryApplyRecordsHistory(t *testing.T) {
 2    repo := &JobRepository{records: make(map[string]JobRecord)}
 3    startedAt := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 4
 5    err := repo.Apply(JobEvent{
 6        JobID:      "job_1",
 7        Type:       "job.started",
 8        OccurredAt: startedAt,
 9    })
10    if err != nil {
11        t.Fatalf("apply event: %v", err)
12    }
13
14    job, ok := repo.Get("job_1")
15    if !ok {
16        t.Fatalf("job should exist")
17    }
18    if job.Status != JobStatusRunning {
19        t.Fatalf("status = %q, want %q", job.Status, JobStatusRunning)
20    }
21
22    history := repo.History("job_1")
23    if len(history) != 1 {
24        t.Fatalf("history length = %d, want 1", len(history))
25    }
26}

這個測試鎖定的是狀態規則，而不是鎖本身。

【執行】copy boundary 測試要嘗試破壞資料

copy boundary 測試的核心目標是證明呼叫端拿到的資料不能修改 repository 內部狀態。

 1func TestJobRepositoryHistoryReturnsCopy(t *testing.T) {
 2    repo := &JobRepository{records: make(map[string]JobRecord)}
 3    occurredAt := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 4
 5    _ = repo.Apply(JobEvent{
 6        JobID:      "job_1",
 7        Type:       "job.started",
 8        OccurredAt: occurredAt,
 9    })
10
11    history := repo.History("job_1")
12    history[0].Status = JobStatusFailed
13
14    again := repo.History("job_1")
15    if again[0].Status != JobStatusRunning {
16        t.Fatalf("repository history was modified through returned slice")
17    }
18}

這種測試比只看程式碼更可靠。它直接模擬呼叫端拿到資料後做了危險操作。

【執行】並發測試配合 race detector

並發測試的核心目標是讓 race detector 執行到共享狀態路徑。測試本身可以只檢查不 panic 或基本結果，真正的 data race 由 go test -race 回報。

 1func TestJobRepositoryConcurrentAccess(t *testing.T) {
 2    repo := &JobRepository{records: make(map[string]JobRecord)}
 3    var wg sync.WaitGroup
 4
 5    for i := 0; i < 100; i++ {
 6        wg.Add(1)
 7        go func(i int) {
 8            defer wg.Done()
 9
10            id := fmt.Sprintf("job_%d", i%10)
11            _ = repo.Apply(JobEvent{
12                JobID:      id,
13                Type:       "job.started",
14                OccurredAt: time.Date(2026, 4, 22, 10, 0, i, 0, time.UTC),
15            })
16            _, _ = repo.Get(id)
17            _ = repo.History(id)
18        }(i)
19    }
20
21    wg.Wait()
22}

執行：

1go test -race ./...

race detector 只能檢查測試實際跑到的路徑。若並發讀寫沒有被測試覆蓋，它也不會發現問題。

重構步驟

從共享狀態外洩重構到安全邊界，可以按這個順序：

找出所有直接讀寫 map、slice 或 projection 的地方。
建立 state owner 或 repository。
把最常用的寫入流程搬成方法。
在方法內加入 lock，保護完整不變式。
把讀取方法改成回傳 copy。
讓 handler、worker、publisher 改呼叫方法，不直接碰資料。
補 state transition 與 copy boundary 測試。
補並發測試並執行 go test -race ./...。

不要一開始就重寫所有狀態模型。先把寫入集中，再逐步整理 state/projection 與資料庫邊界。

設計檢查

檢查一：加鎖後仍要保護回傳資料

鎖只保護鎖內操作。回傳內部 map 或 slice 後，呼叫端可以在鎖外修改資料，狀態邊界仍然失效。

檢查二：讀取鎖只保護讀取

RLock 只適合讀取。只要會修改 map、slice、pointer 指向的值或 struct 欄位，就必須使用 Lock。

檢查三：狀態副本需要明確 owner

多份狀態副本會造成 source of truth 混亂。handler 應該請求同一個 state owner 更新或查詢。

檢查四：持久化替換跟著需求前進

狀態邊界是程式碼架構的責任；資料庫只負責持久化。把 memory repository 換成 ORM 只解決「資料存在哪裡」，沒有解決「誰有權利寫、怎麼寫才一致」。

引入資料庫後，清楚的寫入方法、交易語意、copy/DTO 邊界與測試仍要留在程式碼設計中。這些規則決定狀態如何被修改，不能交給資料庫連線本身代勞。

本章不處理

本章先處理 state owner、lock boundary 與 copy boundary；資料庫 transaction 與分散式一致性，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 repository、read model 與 shared state 的邊界；如果你要先回看語言教材，可以讀：

小結

狀態管理重構的重點是建立資料擁有者。寫入集中在 repository 或 state owner，lock 保護完整不變式，讀取回傳 copy，handler 和 worker 只請求狀態更新。當狀態邊界清楚時，race detector 才有意義，未來換成資料庫也只是 adapter 變化，不會改變核心狀態規則。

7.5 以 domain 重新整理 package

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

以 domain 重新整理 package 的核心目標是讓程式結構反映業務語意，而不是只反映技術元件。當系統開始有 account、job、event、workflow 這些不同概念時，平面檔案會讓邊界越來越難看見。

Go package 是語意邊界，不只是檔案分類。好的 package 名稱應該讓讀者知道這裡負責哪一組概念；如果只能命名成 utils、common 或 helpers，通常代表邊界還沒有想清楚。

這一章承接入門篇的「單檔到多檔案」路線。平面多檔案是 Go 程式自然長大的中間階段；只有當檔案切分已經無法表達業務邊界時，才需要把概念搬成更清楚的 domain package。

本章目標

學完本章後，你將能夠：

判斷何時該從平面多檔案拆出 package
用業務語意命名 package
依照純型別、純規則、usecase/repository 的順序搬移
避免 import cycle
用 type alias 與測試降低搬移風險

【觀察】平面多檔案是自然成長階段

平面 package 的核心價值是初期簡單。服務還小時，main.go、models.go、handlers.go、repository.go 放在同一層，常常比一開始切十幾個資料夾更容易理解。

常見中間階段：

1notify/
2├── go.mod
3├── main.go
4├── models.go
5├── handlers.go
6├── repository.go
7├── events.go
8└── worker.go

這個結構不是問題本身。真正的問題通常出現在概念開始混在一起：HTTP request struct、domain state、event type、repository model 都放在 models.go；handler、worker、processor 都直接引用同一批可變資料。

【判讀】拆 package 的訊號是語意邊界變模糊

拆 package 的核心判斷是讀者是否能從結構看出概念邊界。若只是檔案變多，先拆檔案即可；若業務概念混在一起，才需要拆 package。

適合拆 package 的訊號：

models.go 同時包含 request DTO、domain state、response view。
新增功能時不知道型別該放哪個檔案。
event、job、account 規則互相 import 或互相修改。
測試一個 domain 規則必須初始化 handler 或 server。
package 內 unexported helper 太多，讀者很難判斷哪些屬於哪個概念。

不一定要拆 package 的情境：

檔案只是稍長，但仍圍繞同一個概念。
只有單一 main package 的小工具。
邊界還不穩，拆完很可能馬上搬回來。
只是為了符合某個目錄模板。

【策略】package 名稱要表達業務概念

domain package 的核心要求是名稱要讓讀者知道這裡負責哪組概念。job、event、account、workflow 比 common、types、utils 更有語意。

一個可能的拆分：

 1notify/
 2├── go.mod
 3├── main.go
 4├── domain/
 5│   ├── account/
 6│   ├── job/
 7│   ├── event/
 8│   └── workflow/
 9├── transport/
10│   └── http/
11└── storage/
12    └── memory/

這是示範語意方向的參考結構。小型服務也可以先只拆：

1notify/
2├── main.go
3├── notification/
4└── httpapi/

Go package 不需要層數多才算成熟。好的 package 是讓 import 讀起來自然：

1import "example.com/notify/domain/job"

如果 package 名稱只能叫 misc 或 helpers，代表邊界還沒有清楚。

【執行】先搬純型別

搬移 package 的核心順序是先搬依賴最少的東西。純型別通常最安全，因為它不呼叫外部元件。

重構前：

 1// models.go
 2package main
 3
 4type JobStatus string
 5
 6const (
 7    JobStatusPending   JobStatus = "pending"
 8    JobStatusRunning   JobStatus = "running"
 9    JobStatusSucceeded JobStatus = "succeeded"
10    JobStatusFailed    JobStatus = "failed"
11)
12
13type JobProjection struct {
14    ID        string
15    Status    JobStatus
16    UpdatedAt time.Time
17}

重構後：

 1// domain/job/job.go
 2package job
 3
 4import "time"
 5
 6type Status string
 7
 8const (
 9    StatusPending   Status = "pending"
10    StatusRunning   Status = "running"
11    StatusSucceeded Status = "succeeded"
12    StatusFailed    Status = "failed"
13)
14
15type Projection struct {
16    ID        string
17    Status    Status
18    UpdatedAt time.Time
19}

使用端改成：

1import "example.com/notify/domain/job"
2
3var projection job.Projection

package 名稱已經提供語境，所以型別不必再叫 JobProjection。在 job package 裡叫 Projection 就夠清楚。

【策略】用 type alias 過渡

type alias 的核心用途是降低搬移風險。若一次改完所有 import 太大，可以先在舊位置保留 alias，讓既有程式逐步遷移。

 1// models.go
 2package main
 3
 4import "example.com/notify/domain/job"
 5
 6type JobStatus = job.Status
 7type JobProjection = job.Projection
 8
 9const (
10    JobStatusPending   = job.StatusPending
11    JobStatusRunning   = job.StatusRunning
12    JobStatusSucceeded = job.StatusSucceeded
13    JobStatusFailed    = job.StatusFailed
14)

這是過渡工具。等呼叫端逐步改成直接 import domain/job，再移除 alias。

type alias 適合降低大型搬移風險，但不要讓新舊命名長期並存，否則讀者會不知道哪個才是正式 API。

【執行】再搬純規則

純規則的核心特徵是輸入值、回傳值，不依賴 handler、repository 或外部 I/O。這類函式也適合早期搬入 domain package。

 1// domain/job/transition.go
 2package job
 3
 4import "fmt"
 5
 6func CanTransition(from Status, to Status) bool {
 7    switch from {
 8    case StatusPending:
 9        return to == StatusRunning || to == StatusFailed
10    case StatusRunning:
11        return to == StatusSucceeded || to == StatusFailed
12    default:
13        return false
14    }
15}
16
17func Transition(current Projection, next Status) (Projection, error) {
18    if !CanTransition(current.Status, next) {
19        return Projection{}, fmt.Errorf("invalid job status transition: %s -> %s", current.Status, next)
20    }
21    current.Status = next
22    return current, nil
23}

這些規則不應 import HTTP package，也不應知道 repository。它們是 domain 的穩定核心。

【判讀】domain 不依賴 adapter

避免 import cycle 的核心規則是低層 domain 不依賴高層 adapter。domain 可以被 HTTP、worker、repository 使用；但 domain 不應 import 這些外部層。

不良方向：

1domain/job -> transport/http -> domain/job

良好方向：

1transport/http -> application -> domain/job
2storage/memory -> domain/job

如果 domain/job 需要知道 HTTP request struct，代表 request DTO 沒有停在 transport layer。應把 HTTP request 轉成 command 或 domain value，再交給下層。

【執行】最後搬 repository/usecase

repository 和 usecase 的核心特徵是它們開始協調多個概念，所以搬移時要更謹慎。通常先搬 domain 型別與規則，再處理 application layer。

可能的結構：

 1notify/
 2├── domain/
 3│   ├── job/
 4│   └── event/
 5├── application/
 6│   ├── command.go
 7│   └── processor.go
 8├── transport/
 9│   └── http/
10└── storage/
11    └── memory/

application 可以協調 domain：

 1package application
 2
 3import (
 4    "context"
 5
 6    "example.com/notify/domain/event"
 7    "example.com/notify/domain/job"
 8)
 9
10type JobRepository interface {
11    Apply(ctx context.Context, projection job.Projection) error
12}
13
14type Processor struct {
15    jobs JobRepository
16}
17
18func (p *Processor) Process(ctx context.Context, e event.Event) error {
19    projection := job.Projection{
20        ID:     e.SubjectID,
21        Status: job.StatusRunning,
22    }
23    return p.jobs.Apply(ctx, projection)
24}

application 可以依賴多個 domain package，因為它負責協調 usecase。domain package 之間若互相依賴太多，通常代表邊界切得不對。

【策略】每次只搬一個邊界

package 重構的核心風險是 import 修改範圍太大。每次只搬一個語意邊界，測試通過後再搬下一個。

建議順序：

搬 domain/job 純型別。
搬 domain/job 純規則。
修正使用端 import。
搬 domain/event 純型別。
搬 event validation/normalize helper。
搬 application processor。
搬 adapter implementation。

不要同時搬 job、event、repository、handler。一次搬太多會讓失敗原因難以定位。

【執行】測試保護搬移

package 搬移的核心驗證是行為不變。搬檔案本身不是功能變更，所以測試應該確認原本行為仍然存在。

domain 規則測試：

1func TestJobCanTransition(t *testing.T) {
2    if !job.CanTransition(job.StatusPending, job.StatusRunning) {
3        t.Fatalf("pending should transition to running")
4    }
5    if job.CanTransition(job.StatusSucceeded, job.StatusRunning) {
6        t.Fatalf("succeeded should not transition to running")
7    }
8}

application 測試：

 1func TestProcessorAppliesJobProjection(t *testing.T) {
 2    repo := &fakeJobRepository{}
 3    processor := application.NewProcessor(repo)
 4
 5    err := processor.Process(context.Background(), event.Event{
 6        SubjectID: "job_1",
 7        Type:      event.JobStarted,
 8    })
 9    if err != nil {
10        t.Fatalf("process event: %v", err)
11    }
12
13    if repo.got.ID != "job_1" {
14        t.Fatalf("job ID = %q, want job_1", repo.got.ID)
15    }
16}

測試不需要關心檔案搬到哪裡，它只確認 package API 與行為仍然正確。

重構步驟

從平面 package 重構成 domain package，可以按這個順序：

列出現有檔案中的概念：request、response、domain state、event、repository、worker。
找出最穩定的 domain 名稱，例如 job、event、account。
先建立一個 domain package，不要一次建立整棵架構。
搬純型別與 typed constant。
用 type alias 過渡大型呼叫端。
搬純規則與測試。
修正 import，避免 domain 依賴 adapter。
測試通過後，再搬下一個 domain。

設計檢查

檢查一：目錄跟著概念壓力成長

服務還小時，一次建立 domain/application/infrastructure/interfaces 可能只會增加跳轉成本。先拆最痛的語意邊界。

檢查二：package 名稱表達 domain 概念

models、types、helpers 通常不夠好。它們說明了程式碼形狀，沒有說明業務語意。

檢查三：domain package 保持技術無關

domain 應保存業務語意，不應知道傳輸協定。若 domain import adapter，依賴方向已經反了。

檢查四：搬移和行為變更分開

package 重構應先保持行為不變。若同時改規則與搬檔案，測試失敗時很難判斷是搬移錯誤還是行為改動。

本章不處理

本章先處理 package 結構如何反映 domain 語意；更大型的 module 拆分與 monorepo 策略，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 type、rule 與 package 邊界；如果你要先回看語言教材，可以讀：

7.6 逐步遷移到 ports/adapters 架構

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

ports/adapters 遷移的核心目標是讓 application 與 domain 不依賴外部技術細節。HTTP、WebSocket、callback receiver、database 都是 adapters；usecase 透過 ports 使用它們。

這種重構不需要一次套完整架構。Go 專案更常見的做法是先把過重 handler、外部依賴與狀態寫入切開，再在壓力最大的邊界引入 port。

本章目標

學完本章後，你將能夠：

用依賴方向理解 ports/adapters
分辨 inbound adapter 與 outbound adapter
把 usecase 從 handler、repository、publisher 中切出
用新功能先走新架構的方式漸進遷移
驗證 import direction、usecase test 與 adapter integration test

【觀察】ports/adapters 是依賴方向

ports/adapters 的核心規則是外部技術依賴 application，而不是 application 依賴外部技術。HTTP、WebSocket、database、queue 都是可替換的邊界；usecase 應該依賴自己定義的 port。

目標方向：

1transport/http      ┐
2transport/websocket ├─> application ──> domain
3transport/callback  ┘        │
4                             ▼
5                      ports defined here
6                             ▲
7storage/memory       ┐       │
8eventlog/memory      ├───────┘
9publisher/websocket  ┘

資料夾名稱可以不同。真正重要的是 import direction：domain 不 import HTTP，application 不 import database implementation，adapter import application 並實作 application 需要的 port。

【判讀】inbound adapter 把外部輸入轉成 command

inbound adapter 的核心責任是接收外部訊號，轉成 application command 或 domain event。它不應直接修改 state，也不應保存業務規則。

常見 inbound adapter：

adapter	輸入	轉換結果
HTTP handler	HTTP request	command
WebSocket router	client message	command
callback receiver	external callback	domain event
worker	timer 或 queue item	command/event

例如 HTTP adapter：

 1type HTTPNotificationHandler struct {
 2    usecase *application.CreateNotificationUsecase
 3    now     func() time.Time
 4}
 5
 6func (h HTTPNotificationHandler) Create(w http.ResponseWriter, r *http.Request) {
 7    var req createNotificationRequest
 8    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 9        writeError(w, http.StatusBadRequest, "invalid_json", "request body must be valid JSON")
10        return
11    }
12
13    cmd := application.CreateNotificationCommand{
14        ID:        req.ID,
15        Topic:     req.Topic,
16        Title:     req.Title,
17        CreatedAt: h.now(),
18    }
19
20    if err := h.usecase.Execute(r.Context(), cmd); err != nil {
21        writeUsecaseError(w, err)
22        return
23    }
24
25    w.WriteHeader(http.StatusCreated)
26}

HTTP adapter 知道 JSON、status code、request body。usecase 不知道這些協定細節。

【判讀】outbound adapter 實作 application port

outbound adapter 的核心責任是實作 application 定義的 port。application 說「我需要儲存 notification」，adapter 決定用 memory、SQLite 或其他技術完成。

application 定義 port：

1package application
2
3type NotificationRepository interface {
4    Save(ctx context.Context, notification domain.Notification) error
5    FindByID(ctx context.Context, id string) (domain.Notification, bool, error)
6}

memory adapter 實作：

 1package memory
 2
 3type NotificationRepository struct {
 4    mu            sync.RWMutex
 5    notifications map[string]domain.Notification
 6}
 7
 8func (r *NotificationRepository) Save(ctx context.Context, notification domain.Notification) error {
 9    r.mu.Lock()
10    defer r.mu.Unlock()
11    r.notifications[notification.ID] = notification
12    return nil
13}
14
15func (r *NotificationRepository) FindByID(ctx context.Context, id string) (domain.Notification, bool, error) {
16    r.mu.RLock()
17    defer r.mu.RUnlock()
18    notification, ok := r.notifications[id]
19    return notification, ok, nil
20}

adapter import application 不一定必要，因為 Go implicit interface 不要求顯式宣告。只要 method set 符合，組裝時就能傳給 usecase。

【策略】usecase 是遷移中心

usecase 的核心角色是協調 domain 規則與 ports。它不處理 HTTP，也不操作具體資料庫。

 1package application
 2
 3type CreateNotificationUsecase struct {
 4    repository NotificationRepository
 5    eventLog   EventLog
 6}
 7
 8func NewCreateNotificationUsecase(repository NotificationRepository, eventLog EventLog) *CreateNotificationUsecase {
 9    return &CreateNotificationUsecase{
10        repository: repository,
11        eventLog:   eventLog,
12    }
13}
14
15func (u *CreateNotificationUsecase) Execute(ctx context.Context, cmd CreateNotificationCommand) error {
16    notification := domain.Notification{
17        ID:        cmd.ID,
18        Topic:     cmd.Topic,
19        Title:     cmd.Title,
20        CreatedAt: cmd.CreatedAt,
21    }
22
23    if err := u.repository.Save(ctx, notification); err != nil {
24        return fmt.Errorf("save notification: %w", err)
25    }
26
27    event := domain.NewNotificationCreated(notification)
28    if err := u.eventLog.Append(ctx, event); err != nil {
29        return fmt.Errorf("append event: %w", err)
30    }
31
32    return nil
33}

這個 usecase 只依賴 domain 與 ports。HTTP handler、WebSocket router、memory repository、[event log](/go/backend/knowledge-cards/event-log) implementation 都在外面。

【執行】組裝放在 main 或 composition root

composition root 的核心責任是建立 concrete implementation，並把它們接到 usecase 與 adapter。Go 專案常把這件事放在 main.go 或 cmd/.../main.go。

 1func main() {
 2    notificationRepo := memory.NewNotificationRepository()
 3    eventLog := memory.NewEventLog()
 4
 5    createNotification := application.NewCreateNotificationUsecase(
 6        notificationRepo,
 7        eventLog,
 8    )
 9
10    handler := httpadapter.NewNotificationHandler(createNotification, time.Now)
11
12    mux := http.NewServeMux()
13    mux.HandleFunc("POST /notifications", handler.Create)
14
15    server := &http.Server{
16        Addr:    ":8080",
17        Handler: mux,
18    }
19
20    if err := server.ListenAndServe(); err != nil {
21        log.Fatal(err)
22    }
23}

main 可以知道所有具體實作，因為它負責組裝。這不違反依賴方向；問題是 application 或 domain 不能反過來 import main、HTTP adapter 或 memory adapter。

【策略】新功能先走新架構

漸進式遷移的核心策略是新功能先走新邊界，舊功能在被修改時再搬。一次性大重構風險高，容易同時改壞行為與結構。

建議做法：

新 endpoint 直接建立 command/usecase。
新 repository 先定義小 port。
新 event flow 先走 DomainEvent 與 processor。
舊 handler 只有在新增需求或修 bug 時才拆。
保留舊路徑測試，搬移完成再刪掉。

這樣可以讓新架構逐步長出來，而不是一次強迫整個專案符合模板。

【執行】從 callback ingestion 開始切

以外部 callback 進入事件系統為例，application usecase 可以叫 IngestExternalEvent：

 1package application
 2
 3type EventLog interface {
 4    Append(ctx context.Context, event domain.Event) error
 5}
 6
 7type EventProcessor interface {
 8    Process(ctx context.Context, event domain.Event) error
 9}
10
11type IngestExternalEvent struct {
12    eventLog  EventLog
13    processor EventProcessor
14}
15
16func (u *IngestExternalEvent) Execute(ctx context.Context, event domain.Event) error {
17    if err := event.Validate(); err != nil {
18        return fmt.Errorf("validate event: %w", err)
19    }
20    if err := u.eventLog.Append(ctx, event); err != nil {
21        return fmt.Errorf("append event: %w", err)
22    }
23    if err := u.processor.Process(ctx, event); err != nil {
24        return fmt.Errorf("process event: %w", err)
25    }
26    return nil
27}

callback adapter 只負責 raw input 轉 domain event：

 1func (h CallbackHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 2    var raw RawNotificationCallback
 3    if err := json.NewDecoder(r.Body).Decode(&raw); err != nil {
 4        writeError(w, http.StatusBadRequest, "invalid_json", "invalid JSON")
 5        return
 6    }
 7
 8    event, err := NormalizeNotificationCallback(raw, time.Now())
 9    if err != nil {
10        writeError(w, http.StatusBadRequest, "invalid_payload", "invalid callback payload")
11        return
12    }
13
14    if err := h.ingest.Execute(r.Context(), event); err != nil {
15        writeError(w, http.StatusInternalServerError, "ingest_failed", "event ingest failed")
16        return
17    }
18
19    w.WriteHeader(http.StatusAccepted)
20}

這個切法讓 callback 格式停在 adapter，event log 與 processor 行為停在 application。

【判讀】WebSocket adapter 也是 inbound adapter

WebSocket adapter 的核心責任是把 client message 轉成 command。它不應直接知道 repository 或 event log implementation。

1type WebSocketAdapter struct {
2    router *MessageRouter
3}
4
5type MessageRouter struct {
6    subscriptions application.SubscriptionUsecase
7}

router 可以呼叫 application usecase：

 1func (r *MessageRouter) handleSubscribeTopic(ctx context.Context, clientID string, req SubscribeTopicRequest) ServerMessage {
 2    cmd := application.SubscribeTopicCommand{
 3        ClientID:       clientID,
 4        Topic:          req.Topic,
 5        IncludeHistory: req.IncludeHistory,
 6    }
 7
 8    if err := r.subscriptions.SubscribeTopic(ctx, cmd); err != nil {
 9        return ErrorMessage("", "subscribe_failed", "topic subscription failed")
10    }
11
12    return OKMessage("", map[string]string{"topic": req.Topic})
13}

這和 HTTP handler 的方向相同：adapter 處理協定，application 處理行為。

【執行】驗證 import direction

架構邊界的核心驗證是 import direction。即使沒有工具，也可以用簡單規則檢查：

1domain       不 import application、transport、storage
2application  可以 import domain，不 import transport/storage implementation
3transport    可以 import application/domain
4storage      可以 import application/domain
5cmd/main     可以 import 所有 adapter 與 application 做組裝

可以用 go list 觀察 package 依賴：

1go list -deps ./...

也可以在 review 時檢查：如果 domain/job import 了 net/http，幾乎一定是邊界錯了；如果 application import 了 storage/memory，則 usecase 已經依賴 implementation。

【執行】usecase test 與 adapter integration test 分工

測試分工的核心原則是 usecase 測規則，adapter 測協定轉換與組裝。不要只靠端到端測試保護所有行為。

usecase test：

 1func TestIngestExternalEventAppendsAndProcesses(t *testing.T) {
 2    eventLog := &fakeEventLog{}
 3    processor := &fakeEventProcessor{}
 4    usecase := &application.IngestExternalEvent{
 5        eventLog:  eventLog,
 6        processor: processor,
 7    }
 8
 9    event := validDomainEvent()
10    if err := usecase.Execute(context.Background(), event); err != nil {
11        t.Fatalf("ingest event: %v", err)
12    }
13
14    if len(eventLog.appended) != 1 {
15        t.Fatalf("appended events = %d, want 1", len(eventLog.appended))
16    }
17    if len(processor.processed) != 1 {
18        t.Fatalf("processed events = %d, want 1", len(processor.processed))
19    }
20}

adapter integration test 則可以用 httptest 驗證 request/response 與 usecase fake 是否被呼叫。兩種測試分工清楚，失敗時才知道是規則錯還是協定轉換錯。

重構步驟

逐步遷移到 ports/adapters，可以按這個順序：

先找一條最痛的功能路徑，例如新增 notification 或 ingest external event。
把 handler/router 中的規則抽成 command/usecase。
在 application 定義 repository、event log、publisher port。
讓現有 memory store 或 publisher 實作 port。
main 組裝 concrete adapter 與 usecase。
新功能只走新路徑。
舊功能被修改時，逐步搬到同樣邊界。
用 import direction review 防止反向依賴。

設計檢查

檢查一：遷移從單一邊界開始

ports/adapters 的價值是依賴方向。若沒有先拆 usecase 與 port，只是搬資料夾，複雜度會上升但邊界不會變清楚。

檢查二：application 依賴 port

application 應依賴 port，不依賴 memory、SQLite 或 database adapter。若 application import storage，依賴方向已經反了。

檢查三：業務規則留在 application 或 domain

adapter 可以驗證輸入格式，但業務規則應該在 usecase 或 domain。否則 HTTP 與 WebSocket 會各自複製規則。

檢查四：port 跟著使用端分散

port 應靠近使用端。把所有 interface 集中到一個大型 package，常會讓依賴重新糾纏在一起。

本章不處理

本章先處理 ports/adapters 的依賴方向；分散式系統、資料庫與平台 wiring，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 handler、repository、event 與 composition root 的遷移路線；如果你要先回看語言教材，可以讀：

小結

ports/adapters 遷移的重點是控制依賴方向：adapter 處理外部技術，application 定義 usecase 與 ports，domain 保存核心語意。Go 專案可以漸進式遷移，新功能先走清楚邊界，舊功能在修改時再搬。架構的價值在於測試更直接、替換更容易、核心規則不被外部技術綁住。

7.7 composition root 與依賴組裝

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

composition root 的核心責任是集中建立具體依賴。domain 與 application 應依賴 port；main 或啟動層負責讀取 config、建立 adapter、組裝 usecase、註冊 handler 與啟動 server。

本章目標

學完本章後，你將能夠：

理解 composition root 為什麼要集中在啟動層
分辨 port、adapter 與 usecase 的組裝責任
用 typed config 讓 wiring 依賴可讀、可測、可替換
看懂哪些依賴應在 main 組裝，哪些不該散在 handler 裡
讓啟動層只負責「把系統接起來」，不負責業務規則

【觀察】composition root 是整個應用的接線板

composition root 的核心用途是把具體依賴集中在一個地方建立。這個地方通常是 main()、cmd/.../main.go 或啟動層 package。

當讀者打開入口程式時，應該能直接看到：

config 從哪裡來
repository 怎麼建立
publisher / worker / server 怎麼串起來
哪些 dependency 是 mockable port
哪些是明確的外部 adapter

這種集中式 wiring 的好處是：

依賴方向清楚
測試替身好替換
啟動問題容易定位
不會把建構邏輯散落到各個 handler 或 usecase

【判讀】dependency injection 的重點是方向

Go 的依賴注入通常不需要框架。真正的重點是：高層只依賴 port，低層在入口被組裝進來。

例如：

1type App struct {
2 jobs JobRepository
3 log EventLog
4}
5
6func NewApp(jobs JobRepository, log EventLog) *App {
7 return &App{jobs: jobs, log: log}
8}

main() 負責建立具體實作，再傳給 NewApp：

 1func main() {
 2 cfg := LoadConfig()
 3
 4 repo := NewSQLJobRepository(cfg.DatabaseDSN)
 5 eventLog := NewRedisEventLog(cfg.RedisAddr)
 6 app := NewApp(repo, eventLog)
 7
 8 server := NewHTTPServer(app)
 9 log.Fatal(server.ListenAndServe())
10}

這裡沒有框架，但依賴方向已經清楚：App 不知道 SQL 或 Redis 是怎麼接的。

【策略】typed config 先收斂設定，再進行組裝

composition root 會變亂，通常是因為設定沒有先整理成型別清楚的 config。把環境變數、flag 與預設值先集中讀成結構體，wiring 會清楚很多。

1type Config struct {
2 HTTPAddr string
3 DatabaseDSN string
4 RedisAddr string
5}

load config 的責任是把外部輸入變成可預期的程式設定，而不是在每個 adapter 初始化時各自讀環境變數。

【執行】建立 adapter 後再注入 usecase

常見的組裝順序是：

讀 config。
建立 logger / metrics / tracer。
建立 database / cache / broker client。
建立 repository 與 service。
建立 handler 或 server。
啟動背景 worker 與 HTTP server。

這樣做可以讓初始化失敗在入口層就被看見，不會等到請求進來才爆。

【判讀】組裝邏輯應集中在入口層

如果 handler 自己 new repository、new client、new worker，就會出現這些問題：

測試無法替換依賴
生命週期很難控制
每個 request 都可能建立不必要的資源
啟動路徑與請求路徑混在一起

handler 應該只接收已組裝好的依賴，專心處理輸入和回應。

【延伸】Backend 教材負責具體外部服務語意

Go 章節只需要知道依賴怎麼接，真正的外部服務語意留給 Backend 教材：

database client 建立、pool 與 transaction 語意
Redis client、pipeline 與 cache 邊界
broker connection、[durable queue](/go/backend/knowledge-cards/durable-queue) 與重試
platform secret、runtime limit 與部署環境

Go 的 composition root 不需要重複教這些技術，只要把它們正確接上即可。

模組七：重構實戰

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

Go 重構的核心目標是讓邊界更清楚、測試更直接、資料競爭更少。抽象只在它能降低耦合或保護行為時才有價值；本模組用一般 Go 服務範例說明如何在程式仍可運行的前提下，從平面檔案結構逐步走向更清楚的 package、interface、state 與 adapter 邊界。

重構章節的主軸是「壓力出現後再拆分」。小型 Go 程式可以保持簡單；當 handler 過重、狀態外洩、測試困難、事件語意混亂或外部依賴變多時，再逐步引入 domain-oriented package 與 ports/adapters。這種順序比一開始套用完整分層架構更符合 Go 的工程習慣。

章節列表

章節	主題	關鍵收穫
7.1	把 handler 邏輯拆成可測單元	分離協定處理與業務邏輯
7.2	用 interface 隔離外部依賴	建立小而穩定的測試替身
7.3	事件去重邏輯的重構策略	保留語義鍵，降低重複流程
7.4	狀態管理的安全邊界	用複製與鎖保護共享資料
7.5	以 domain 重新整理 package	讓 account、job、event、workflow 這類語意邊界可見
7.6	逐步遷移到 ports/adapters 架構	用 ports/adapters 控制依賴方向
7.7	composition root 與依賴組裝	把具體 adapter、config 與 usecase wiring 留在入口層
7.8	壓力出現後的重構路線	按壓力逐步拆邊界，讓服務變大仍可維護

本模組的重構判斷

先保行為，再搬結構：每次重構都要有測試或可觀察行為保護。
package 代表語意邊界：清楚的 domain 名稱能讓責任可見；utils、common 這類技術分類容易把不同概念混在一起。
interface 由使用端定義：usecase 需要什麼能力，就定義什麼 port。
state 要有擁有者：共享 map、slice、projection 必須集中寫入並保護 copy boundary。
架構不是目錄模板：ports/adapters 的重點是依賴方向，不是固定資料夾名稱。

章節粒度說明

重構章節刻意維持「一章一條遷移路線」。每章會先說明壓力訊號，再給局部重構策略、測試保護、設計檢查與延伸範圍。這種安排讓讀者能照著章節做小步遷移；完整架構模板應在遷移壓力明確後再引入。

如果只想查單一概念，可以依照下列對照閱讀：

重構問題	優先閱讀
handler 太厚	把 handler 邏輯拆成可測單元
外部依賴難測	用 interface 隔離外部依賴
事件重複或來源變多	事件去重邏輯的重構策略
共享狀態外洩	狀態管理的安全邊界
檔案平面結構失去語意	以 domain 重新整理 package
依賴方向需要穩定	逐步遷移到 ports/adapters 架構
抽出 port 後不知道在哪裡 new adapter	composition root 與依賴組裝

本模組使用的範例主題

事件處理流程重構
共享狀態重構
查詢介面邊界
feature gate 邏輯
domain package 切分
inbound/outbound adapter 遷移
composition root 與依賴組裝

學習時間

預計 2.5 小時

模組七：重構實戰

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

本模組基於 v0.28.0-v0.31.0 Hook 系統重構的實際經驗，教你如何識別程式碼問題並進行系統性重構。

學習目標

學會識別常見的程式碼壞味道
理解配置與程式碼分離的重要性
掌握 DRY 原則的實踐方法
學會消除魔法數字
能夠進行系統性的程式碼重構
理解變數作用域變更在重構中的風險

章節內容

重構的動機與策略

量化認知負擔、制定重構策略、掌握階段分解方法。

程式碼壞味道識別

學習如何識別程式碼中的問題，包括 Error Patterns 系統介紹和 5 Why 分析方法。

DRY 原則與共用程式庫

基於 IMP-001 錯誤模式，學習如何識別重複程式碼並建立共用模組。

配置分離與常數管理

基於 IMP-002、ARCH-001 錯誤模式，學習三種硬編碼（魔法數字、配置、字串）的系統性消除。

大規模統一化重構

基於 W22-W24 統一化重構經驗，學習三階段漸進式重構方法。

重構陷阱與防護

基於 IMP-003、IMP-005 錯誤模式，學習重構中的常見陷阱和防護措施。

非程式碼的重構

文件壞味道識別與 Progressive Disclosure 精簡策略。

完整案例回顧

完整回顧 v0.28.0-v0.31.0 重構流程，從問題識別到最終成果。

作用域迴歸案例研究

基於 IMP-003 錯誤模式，學習 Python 變數作用域在重構中的陷阱。W24 統一 logger 初始化時，7 個 Hook 因作用域變更靜默失敗的真實案例。

重構成效數據

v0.28.0 重構的實際成果：

指標	數值
消除重複程式碼	~415 行
Hook 檔案縮減	38%-65%
新增共用模組	7 個
單元測試	28 個（全部通過）

資料來源

本模組使用的實際案例來自：

Error Patterns: .claude/error-patterns/ 目錄下的錯誤模式文件
Git 歷史: Commit 60f1b95（v0.28.0）、3cf47d4e（v0.31.0 W24）及相關重構提交
共用程式庫: .claude/lib/ 目錄下的模組

先修知識

建議先完成以下模組：

文件版本：v0.31.0 最後更新：2026-03-04

7.8 壓力出現後的重構路線

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

這一章補的是一個很實際的問題：服務還能跑，但已經不好讀、不好測、不好改時，應該怎麼重構。Go 的重構是先辨認壓力來源，再逐步把邊界拉開。

本章目標

學完本章後，你將能夠：

辨認 handler、state、interface 與 adapter 的壓力訊號
了解什麼時候該先拆函式，什麼時候該拆 package
用小步遷移方式保持行為穩定
將重構與測試保護綁在一起
讓服務變大時仍能維持可讀性

【觀察】壓力通常先出現在局部

Go 服務變大後，最先冒出來的問題通常是局部壓力：

handler 開始太厚
state 太分散
event 語意不清
依賴越來越多
測試開始很脆弱

這些訊號表示該重構，但不代表要一次重寫。

【判讀】先保行為，再搬結構

重構的基本順序應該是：

先讓行為有測試或觀察點
再把大函式拆成小函式
再把責任拆到 package 或 interface
最後才引入更清楚的 adapter 邊界

這樣可以降低重構風險，也比較符合 Go 的漸進式習慣。

【策略】先拆最有壓力的邊界

最值得先處理的通常是這幾種：

壓力訊號	優先動作
handler 過重	拆成協定處理與業務函式
外部依賴難測	抽出小介面
state 外洩	集中擁有者並控制 copy boundary
事件混亂	先定義語意，再拆 package
依賴耦合太高	用 ports/adapters 穩定方向

這些動作不一定同時做，而是按壓力大小逐步處理。

【執行】composition root 是最後的收斂點

當系統開始出現明確的 application、domain 與 adapter 時，composition root 會變成依賴組裝的收斂點。重構的目標是讓邏輯邊界與依賴方向更穩定。

重構的動機與策略

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

你有沒有修完一個 Bug，一週後發現另一個地方有完全一樣的問題？或者改了一個函式的行為，卻不確定還有哪些地方依賴它？這些情境的根源往往是程式碼結構讓問題難以被看見。

重構是改變程式碼的內部結構，而不改變其外部行為。聽起來簡單，但實務上最困難的問題不是「怎麼改」，而是「為什麼改」和「什麼順序改」。

本章從 Hook 系統兩次大規模重構（v0.28.0 和 v0.31.0）的經驗出發，討論重構的動機判斷和階段分解策略。Hook 系統是一個由數十個 Python 腳本組成的自動化系統，負責程式碼品質檢查、流程驗證和開發規範執行。

為什麼要重構

認知負擔超載

重構的第一個訊號是：讀程式碼時，你需要同時記住太多東西。

v0.28.0 重構前，task-dispatch-readiness-check.py 有 858 行。閱讀這個檔案時，你需要同時追蹤：

15 個代理人的名稱和觸發條件
Git 分支操作的 subprocess 細節
Worktree 路徑解析邏輯
重複出現的工具函式（同一個 run_git_command 在多個檔案中各自定義一次）

心理學家 George Miller 的研究指出，人類的工作記憶一次只能處理 7 加減 2 個項目。858 行的檔案遠超這個限制。你不可能在腦中同時維護這麼多上下文來理解程式碼的行為。

我們可以用一個簡單的公式量化這個問題：

1認知負擔指數 = 變數數 + 分支數 + 巢狀深度 + 依賴數

指數	評估	行動
1-5	優良	維持
6-10	可接受	考慮最佳化
11-15	需重構	排入計畫
> 15	必須重構	立即處理

v0.28.0 重構前的 task-dispatch-readiness-check.py，光是頂層函式就有 23 個，模組級變數超過 10 個。認知負擔指數遠超 15，屬於「必須重構」等級。

不重構的代價

「能動就不要碰」是常見的想法，但不重構的代價會隨時間累積。

v0.31.0 的 W24 開發週期提供了一個具體案例。任務是統一 16 個 Hook 檔案的 logger 初始化風格——看起來是一個簡單的機械性修改。但因為缺乏共用模組和清晰的模組邊界，修改引發了一個作用域問題（將全域變數移入函式後，其他引用該變數的函式失去存取權限），導致 7 個 Hook 靜默失敗，影響 41 個函式。更糟的是，這個問題至少持續了 2 個 session 才被發現。

完整的作用域迴歸分析參見作用域迴歸案例研究。

靜默失敗比直接報錯更危險。錯誤被頂層的 try/except 吞掉，只寫入日誌檔案，而沒有人在看日誌。如果重構前就有清晰的模組邊界和完整的測試覆蓋，這個問題可以在修改當下就被偵測到。

重複程式碼的連鎖效應

另一個推動重構的因素是重複。我們用一行指令就能量化問題的嚴重程度：

1# 在專案根目錄執行
2grep -h "^def " .claude/hooks/*.py | sort | uniq -c | sort -rn | head -5

v0.28.0 重構前的結果顯示，run_git_command 在多個檔案中各有一份定義。這意味著：

修復一個 Bug 要改 4 個地方
漏改任何一個就會產生行為不一致
新增 Hook 時需要再複製一份

重複程式碼的總行數約 415 行。這 415 行不只是浪費空間——它們是 415 行的維護風險。

判斷三問

在決定是否重構之前，問自己三個問題：

讀這段程式碼時，我需要同時記住多少東西？ 超過 7 個就是警訊。
如果要修改一個行為，我需要改幾個地方？ 超過 1 個就有重複的問題。
新人加入團隊後，需要多久才能理解這段程式碼？ 如果答案是「需要有人口頭解釋」，那就是程式碼本身不夠清楚。

如果三個問題的答案都指向問題，那就該動手了。

何時不應該重構

不是所有情況都適合重構。以下三個時機，重構通常會帶來更多問題。

沒有測試保護時

重構的前提是：你能驗證修改後的行為和修改前一致。沒有測試，你就無法確認這一點。

1# 假設你想把這段程式碼抽成函式
2if len(result.stdout.strip()) > 0:
3    branches = result.stdout.strip().split("\n")
4    branches = [b.strip() for b in branches if b.strip()]
5    protected = [b for b in branches if b in ["main", "master"]]

這段邏輯涉及空字串處理、換行符分割、空白清理。如果沒有測試覆蓋這些邊界情況，抽取函式時很容易改變行為而不自知。

原則：先寫測試，再重構。如果時間只夠做一件事，選擇寫測試。

修 Bug 時順手重構

修 Bug 和重構是兩件不同的事。混在一起做會產生兩個問題：

難以驗證：Bug 修好了嗎？還是被重構掩蓋了？
難以回溯：如果重構引入了新問題，git bisect 無法區分哪些變更是修 Bug、哪些是重構

1# 錯誤的工作流程
2commit: "修復 #42 並重構 git_utils"  ← 兩件事混在一個 commit
3
4# 正確的工作流程
5commit: "修復 #42：branch 名稱解析的空字串處理"
6commit: "重構 git_utils：抽取 parse_branch_name 函式"

原則：先修好 Bug 並提交，確認測試通過，然後再開始重構。

時間壓力下

v0.31.0 W24 的 logger 統一修改就是一個教訓——在時間壓力下跳過了跨函式引用的完整驗證，結果 7 個 Hook 靜默失敗，修復花費的時間遠超原本省下的。

重構需要完整的注意力。趕進度時進行重構，容易在壓力下跳過驗證步驟（「測試之後再補」），反而製造更多技術債務。

原則：記錄下需要重構的地方，排入後續計畫。不要在時間壓力下動手。

判斷清單

把上述三個情境整理成一個快速檢查清單：

問題	是	否
有測試覆蓋修改區域？	可以繼續	先寫測試
修改範圍只有重構？	可以繼續	先分開 Bug 修復和重構
有足夠的時間完成驗證？	可以繼續	記錄後排入計畫

三個問題都回答「是」，才開始動手。

Wave 分解策略

大規模重構最容易失敗的原因是：試圖一次做完所有事情。

Wave：一個有明確目標和驗證點的重構階段。每完成一個 Wave，程式碼都必須處於可用狀態。

Wave 分解的核心思想是：把重構拆成多個有序的 Wave，確保每一步都可驗證、可回退。

v0.28.0：基礎架構重構

v0.28.0 將 Hook 系統從「各自為政」重構為「共用模組 + 配置分離」的架構。拆分為 4 個 Wave：

Wave 1：建立共用程式庫

先建立共用模組的介面和測試，不改動任何現有 Hook。

1建立模組    →  寫測試    →  確認測試通過
2config_loader    4 個測試
3git_utils        6 個測試
4hook_io          3 個測試
5hook_logging     2 個測試

為什麼先做這步？因為後續 Wave 需要依賴這些模組。如果跳過這步直接改 Hook，會遇到「要用的函式還不存在」的問題。

Wave 2：配置分離

把 task-dispatch 中的硬編碼清單（代理人名稱、品質規則、指令對應表）抽到 YAML 配置檔。這是行數最多、修改範圍最大的階段。

1# 重構前：硬編碼在 Python 中
2AGENTS = {
3    "parsley-flutter-developer": {"type": "implementation", "lang": "dart"},
4    "thyme-python-developer": {"type": "implementation", "lang": "python"},
5    # ... 15 個代理人定義散落在程式碼中
6}
7
8# 重構後：讀取 YAML 配置
9agents = config_loader.load_config("agents.yaml")

分離後，新增代理人只需要編輯 YAML 檔案，不需要動 Python 程式碼。

Wave 3：逐檔重構

有了共用程式庫和配置檔，逐一修改 Hook 檔案。每改完一個檔案就執行測試，確保沒改壞東西。這個階段的關鍵是紀律：每次只改一個檔案，改完就跑測試，不要累積多個修改後一起驗證。

Wave 4：驗證與清理

28 個單元測試全部通過。移除不再需要的重複程式碼。檢查是否有遺漏的相依性。

v0.31.0：風格統一與防護強化

v0.31.0 的重構是在既有架構上統一風格和強化防護，規模與性質都與 v0.28.0 不同。拆分為 4 個 Wave（W22-W25）：

Wave	目標	性質
W22	日誌系統統一	機械性修改
W23	訊息常數抽取	機械性修改
W24	程式碼風格統一	機械性，但觸發了作用域問題
W25	修復 W24 問題 + 防護機制	修復 + 新功能

注意 W25 的存在。它不在原始計畫中，而是 W24 出問題後臨時新增的。好的分解策略要預留處理意外的空間。

兩次重構的對比：

維度	v0.28.0	v0.31.0
性質	建立新架構	統一既有架構的風格
風險來源	介面設計是否正確	機械性修改是否有隱含的邏輯變更
Wave 數	4（全部計畫內）	4（第 4 個是意外新增）
教訓	先建基礎設施再動手	機械性修改也可能觸發邏輯問題

Wave 分解的原則

從兩次重構經驗中，可以歸納出三個分解原則：

原則 1：依賴方向決定順序

被依賴的模組先做。v0.28.0 先建共用程式庫（Wave 1），因為後續所有 Wave 都會用到它。

1Wave 1: 共用模組（被所有 Hook 依賴）
2    ↓
3Wave 2: 配置檔（被 task-dispatch 依賴）
4    ↓
5Wave 3: Hook 檔案（依賴共用模組和配置檔）
6    ↓
7Wave 4: 驗證（依賴所有修改完成）

原則 2：機械性修改和邏輯修改分開

機械性修改（如統一命名風格、統一匯入路徑）和邏輯修改（如改變函式行為、改變變數作用域）不該放在同一個 Wave。

v0.31.0 的 W24 表面上是機械性修改（統一 logger 初始化位置），但實際上涉及了作用域的邏輯變更——把全域變數移入函式，會影響所有引用它的其他函式。如果在規劃時就識別出這一點，應該把「移動 logger 位置」和「修改函式簽名以傳遞 logger 參數」拆成兩個步驟。

怎麼區分？問自己：這個修改會不會改變任何函式的可見變數？ 如果會，就不是純機械性修改。

原則 3：每個 Wave 結束時程式碼必須可用

不能出現「改到一半，程式跑不起來」的狀態。每個 Wave 完成後：

所有測試通過
程式碼可正常執行
可以安全地提交

這保證了即使中途需要停下來處理其他事情，程式碼也不會處於損壞狀態。

分解流程

把上述原則整理成一個可操作的流程：

 1Step 1: 畫出依賴關係圖
 2    → 哪些模組被其他模組依賴？（先做）
 3    → 哪些模組互相獨立？（可以並行）
 4
 5Step 2: 分類修改類型
 6    → 機械性修改：統一命名、統一格式、統一匯入
 7    → 邏輯修改：改變函式行為、改變資料流、改變作用域
 8
 9Step 3: 分配到 Wave
10    → Wave N: 基礎設施（被依賴的、獨立的）
11    → Wave N+1: 機械性修改（依賴基礎設施）
12    → Wave N+2: 邏輯修改（依賴前面的修改）
13    → Wave N+3: 驗證與清理
14
15Step 4: 每個 Wave 定義驗證標準
16    → 哪些測試必須通過？
17    → 程式碼能正常執行嗎？
18    → 可以安全提交嗎？

度量表

用量化指標驗證重構是否達到目標：

指標	v0.28.0 前	v0.28.0 後	v0.31.0 後
共用模組數	0	4	7+
重複程式碼行數	~415 行	~0	~0
新增 Hook 的樣板行數	~15 行	~10 行	~5 行（核心呼叫 1 行）
Error Patterns 記錄數	4	8	19
task-dispatch 行數	858	296	267

幾個值得注意的趨勢：

共用模組數從 0 成長到 7+。這代表重複程式碼有了歸屬，不再散落各處。
新增 Hook 的樣板行數從 15 行降到約 5 行（核心只需 1 行匯入呼叫）。新增一個 Hook 從「複製一堆工具函式」變成「匯入共用模組」。
Error Patterns 從 4 成長到 19。這不是壞事——它代表團隊開始系統性地記錄和傳承經驗，而不是每個人各自出問題。

小結

重構的決策可以歸納為三個問題：

該不該做？ 認知負擔超載、重複程式碼累積、維護成本持續上升，就該做。
現在能做嗎？ 有測試保護、不在修 Bug、時間充裕，才能做。
怎麼拆分？ 按依賴順序，機械和邏輯分開，每步結束都可用。

後續章節會深入每個具體的重構技巧：如何識別壞味道、如何抽取配置、如何消除重複、如何處理作用域陷阱。

思考題

你目前的專案中，有哪些檔案的行數超過 200 行？列出前三名，分析它們為什麼會這麼長——是職責太多、重複程式碼、還是配置和邏輯混在一起？
回想一次你在修 Bug 時順手重構的經驗。事後回頭看 git log，能清楚區分哪些變更是修 Bug、哪些是重構嗎？
如果你的專案完全沒有測試，但認知負擔已經很高，你會怎麼規劃「補測試」和「重構」的先後順序？

實作練習

用以下指令掃描你的專案，找出重複定義的函式：
```
1# 在專案根目錄執行
2grep -h "^def " your_project/*.py | sort | uniq -c | sort -rn | head -10
```
分析結果：哪些函式被重複定義了？它們應該被抽到哪個共用模組？
選一個超過 200 行的檔案，嘗試畫出它的 Wave 分解計畫。回答以下問題：
- 哪些部分被其他部分依賴？（先做）
- 哪些修改是機械性的？（可以批量處理）
- 每個 Wave 完成後，程式碼能正常執行嗎？
計算你選定檔案的認知負擔指數（變數數 + 分支數 + 巢狀深度 + 依賴數）。找出指數最高的函式，思考如何將它拆分到指數低於 10。

下一章：程式碼壞味道偵測

文件版本：v0.31.0 最後更新：2026-03-04

程式碼壞味道偵測

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

上一章：重構的動機與策略

「程式碼壞味道」(Code Smell) 是 Martin Fowler 在《Refactoring》中提出的概念：程式碼中暗示深層問題的表面跡象。壞味道不是 Bug，程式仍然能正常執行，但它們預告了維護成本的攀升。上一章介紹了認知負擔指數——重複程式碼和難以理解的結構是指數升高的主要原因。本章把這些讓認知負擔上升的具體模式系統化，稱為「壞味道」。

本章建立一套從「識別」到「行動」的完整流程：先以三級分類理解問題的嚴重程度，再以工具鏈偵測，最後透過 5 Why 分析找到根本原因。

壞味道三級分類

不是所有壞味道都一樣嚴重。依照影響範圍和修復成本，分成三個等級：

第一級：實作級 – 單一檔案內的問題

影響範圍最小，通常改一個檔案就能解決。

Pattern ID	壞味道	典型症狀	風險
IMP-001	重複程式碼散落各處	同一個函式在 4 個檔案各寫一次	中
IMP-002	魔法數字	`line[9:]` – 為什麼是 9？	低

IMP-001 範例：四份一模一樣的函式

 1# hooks/pre_commit.py
 2def run_git_command(cmd):
 3    result = subprocess.run(cmd, capture_output=True, text=True)
 4    return result.stdout.strip()
 5
 6# hooks/post_merge.py -- 完全相同的程式碼
 7def run_git_command(cmd):
 8    result = subprocess.run(cmd, capture_output=True, text=True)
 9    return result.stdout.strip()
10
11# hooks/branch_check.py -- 又是一模一樣
12# hooks/worktree_guardian.py -- 第四份...

問題在於當你需要加入錯誤處理時，要改四個地方，漏掉一個就是 Bug。

IMP-002 範例：沒人記得的數字

1def parse_worktree_line(line):
2    if line.startswith("worktree "):
3        return line[9:]  # 三個月後，你還記得 9 是什麼嗎？

第二級：架構級 – 跨模組的結構問題

影響多個檔案的互動方式，需要架構層面的重新設計。

Pattern ID	壞味道	典型症狀	風險
ARCH-001	配置與程式碼混合	800 行的檔案，一半是配置資料	高

ARCH-001 範例：被配置淹沒的邏輯

 1# 一個 800+ 行的 Hook 檔案
 2PROTECTED_BRANCHES = ["main", "master", "develop"]
 3ALLOWED_PATTERNS = ["feat/*", "fix/*", "chore/*"]
 4ERROR_MESSAGES = {
 5    "branch_not_allowed": "分支名稱不符合規範",
 6    "missing_ticket": "缺少 Ticket 引用",
 7    # ... 數十行配置繼續
 8}
 9
10def check_branch():
11    # 真正的邏輯只有幾十行，卻埋在幾百行配置之下
12    pass

修改一條錯誤訊息就要打開整個程式碼檔案，負責配置的人被迫閱讀程式邏輯，負責邏輯的人被迫捲過數百行配置——兩者都承受了不必要的負擔。

第三級：遷移級 – 重構過程中引入的問題

最危險的一類。它們是在修復其他壞味道時「創造」出來的新問題。遷移級問題在 Error Pattern 系統中仍使用 IMP 前綴，因為它們本質上是實作層面的作用域和 Import 問題——只是發生在重構過程中，因此格外危險。

Pattern ID	壞味道	典型症狀	風險
IMP-003	重構作用域迴歸	變數移入函式後，其他函式找不到	高
IMP-005	模組遷移 Import 斷裂	檔案搬家後，Import 路徑沒跟著改	高

IMP-003 範例：搬家沒留新地址

 1# 修正前：logger 是全域變數，所有函式都看得到
 2logger = setup_hook_logging("hook-name")
 3
 4def helper_function():
 5    logger.info("doing something")  # OK，全域可見
 6
 7def main():
 8    result = helper_function()
 9
10# 修正後：logger 搬進 main()，但 helper 沒收到通知
11def helper_function():
12    logger.info("doing something")  # NameError! logger 不見了
13
14def main():
15    logger = setup_hook_logging("hook-name")  # 現在是區域變數
16    result = helper_function()  # helper 找不到 logger

這個 Bug 在真實專案中影響了 7 個 Hook、41 個函式。更危險的是，例外捕捉機制將錯誤靜默吞掉，直到開發者主動翻查日誌才發現。在事件發生當時，錯誤被靜默吞掉。此問題後來已修復，現在 Hook 失敗會輸出到 stderr 確保開發者可見。

三級分類速查表

級別	影響範圍	修復成本	偵測難度	典型 Pattern
實作級	單一檔案	低	容易	IMP-001, IMP-002
架構級	跨模組	中-高	中等	ARCH-001
遷移級	重構過程	高	困難（可能靜默）	IMP-003, IMP-005

偵測工具鏈

識別壞味道不能只靠肉眼。以下工具從簡單到進階，組成完整的偵測鏈。

第一層：grep 模式掃描

最快的初步篩檢，幾秒鐘就能掃完整個專案。

 1# 偵測 IMP-001：找出重複的函式定義
 2grep -rh "^def " hooks/*.py | sort | uniq -c | sort -rn | head -10
 3#  4 def run_git_command(cmd):    <-- 出現 4 次，高度疑似重複
 4#  2 def parse_output(line):      <-- 出現 2 次，需要確認
 5
 6# 偵測 IMP-002：找出魔法數字
 7grep -rn -E "\[[0-9]+:\]" hooks/*.py      # 數字切片 [9:]
 8grep -rn "sleep([0-9]" hooks/*.py        # 硬編碼的等待時間
 9grep -rn "range([0-9]" hooks/*.py        # 硬編碼的迴圈次數
10
11# 偵測 ARCH-001：找出超長檔案
12find hooks/ -name "*.py" -exec wc -l {} \; | awk '$1 > 500'
13# 847 hooks/user_prompt_submit.py    <-- 紅色警報
14
15# 偵測 IMP-005：模組遷移後殘留的舊 Import
16grep -rn "from common_functions import" hooks/*.py
17# 如果 common_functions.py 已經搬到 lib/，這些都是未更新的引用

grep 的限制：只做文字比對，無法理解程式碼結構。line[9:] 會被抓到，但 offset = 9; line[offset:] 就抓不到了。

第二層：AST 分析

Python 的 ast 模組能解析程式碼結構，做到 grep 做不到的事。

 1import ast
 2import sys
 3
 4def find_scope_references(filename, variable_name):
 5    """找出所有在非 main 函式中引用特定變數的位置。
 6    限制：此函式只做名稱比對，無法追蹤賦值或閉包捕獲。"""
 7    with open(filename) as f:
 8        tree = ast.parse(f.read())
 9
10    issues = []
11    for node in ast.walk(tree):
12        if isinstance(node, ast.FunctionDef) and node.name != "main":
13            param_names = {arg.arg for arg in node.args.args}
14            if variable_name in param_names:
15                continue  # 函式已接收此變數為參數，非問題
16            for child in ast.walk(node):
17                if isinstance(child, ast.Name) and child.id == variable_name:
18                    issues.append(f"  {node.name}() 在第 {child.lineno} 行引用 {variable_name}")
19                    break
20    return issues
21
22# 使用方式
23issues = find_scope_references("hooks/pre_commit.py", "logger")
24for issue in issues:
25    print(issue)

AST 能做而 grep 做不到的事：

能力	grep	AST
找出字面上的文字模式	可以	可以
區分變數定義和使用	不行	可以
分析函式的參數列表	不行	可以
偵測作用域問題	不行	可以
計算巢狀深度	不行	可以

自己撰寫 AST 腳本適合針對特定問題的精確偵測。但對於更廣泛的靜態分析需求，現成工具能用更低的成本涵蓋更多場景。

第三層：靜態分析工具比較

不同工具的偵測能力差異很大，選錯工具會漏掉關鍵問題。

偵測能力	py_compile	pylint	mypy
語法錯誤	可以	可以	可以
未使用的變數	不行	可以	不行
作用域問題 (IMP-003)	不行	可以	部分
Import 路徑錯誤 (IMP-005)	不行	可以	部分*
型別錯誤	不行	部分	可以
程式碼風格	不行	可以	不行
執行速度	最快	中等	較慢

*mypy 偵測 Import 路徑錯誤需正確設定 MYPYPATH 或 mypy.ini，對動態 sys.path 無效。

py_compile 只檢查語法是否合法。logger 變數不存在是執行期錯誤，不是語法錯誤。這就是為什麼 IMP-003 能通過 py_compile 的檢查，卻在執行時爆炸。

 1# py_compile：語法 OK 不代表能跑
 2python3 -m py_compile hooks/pre_commit.py  # 通過！但 logger 根本找不到
 3
 4# pylint：能抓到更多問題
 5pylint hooks/pre_commit.py
 6# E0602: Undefined variable 'logger' (undefined-variable)
 7
 8# 實際執行：最可靠的驗證
 9python3 hooks/pre_commit.py < /dev/null
10# NameError: name 'logger' is not defined

建議的偵測策略：先用 grep 做快速掃描，對疑似問題用 AST 確認，重構後用 pylint 或實際執行做最終驗證。

使用場景	推薦工具	適用理由
快速掃描重複模式	grep	速度最快，適合初篩
確認特定函式結構問題	AST 分析	精確到語法層級，無正規表達式偽陽性
重構後整體品質驗證	pylint / mypy	涵蓋面廣，可持續整合
作用域和型別問題	實際執行	py_compile 不夠，需 pytest 或直接執行

5 Why 根因分析

找到壞味道只是起點；若要防止問題再次出現，必須找到根本原因。

完整範例：ARCH-001 配置與程式碼混合

 1問題：單一 Hook 檔案超過 800 行，其中約一半是硬編碼的配置資料
 2
 3Why 1: 為什麼檔案會有 800 行？
 4--> 因為配置資料（分支規則、錯誤訊息、檔案模式）和程式邏輯
 5    全部寫在同一個檔案中
 6
 7Why 2: 為什麼配置和邏輯放在一起？
 8--> 因為開發時為求快速，直接在程式碼中定義配置常數
 9
10Why 3: 為什麼選擇快速做法而非分離？
11--> 因為缺乏配置管理策略，沒有標準化的做法可以遵循
12
13Why 4: 為什麼沒有配置管理策略？
14--> 因為 Hook 系統初期設計時，只考慮了功能實現，
15    沒有考慮到配置會不斷增長
16
17Why 5: 為什麼初期設計沒考慮配置增長？
18--> 【根本原因】缺乏明確的架構原則指導配置與程式碼分離

根因指向的行動：制定架構原則，明確規定什麼放在 YAML、什麼留在程式碼中。

資料類型	正確位置	判斷依據
業務規則配置	YAML 檔案	會隨環境改變嗎？非工程師可能修改嗎？
錯誤訊息	YAML 或 i18n	需要多語言嗎？
常數定義	Python 常數檔	與程式邏輯緊密耦合嗎？
程式邏輯	Python 檔案	是演算法或流程控制嗎？

5 Why 的技巧

持續追問：第一個「為什麼」幾乎永遠不是根本原因
客觀描述：寫「缺乏審查機制」而不是「某人偷懶」
可驗證：每一層的回答都應該可以被事實確認
可行動：最終原因必須能轉化成具體的改善措施
停止條件：當答案指向「流程或規範的缺失」時，通常就是根因

Error Patterns 經驗傳承系統

個人發現壞味道是一次性的收穫；將其記錄為 Error Pattern，才能讓整個團隊持續受益。

目錄結構

1.claude/error-patterns/
2├── README.md              # 系統說明與索引
3├── test/                  # 測試相關：TEST-001, TEST-002, ...
4├── documentation/         # 文件相關：DOC-001, DOC-002, ...
5├── architecture/          # 架構相關：ARCH-001, ARCH-002, ...
6└── implementation/        # 實作相關：IMP-001, IMP-002, ...

Pattern 文件模板

 1# [Pattern ID]: [簡短標題]
 2
 3## 基本資訊
 4
 5- **Pattern ID**: {CATEGORY}-{NNN}
 6- **風險等級**: 高/中/低
 7- **發現日期**: YYYY-MM-DD
 8
 9## 問題描述
10
11### 症狀
12
13[用程式碼範例展示問題的外在表現]
14
15### 根本原因 (5 Why 分析)
16
171. Why 1: ...
182. Why 2: ...
193. Why 3: ...
204. Why 4: ...
215. Why 5: (根本原因)
22
23## 解決方案
24
25### 正確做法
26
27[程式碼範例]
28
29### 錯誤做法 (避免)
30
31[程式碼範例]
32
33## 檢測方法
34
35[grep 指令、AST 腳本或工具配置]

建立流程

識別模式：確認問題確實重複出現（至少 2 次）
分類歸檔：選擇 TEST / DOC / ARCH / IMP
5 Why 分析：找出根本原因
記錄方案：寫下正確和錯誤做法的對比
加入偵測：提供 grep 或 AST 的偵測指令

從識別到行動的決策流程

找到壞味道之後，不是每個都要立刻修。用這個流程判斷優先級：

 1發現壞味道
 2    |
 3    v
 4影響正確性嗎？（會導致 Bug）
 5    |
 6    +-- 是 --> 立即修復，建立 Ticket
 7    |
 8    +-- 否 --> 影響多個檔案嗎？
 9                |
10                +-- 是 --> 記錄 Error Pattern + 建立 Ticket
11                |
12                +-- 否 --> 認知負擔高嗎？（函式超長、巢狀太深）
13                            |
14                            +-- 是 --> 排入下次重構
15                            |
16                            +-- 否 --> 記錄，暫不處理

關鍵原則：遷移級壞味道（IMP-003、IMP-005）幾乎都會影響正確性，必須立即處理。實作級壞味道（IMP-001、IMP-002）通常不影響正確性，可以排入重構計畫。

實作練習

練習 1：分類壞味道

以下程式碼有哪些壞味道？各屬於哪一級？

 1BRANCH_RULES = {
 2    "protected": ["main", "master"],
 3    "max_length": 50,
 4    "patterns": ["feat/*", "fix/*", "chore/*"],
 5}
 6
 7def check(data):
 8    res = []
 9    for i in range(len(data)):
10        if data[i]["type"] == "A":
11            if data[i]["status"] == 1:
12                if data[i]["value"] > 100:
13                    res.append(data[i]["name"][5:])
14    return res

參考答案

DRY 原則與共用程式庫

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

上一章：程式碼壞味道偵測

DRY (Don’t Repeat Yourself) 是軟體開發的核心原則之一。本章基於 Error Pattern IMP-001，學習如何識別重複程式碼並建立共用模組。後半部分以 v0.31.0 的模組演進和遷移實戰為例，示範共用庫如何隨系統成長持續演進。

問題背景

症狀

相同功能在多個檔案中重複實作：

1# hooks/pre_commit.py
2def run_git_command(cmd):
3    result = subprocess.run(cmd, capture_output=True, text=True)
4    return result.stdout.strip()
5
6# hooks/post_merge.py  -- 完全相同
7# hooks/branch_check.py  -- 完全相同
8# hooks/worktree_guardian.py  -- 完全相同

四個檔案中存在完全相同的函式定義。

5 Why 分析

Why 1: 相同的 run_git_command 函式在 4 個檔案中重複
Why 2: 每個 Hook 獨立開發，沒有共用模組
Why 3: 缺乏 Hook 系統的架構設計和共用程式庫規劃
Why 4: 快速開發時複製貼上最快
Why 5: 缺乏 DRY 原則的強制檢查機制

DRY 原則核心

重複程式碼的四大壞處：修改需改多處、容易不一致、增加維護成本、測試困難。

DRY 的完整含義不只是「不要複製貼上」：

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

– Andy Hunt & Dave Thomas, The Pragmatic Programmer

這意味著不只是程式碼，還包括業務邏輯、資料定義、設定內容。

識別重複程式碼

1# 找出重複的函式定義
2grep -rh "^def " .claude/hooks/*.py | sort | uniq -c | sort -rn | head -20
3
4# 範例輸出：
5#    4 def run_git_command(cmd):
6#    3 def get_current_branch():
7#    2 def parse_worktree_line(line):

重複類型	範例	處理方式
完全相同	複製貼上的程式碼	抽取到共用模組
結構相同	相似但參數不同	抽取並參數化
概念相同	做同樣的事但實作不同	統一介面

建立共用程式庫

模組結構

1.claude/lib/
2├── __init__.py           # 公開介面
3├── git_utils.py          # Git 操作
4├── config_loader.py      # 配置載入
5├── hook_io.py            # 輸入輸出
6└── hook_logging.py       # 日誌系統

抽取共用函式

從重複程式碼中抽取，加上完整的型別標註和 docstring：

 1# lib/git_utils.py
 2"""Git 操作工具模組。"""
 3
 4import subprocess
 5from pathlib import Path
 6from typing import List, Optional
 7
 8def run_git_command(
 9    cmd: List[str],
10    cwd: Optional[Path] = None,
11    check: bool = False
12) -> str:
13    """執行 Git 命令並回傳輸出。
14
15    Args:
16        cmd: Git 命令列表，例如 ["git", "status"]
17        cwd: 工作目錄，預設為當前目錄
18        check: 是否在命令失敗時拋出異常
19    """
20    result = subprocess.run(
21        cmd, capture_output=True, text=True, cwd=cwd, check=check
22    )
23    return result.stdout.strip()
24
25def get_current_branch(cwd: Optional[Path] = None) -> str:
26    """取得當前分支名稱。"""
27    return run_git_command(["git", "branch", "--show-current"], cwd=cwd)

更新使用處

1# hooks/pre_commit.py（重構後）
2from lib.git_utils import run_git_command, get_current_branch
3
4def check_branch():
5    current_branch = get_current_branch()
6    # 使用共用函式，不再重複定義

抽取技巧

處理微小差異

當重複程式碼有微小差異時，使用參數化：

 1# 重構前：三個檔案各自的版本
 2# hooks/file_a.py
 3def parse_worktree_line(line):
 4    return line[9:]                        # 不 strip
 5
 6# hooks/file_b.py
 7def parse_worktree_line(line):
 8    return line[9:].strip()                # 有 strip
 9
10# hooks/file_c.py
11def parse_worktree_line(line):
12    return line.removeprefix("worktree ")  # 用 Python 3.9+ API
13
14# 重構後：統一實作，支援選項
15WORKTREE_PREFIX = "worktree "
16
17def parse_worktree_line(line: str, strip: bool = True) -> str:
18    """解析 worktree 輸出行。"""
19    result = line.removeprefix(WORKTREE_PREFIX)
20    return result.strip() if strip else result

使用高階函式

當邏輯結構相同但操作不同時：

 1from pathlib import Path
 2from typing import Callable
 3
 4# 重構前
 5def check_all_python_files():
 6    for file in Path(".").glob("**/*.py"):
 7        if validate_python(file): print(f"OK: {file}")
 8
 9def check_all_yaml_files():
10    for file in Path(".").glob("**/*.yaml"):
11        if validate_yaml(file): print(f"OK: {file}")
12
13# 重構後
14def check_files(pattern: str, validator: Callable[[Path], bool]) -> None:
15    for file in Path(".").glob(pattern):
16        if validator(file): print(f"OK: {file}")
17
18check_files("**/*.py", validate_python)
19check_files("**/*.yaml", validate_yaml)

共用模組設計原則

原則	做法	反面教材
單一職責	`git_utils.py`（Git 操作）、`config_loader.py`（配置載入）。模組名稱即可看出職責	`utils.py`（什麼都放，職責不明確）
穩定的介面	透過 `__init__.py` 定義公開 API，內部可自由重構	讓使用者直接 import 內部實作細節
完整的 docstring	每個公開函式都要有 docstring（Args/Returns/Raises）	只有程式碼，沒有使用說明
充分的測試	每個共用函式都要有對應的單元測試	重構後不跑測試就上線

模組演進：從 4 個到 7+ 個

共用程式庫隨著系統成長持續演進。

模組演進表

版本	模組	職責	說明
v0.28.0	`git_utils.py`	Git 命令執行、分支管理	消除 4 處 run_git_command 重複
v0.28.0	`hook_io.py`	Hook JSON 輸入讀取、輸出生成	統一 stdin/stdout 處理
v0.28.0	`config_loader.py`	YAML 配置檔案載入	支援 PyYAML fallback JSON
v0.28.0	`hook_logging.py`	日誌設定	統一日誌格式
v0.31.0	`hook_utils.py`	統一日誌 + 頂層例外處理	取代分散的兩套日誌系統
v0.31.0	`hook_messages.py`	訊息常數集中管理	消除 19 個 Hook 的硬編碼訊息
v0.31.0	`hook_validator.py`	Hook 健康檢查	驗證 import 和執行狀態

演進的驅動力

每次新增模組都有明確的驅動力，而非預先設計：

v0.28.0（初建期）：四個函式重複 → 建立四個共用模組。

v0.31.0（成熟期）：Hook 數量從 7 個成長到 40+ 個，新的重複模式浮現：

日誌系統分裂：hook_logging.py 和 common_functions.setup_hook_logging 兩套實作並存，40+ 個 Hook 各自選用。最終建立 hook_utils.py 統一取代
訊息散落各處：19 個 Hook 各自硬編碼使用者訊息 → 建立 hook_messages.py 集中管理

這驗證了「至少重複兩次再抽取」的 Rule of Three 原則：模組是在真實需求驅動下自然長出來的。

漸進遷移策略

共用庫建立後，需要將現有使用者逐步遷移。「一次全改」風險太高，以下是 W22 遷移 40+ 個 Hook 到新日誌系統的實戰策略。

分批遷移計畫

批次	範圍	檔案數	策略
W22-001.2	主力遷移	14 個	按 Hook 事件類型分組遷移
W22-001.3	補漏	3 個	掃描殘留的舊 import

每個 Hook 的遷移步驟

 1# === 步驟 1：替換 import ===
 2# 遷移前
 3from lib.common_functions import setup_hook_logging
 4# 遷移後
 5from hook_utils import setup_hook_logging
 6
 7# === 步驟 2：包裹主函式 ===
 8# 遷移前
 9if __name__ == "__main__":
10    try:
11        main()
12    except Exception as e:
13        logger.error(f"執行失敗: {e}")
14        sys.exit(1)
15# 遷移後
16from hook_utils import run_hook_safely
17if __name__ == "__main__":
18    sys.exit(run_hook_safely(main, "my-hook"))
19
20# === 步驟 3：驗證 ===
21uv run python hook-name.py < /dev/null

為什麼分批而非一次全改

一次全改	分批遷移
改動 40+ 個檔案，review 困難	每批 14-3 個，可仔細確認
一個錯誤影響所有 Hook	錯誤影響範圍有限
無法中途暫停	每批獨立可交付
回滾等於全部回滾	只回滾出問題的批次

遷移陷阱：IMP-005

模組遷移最常見的陷阱是 import 路徑未同步更新。這個問題在系統中發生過兩次，我們將其記錄為 Error Pattern IMP-005。

症狀

模組從目錄 A 移到目錄 B 後，部分使用者的 import 忘記更新：

1# 遷移前（同目錄）
2from common_functions import hook_output  # OK
3
4# 遷移後（模組移到 lib/，但 import 未更新）
5from common_functions import hook_output  # ModuleNotFoundError!
6
7# 正確的遷移後 import
8from lib.common_functions import hook_output  # OK

為什麼容易遺漏

py_compile 不偵測 import 問題：只檢查語法，不解析模組路徑
部分 Hook 不常觸發：SessionStart Hook 只在啟動時執行，測試不容易覆蓋
多源錯誤疊加：多個 Hook 同時報錯，修完幾個就以為全部修好

遷移前強制檢查清單

1# 1. 列出所有引用舊路徑的檔案
2grep -r "from common_functions import" .claude/hooks/*.py
3
4# 2. 逐一更新每個引用者的 import 路徑
5
6# 3. 逐一驗證（不能只跑其中幾個！）
7for f in .claude/hooks/*.py; do
8    uv run python "$f" < /dev/null 2>&1 | grep -q "Error" && echo "FAIL: $f"
9done

Import 防護機制

在 Hook 入口加 try-except，讓 import 失敗時顯示具體原因：

1try:
2    from hook_utils import setup_hook_logging
3except ImportError as e:
4    print(f"[Hook Import Error] {Path(__file__).name}: {e}", file=sys.stderr)
5    sys.exit(1)

實際案例統計

v0.28.0 初建共用庫：

函式	重複次數	重構後
run_git_command	4	1 (git_utils.py)
get_current_branch	3	1 (git_utils.py)
parse_worktree_line	2	1 (git_utils.py)
load_json	2	1 (hook_io.py)

總計消除數百行重複程式碼。

v0.31.0 持續演進：

項目	重複次數	重構後
setup_hook_logging	2 套系統	1 (hook_utils.py)
run_hook_safely	40+ 處 try-except	1 (hook_utils.py)
使用者訊息字串	19 個 Hook 散落	1 (hook_messages.py)

常見錯誤

錯誤 1：過早抽象

只用一次就抽出去是過度抽象。原則：至少重複兩次再抽取（Rule of Three）。

錯誤 2：強行統一

不同概念硬塞進同一個函式（靠 mode 參數切換）。解決：不同概念應該是不同的函式。

錯誤 3：忽略測試

重構時沒有先寫測試，導致引入新 bug。原則：先寫測試，確保重構不改變行為。

錯誤 4：遷移不徹底

模組搬家後只更新「自己知道的」使用處。原則：用 grep 列出所有引用，逐一更新並驗證（詳見 IMP-005）。

實作練習

練習 1：識別重複

找出以下程式碼的可抽取重複：

 1# file1.py
 2def process_user_data(user):
 3    if not user.get("name"):
 4        return {"error": "缺少姓名"}
 5    if not user.get("email"):
 6        return {"error": "缺少信箱"}
 7    return {"success": True, "data": user}
 8
 9# file2.py
10def process_order_data(order):
11    if not order.get("product"):
12        return {"error": "缺少商品"}
13    if not order.get("quantity"):
14        return {"error": "缺少數量"}
15    return {"success": True, "data": order}

參考答案

配置分離與常數管理

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

上一章：DRY 原則與共用程式庫

硬編碼問題不只是魔法數字。當專案成長到數十個模組時，三種不同形態的硬編碼會同時出現：看不懂的數字、混在邏輯裡的配置資料、散落各處的使用者訊息。本章整合 Error Pattern IMP-002（魔法數字）和 ARCH-001（配置與邏輯混合）的實戰經驗，並加入 W23 訊息集中化的完整案例。

三種硬編碼問題

在維護 19 個 Hook 模組的過程中，我們遇到了三種不同但相關的硬編碼問題：

類型	Error Pattern	典型症狀	危害
魔法數字	IMP-002	`line[9:]`、`sleep(3)`、`range(5)`	無法理解數字含義，修改時容易遺漏
配置混合	ARCH-001	800 行檔案中 400 行是配置資料	配置散落各處，同一資料有多個版本
散落訊息	W23 發現	57+ 個硬編碼中文字串散落在 19 個檔案中	訊息不一致，無法統一維護

三種問題的共同根因：開發時為求快速，把應該集中管理的資料直接寫在邏輯程式碼裡。

一、消除魔法數字 (IMP-002)

魔法數字是程式碼中無法理解含義的字面值：

1def parse_worktree_line(line: str) -> str:
2    if line.startswith("worktree "):
3        return line[9:]  # 為什麼是 9？
4    return line
5
6if len(branch) > 50:    # 為什麼是 50？
7    raise Error("分支名稱過長")
8
9time.sleep(3)           # 為什麼等 3 秒？

問題不只是可讀性。當前綴改成 "work tree " 時，line[9:] 不會自動更新，產生隱蔽的 bug。

三種消除方法

方法 1：len() 動態計算（最安全）

1WORKTREE_PREFIX = "worktree "
2
3def parse_worktree_line(line: str) -> str:
4    if line.startswith(WORKTREE_PREFIX):
5        return line[len(WORKTREE_PREFIX):]
6    return line

前綴改變時切片自動正確，不需要同步更新數字。

方法 2：removeprefix（最簡潔，Python 3.9+）

1WORKTREE_PREFIX = "worktree "
2
3def parse_worktree_line(line: str) -> str:
4    return line.removeprefix(WORKTREE_PREFIX)

不需要先檢查 startswith，沒有前綴時安全返回原字串。

方法 3：IntEnum 管理相關常數群組

 1from enum import IntEnum
 2
 3class Limits(IntEnum):
 4    MAX_BRANCH_LENGTH = 50
 5    MAX_COMMIT_MSG_LENGTH = 72
 6    MAX_RETRIES = 3
 7    TIMEOUT_SECONDS = 30
 8
 9if len(branch) > Limits.MAX_BRANCH_LENGTH:
10    raise ValueError("分支名稱過長")

常見處理對照

場景	壞	好
字串切片	`line[7:]`	`line.removeprefix(PREFIX)`
時間限制	`sleep(3)`	`sleep(RETRY_DELAY_SECONDS)`
大小限制	`len(x) > 50`	`len(x) > MAX_BRANCH_LENGTH`
重試次數	`range(5)`	`range(MAX_RETRIES)`

可接受的例外

不是所有數字都需要命名：

1if count == 0:               # 可接受：0 在布林邏輯中
2if text.find("key") == -1:   # 可接受：-1 作為找不到的標記
3half = total / 2              # 可接受：明顯的數學常數

判斷標準：如果閱讀者需要思考「這個數字為什麼是這個值」，就應該命名。

二、YAML 配置分離 (ARCH-001)

問題識別

單一 Hook 檔案超過 800 行，其中約一半是硬編碼的配置資料：

 1# user_prompt_submit.py (847 行，配置佔 400+)
 2PROTECTED_BRANCHES = ["main", "master", "develop"]
 3ALLOWED_PATTERNS = ["feat/*", "fix/*", "chore/*"]
 4ERROR_MESSAGES = {
 5    "branch_not_allowed": "分支名稱不符合規範",
 6    "missing_ticket": "缺少 Ticket 引用",
 7    # ... 數百行配置
 8}
 9
10def main():
11    # 實際邏輯只有 200 行
12    pass

更嚴重的是，同一份配置在多個檔案中各自定義，彼此不一致：

1# file1.py
2PROTECTED_BRANCHES = ["main", "master"]
3# file2.py
4PROTECTED_BRANCHES = ["main", "master", "develop"]  # 多了 develop！

判斷標準

問題	若答「是」	放置位置
會隨環境改變？	是	YAML 配置檔
非工程師可能修改？	是	YAML 配置檔
是業務規則？	是	程式碼常數檔（附註解）
與程式邏輯緊密耦合？	是	程式碼內常數

簡單記憶：資料放配置，邏輯留程式碼。

實作：config_loader 模式

步驟 1：抽離配置到 YAML

 1# config/branch_rules.yaml
 2protected_branches:
 3  - main
 4  - master
 5  - develop
 6
 7allowed_patterns:
 8  - "feat/*"
 9  - "fix/*"
10  - "chore/*"
11
12error_messages:
13  branch_not_allowed: "分支名稱不符合規範"
14  missing_ticket: "缺少 Ticket 引用"

步驟 2：建立載入器（含快取）

 1# lib/config_loader.py
 2from pathlib import Path
 3from typing import Any, Dict
 4import yaml
 5
 6_config_cache: Dict[str, Any] = {}
 7
 8def load_config(filename: str) -> Dict[str, Any]:
 9    """載入 YAML 配置檔案（含快取）。"""
10    if filename in _config_cache:
11        return _config_cache[filename]
12
13    config_path = Path(__file__).parent.parent / "config" / filename
14    if not config_path.exists():
15        raise FileNotFoundError(f"配置檔案不存在: {config_path}")
16
17    with open(config_path, "r", encoding="utf-8") as f:
18        config = yaml.safe_load(f)
19
20    _config_cache[filename] = config
21    return config

步驟 3：在 Hook 中使用

1from lib.config_loader import load_config
2
3def check_branch():
4    config = load_config("branch_rules.yaml")
5    if current_branch in config["protected_branches"]:
6        print(f"錯誤: {config['error_messages']['branch_not_allowed']}")
7        return False
8    return True

重構後結構：847 行的單一檔案拆成約 200 行純邏輯 + config/ 目錄的 YAML 檔 + 共用的 config_loader.py。

常見錯誤

過度配置化 – 把程式邏輯也放進配置檔：

1# 錯誤：這是邏輯，不是資料
2process_steps:
3  - name: "validate"
4    function: "validate_input"

缺乏預設值 – 沒有處理配置缺失：

1timeout = config["timeout"]        # KeyError!
2timeout = config.get("timeout", 30)  # 正確

三、訊息集中化 (W23)

消除魔法數字和分離配置後，還有一種硬編碼藏在邏輯裡：使用者訊息字串。

W23 審計發現 19 個 Hook 中散落了 57+ 個硬編碼中文字串：

1# hook_a.py
2print("錯誤：未找到待處理的 Ticket")
3print("建議執行 /ticket create 建立新 Ticket")
4
5# hook_b.py
6print("錯誤：未找到待處理的 Ticket")  # 同一訊息，略有不同
7print("請先建立 Ticket 再執行")

同一個錯誤概念有 2-3 種不同措辭，修改一則訊息需要搜尋所有檔案。

Messages 類別模式

解決方案：建立 hook_messages.py，用類別分組管理所有訊息常數。

 1# lib/hook_messages.py
 2class CoreMessages:
 3    """Hook 執行通用訊息 - 所有 Hook 共用"""
 4    HOOK_START = "{hook_name} 啟動"
 5    INPUT_EMPTY = "輸入為空，預設允許"
 6    JSON_PARSE_ERROR = "JSON 解析錯誤，預設允許: {error}"
 7
 8class GateMessages:
 9    """Gate Hook 阻擋訊息 - 5 個 gate hooks 使用"""
10    TICKET_NOT_FOUND_ERROR = """錯誤：未找到待處理的 Ticket
11建議: 執行 /ticket create 建立新 Ticket"""
12
13    TICKET_NOT_CLAIMED_ERROR = """錯誤：Ticket {ticket_id} 尚未認領
14建議: 執行 /ticket track claim {ticket_id} 認領"""
15
16class WorkflowMessages:
17    """工作流指導訊息 - 5 個工作流 hooks 使用"""
18    PRE_FIX_EVAL_REQUIRED = """[強制] 修復前評估
19  1. 執行 /pre-fix-eval
20  2. 派發 incident-responder 分析"""

最終產出 7 個 Messages 類別，管理約 45 個訊息常數。

使用方式

Hook 中引用常數，使用 .format() 填入動態值：

1from lib.hook_messages import GateMessages
2
3def validate_ticket(ticket_id: str):
4    if not is_claimed(ticket_id):
5        print(GateMessages.TICKET_NOT_CLAIMED_ERROR.format(
6            ticket_id=ticket_id
7        ))
8        return False
9    return True

組織原則

分類依據	類別名稱	涵蓋範圍
核心通用	`CoreMessages`	所有 Hook 共用的啟動、錯誤訊息
阻擋訊息	`GateMessages`	5 個 Gate Hook 的阻止原因和建議
工作流指導	`WorkflowMessages`	5 個工作流 Hook 的流程提示
品質檢查	`QualityMessages`	5 個品質 Hook 的檢查結果
驗證相關	`ValidationMessages`	驗證 Hook 的成功/失敗訊息

分類原則：按使用者角色和觸發情境分組，而不是按技術功能。

命名規範

常數類型	命名規則	範例
訊息常數	大寫蛇形	`TICKET_NOT_FOUND_ERROR`
Messages 類別	PascalCase + Messages	`GateMessages`
格式化佔位符	`{variable_name}`	`"Ticket {ticket_id} 尚未認領"`

W23 實際數據

指標	重構前	重構後
硬編碼訊息位置	散落 19 個檔案	集中 1 個檔案
訊息總數	57+ 個（含重複）	45 個（去重後）
修改訊息需搜尋	所有 Hook 檔案	只需 hook_messages.py
訊息一致性	同概念 2-3 種措辭	每個概念一個定義

決策框架

遇到硬編碼時，用這張表判斷該怎麼處理：

硬編碼類型	識別特徵	處理方式	存放位置
魔法數字	裸露的數字或字串切片	具名常數、`len()`、`removeprefix()`	同檔案頂部或常數模組
配置資料	清單、規則表、業務參數	抽離到 YAML 配置檔	`config/` 目錄
使用者訊息	字串直接嵌入邏輯	提取到 Messages 類別	`lib/*_messages.py`
程式邏輯常數	與邏輯緊密耦合的值	具名常數，保留在程式碼	檔案頂部

決策流程

 1發現硬編碼
 2    |
 3    v
 4會隨環境改變？ ─是→ YAML 配置檔
 5    |
 6    否
 7    v
 8是使用者看到的文字？ ─是→ Messages 類別
 9    |
10    否
11    v
12是無法理解的數字？ ─是→ 具名常數 / len() / removeprefix()
13    |
14    否
15    v
16保留原樣（程式邏輯的一部分）

完整重構範例

重構前

 1def validate_branch(branch):
 2    if len(branch) > 50:
 3        return False
 4    if branch.startswith("refs/heads/"):
 5        branch = branch[11:]
 6    for i in range(3):
 7        if check_remote(branch):
 8            return True
 9        time.sleep(2)
10    return False

重構後

 1MAX_BRANCH_LENGTH = 50
 2REFS_HEADS_PREFIX = "refs/heads/"
 3MAX_RETRIES = 3
 4RETRY_DELAY_SECONDS = 2
 5
 6def validate_branch(branch: str) -> bool:
 7    """驗證分支名稱。"""
 8    if len(branch) > MAX_BRANCH_LENGTH:
 9        return False
10    branch = branch.removeprefix(REFS_HEADS_PREFIX)
11    for attempt in range(MAX_RETRIES):
12        if check_remote(branch):
13            return True
14        time.sleep(RETRY_DELAY_SECONDS)
15    return False

四個魔法數字全部消除，每個值的含義一目了然。

檢測方法

1# 找出數字切片（潛在魔法數字）
2grep -rn "\[[0-9]*:\]" hooks/*.py
3
4# 找出 sleep 和 range 中的硬編碼
5grep -rn "sleep([0-9]" hooks/*.py
6grep -rn "range([0-9]" hooks/*.py
7
8# 找出硬編碼中文字串（潛在散落訊息）
9grep -rn '[一-龥]' hooks/*.py

實作練習

找出以下程式碼中的三種硬編碼問題，並提出修正方案：

 1def process_hook_result(result_line):
 2    if result_line.startswith("status: "):
 3        status = result_line[8:]
 4    else:
 5        status = "unknown"
 6
 7    if len(status) > 100:
 8        print("狀態文字過長，已截斷")
 9        status = status[:97] + "..."
10
11    VALID_STATUSES = ["pass", "fail", "skip", "error"]
12    if status not in VALID_STATUSES:
13        print("無效的狀態值: " + status)
14        return None
15    return status

參考答案

大規模統一化重構

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

前面幾章的重構案例都在解決局部問題：提取常數、分離配置、消除重複。本章探討一個更大的挑戰：當系統中有 44 個獨立腳本，各自發展出不同的基礎設施實作時，如何系統性地統一它們？

這是 W22-W24 開發週期中實際執行的三階段統一化重構。每個階段解決一個維度的分歧，最終讓所有 Hook 共享同一套基礎設施。

問題全貌

44 個 Hook，N 種實作

Hook 系統經過數個版本的有機成長，累積了大量不一致：

 1# Hook A：用 common_functions 的 setup_hook_logging
 2from lib.common_functions import setup_hook_logging
 3logger = setup_hook_logging("hook-a")
 4
 5# Hook B：用 hook_logging 的 setup_hook_logging（不同模組，同名函式）
 6from lib.hook_logging import setup_hook_logging
 7logger = setup_hook_logging("hook-b")
 8
 9# Hook C：直接用 logging 模組
10import logging
11logging.basicConfig(level=logging.INFO)
12logger = logging.getLogger(__name__)
13
14# Hook D：print 大法
15def log(msg):
16    print(f"[hook-d] {msg}")

不只日誌，訊息和錯誤處理也是如此：

維度	分歧數量	常見變體
日誌初始化	3 種	common_functions / hook_logging / 直接 logging
錯誤處理	3 種	try-except 包 main / 不處理 / 自訂裝飾器
使用者訊息	19 個檔案各自定義	每個 Hook 硬編碼自己的字串（共 57+ 個）
logger 作用域	2 種	模組級全域 / main() 內區域

為什麼要統一

分歧帶來的實際問題：

修改成本倍增：改一個日誌格式，要改 44 個檔案
行為不一致：有的 Hook 失敗時靜默，有的會 crash
難以排查問題：每個 Hook 的日誌格式不同，無法統一搜尋
新 Hook 沒有範本：寫新 Hook 時不知道該參考哪個

統一化模式

三階段統一化遵循一個共同的模式：

11. 建立統一介面    → 寫一個所有人都要用的模組
22. 漸進式遷移      → 逐批將現有 Hook 切換到新介面
33. 驗證           → 確認行為一致
44. 處理例外       → 處理少數無法直接遷移的情況

這個模式的關鍵在於不一次改完。每個階段只統一一個維度，確認穩定後再進入下一個。

第一階段：統一日誌（W22）

設計統一介面

目標是用一個模組取代三套日誌實作。核心 API 只有兩個函式：

 1# hook_utils.py — 統一日誌模組
 2
 3def setup_hook_logging(hook_name: str) -> logging.Logger:
 4    """建立並設定 Hook 日誌系統
 5
 6    - 建立日誌目錄 .claude/hook-logs/{hook_name}/
 7    - 建立帶時間戳的日誌檔案
 8    - 配置 FileHandler + StreamHandler
 9    """
10
11def run_hook_safely(main_func: Callable[[], int], hook_name: str) -> int:
12    """安全執行 Hook 函式，頂層例外處理
13
14    - 呼叫 setup_hook_logging 取得 logger
15    - 執行 main_func，捕獲所有 Exception
16    - 異常時記錄完整 traceback，返回 1
17    """

setup_hook_logging 封裝了所有日誌配置細節：

 1def setup_hook_logging(hook_name: str) -> logging.Logger:
 2    sanitized_name = _sanitize_hook_name(hook_name)
 3    root_dir = _find_project_root()
 4    log_base_dir = root_dir / ".claude" / "hook-logs" / sanitized_name
 5
 6    try:
 7        log_base_dir.mkdir(parents=True, exist_ok=True)
 8    except OSError:
 9        return _create_fallback_logger(hook_name)
10
11    logger = logging.getLogger(hook_name)
12    _clear_logger_handlers(logger)
13    logger.setLevel(logging.DEBUG)
14
15    is_debug = os.getenv("HOOK_DEBUG", "").lower() == "true"
16    _setup_logger_handlers(logger, log_base_dir, sanitized_name, is_debug)
17
18    return logger

幾個設計決策值得注意：

決策	理由
`_sanitize_hook_name`	Hook 名稱可能包含 `/` 等特殊字元，不能直接用作目錄名
`_clear_logger_handlers`	避免重複呼叫時 handler 累加
Fallback logger	目錄建立失敗時仍可輸出到 stdout，不會 crash
`HOOK_DEBUG` 環境變數	開發時可開啟 DEBUG 級別的 stream 輸出

`run_hook_safely`：一行搞定錯誤處理

這是統一化的核心武器。原本每個 Hook 自己寫 try-except：

1# 重構前：每個 Hook 自己處理
2if __name__ == "__main__":
3    try:
4        result = main()
5        sys.exit(result)
6    except Exception as e:
7        # 有的寫日誌，有的 print，有的什麼都不做
8        print(f"Error: {e}")
9        sys.exit(1)

統一後：

1# 重構後：一行搞定
2if __name__ == "__main__":
3    sys.exit(run_hook_safely(main, "acceptance-gate"))

run_hook_safely 內部處理三個邊界：

返回值驗證：main() 可能回傳 None 或布林值，run_hook_safely 會將非整數返回值轉換為 0（成功）或 1（失敗），確保 sys.exit 收到合法的退出碼
不攔截 SystemExit：刻意的 sys.exit() 呼叫不該被吃掉
不攔截 KeyboardInterrupt：Ctrl+C 中斷不該被捕獲

所有其他 Exception 子類別都被捕獲、記錄到日誌、返回錯誤碼 1。

遷移策略

不可能一次改完 44 個檔案。按風險分批：

批次	範圍	策略
第 1 批	5 個低風險 Hook	驗證新模組行為正確
第 2 批	15 個中等複雜度	建立遷移信心
第 3 批	剩餘所有 Hook	批量遷移

每批遷移後執行全量測試，確認無迴歸。

第二階段：統一訊息（W23）

問題：硬編碼訊息散落各處

日誌統一後，下一個問題浮現：每個 Hook 的使用者訊息各自定義。

1# command-entrance-gate-hook.py
2print("錯誤：未找到待處理的 Ticket\n建議操作: 執行 /ticket create")
3
4# acceptance-gate-hook.py
5print("[ERROR] 子任務未全部完成\nTicket: {}\n請先完成所有子任務")
6
7# main-thread-edit-restriction-hook.py
8print("編輯操作受限")

同樣的問題：改一個訊息格式要翻遍所有 Hook。訊息重複時會出現不一致。

集中管理：hook_messages.py

建立一個訊息常數模組，按職責分類：

 1# lib/hook_messages.py
 2
 3class CoreMessages:
 4    """所有 Hook 共用的通用訊息"""
 5    HOOK_START = "{hook_name} 啟動"
 6    INPUT_EMPTY = "輸入為空，預設允許"
 7    JSON_PARSE_ERROR = "JSON 解析錯誤，預設允許: {error}"
 8
 9class GateMessages:
10    """5 個 Gate Hook 的阻擋/警告訊息"""
11    TICKET_NOT_FOUND_ERROR = """錯誤：未找到待處理的 Ticket
12
13    為什麼阻止執行：
14      開發命令必須有對應的 Ticket，確保工作可追蹤和驗收。
15
16    建議操作:
17      1. 執行 /ticket create 建立新 Ticket
18      2. 或執行 /ticket track claim {id} 認領現有 Ticket"""
19
20class WorkflowMessages:
21    """工作流指導 Hook 的訊息"""
22    EXTERNAL_QUERY_DETECTED = "檢測到 {tool_name} 調用"
23
24class QualityMessages:
25    """品質檢查 Hook 的訊息"""
26    # ...

分類原則

類別	包含的 Hook	訊息特徵
CoreMessages	所有 Hook	啟動、錯誤、預設行為
GateMessages	5 個 Gate Hook	阻擋、警告、建議操作
WorkflowMessages	5 個工作流 Hook	流程指導、步驟說明
QualityMessages	品質檢查 Hook	掃描結果、改善建議
ValidationMessages	驗證 Hook	格式檢查、合規結果

使用方式：

1# 重構前
2print("錯誤：未找到待處理的 Ticket\n建議操作: ...")
3
4# 重構後
5from lib.hook_messages import GateMessages
6print(GateMessages.TICKET_NOT_FOUND_ERROR)

參數化的訊息用 format() ：

1# 帶參數的訊息
2print(GateMessages.TICKET_NOT_CLAIMED_ERROR.format(ticket_id="0.31.0-W2-001"))

效果

指標	重構前	重構後
訊息定義位置	散落 19 個檔案（57+ 個硬編碼字串）	集中 1 個模組（45 個常數）
修改訊息格式	逐檔搜尋修改	改一處生效
訊息一致性	同概念 2-3 種措辭	每個概念一個定義
新 Hook 訊息	自行發明	複用現有類別

第三階段：統一風格（W24）

問題：logger 初始化位置不一致

日誌模組和訊息常數統一後，16 個 Hook 的 logger 初始化位置仍然不一致：

 1# 風格 A：模組級初始化（13 個 Hook）
 2logger = setup_hook_logging("my-hook")  # 最外層
 3
 4def helper():
 5    logger.info("working...")           # 引用全域 logger
 6
 7def main():
 8    helper()
 9    return 0
10
11# 風格 B：main() 內初始化（3 個 Hook）
12def helper(logger):
13    logger.info("working...")           # 接收 logger 參數
14
15def main():
16    logger = setup_hook_logging("my-hook")
17    helper(logger)
18    return 0

目標是統一為風格 B。理由是：模組級初始化的 logger 會在 import 時立即建立日誌目錄和檔案，即使這個模組只是被其他工具引用而不是作為 Hook 執行。將 logger 移入 main() 可以確保只有真正執行時才初始化日誌系統。

事故：7 個 Hook 靜默失敗

統一風格的過程中發生了一個典型的作用域迴歸 bug。把 logger 從模組級移到 main() 內部後，引用全域 logger 的 helper 函式觸發了 NameError：

1# 修改後（有 bug）
2def check_acceptance_criteria(ticket_path):
3    logger.info(f"Checking {ticket_path}")  # NameError!
4
5def main():
6    logger = setup_hook_logging("acceptance-gate-hook")
7    result = check_acceptance_criteria(path)

更危險的是，run_hook_safely 的頂層 try-except 捕獲了 NameError（它是 Exception 的子類別），寫入日誌檔案，返回錯誤碼。用戶完全看不到任何異常。7 個 Hook 在至少 2 個 session 中靜默失敗。

這個事故的完整分析見下一章：重構陷阱與防護

修正：逐一分析影響範圍

正確的做法是在修改作用域之前，用 AST 分析或 grep 找出所有引用 logger 的非 main 函式，然後為每個函式加入 logger 參數：

1def check_acceptance_criteria(ticket_path, logger):  # 加入參數
2    logger.info(f"Checking {ticket_path}")
3
4def main():
5    logger = setup_hook_logging("acceptance-gate-hook")
6    result = check_acceptance_criteria(path, logger)  # 傳遞 logger

修正規模：7 個 Hook、41 個函式、+143/-81 行。

事故後的改善

這次事故直接促成了 _log_exception 的 stderr 輸出改善（W25-005）：在寫入日誌檔案之外，額外輸出一行到 sys.stderr，確保即使 run_hook_safely 捕獲了異常，用戶也能在終端看到 [Hook Error] 提示。

重構後的標準樣板

三階段統一完成後，每個 Hook 的結構變得極為一致：

 1#!/usr/bin/env python3
 2"""Hook 說明文件"""
 3
 4import sys
 5import json
 6from pathlib import Path
 7
 8# 引入統一基礎設施
 9# Hook 不是安裝的套件，需要手動把 hooks/ 目錄加入 Python 搜尋路徑
10# 這樣才能 import 同目錄下的 hook_utils 和 lib/ 子模組
11_hooks_dir = Path(__file__).parent
12if _hooks_dir not in [p for p in sys.path if Path(p) == _hooks_dir]:
13    sys.path.insert(0, str(_hooks_dir))
14
15from hook_utils import run_hook_safely, setup_hook_logging
16from lib.hook_messages import GateMessages, CoreMessages
17
18# 常數定義
19EXIT_SUCCESS = 0
20EXIT_BLOCK = 2
21
22# ---- 業務邏輯 ----
23
24def check_something(data, logger):
25    """每個 helper 都接收 logger 參數"""
26    logger.info(CoreMessages.HOOK_START.format(hook_name="my-hook"))
27    # ...
28
29def main():
30    logger = setup_hook_logging("my-hook")
31    # 讀取輸入、執行檢查、輸出結果
32    return EXIT_SUCCESS
33
34# ---- 入口 ----
35if __name__ == "__main__":
36    sys.exit(run_hook_safely(main, "my-hook"))

對比重構前後：

面向	重構前	重構後
日誌初始化	3 種模組 + 散裝 logging	`setup_hook_logging` 一行
錯誤處理	自寫 try-except 或不處理	`run_hook_safely` 一行
使用者訊息	硬編碼在各檔案	引用 `hook_messages` 常數
logger 傳遞	全域變數	參數傳遞
入口點	5-15 行樣板	1 行
新 Hook 開發	參考哪個都不確定	複製標準樣板

統一化的通用教訓

教訓 1：先建介面，再遷移

不要試圖「就地重構」現有程式碼。先寫好新模組，測試通過，然後逐步切換。

1錯誤路徑：邊改邊用 → 半成品狀態 → 新舊混合更亂
2正確路徑：新模組獨立完成 → 逐批遷移 → 舊模組標記棄用

教訓 2：分批遷移，每批驗證

44 個 Hook 一次改完的風險太高。分批的目的不只是降低風險，更是建立信心。第一批 5 個成功後，第二批 15 個就能更快。

教訓 3：統一風格是最危險的一步

統一「介面」（W22 日誌、W23 訊息）相對安全，因為是新增模組再切換引用。統一「風格」（W24 作用域）涉及修改現有程式碼的結構，牽一髮動全身。

風險等級	操作類型	範例
低	新增模組 + 替換 import	W22 新增 hook_utils.py
中	替換訊息字串	W23 硬編碼 → 常數引用
高	修改變數作用域	W24 全域 logger → 參數傳遞

教訓 4：安全網要先到位

W24 的事故之所以嚴重，是因為安全網（stderr 輸出）在事故之後才補上。正確的順序應該是：

11. 先確認安全網（stderr 輸出、測試覆蓋）
22. 再執行風險操作（作用域修改）
33. 最後清理（移除棄用程式碼）

量化成果

三階段統一化的最終成果：

指標	統一前	統一後
日誌模組	3 個	1 個 (hook_utils.py)
錯誤處理模式	3 種	1 種 (run_hook_safely)
訊息定義位置	19 個檔案（57+ 個字串）	1 個 (hook_messages.py)
logger 初始化風格	2 種	1 種 (main 內 + 參數傳遞)
新 Hook 開發時間	~30 分鐘	~10 分鐘
Hook 入口樣板	5-15 行	1 行

思考題

如果你的系統有 100 個腳本而不是 44 個，統一化策略會有什麼不同？
run_hook_safely 選擇返回錯誤碼而不是重新拋出異常，這個設計在什麼情境下會是錯誤的？
訊息常數用 class 分類（GateMessages、WorkflowMessages）而不是單一字典，有什麼優缺點？

實作練習

為一組 3 個以上的腳本設計統一日誌模組，包含 setup_logging 和 run_safely 兩個函式
掃描一個多檔案專案，找出所有硬編碼的使用者訊息字串，規劃集中管理方案
嘗試用本章的分批遷移策略，將練習 2 的訊息逐批遷移到常數模組

小結

大規模統一化的核心模式：建立統一介面 -> 分批遷移 -> 驗證 -> 處理例外
統一「介面」（新增模組 + 替換引用）風險低，統一「風格」（修改現有結構）風險高
run_hook_safely 一行取代 44 套自寫的錯誤處理，確保行為一致
訊息集中化用 Messages 類別按使用者角色分組，消除散落的硬編碼字串
分批遷移不只降低風險，更是建立信心的過程
安全網（stderr 輸出、測試覆蓋）必須在風險操作之前到位

上一章：配置分離與常數管理 下一章：重構陷阱與防護 相關：5.5 頂層例外處理機制

作用域迴歸案例研究

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

本章記錄 W24 開發週期中發生的一個真實 bug：在統一 16 個 Hook 的 logger 初始化風格時，7 個 Hook 因為變數作用域變更而靜默失敗，影響 41 個函式。

這個案例的價值在於：bug 本身很簡單（NameError），但它暴露了重構時一個容易被忽略的系統性風險。

背景

W24 的任務是統一所有 Hook 的 logger 初始化風格。原本各 Hook 的 logger 初始化位置不一致：

 1# 風格 A：模組級初始化（13 個 Hook 使用）
 2logger = setup_hook_logging("my-hook")  # 在最外層
 3
 4def helper():
 5    logger.info("working...")  # OK：logger 是全域變數
 6
 7def main():
 8    helper()
 9    logger.info("done")
10    return 0
11
12# 風格 B：main() 內初始化（已有部分 Hook 使用）
13def helper(logger):
14    logger.info("working...")  # OK：logger 是參數
15
16def main():
17    logger = setup_hook_logging("my-hook")  # 在 main() 內
18    helper(logger)
19    logger.info("done")
20    return 0

統一目標：全部改為風格 B（main() 內初始化），理由是：

logger 不該在模組被 import 時就建立
main() 內初始化更明確，生命週期更可控

出了什麼問題

修改時只做了一件事：把 logger = setup_hook_logging(...) 從模組級移到 main() 內部。

 1# 修改前
 2logger = setup_hook_logging("acceptance-gate-hook")
 3
 4def check_acceptance_criteria(ticket_path):
 5    logger.info(f"Checking {ticket_path}")  # OK
 6    # ...
 7
 8def validate_ticket_format(content):
 9    logger.info("Validating format")  # OK
10    # ...
11
12def main():
13    result = check_acceptance_criteria(path)
14    # ...
15
16# 修改後（有 bug）
17def check_acceptance_criteria(ticket_path):
18    logger.info(f"Checking {ticket_path}")  # NameError!
19    # ...
20
21def validate_ticket_format(content):
22    logger.info("Validating format")  # NameError!
23    # ...
24
25def main():
26    logger = setup_hook_logging("acceptance-gate-hook")  # 區域變數
27    result = check_acceptance_criteria(path)
28    # ...

logger 從全域變數變成了 main() 的區域變數。但 check_acceptance_criteria 和 validate_ticket_format 仍然以全域方式引用 logger——它們不知道 logger 已經不在全域作用域了。

Python 作用域規則回顧

Python 的變數查找遵循 LEGB 規則：

1L - Local      : 函式內部
2E - Enclosing  : 外層函式（閉包）
3G - Global     : 模組級
4B - Built-in   : Python 內建

 1# 修改前：logger 在 G（Global）
 2logger = setup_hook_logging("hook")  # Global scope
 3
 4def helper():
 5    logger.info("...")  # L 找不到 → E 找不到 → G 找到了
 6
 7# 修改後：logger 在 main 的 L（Local）
 8def helper():
 9    logger.info("...")  # L 找不到 → E 找不到 → G 找不到 → NameError!
10
11def main():
12    logger = setup_hook_logging("hook")  # main 的 Local scope
13    helper()  # helper 無法存取 main 的 Local

main() 的區域變數對 helper() 來說是不可見的。helper() 不是定義在 main() 內部（不是閉包），所以 Enclosing scope 也找不到。

為什麼沒被立刻發現

這個 bug 最危險的地方是靜默失敗。原因是 run_hook_safely 的頂層例外處理：

 1def run_hook_safely(main_func, hook_name):
 2    logger = setup_hook_logging(hook_name)
 3    try:
 4        exit_code = main_func()
 5    except (KeyboardInterrupt, SystemExit):
 6        raise
 7    except Exception:
 8        tb_str = traceback.format_exc()
 9        _log_exception(logger, hook_name, tb_str)
10        return EXIT_ERROR  # 返回錯誤碼，但不會 crash

流程是這樣的：

11. main() 被 run_hook_safely 呼叫
22. main() 內呼叫 check_acceptance_criteria()
33. check_acceptance_criteria() 引用 logger → NameError
44. NameError 是 Exception 的子類別
55. run_hook_safely 捕獲，寫入日誌檔案
66. 返回 EXIT_ERROR（整數 1）
77. Hook 系統收到非零退出碼 → 顯示 "hook success"（suppressOutput）
88. 用戶看不到任何異常

7 個 Hook 就這樣在至少 2 個 session 中靜默失敗。直到有人手動觸發了一個受影響的 Hook 並檢查日誌，才發現問題。

這也是為什麼 W25-005 後來在 _log_exception 加入了 stderr 輸出。詳見 5.5 頂層例外處理機制。

正確的修正方式

Step 1：影響範圍分析

修改變數作用域之前，先列出所有引用該變數的函式：

 1# 用 AST 分析找出所有引用 logger 的非 main 函式
 2python3 -c "
 3import ast, sys
 4
 5tree = ast.parse(open(sys.argv[1]).read())
 6for node in ast.walk(tree):
 7    if isinstance(node, ast.FunctionDef) and node.name != 'main':
 8        for child in ast.walk(node):
 9            if isinstance(child, ast.Name) and child.id == 'logger':
10                print(f'  {node.name}() references logger')
11                break
12" acceptance-gate-hook.py

輸出：

1  check_acceptance_criteria() references logger
2  validate_ticket_format() references logger
3  check_worklog_sections() references logger
4  ... (共 11 個函式)

Step 2：修改函式簽名

每個引用 logger 的函式都必須接收 logger 作為參數：

1def check_acceptance_criteria(ticket_path, logger):  # 加入 logger 參數
2    logger.info(f"Checking {ticket_path}")
3    # ...
4
5def validate_ticket_format(content, logger):  # 加入 logger 參數
6    logger.info("Validating format")
7    # ...

Step 3：更新所有呼叫端

1def main():
2    logger = setup_hook_logging("acceptance-gate-hook")
3    result = check_acceptance_criteria(path, logger)  # 傳遞 logger
4    validate_ticket_format(content, logger)            # 傳遞 logger
5    return 0

Step 4：驗證

 1# AST 驗證：確認沒有函式在引用全域 logger
 2python3 -c "
 3import ast, sys
 4
 5tree = ast.parse(open(sys.argv[1]).read())
 6issues = []
 7for node in ast.walk(tree):
 8    if isinstance(node, ast.FunctionDef) and node.name != 'main':
 9        params = {arg.arg for arg in node.args.args}
10        if 'logger' not in params:
11            for child in ast.walk(node):
12                if isinstance(child, ast.Name) and child.id == 'logger':
13                    issues.append(node.name)
14                    break
15if issues:
16    print(f'FAIL: {issues} still reference global logger')
17else:
18    print('PASS: all functions receive logger as parameter')
19" acceptance-gate-hook.py

修正規模

指標	數值
受影響 Hook	7 個
受影響函式	41 個
修正行數	+143 / -81
靜默失敗持續時間	至少 2 個 session

為什麼 py_compile 抓不到這個 bug

你可能會想：修改後跑一下語法檢查不就好了？

1python3 -m py_compile acceptance-gate-hook.py
2# 通過！沒有任何錯誤

py_compile 只檢查語法（syntax），不檢查作用域（scope）。logger.info("...") 在語法上完全正確——它是一個合法的「存取名稱 logger 的 info 屬性並呼叫」。只有在執行時，Python 才會查找 logger 這個名稱，發現找不到，拋出 NameError。

驗證工具的能力比較

工具	能否偵測此 bug	原因
`py_compile`	否	只檢查語法
`mypy`	可能	型別檢查會分析名稱可見性
AST 分析	是	可以追蹤名稱引用和定義
實際執行	是	直接觸發 `NameError`
`pylint`	是	會警告 `undefined-variable`

教訓：作用域變更的強制檢查清單

任何涉及變數作用域變更的重構（全域 → 區域、模組級 → 函式內、類別屬性 → 方法參數），都必須執行：

步驟	動作	驗證方式
1	列出所有引用該變數的函式	`grep` 或 AST 分析
2	每個函式確認：透過參數接收還是依賴全域？	逐一檢查函式簽名
3	依賴全域的函式必須新增參數	修改函式簽名
4	所有呼叫端必須傳遞新參數	修改所有 call site
5	驗證	AST 分析或實際執行（不要只用 py_compile）

更廣泛的啟示

這個案例不只適用於 logger。任何「移動變數定義位置」的重構都有同樣的風險：

 1# 範例：將資料庫連線從全域移入函式
 2# 修改前
 3db = connect_database()
 4
 5def get_user(user_id):
 6    return db.query(f"SELECT * FROM users WHERE id = {user_id}")
 7
 8# 修改後（有 bug）
 9def get_user(user_id):
10    return db.query(...)  # NameError: db 不再是全域
11
12def main():
13    db = connect_database()
14    user = get_user(123)

同樣的模式，同樣的陷阱。解決方式也一樣：分析引用 → 修改簽名 → 傳遞參數 → 驗證。

思考題

如果使用 global logger 宣告，能否解決這個問題？為什麼不推薦這種做法？
閉包（closure）能否解決這個問題？把 helper 定義在 main() 內部會怎樣？
這個 bug 在什麼條件下才會被發現？（提示：考慮測試覆蓋率和 Hook 觸發時機）

實作練習

找一段使用全域變數的程式碼，嘗試將變數移入函式內部，並用 AST 分析驗證所有引用
寫一個腳本，掃描指定的 Python 檔案，找出所有「函式內引用但未定義、也不在參數中」的名稱
設計一個 pre-commit hook，在 git diff 中偵測「變數定義位置改變」的情況

上一章：重構案例研究 相關：5.5 頂層例外處理機制 — 本案例中 bug 被靜默吞掉的機制分析

重構陷阱與防護

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

「只是把變數移個位置」「只是搬個檔案」「只是加個參數」——這些聽起來無害的操作，在我們的專案中分別造成了 7 個 Hook 靜默失敗、5 個 Hook 啟動崩潰、以及使用者看到莫名其妙的 “hook error” 訊息。

本章整合三個真實事故（IMP-003、IMP-005、IMP-006），分析它們的共通模式，並建立一套防護方法。如果你只帶走一句話，請記住：修改了定義，就必須更新所有引用。

三個陷阱的概覽

陷阱	重構類型	遺漏	靜默時間
作用域迴歸 (IMP-003)	變數從全域移入函式	引用該變數的函式未更新	2+ sessions
Import 未同步 (IMP-005)	模組搬遷至子目錄	引用該模組的檔案未更新	直到下次啟動
靜默故障 (IMP-006)	函式簽名變更	部分 call site 未更新	直到該路徑被執行

三者看似不同，但根本原因完全一致：修改了定義，但沒有更新所有引用。

陷阱一：作用域迴歸

本節是概要。IMP-003 的完整分析（含 LEGB 規則詳解、AST 修正腳本）請見作用域迴歸案例研究。

事件摘要

W24 的任務是統一 16 個 Hook 的 logger 初始化風格：從模組級初始化（全域變數）改為 main() 內初始化（區域變數）。

 1# 修改前：logger 是全域變數，所有函式可存取
 2logger = setup_hook_logging("my-hook")
 3
 4def helper():
 5    logger.info("working...")  # OK：LEGB 在 Global 層找到
 6
 7# 修改後：logger 變成 main() 的區域變數
 8def helper():
 9    logger.info("working...")  # NameError! helper 看不到 main 的區域變數
10
11def main():
12    logger = setup_hook_logging("my-hook")
13    helper()

為什麼危險

兩個因素疊加讓這個 bug 特別難發現：

py_compile 抓不到：logger.info(...) 語法完全合法，名稱解析要到執行時才發生
頂層例外處理吞掉了 NameError：run_hook_safely() 捕捉所有 Exception，Hook 靜默失敗而非 crash（詳見 5.5 頂層例外處理機制）

結果：7 個 Hook 在至少 2 個 session 中靜默失敗，41 個函式需要修正，+143/-81 行修改——全部源自一個「只是移動定義位置」的操作。

正確做法

修改前用 grep 或 AST 列出所有引用，逐一加入 logger 參數，再用 AST 驗證無遺漏。完整的四步修正流程見作用域迴歸案例研究。

陷阱二：Import 未同步

背景

W22 重構將 common_functions.py 從 .claude/hooks/ 遷移至 .claude/hooks/lib/。但只更新了部分 Hook 的 import 路徑。

 1# 遷移前（模組在同目錄）
 2sys.path.insert(0, str(Path(__file__).parent))
 3from common_functions import hook_output  # OK
 4
 5# 遷移後（模組移到 lib/，但 import 未更新）
 6sys.path.insert(0, str(Path(__file__).parent))
 7from common_functions import hook_output  # ModuleNotFoundError!
 8
 9# 正確的遷移後寫法
10from lib.common_functions import hook_output  # OK

5 Why 分析

Hook 啟動時拋出 ModuleNotFoundError
from common_functions import ... 找不到模組
common_functions.py 已遷移至 lib/ 子目錄
遷移時只更新了部分 Hook 的 import 路徑
根本原因：模組遷移後缺乏「全量引用更新」步驟

5 個 Hook 受影響，涵蓋 SessionStart、PostToolUse、UserPromptSubmit 三種事件類型。

第二次發生

同一個模式在後續又發生了一次。W24 統一 sys.path 風格時，task-dispatch-readiness-check.py 的 sys.path 只包含 .claude/hooks/，缺少 .claude/lib/。

更危險的是，這次的 error 與另一個 Hook 的 error（plugin timeout）同時出現。移除 plugin 後以為問題解決了，實際上只消除了其中一個來源。

教訓：多個不同來源的 error 同時存在時，修一個後不能假設全部修好了——必須逐一驗證每一個。

正確的遷移步驟

 1# Step 1：列出所有引用
 2grep -r "from common_functions import" .claude/hooks/*.py
 3
 4# Step 2：列出所有直接 import
 5grep -r "import common_functions" .claude/hooks/*.py
 6
 7# Step 3：逐一更新 import 路徑（根據 Step 1-2 的清單）
 8
 9# Step 4：逐一驗證
10for f in .claude/hooks/*.py; do
11    echo "Testing $f..."
12    echo '{}' | python3 "$f" 2>&1 | head -5
13done

與陷阱一的對比

維度	陷阱一（作用域）	陷阱二（Import）
修改了什麼	變數定義的位置	模組檔案的位置
遺漏了什麼	引用該變數的函式	引用該模組的檔案
py_compile 能偵測？	否	否
grep 能找出？	是	是

根本結構完全相同：移動了定義，沒有追蹤引用。

陷阱三：靜默故障

IMP-006 收錄了四個 Hook 隱性故障案例。這裡選取三個，分別代表不同的「部分更新」變體。

案例 A：函式參數遺漏

save_check_log() 需要 5 個參數，但某個 call site 只傳了 4 個：

1# 第 471 行（正確）
2save_check_log(prompt, result, is_dev, count, logger)
3
4# 第 453 行（早期返回路徑，遺漏 logger）
5save_check_log(prompt, None, False, 0)  # TypeError: missing argument

同一個函式在同一個檔案中呼叫了兩次。第二次是在早期返回（early return）路徑上，開發者 copy-paste 後漏掉了最後一個參數。

這跟陷阱一本質相同——函式簽名變更後（加入 logger 參數），沒有更新所有 call site。

案例 B：語義分類錯誤

command-entrance-gate-hook.py 將「分析、調查、研究」等關鍵字歸入 DEVELOPMENT_KEYWORDS，導致分析命令被當作開發命令處理，被要求先建立 Ticket 才能執行。

但根據決策樹，分析類命令走「問題處理流程」，不需要 Ticket。

1# 錯誤：ANALYSIS_KEYWORDS 被放進 DEVELOPMENT_KEYWORDS
2DEVELOPMENT_KEYWORDS = [
3    "implement", "create", "fix",
4    "analyze", "investigate", "research",  # 這些不是開發命令！
5]
6
7# 正確：分析類關鍵字應在白名單中
8exploration_patterns = ["analyze", "investigate", "research", "trace"]

這不是典型的「引用未更新」，但仍屬於部分更新問題：Hook 的語義分類與決策樹的語義定義不同步。修改了決策樹的行為分類，但沒有同步更新 Hook 的關鍵字分類。

案例 C：多路徑覆蓋不完整

agent-ticket-validation-hook.py 有兩條錯誤路徑：

1# 路徑 1：未預期異常（已有 stderr 輸出）
2except Exception:
3    print(f"[Error] {traceback.format_exc()}", file=sys.stderr)
4
5# 路徑 2：有意阻止（遺漏 stderr 輸出）
6if not valid:
7    return 2  # exit code 2，但沒有 stderr 告訴使用者為什麼

開發者只覆蓋了第一條路徑。第二條路徑（業務邏輯拒絕）執行時，使用者只看到 “hook error” 和 “No stderr output”，無法得知被拒絕的原因。

教訓：一個函式的所有非成功路徑都需要相同等級的錯誤報告，不能只覆蓋 exception 路徑。

共通模式：部分更新

三個陷阱的根本結構完全相同：

1          修改了 A
2              |
3    A 有 N 個引用/依賴
4              |
5     只更新了其中 M 個
6              |
7       N - M 個壞掉了
8              |
9         靜默失敗

不管 A 是變數定義（陷阱一）、模組路徑（陷阱二）、還是函式簽名（陷阱三），模式一致：

修改了某個「被依賴的東西」
沒有找出所有依賴它的地方
遺漏的部分在執行時才爆炸
由於例外處理或 UI 限制，爆炸被吞掉

防護公式

1安全的重構 = 修改定義 + 列出全部引用 + 逐一更新 + 逐一驗證

四步少一步都會出事：

少了「列出全部引用」 – 你不知道影響範圍（三個陷阱的共通原因）
少了「逐一更新」 – 知道但沒做完（陷阱二的第二次發生）
少了「逐一驗證」 – 做了但不確定對不對（陷阱一用 py_compile 驗證的盲點）

grep：防護公式的第一步

「列出全部引用」聽起來很簡單，但容易被跳過。以下是每種重構類型對應的 grep 命令：

1# 變數作用域變更：找出所有引用某變數的位置
2grep -rn "logger" hooks/*.py | grep -v "def.*logger" | grep -v "^#"
3
4# 模組遷移：找出所有 import 語句
5grep -rn "from common_functions import" .claude/hooks/*.py
6grep -rn "import common_functions" .claude/hooks/*.py
7
8# 函式簽名變更：找出所有呼叫端
9grep -rn "save_check_log(" .claude/hooks/*.py

重點是養成習慣：修改定義之前，先跑一次搜尋，看看這個名稱出現在哪些地方。這一步花不到 30 秒，但能避免幾小時的除錯。

防護工具箱

不同的驗證工具能偵測不同層級的問題。沒有銀彈，但可以根據重構類型選擇正確的工具組合。

工具能力對照表

工具	語法錯誤	作用域問題	Import 問題	參數數量	語義正確性
`py_compile`	是	否	否	否	否
`grep` / 文字搜尋	–	找出引用	找出引用	找出 call site	–
AST 分析	是	是	部分	是	否
`pylint`	是	是	是	是	否
`mypy`	是	是	是	是	否
實際執行	是	是	是	是	是

關鍵發現

py_compile 是必要但不充分的。它能確認「Python 能讀懂這個檔案」，但不能確認「這個檔案能正確執行」。三個陷阱中沒有一個能被 py_compile 偵測到。

grep 是最可靠的第一步。不管是變數引用、import 路徑還是函式呼叫，文字搜尋都能找出所有使用處。它不聰明，但不會遺漏。

實際執行是唯一能驗證語義的工具。案例 B 的語義分類錯誤，靜態工具全部無法偵測——因為程式碼邏輯上沒錯，錯的是業務語義。

按重構類型選擇工具

重構類型	最低要求	建議
移動變數定義	grep + AST 分析	+ 實際執行覆蓋所有路徑
移動模組檔案	grep + 逐一 import 驗證	+ `echo '{}' \| python3 file.py`
修改函式簽名	grep + AST 參數檢查	+ pylint + 測試覆蓋
修改關鍵字/分類	與設計文件交叉比對	+ 手動場景測試
統一風格（批量）	先 grep 建立完整清單	+ 逐一驗證，不依賴數量判斷

批量重構的特殊風險

統一化重構（如「把 16 個 Hook 的 logger 風格統一」）比單一檔案的修改危險得多，因為：

數量產生虛假信心：改了 13 個成功了，容易假設剩下 3 個也沒問題
機械性動作降低警覺：重複相同操作 16 次，注意力會下降
驗證疲勞：逐一驗證 16 個檔案很煩，容易偷懶跳過

對策：建立完整清單，逐一打勾，用腳本自動化驗證。

建立自己的重構檢查清單

根據本章三個陷阱的經驗，任何涉及「移動或修改被引用物件」的重構，都應該執行以下清單：

修改前（強制）

用 grep 列出所有引用/使用處，建立完整清單
評估每個引用是否需要同步更新
確認驗證方法（不能只用 py_compile）

修改中

按清單逐一更新每個引用
每更新一個就在清單打勾，不跳過

修改後（強制）

用 AST 分析或 pylint 驗證作用域和參數
實際執行（或測試）覆蓋所有修改過的檔案
如果是批量修改，逐一驗證每個檔案，不依賴數量判斷

思考題

為什麼動態語言（Python、JavaScript）比靜態語言（Java、Dart）更容易出現這類問題？靜態語言的什麼機制能在編譯期偵測到陷阱一和陷阱二？
陷阱三案例 B（語義分類錯誤）無法被任何靜態工具偵測。你會如何設計一個測試來防護這類問題？
「頂層例外處理吞掉錯誤」既是安全機制（防止 crash），也是風險（隱藏 bug）。如何在這兩個需求之間取得平衡？（可參考 5.5 頂層例外處理機制的設計方案）

實作練習

選擇一個使用全域變數的 Python 專案，嘗試將一個全域變數移入函式內部。在修改前後分別用 py_compile、AST 分析、pylint 驗證，比較各工具的偵測能力。
寫一個 Python 腳本，接受一個 Python 檔案和一個變數名稱作為輸入，輸出「所有引用該變數但沒有在參數中接收它的函式」清單。
設計一個模組遷移的自動化腳本：接受舊路徑和新路徑，自動搜尋所有 import 語句並更新，最後逐一驗證每個修改過的檔案是否能成功 import。

上一章：大規模統一化重構 下一章：非程式碼的重構 相關：作用域迴歸案例研究 – 陷阱一的完整深入分析 相關：5.5 頂層例外處理機制 – 例外處理如何隱藏 bug 的機制分析

非程式碼的重構

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

前面幾章我們重構的對象都是程式碼：提取函式、消除魔法數字、分離配置。但你有沒有想過，文件也會腐敗？

當一份規則文件從 50 行長到 450 行，閱讀者要在腦中同時追蹤的概念數量跟第一章提到的那個 858 行 Python 檔案沒有本質區別。認知負擔不只存在於程式碼中——任何需要人類閱讀和理解的東西都受它影響。

問題：文件膨脹

v0.28.0 到 v0.31.0 之間，專案的規則文件經歷了 9 個版本的迭代。每次迭代都在解決真實的問題：補充遺漏的邊界情況、新增流程步驟、記錄決策理由。每一次修改都合理，但累積的結果是：

1parallel-dispatch.md     280 行  ← 原本是「什麼時候可以並行」的簡單指南
2task-splitting.md        230 行  ← 原本是「怎麼拆任務」的清單
3ticket-lifecycle.md      220 行  ← 原本是「Ticket 狀態怎麼轉」的流程
4version-progression.md   180 行  ← 原本是「什麼時候推進版本」的判斷
5incident-response.md     170 行  ← 原本是「出錯了怎麼辦」的流程
6query-vs-research.md     130 行  ← 原本是「查資料要不要派人」的二選一
7plan-to-ticket.md        100 行  ← 原本是「計畫怎麼變成 Ticket」的流程
8decision-tree.md         452 行  ← 核心決策樹，每次都在「補一個分支」

問題不是內容不正確——每一行都有存在的理由。問題是讀不動。

一個新加入的代理人需要閱讀 parallel-dispatch.md 來決定能不能並行派發任務。它真正需要的資訊是：觸發條件（5 行）、安全檢查清單（6 行）、決策流程圖（5 行）。但它必須在 280 行中找到這些——剩下的 264 行是 5W1H 格式範例、分析任務的並行原則、Agent Teams 場景表、進度追蹤模板。

這就像在一個 500 行的函式裡找那 20 行核心邏輯。

膨脹的過程

文件膨脹的方式和程式碼膨脹幾乎一模一樣。回顧 parallel-dispatch.md 的成長軌跡：

版本	行數	新增原因
v1.0	60 行	初始版本：觸發條件 + 決策流程
v1.1	90 行	補充：安全檢查清單（因為有人忘記檢查檔案衝突）
v1.2	130 行	新增：Agent Teams 派發方式（新功能）
v2.0	180 行	新增：5W1H 格式範例（因為有人不知道怎麼寫）
v2.3	230 行	新增：分析任務並行原則、進度追蹤模板
v2.5	280 行	新增：並行派發後驗證流程（因為有人忘記驗證）

每一次新增都在解決真實問題。沒有人故意讓文件變長。但六個版本之後，一個簡單的「能不能並行」判斷指南變成了包羅萬象的操作手冊。

這和程式碼中的「上帝函式」成因一樣：每次「加一點」都合理，但沒有人停下來問「這個函式是不是該拆了」。

解決方案：Progressive Disclosure

程式碼重構有 Extract Method——把函式內部的細節提取到獨立函式中。文件重構有對應的技巧：Progressive Disclosure（漸進式揭露）。

核心思想：常駐只保留決策入口和強制規則，細節放到參考文件中按需載入。

這和函式設計的道理一樣。你不會把排序演算法的完整實作放在 main() 裡面，你會呼叫 sort()。同樣地，規則文件的讀者不需要在判斷「能不能並行」時看到「Agent Teams 的 3-4x 成本計算方式」。

精簡原則

我們制定了四條原則來指導文件重構，和程式碼重構的原則一一對應：

程式碼原則	文件原則	說明
單一責任	一個文件回答一個問題	常駐文件只回答「怎麼判斷」，不回答「細節怎麼做」
資訊層級	決策入口 → 強制規則 → 參考細節	讀者按需深入，不強制閱讀全部
DRY	細節只寫一次，放在 references/	多個文件引用同一份參考，不複製貼上
量化驗證	精簡前後行數對比	有數字才知道改善了多少

具體做法

以 parallel-dispatch.md 為例，精簡過程分三步：

Step 1：識別「決策入口」和「參考細節」

閱讀 280 行內容，對每一段問：「讀者在做『能不能並行』這個決策時需要這段嗎？」

觸發條件表格 → 需要（決策入口）
安全檢查清單 → 需要（強制規則）
決策流程圖 → 需要（快查表）
數量原則 → 需要（簡短規則）
不適用場景 → 需要（負面清單）
5W1H 格式範例 → 不需要（移出）
Agent Teams 場景表 → 不需要（移出）
進度追蹤模板 → 不需要（移出）

Step 2：提取到參考文件

1# 精簡前
2parallel-dispatch.md (280 行，所有內容混在一起)
3
4# 精簡後
5parallel-dispatch.md (98 行，決策入口 + 強制規則)
6  └→ references/parallel-dispatch-details.md (剩餘細節，按需查閱)

Step 3：加入連結

1## 並行派發後驗證（強制）
2
3所有並行代理人回報完成後，**必須**執行 `git diff --stat` 驗證。
4
5> 詳細驗證步驟和常見原因：.claude/references/parallel-dispatch-details.md

讀者看到這段就知道：「驗證是強制的，具體步驟在那個連結裡。」它可以選擇深入閱讀，也可以先完成手邊的決策。

精簡前後對比

看看 incident-response.md 精簡前後的結構差異：

 1# 精簡前 (170 行)
 2
 3## 強制流程
 4（流程圖 + 說明）
 5
 6## 強制觸發條件
 7（觸發表格）
 8
 9## 派發對應表
10（代理人對應表）
11
12## 多視角分析原則             ← Level 3
13（詳細的分析方法論）
14
15## 安全等級分類               ← Level 3
16（安全等級表格 + 處理流程）
17
18## 報告格式範例               ← Level 3
19（完整的報告模板）
20
21## 禁止行為
22（禁止清單）

 1# 精簡後 (64 行)
 2
 3## 強制流程
 4（流程圖 + 說明）
 5
 6## 強制觸發條件
 7（觸發表格）
 8
 9## 派發對應表
10（代理人對應表）
11
12## 禁止行為
13（禁止清單）
14
15## 相關文件
16> 詳細規則：.claude/references/incident-response-details.md

Level 3 的內容（多視角分析、安全等級、報告格式）整段移到 references/ 目錄。常駐文件只剩下做決策需要的資訊。

實際成果

7 個規則文件的精簡結果：

文件	精簡前	精簡後	縮減
parallel-dispatch.md	280 行	98 行	-65%
task-splitting.md	230 行	93 行	-60%
ticket-lifecycle.md	220 行	70 行	-68%
version-progression.md	180 行	69 行	-62%
incident-response.md	170 行	64 行	-62%
query-vs-research.md	130 行	46 行	-65%
plan-to-ticket.md	100 行	43 行	-57%
合計	1310 行	483 行	-63%

核心決策樹 decision-tree.md 也從 452 行精簡到 286 行（-37%）。它的縮減幅度較小，因為決策樹本身就是「決策入口」——大部分內容都是必要的分支判斷。

後記：上面的數字是 v3.0.0 精簡完成時的快照。精簡後不到兩週，plan-to-ticket.md 因為新增「執行中額外發現」流程從 43 行長回 87 行，decision-tree.md 因為新增 TDD Phase 路由從 286 行長回 434 行。這不代表精簡失敗——新增的內容都是必要的新功能。但它提醒我們：文件重構和程式碼重構一樣，是持續的紀律。

通用原則

從這次文件重構中，我們提煉出四個可複用的原則：

原則 1：單一責任

每份文件應該只回答一個核心問題。

文件	核心問題	不該包含
parallel-dispatch.md	能不能並行？	Agent Teams 的完整操作手冊
incident-response.md	出錯了怎麼處理？	每種錯誤的詳細分析範例
ticket-lifecycle.md	Ticket 狀態怎麼轉？	Hook 的技術實作細節

判斷方式和函式一樣：如果描述這份文件的用途需要「和」這個字，它可能需要拆分。

原則 2：資訊層級

按讀者的需求深度分層：

1Level 0: 快查表（一眼就能找到答案）
2Level 1: 強制規則（必須遵守的約束）
3Level 2: 決策流程（判斷邏輯）
4Level 3: 參考細節（範例、模板、歷史記錄）

常駐文件只包含 Level 0-2，Level 3 放在 references/ 目錄下。

對比程式碼的資訊層級：

 1# Level 0: 函式簽名（一眼就知道做什麼）
 2def can_dispatch_parallel(tasks: list[Task]) -> bool:
 3    # Level 1: Guard clauses（強制規則）
 4    if len(tasks) < 2:
 5        return False
 6    if has_dependency(tasks):
 7        return False
 8
 9    # Level 2: 核心邏輯（判斷邏輯）
10    return not has_file_overlap(tasks)
11
12# Level 3: 實作細節（在被呼叫的函式裡）
13def has_file_overlap(tasks):
14    # 50 行的具體實作...

同一個概念，同一個結構。

原則 3：DRY

文件之間也會出現重複。同一段「Wave 獨立性原則」如果在 parallel-dispatch.md、task-splitting.md、version-progression.md 三個地方都寫了，修改時就要改三處。

解決方式和程式碼一樣：抽到共用的參考文件，其他文件用連結引用。

原則 4：量化驗證

沒有數字的重構是自我感覺良好。精簡前後一定要量化比較：

1# 文件行數統計
2wc -l .claude/rules/flows/*.md .claude/rules/guides/*.md
3
4# 前後對比
5echo "精簡前: 1310 行"
6echo "精簡後:  483 行"
7echo "縮減率: 63%"

和程式碼重構的 -65% 行數對比一樣，行數本身不是目標，但它是認知負擔降低的代理指標。

常見錯誤

文件重構也有自己的陷阱：

錯誤 1：過度精簡

把所有細節都移走，常駐文件只剩下標題和連結。讀者每做一個決策都要點開參考文件，跳轉次數太多反而增加認知負擔。

1# 錯誤：過度精簡
2## 並行派發
3> 詳見：references/parallel-dispatch-details.md
4
5## 任務拆分
6> 詳見：references/task-splitting-details.md

這等於一個函式裡全是 call_other_function()，讀者什麼都看不到。常駐文件至少要包含決策入口（判斷邏輯）和強制規則（不可違反的約束）。

錯誤 2：按「章節」拆分而非按「層級」拆分

把文件按目錄拆成多個小文件，但每個小文件仍然混合了決策入口和參考細節。這只是把一個大問題變成了多個小問題。

正確的拆分維度是資訊層級，不是主題章節。

錯誤 3：沒有更新連結

精簡後忘記在常駐文件中加入參考文件的連結。讀者需要細節時找不到入口。這和重構後忘記更新 import 一樣危險。

程式碼 vs 文件重構對照表

程式碼重構和文件重構的手法其實是同一套思維的不同實踐：

維度	程式碼重構	文件重構
壞味道	函式太長、巢狀過深	文件太長、層級不分
核心手法	Extract Method	Progressive Disclosure
單一責任	一個函式做一件事	一份文件回答一個問題
DRY	提取共用模組	提取共用參考文件
量化指標	行數、認知負擔指數	行數、常駐 vs 參考比例
驗證方式	測試通過	讀者能在 30 秒內找到答案
失敗的重構	過度拆分導致跳轉太多	過度精簡導致資訊不足
觸發條件	函式超過 30 行	文件超過 100 行且混合多個層級
典型比例	858 行 → 296 行 (-65%)	280 行 → 98 行 (-65%)

最後一行不是巧合。兩個案例的縮減率接近，是因為底層原理相同：大約 1/3 的內容是核心邏輯（決策入口），2/3 的內容是支撐細節（參考資料）。

什麼時候該重構文件

和程式碼一樣，不是所有文件都需要重構。觸發條件：

指標	閾值	行動
文件長度	> 100 行且混合多層級	評估是否需要分離
讀者反饋	「找不到需要的資訊」	重新組織資訊層級
更新頻率	每次更新都在不同段落	考慮按變更頻率拆分
重複內容	同一段話出現在 2+ 份文件	提取到共用參考

思考題

你的專案有沒有「什麼都寫在 README」的情況？如果有，試著用 Progressive Disclosure 原則拆分它。
為什麼 decision-tree.md 的縮減幅度（-37%）比其他文件（-57% 到 -68%）小？這說明了什麼？
文件重構有一個程式碼重構沒有的風險：「過度精簡導致讀者找不到需要的資訊」。你會怎麼驗證精簡後的文件仍然足夠完整？

實作練習

練習 1：評估文件健康度

找一份超過 150 行的文件（你自己的專案 README、API 文件、團隊 Wiki），回答以下問題：

這份文件回答幾個核心問題？（如果超過 1 個，考慮拆分）
讀者能在 30 秒內找到最常需要的資訊嗎？
有沒有段落只在特定情境下才需要閱讀？

練習 2：執行 Progressive Disclosure

對那份文件執行三步精簡：

標記每一段的資訊層級（Level 0-3）
將 Level 3 的內容提取到獨立的參考文件
在原文件中加入連結

練習 3：量化驗證

計算精簡前後的行數和縮減率。如果縮減率低於 30%，思考是否原本的結構就已經不錯。如果超過 70%，檢查是否過度精簡了。

參考範圍

完整案例回顧

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

本章是模組七的總結。前面九章從動機判斷開始，依序教了壞味道識別、配置分離、DRY 原則、常數管理、消除魔法數字、大規模統一化、重構陷阱防護、作用域迴歸、以及非程式碼的重構——這些都是從同一個真實專案提煉的。現在把時間線拉開，看看這些技術在三個階段中如何逐步應用，以及過程中犯了哪些錯。

起點：超過 30 個 Hook 各自為政

v0.28.0 之前的 Hook 系統是「有機生長」的典型案例。32 個 Hook 各自獨立開發，沒有共用程式庫、沒有統一風格、沒有測試。

具體問題：

問題	嚴重度	量化
單檔過大	高	task-dispatch 達 858 行
函式重複	高	`run_git_command` 等函式在多個檔案中複製貼上
配置硬編碼	中	代理人清單散落在程式碼各處
魔法數字	中	`line[9:]` 這類寫法隨處可見
無測試	高	任何修改都是盲改

這些問題不是一天造成的。每次新增 Hook 時，最快的做法就是從現有 Hook 複製一份再改。沒人想著「先建共用模組」，因為每次都只是「加一個小功能」。第一個 Hook 50 行，第二個 80 行，到第十個 Hook 時，已經有三四份 run_git_command 的副本了。但每次都覺得「下次再整理」。

用程式碼壞味道識別中教的 grep 方法掃描一次：

1grep -rh "^def " .claude/hooks/*.py | sort | uniq -c | sort -rn | head -5

掃描後會發現同樣的函式定義散落在多個檔案中。run_git_command 出現在 2 個以上的 Hook 裡，get_current_branch、read_yaml_file 等也有各自的副本。如果修復 run_git_command 的一個 bug，你需要同時改每個有副本的檔案，而且不能漏掉任何一個。

累積到 32 個 Hook 時，技術債務已經大到無法忽視。

第一階段：v0.28.0 結構性重構

第一階段的目標很明確：消除重複、建立結構。我們把工作拆成四個 Wave，每個 Wave 有獨立的交付物和驗證點。

Wave 1：建立共用程式庫

先不動任何 Hook 檔案。第一步是把散落各處的重複邏輯抽取到獨立模組，並為每個模組寫測試。

建立的模組：

模組	職責	對應的壞味道
config_loader	讀取 YAML 配置	ARCH-001 硬編碼配置
git_utils	封裝 Git 命令	IMP-001 重複程式碼
hook_io	統一 Hook I/O 處理	IMP-001 重複程式碼
hook_logging	統一日誌設定	IMP-001 重複程式碼

為什麼先建程式庫而不是先改 Hook？因為如果直接改 Hook，會遇到雞生蛋問題——Hook A 需要共用函式，但共用函式還沒建立。先建好程式庫並通過測試，後續每改一個 Hook 都有安全網。

建立模組時的關鍵決策：介面設計先於實作。我們先定義每個模組的公開函式簽名，寫測試驗證這些簽名的行為，最後才把各 Hook 中的重複邏輯搬進來。這確保了模組的介面是「為使用者設計」的，而不是「照搬原始碼」的。

這個順序的思考方式在 DRY 原則與共用程式庫中有詳細說明。

Wave 2：配置分離

把 task-dispatch 中的硬編碼清單抽到 YAML 檔案：

1# agents.yaml（節錄）
2agents:
3  incident-responder:
4    triggers: ["test failed", "compile error", "runtime error"]
5    priority: 1
6  system-analyst:
7    triggers: ["架構", "設計", "需求"]
8    priority: 2

這一步的行數縮減最明顯。task-dispatch 中原本有大量的 if-elif 鏈在比對代理人名稱和觸發條件，類似這樣：

1# 修改前：60+ 行的 if-elif 鏈
2if "test failed" in message or "compile error" in message:
3    agent = "incident-responder"
4elif "架構" in message or "設計" in message:
5    agent = "system-analyst"
6elif "安全" in message or "auth" in message:
7    agent = "security-reviewer"
8# ... 還有 20 幾個 elif

全部變成配置查表後，程式碼只剩下查表邏輯本身：

1# 修改後：配置驅動
2agents = config_loader.load("agents.yaml")
3for agent_name, config in agents.items():
4    if any(trigger in message for trigger in config["triggers"]):
5        return agent_name

詳細的抽取過程在配置分離與常數管理中說明。

Wave 3：逐檔重構

有了共用程式庫和配置檔，開始逐一重構 Hook 檔案。策略是：

選擇一個 Hook 檔案
用 from lib.xxx import yyy 替換重複程式碼
跑測試確認行為不變
確認通過後繼續下一個檔案

逐檔處理的好處是認知負擔可控——每次只需要理解一個 Hook 的邏輯，不需要同時在腦中處理所有修改。即使最後在同一個 commit 中提交，工作過程中仍然是一個一個檔案獨立驗證的。這就是 Wave 作為安全網的具體體現。

Wave 4：驗證與收尾

28 個單元測試全部通過。主要檔案的變化：

檔案	重構前	重構後	縮減
task-dispatch-readiness-check.py	858 行	296 行	-65%
branch-verify-hook.py	238 行	109 行	-54%
branch-status-reminder.py	167 行	103 行	-38%

第一階段成果

指標	數值
消除重複程式碼	約 415 行
新增共用模組	4 個
新增單元測試	28 個
建立 Error Patterns	3 個（ARCH-001、IMP-001、IMP-002）

第一階段解決了最顯眼的問題：重複和膨脹。但還有更深層的問題藏在下面。

第二階段：v0.31.0 品質深化

第一階段建立了結構，但結構內部的品質仍然參差不齊。v0.31.0 的四個連續 Wave 處理的是「統一風格」這個看似簡單但實際上充滿陷阱的任務。

W22：統一日誌格式

Hook 的日誌格式不一致。有的用 print，有的用 logging，有的用自訂格式。同樣是輸出一行日誌，你可能看到三種寫法：

1# 風格 A：直接 print
2print(f"[{hook_name}] Processing ticket {tid}")
3
4# 風格 B：logging 模組
5logging.info(f"Processing ticket {tid}")
6
7# 風格 C：自訂 logger
8logger = setup_hook_logging(hook_name)
9logger.info(f"Processing ticket {tid}")

W22 統一為風格 C，讓所有 Hook 的日誌都通過 hook_logging 模組。這個 Wave 相對順利，因為只涉及輸出格式的統一，不改變程式邏輯。日誌行為改變不影響 Hook 的核心功能。

W23：統一錯誤訊息

把散落在各 Hook 中的硬編碼錯誤訊息提取到集中的 messages 模組。這對應的是配置分離與常數管理中「禁止硬編碼字串」的原則。

1# 修改前：訊息散落各處，同一個概念有不同的說法
2print("Error: ticket not found")       # Hook A
3print("找不到 ticket")                  # Hook B
4print("Ticket does not exist")          # Hook C
5
6# 修改後：集中管理，一個概念一種說法
7from lib.messages import HookMessages
8print(HookMessages.TICKET_NOT_FOUND)

集中管理的好處不只是一致性。如果需要把所有訊息改成中文，只需要改 messages 模組，不需要搜尋散落在幾十個檔案中的字串。

W24：統一 Logger 初始化風格——IMP-003 事故

這是第二階段最慘痛的一課。

目標很簡單：把所有 Hook 的 logger = setup_hook_logging(...) 從模組級移到 main() 內部。理由是 logger 不該在模組被 import 時就建立——這是 Python 社群的通用最佳實踐。

結果：7 個 Hook 靜默失敗，41 個函式受影響，至少 2 個 session 沒人發現。

根本原因是作用域變更：logger 從全域變數變成 main() 的區域變數後，其他函式無法存取它。Python 的 LEGB 規則決定了 main() 的區域變數對同級的其他函式是不可見的。

更危險的是，run_hook_safely 的頂層例外處理把 NameError 吞掉了——它捕獲所有 Exception，只寫入檔案日誌而不輸出到 stderr 或 stdout。於是使用者端完全看不到任何異常。

這個事故的完整分析在作用域迴歸案例研究中。

IMP-003 帶來兩個直接改善：

作用域變更檢查清單：任何涉及變數作用域變更的重構，都必須先用 AST 分析列出所有引用，逐一確認每個函式的存取方式
stderr 輸出：_log_exception 在寫入檔案日誌後，額外輸出到 stderr，確保 Hook 失敗對使用者可見——再也不會有「靜默失敗」的情況

W25：修復連鎖問題——IMP-005

W22 的模組遷移留下了另一個隱患。把 common_functions.py 從 hooks/ 遷移到 hooks/lib/ 時，部分 Hook 的 import 路徑沒有同步更新，導致 ModuleNotFoundError。這就是 IMP-005（模組遷移後 Import 路徑未同步更新），影響了 5 個 Hook。

修正流程本身不複雜：更新 import 路徑就好。但問題是遷移時沒有系統性地掃描所有引用——只改了「知道有引用的」檔案，漏掉了幾個不常觸發的 Hook。

這裡學到的教訓是：批量修正必須機械化。應該用 grep 或 AST 分析列出所有引用點，再逐一修改並驗證，確認沒有遺漏。手動作業的錯誤率和修改數量成正比。

第二階段成果

指標	數值
統一的風格規範	日誌格式、錯誤訊息、初始化方式
新增 Error Patterns	2 個（IMP-003、IMP-005）
受影響的事故	7 Hook 靜默失敗（IMP-003）
新增防護機制	stderr 輸出、作用域檢查清單、AST 驗證

第二階段的教訓比第一階段更有價值。結構性重構（消除重複、建立模組）相對直接，風險可控。但風格統一涉及的是「改變現有能運作的程式碼」，任何疏忽都可能引入迴歸。

第三階段：系統級改善

前兩個階段解決了程式碼層面的問題。第三階段的視角拉高到「系統如何自我保護」。以下按主題分組，部分改善與第二階段穿插進行。

W9：Progressive Disclosure 精簡

隨著規則、方法論、指南越寫越多，文件系統本身的認知負擔也在增加。一份「並行派發指南」原本 200 行，因為不斷補充場景表、案例、FAQ，膨脹到 600 行。讀者只想知道「怎麼判斷能不能並行」，卻被淹沒在細節中。

W9 做了一次系統性的文件瘦身：

主文件只保留核心規則和決策邏輯（判斷標準、流程圖、檢查清單）
詳細說明、範例、模板移到 references/ 子目錄
每份主文件的 token 數量縮減 20-40%
需要深入了解時，透過連結跳到 references

這不是程式碼重構，但思考方式完全一樣：識別膨脹 → 分析哪些是核心哪些是細節 → 職責分離 → 驗證可讀性。重構的對象不只是程式碼，任何隨時間膨脹的結構化資訊都適用同樣的方法。

W28：一致性審查

對所有 Hook、規則、方法論進行一致性審查。檢查項目包括：

命名是否遵循統一規範（例如 Hook 檔名的 kebab-case）
錯誤處理是否都通過 run_hook_safely
日誌格式是否統一（W22 的成果是否被維持）
配置是否都從 YAML 讀取（W2 的成果是否被維持）
新 Hook 是否使用共用程式庫（W1 的成果是否被維持）

審查的結果是發現了幾個遺漏：v0.28.0 之後新建的 Hook 有部分沒有使用共用程式庫，而是又開始「複製貼上」。開發者說：「我只是從隔壁 Hook 複製了幾行，沒必要引入整個模組。」這正是 v0.28.0 之前所有問題的起點。

這說明制度化比一次性重構更重要。如果沒有持續的品質檢查，程式碼會自然退化回混亂狀態。一致性審查不是做一次就結束，它需要成為定期的衛生檢查。

量化總結：階段對比

維度	第一階段 (v0.28.0)	第二階段 (v0.31.0)	第三階段 (系統級)
目標	消除重複、建立結構	統一風格、深化品質	系統自我保護
方法	抽取模組、配置分離	風格統一、訊息集中	文件精簡、一致性審查
工作量	Wave 1-4	W22-W25	W9、W28
主要產出	4 模組、28 測試	統一風格、2 Error Patterns	文件瘦身、檢查機制
事故	無	IMP-003（7 Hook 靜默失敗）	無
認知負擔變化	大幅降低（檔案縮減 38-65%）	中度降低（風格一致）	間接降低（文件可讀性）
風險等級	低（新建模組不影響現有）	高（修改現有能運作的程式碼）	低（不涉及程式邏輯）

一個重要觀察：第二階段的風險最高。第一階段是「加法」（新增模組），第三階段是「非程式碼」（文件調整），而第二階段是「改動現有程式碼」。這正是 IMP-003 發生的背景。

重構的風險不取決於修改的「量」，而取決於修改的「性質」。W24 的每個修改都很小（移動一行 logger = ...），但每個修改都觸及了 Python 作用域這個容易被忽略的基礎機制。

教訓

重構是持續過程，不是一次性事件

v0.28.0 做完時，我們以為重構結束了。結果 v0.31.0 又花了四個 Wave 處理品質問題，後面還有系統級的調整。

程式碼會自然退化。每次新增功能、修復 bug、趕進度，都可能引入新的技術債務。重構不是「做完就好」的專案，而是持續進行的衛生習慣——就像每天刷牙，不是做一次根管治療就可以不刷了。

Error Patterns 是知識累積

五個 Error Patterns（ARCH-001、IMP-001、IMP-002、IMP-003、IMP-005）不只是問題記錄。它們是團隊的「免疫記憶」：

ARCH-001（硬編碼配置）→ 以後新增配置時，自動想到用 YAML
IMP-001（重複程式碼）→ 發現重複時，自動想到抽取模組
IMP-002（魔法數字）→ 看到裸數字時，自動想到具名常數
IMP-003（作用域迴歸）→ 移動變數定義時，自動想到影響範圍分析
IMP-005（模組遷移後 Import 路徑未同步更新）→ 搬移模組時，自動想到掃描所有引用點

每個 Error Pattern 都有明確的結構：觸發條件、根本原因、檢查清單、防護措施。新成員不需要親身經歷這些事故，讀文件就能獲得防護。這比「口耳相傳」可靠得多——口頭經驗會隨著人員流動而消失，文件化的 Error Pattern 是永久的。

Wave 是安全網

把大型重構拆成 Wave 的好處：

獨立驗證：每個 Wave 結束時都跑完整測試，確認沒改壞東西
可回滾：如果 Wave 3 出問題，Wave 1 和 2 的成果不受影響
認知管理：每次只需要理解一個 Wave 的範圍，不需要在腦中同時處理所有修改
進度可見：每完成一個 Wave 就有具體的交付物，而不是「重構了三天但還沒完成」

Wave 2（配置分離）如果和 Wave 3（逐檔重構）合併，認知負擔會超過上限——需要同時思考「配置怎麼設計」和「Hook 怎麼改」。拆開後每次只需要想一件事。

反過來說，Wave 也防止了「過度設計」。如果一開始就試圖設計完美的共用程式庫，可能會花太多時間在抽象設計上。Wave 1 先建立「夠用」的模組，Wave 3 在實際使用時再調整介面。實踐中的回饋比預先設計更可靠。

風格統一比結構重構危險

第一階段（結構重構）幾乎沒有事故。第二階段（風格統一）出了 IMP-003。

原因是：結構重構主要是「加法」——建立新模組、新測試。現有程式碼的修改量小，改壞的機率低。而風格統一是在「改動能運作的程式碼」，每一行修改都可能引入迴歸。

如果重來，W24 的做法會改成：

先寫自動化腳本做 AST 分析，列出每個 Hook 的所有 logger 引用關係
用腳本自動修改函式簽名和呼叫端，而不是手動逐檔改
修改後立刻對每個 Hook 做隔離測試，不是改完全部再測
每改完一個 Hook 就提交一次，而不是改完全部再提交

這些改善措施的共同主題是：縮小每次改動的影響範圍。一次改一個 Hook 比一次改 16 個 Hook 安全得多。

章節知識地圖

本模組各章對應到重構過程的哪個環節：

章節	對應的壞味道	對應的階段	核心技能
重構的動機與策略	全部	起點（為什麼重構）	認知負擔量化、階段分解
程式碼壞味道識別	所有	起點（識別問題）	grep 分析、5 Why
DRY 原則與共用程式庫	IMP-001	第一階段 W1	模組抽取、介面設計
配置分離與常數管理	IMP-002, ARCH-001	第一階段 W2 + 第二階段 W23	三種硬編碼的系統性消除
大規模統一化重構	IMP-001, ARCH-001	第二階段 W22-W24	三階段統一化、漸進式重構
重構陷阱與防護	IMP-003, IMP-005	第二階段 W24-W25	部分更新防護、AST 驗證
作用域迴歸案例研究	IMP-003	第二階段 W24	AST 分析、作用域規則
非程式碼的重構	文件壞味道	第三階段 W9	Progressive Disclosure、文件精簡
本章（完整案例回顧）	全部	全部	系統性思考、Wave 規劃

每一章都可以獨立閱讀，但它們來自同一個持續演進的真實專案。單獨學會「怎麼消除魔法數字」是基礎能力；理解「什麼時候該做、以什麼順序做、做的時候可能出什麼事故」才是重構的完整技能。

重構前後的程式碼對比

用一段典型的程式碼說明三個階段的累積效果：

 1# === 起點：v0.28.0 之前 ===
 2# 直接使用 subprocess，硬編碼分支名稱，魔法數字
 3result = subprocess.run(
 4    ["git", "branch", "--show-current"],
 5    capture_output=True, text=True
 6)
 7branch = result.stdout.strip()
 8if branch in ["main", "master", "develop"]:
 9    print("Error: protected branch")
10    sys.exit(1)
11
12# === 第一階段後：v0.28.0 ===
13# 使用共用模組，但訊息仍硬編碼
14from lib.git_utils import get_current_branch, is_protected_branch
15
16branch = get_current_branch()
17if is_protected_branch(branch):
18    print("Error: protected branch")
19    sys.exit(1)
20
21# === 第二階段後：v0.31.0 ===
22# 訊息集中管理，logger 正確初始化
23from lib.git_utils import get_current_branch, is_protected_branch
24from lib.messages import BranchMessages
25
26def check_branch(logger):
27    branch = get_current_branch()
28    if is_protected_branch(branch):
29        logger.warning(BranchMessages.PROTECTED_BRANCH)
30        return EXIT_ERROR
31    return EXIT_SUCCESS
32
33def main():
34    logger = setup_hook_logging("branch-verify")
35    return check_branch(logger)

認知負擔的變化：

版本	需要同時理解的概念	認知負擔指數
起點	subprocess API、Git 命令語法、分支名稱列表、退出碼	8
第一階段後	共用函式名稱、退出碼	4
第二階段後	共用函式名稱、訊息常數名稱	3

每一階段都在降低閱讀者需要同時記住的東西。這就是序章的認知負擔理論在實踐中的應用。

小結

回顧整個過程，重構的節奏是：

先解決最痛的問題（第一階段：重複和膨脹）
再提升內部品質（第二階段：風格和一致性）
最後建立保護機制（第三階段：系統級防護）

每個階段都需要前一個階段的基礎。沒有共用模組就無法統一風格，沒有統一風格就無法做一致性審查。

而貫穿三個階段的不變原則只有一個：這段程式碼讓讀者需要同時記住多少東西？ 如果太多，就需要重構。不管是 858 行的單檔、散落各處的錯誤訊息、還是膨脹到 600 行的文件——認知負擔就是重構的指北針。

上一章：非程式碼的重構

回到模組總覽：模組七：重構實戰