Clean Architecture on Tarragon

4.1 事件來源、處理流程與狀態邊界

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

事件系統的核心邊界是把「收到訊號」、「轉成事件」、「套用規則」、「更新狀態」與「輸出結果」拆開。每個邊界都應該有自己的型別與測試，否則一個 handler 或 worker 很快就會同時負責協定、驗證、去重、狀態與推送。

本章目標

學完本章後，你將能夠：

分辨 event source、normalizer、processor、repository、publisher 的責任
用 Go interface 表達元件能力，而不是表達資料夾模板
把外部格式限制在 adapter 內
讓狀態更新集中到 repository 或 state owner
用測試驗證每個邊界是否可替換

【觀察】事件流程容易被寫成一團

事件流程膨脹的常見原因是入口程式碼太方便。HTTP handler 可以 decode JSON、驗證欄位、查 map、送通知；worker 也可以讀 queue、判斷重複、更新狀態、寫 log。短期看起來直接，長期會讓每個入口都複製一套規則。

反模式示意：

 1func handleCallback(w http.ResponseWriter, r *http.Request) {
 2    var raw CallbackPayload
 3    json.NewDecoder(r.Body).Decode(&raw)
 4
 5    if raw.ID == "" {
 6        http.Error(w, "missing id", http.StatusBadRequest)
 7        return
 8    }
 9
10    if seen[raw.ID] {
11        w.WriteHeader(http.StatusNoContent)
12        return
13    }
14
15    seen[raw.ID] = true
16    states[raw.AccountID] = "active"
17    hub.Broadcast(raw.AccountID, "active")
18}

這段程式的問題是責任混在一起。HTTP 協定、輸入格式、去重策略、狀態更新與推送規則都被綁在同一個函式，任何一項改變都會影響整個入口。

【判讀】事件邊界應該按照責任切開

事件邊界的核心規則是每一層只知道自己必須知道的資訊。adapter 知道外部協定，normalizer 知道格式轉換，processor 知道事件規則，repository 知道狀態保存，publisher 知道輸出方式。

一個可維護的事件流程可以長這樣：

 1HTTP / queue / timer
 2        │
 3        ▼
 4    adapter
 5        │ raw input
 6        ▼
 7   normalizer
 8        │ DomainEvent
 9        ▼
10   processor
11        │
12        ├── deduper
13        ├── repository
14        └── publisher

這是依賴方向的要求。外部來源依賴內部事件模型；內部處理流程不依賴外部 raw payload。

【策略】先定義內部事件模型

內部事件模型的核心責任是提供穩定語意。不同來源可以有不同欄位名稱與時間格式，但進入 processor 前都應轉成同一種事件。

 1type EventType string
 2
 3const (
 4    EventNotificationCreated EventType = "notification.created"
 5    EventAccountActivated    EventType = "account.activated"
 6    EventJobFinished         EventType = "job.finished"
 7)
 8
 9type EventSource string
10
11const (
12    SourceHTTPCallback EventSource = "http_callback"
13    SourceQueue        EventSource = "queue"
14    SourceTimer        EventSource = "timer"
15)
16
17type DomainEvent struct {
18    ID         string
19    Source     EventSource
20    Type       EventType
21    SubjectID  string
22    OccurredAt time.Time
23    ReceivedAt time.Time
24    Payload    json.RawMessage
25}

OccurredAt 是事件發生時間，ReceivedAt 是系統收到時間。這兩個欄位要分開，因為外部事件可能延遲送達；去重與排序通常看事件語意時間，操作監控通常看收到時間。

【執行】adapter 只負責外部格式

adapter 的核心責任是把外部輸入轉成內部事件或 command。它可以知道 JSON tag、HTTP status、queue ack、header，但不應直接修改狀態。

 1type CallbackPayload struct {
 2    EventID   string `json:"event_id"`
 3    AccountID string `json:"account_id"`
 4    EventName string `json:"event_name"`
 5    Timestamp string `json:"timestamp"`
 6}
 7
 8type CallbackHandler struct {
 9    processor *EventProcessor
10    now       func() time.Time
11}
12
13func (h CallbackHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
14    var payload CallbackPayload
15    if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
16        writeError(w, http.StatusBadRequest, "invalid_json")
17        return
18    }
19
20    event, err := NormalizeCallback(payload, h.now())
21    if err != nil {
22        writeError(w, http.StatusBadRequest, "invalid_event")
23        return
24    }
25
26    if err := h.processor.Process(r.Context(), event); err != nil {
27        writeError(w, http.StatusInternalServerError, "process_event_failed")
28        return
29    }
30
31    w.WriteHeader(http.StatusAccepted)
32}

handler 的測試應該檢查 HTTP 行為與 normalize 錯誤對應。事件規則的測試不應透過 HTTP handler 才能執行，否則 processor 的變化會被協定細節干擾。

【執行】normalizer 負責轉換與基本合約

normalizer 的核心責任是把 raw input 轉成 DomainEvent，並拒絕語意不完整的資料。它是外部世界與內部模型的邊界。

 1func NormalizeCallback(raw CallbackPayload, receivedAt time.Time) (DomainEvent, error) {
 2    occurredAt, err := time.Parse(time.RFC3339, raw.Timestamp)
 3    if err != nil {
 4        return DomainEvent{}, fmt.Errorf("parse timestamp: %w", err)
 5    }
 6
 7    event := DomainEvent{
 8        ID:         strings.TrimSpace(raw.EventID),
 9        Source:     SourceHTTPCallback,
10        Type:       mapCallbackEventName(raw.EventName),
11        SubjectID:  strings.TrimSpace(raw.AccountID),
12        OccurredAt: occurredAt,
13        ReceivedAt: receivedAt,
14    }
15
16    if err := event.Validate(); err != nil {
17        return DomainEvent{}, err
18    }
19    return event, nil
20}
21
22func (e DomainEvent) Validate() error {
23    if e.ID == "" {
24        return fmt.Errorf("event id is required")
25    }
26    if e.Type == "" {
27        return fmt.Errorf("event type is required")
28    }
29    if e.SubjectID == "" {
30        return fmt.Errorf("subject id is required")
31    }
32    if e.OccurredAt.IsZero() {
33        return fmt.Errorf("occurred at is required")
34    }
35    if e.ReceivedAt.IsZero() {
36        return fmt.Errorf("received at is required")
37    }
38    return nil
39}

validation 應該保護 envelope 的必要欄位。更細的 payload 規則可以放在特定事件的 normalizer 或 processor，避免 Validate 變成所有事件的巨大規則表。

【執行】processor 負責事件規則

processor 的核心責任是套用內部事件規則。它可以驗證、去重、更新狀態、寫入事件紀錄、呼叫 publisher，但不應知道 HTTP body 或 queue message 的原始格式。

 1type EventRepository interface {
 2    Apply(ctx context.Context, event DomainEvent) error
 3}
 4
 5type Deduper interface {
 6    Seen(ctx context.Context, event DomainEvent) (bool, error)
 7}
 8
 9type Publisher interface {
10    Publish(ctx context.Context, event DomainEvent) error
11}
12
13type EventProcessor struct {
14    deduper    Deduper
15    repository EventRepository
16    publisher  Publisher
17}
18
19func (p *EventProcessor) Process(ctx context.Context, event DomainEvent) error {
20    if err := event.Validate(); err != nil {
21        return err
22    }
23
24    duplicated, err := p.deduper.Seen(ctx, event)
25    if err != nil {
26        return fmt.Errorf("dedup event: %w", err)
27    }
28    if duplicated {
29        return nil
30    }
31
32    if err := p.repository.Apply(ctx, event); err != nil {
33        return fmt.Errorf("apply event: %w", err)
34    }
35
36    if err := p.publisher.Publish(ctx, event); err != nil {
37        return fmt.Errorf("publish event: %w", err)
38    }
39
40    return nil
41}

這個 processor 依賴能力介面，不依賴具體實作。Go 的 implicit interface 讓 memory repository、database repository 或測試 fake 都可以自然接上。

【判讀】publisher 失敗策略必須明確

publisher 的核心問題是「輸出失敗是否影響狀態成功」。即時通知、審計紀錄、外部 webhook 的可靠性要求不同，不能一律用同一個錯誤策略。

常見策略：

輸出類型	失敗策略	適用情境
即時 UI 推送	記錄錯誤，可允許狀態已更新	客戶端可重新查詢最新狀態
事件紀錄	失敗時中止流程	紀錄是不可遺失的資料
外部 webhook	寫入 outbox，稍後重試	下游需要可靠接收

若 repository.Apply 成功但 publisher.Publish 失敗，系統必須知道這是可接受的降級，還是需要重試與補償。這個決策應該寫在 processor 或 usecase 的設計裡，不應藏在 publisher implementation。

【測試】每個邊界分開測

事件邊界的測試目標是讓錯誤定位清楚。normalizer 測 raw input 轉換，processor 測規則順序，repository 測狀態一致性，publisher 測輸出協定。

processor fake test 範例：

 1func TestProcessorSkipsDuplicateEvent(t *testing.T) {
 2    processor := EventProcessor{
 3        deduper:    fakeDeduper{duplicated: true},
 4        repository: &fakeRepository{},
 5        publisher:  &fakePublisher{},
 6    }
 7
 8    err := processor.Process(context.Background(), DomainEvent{
 9        ID:         "evt_1",
10        Type:       EventAccountActivated,
11        SubjectID:  "acct_1",
12        OccurredAt: time.Now(),
13        ReceivedAt: time.Now(),
14    })
15    if err != nil {
16        t.Fatalf("process event: %v", err)
17    }
18
19    if processor.repository.(*fakeRepository).applied {
20        t.Fatalf("duplicate event should not update repository")
21    }
22}

這種測試不需要 HTTP server。它直接驗證 processor 的規則：重複事件不應更新狀態，也不應送出推送。

本章不處理

本章先處理單一 Go 服務內的事件來源與處理邊界；分散式一致性與 event sourcing，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

事件系統的可維護性來自清楚邊界：adapter 處理外部格式，normalizer 建立內部事件，processor 套用規則，repository 擁有狀態，publisher 輸出結果。當每個元件只承擔一種責任時，新增來源、新增事件或替換儲存實作都會變成局部修改。

4.3 Source of Truth：狀態邊界

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

Source of truth 的核心原則是系統中只有一個地方負責判定目前狀態。其他元件可以請求更新、讀取快照或訂閱變化，但不能各自保存一份會被當成真相的資料。

本章目標

學完本章後，你將能夠：

判斷狀態真相應該由哪個元件擁有
把狀態轉移集中在 repository 或 state owner
同步更新 current state 與 history
用 copy boundary 保護 slice、map、pointer
分辨 internal state、projection 與 response view

【觀察】狀態分散會讓系統失去真相

狀態分散的核心風險是每個元件都以為自己看到的是最新資料。handler 可能有 map，worker 可能有 cache，publisher 可能有最後推送狀態；當三者不一致時，系統很難回答「現在到底是什麼狀態」。

反模式示意：

1var handlerStates = map[string]string{}
2var workerStates = map[string]string{}
3var publisherLastSent = map[string]string{}

這三份資料可能都叫做 state，但只有一份應該是 source of truth。其他資料如果存在，應該明確標示為 cache、projection 或 delivery record，不能被當成狀態判斷依據。

【判讀】source of truth 是寫入權責

source of truth 的核心不是「資料存在哪裡」，而是「誰有權決定狀態如何轉移」。memory map、SQLite、PostgreSQL、Redis 都可以承擔儲存；真正的邊界是所有寫入都經過同一組規則。

 1type AccountStatus string
 2
 3const (
 4    AccountPending AccountStatus = "pending"
 5    AccountActive  AccountStatus = "active"
 6    AccountBlocked AccountStatus = "blocked"
 7)
 8
 9type AccountState struct {
10    ID        string
11    Status    AccountStatus
12    UpdatedAt time.Time
13}

AccountState 是 domain 狀態，不是 HTTP response。它應該表達系統內部真正需要維護的資料，而不是直接迎合某個 API 的輸出格式。

【策略】用明確方法集中狀態轉移

狀態轉移的核心規則是呼叫端不能直接改欄位。外部元件應該送進事件或 command，由 state owner 決定是否合法、如何更新、是否記錄 history。

 1type StateRepository struct {
 2    mu      sync.RWMutex
 3    records map[string]AccountRecord
 4}
 5
 6type AccountRecord struct {
 7    Current AccountState
 8    History []AccountState
 9}
10
11func NewStateRepository() *StateRepository {
12    return &StateRepository{
13        records: make(map[string]AccountRecord),
14    }
15}

repository 擁有 records map。其他元件不應取得這個 map 的 reference，也不應繞過 repository 修改狀態。

【執行】Apply 把事件轉成狀態變化

Apply 的核心責任是把 domain event 套用到 state。它是事件系統與狀態系統的交界。

 1func (r *StateRepository) Apply(ctx context.Context, event DomainEvent) error {
 2    r.mu.Lock()
 3    defer r.mu.Unlock()
 4
 5    record := r.records[event.SubjectID]
 6    next, err := transition(record.Current, event)
 7    if err != nil {
 8        return err
 9    }
10
11    record.Current = next
12    record.History = append(record.History, next)
13    r.records[event.SubjectID] = record
14
15    return nil
16}

這段程式在同一個 lock 內更新 current 與 history。讀者可以相信目前狀態與歷史紀錄來自同一筆事件，不會出現 current 已更新但 history 漏記的情境。

transition 可以是純函式：

 1func transition(current AccountState, event DomainEvent) (AccountState, error) {
 2    switch event.Type {
 3    case EventAccountActivated:
 4        return AccountState{
 5            ID:        event.SubjectID,
 6            Status:    AccountActive,
 7            UpdatedAt: event.OccurredAt,
 8        }, nil
 9    default:
10        return AccountState{}, fmt.Errorf("unsupported event type: %s", event.Type)
11    }
12}

純函式讓狀態規則更容易測試。repository 負責 concurrency 與保存，transition 負責 domain 規則。

【判讀】current、history、projection 是不同資料

狀態資料的核心分類是 internal state、history 與 projection。三者用途不同，不應混成同一個 struct 到處傳。

類型	角色	範例
internal state	系統判斷真相的資料	`AccountState`
history	狀態變化紀錄	`[]AccountState`
projection	查詢或 UI 需要的讀取模型	`AccountSummary`
response view	特定 API 的輸出格式	`accountResponse`

projection 可以從 state 與 history 組出來，但 projection 不應反過來成為狀態真相。API 需要新增欄位時，優先新增 response view 或 projection，不要直接污染 internal state。

【執行】查詢要回傳 copy

copy boundary 的核心目標是防止呼叫端修改 repository 內部資料。Go 的 slice、map、pointer 都可能讓內部狀態外洩。

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

AccountState 目前只有值型別欄位，直接回傳值即可。history 是 slice，必須複製：

1func (r *StateRepository) History(ctx context.Context, id string) ([]AccountState, error) {
2    r.mu.RLock()
3    defer r.mu.RUnlock()
4
5    history := r.records[id].History
6    result := make([]AccountState, len(history))
7    copy(result, history)
8    return result, nil
9}

若 state 內含 map、slice 或 pointer，還需要 deep copy。copy 有成本，但它是狀態邊界的保護；資料量大時應用分頁或 projection，不應直接暴露內部 slice。

【策略】projection 讓查詢需求不污染狀態

projection 的核心用途是服務讀取需求。列表頁、儀表板、即時推送可能需要不同欄位，這些需求不應全部塞進 domain state。

 1type AccountSummary struct {
 2    ID              string
 3    Status          AccountStatus
 4    LastChangedAt   time.Time
 5    HistoryCount    int
 6}
 7
 8func (r *StateRepository) Summary(ctx context.Context, id string) (AccountSummary, bool, error) {
 9    r.mu.RLock()
10    defer r.mu.RUnlock()
11
12    record, ok := r.records[id]
13    if !ok {
14        return AccountSummary{}, false, nil
15    }
16
17    return AccountSummary{
18        ID:            record.Current.ID,
19        Status:        record.Current.Status,
20        LastChangedAt: record.Current.UpdatedAt,
21        HistoryCount:  len(record.History),
22    }, true, nil
23}

projection 可以由 repository 即時計算，也可以由背景 worker 預先維護。選擇哪一種取決於讀取量、資料量與一致性要求；小型服務先即時計算通常更容易理解。

【判讀】mutex 與單一 goroutine 都能成為 state owner

狀態擁有權的核心要求是同一時間只有受控路徑能修改資料。mutex 是常見選擇，單一 goroutine 擁有 state 也是 Go 常見模式。

mutex 版本適合直接方法呼叫：

1repository.Apply(ctx, event)

單一 goroutine 版本適合事件流：

1type stateCommand struct {
2    event DomainEvent
3    reply chan error
4}

兩者都可以正確。選擇 mutex 時要小心 copy boundary；選擇 goroutine owner 時要設計 shutdown、reply channel 與 backpressure。不要為了使用 channel 而使用 channel，狀態模型簡單時 mutex 通常更直接。

【測試】狀態測試要覆蓋轉移與外洩

狀態邊界的測試目標是確認轉移一致、history 同步、呼叫端不能修改內部資料。

 1func TestHistoryReturnsCopy(t *testing.T) {
 2    repo := NewStateRepository()
 3    event := DomainEvent{
 4        ID:         "evt_1",
 5        Type:       EventAccountActivated,
 6        SubjectID:  "acct_1",
 7        OccurredAt: time.Now(),
 8        ReceivedAt: time.Now(),
 9    }
10
11    if err := repo.Apply(context.Background(), event); err != nil {
12        t.Fatalf("apply event: %v", err)
13    }
14
15    history, err := repo.History(context.Background(), "acct_1")
16    if err != nil {
17        t.Fatalf("history: %v", err)
18    }
19    history[0].Status = AccountBlocked
20
21    again, err := repo.History(context.Background(), "acct_1")
22    if err != nil {
23        t.Fatalf("history again: %v", err)
24    }
25    if again[0].Status != AccountActive {
26        t.Fatalf("repository state was modified through returned history")
27    }
28}

這個測試檢查的是邊界，不只是結果值。對 Go 服務來說，防止 slice/map 外洩是狀態設計的重要一環。

本章不處理

本章先處理單一服務內誰有寫入權責；資料庫 migration 與 CQRS，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

Source of truth 是寫入權責，不是某個特定資料庫。狀態轉移應集中在 repository 或 state owner，current 與 history 要在同一邊界更新，查詢要回傳 copy 或 projection。當狀態真相清楚時，handler、worker、publisher 都能保持簡單，系統也能更容易加入資料庫或新的讀取模型。

模組四：架構邊界與事件系統

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

架構邊界的核心目標是讓每個元件只承擔一種責任。事件來源負責接收外部訊號，normalize 階段負責轉成內部事件，processor 負責套用規則，repository 負責保存狀態真相，publisher 負責把結果送出去。

事件驅動不是把所有東西都丟進 channel。Go 的事件系統需要明確的型別、清楚的擁有者、可測的狀態轉移，以及能在多來源輸入下維持一致的處理流程。

本模組承接入門篇的 practical 與 refactoring：前面學會新增事件、建立 repository port、拆 handler、整理 domain package；這裡進一步處理「系統開始變大後，事件與狀態如何不失控」。

章節列表

章節	主題	關鍵收穫
4.1	事件來源、處理流程與狀態邊界	用邊界拆開 reader、normalizer、processor、repository、publisher
4.2	事件去重與語義鍵設計	用 domain key、時間窗口與清理策略管理重複事件
4.3	Source of Truth：狀態邊界	集中狀態轉移、保護可變資料、設計 projection
4.4	多來源 event 融合	把 HTTP、queue、timer 等來源收斂到同一套 domain event 流程

本模組使用的範例主題

本模組使用虛構的通知與工作處理服務作為範例。服務可能從 HTTP callback、queue message、timer 或檔案 reader 收到事件，最後更新內部狀態並推送通知。

範例只用來展示 Go 的設計方法，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

用 struct 定義穩定的內部事件模型。
用 interface 表達 reader、repository、publisher 這類能力。
用 context 傳遞 request lifecycle、取消與逾時。
用 mutex 或單一 goroutine 保護共享狀態。
用 package 邊界限制 adapter、application、domain 的依賴方向。
用 table-driven test 驗證 normalize、dedup 與狀態轉移。

學習重點

學完本模組後，你應該能判斷：

外部訊號是否應該轉成 domain event
去重應該使用哪些欄位，哪些欄位不應進入 key
狀態真相應該由哪個元件擁有
新事件來源應該新增 adapter，還是修改 processor
ports/adapters 與 event-driven service 如何在 Go 中自然結合

章節粒度說明

本模組的四章分別處理事件系統的四個核心面向，不建議硬拆成更小的孤立段落。事件來源、去重、狀態真相與多來源融合會互相影響；拆得太碎會讓讀者看不到一筆事件如何從外部輸入走到狀態更新與推送。

閱讀時可以把四章視為一條路線：

事件來源、處理流程與狀態邊界：先建立元件分工。
事件去重與語義鍵設計：再定義「同一事件」的語意。
Source of Truth：狀態邊界：接著決定誰能改狀態。
多來源 event 融合：最後處理 HTTP、queue、timer 等多入口協作。

本模組不處理

本模組不實作完整 message queue、分散式 transaction 或 event sourcing 平台。這些主題需要更多基礎設施與操作細節；本模組先聚焦 Go 程式內部如何建立清楚的事件與狀態邊界。後續可接資料庫 transaction 與 schema migration 以及 Durable queue、outbox 與 idempotency。

BDD 測試方法論

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

三個月的重構週期結束後，我們檢視了測試套件，發現一個令人沮喪的問題：每次修改內部實作，即使業務邏輯完全沒變，也需要跟著修改大量測試。一個 Repository 實作替換，導致二十幾個測試需要逐一調整。

這不是測試該有的樣子。問題根源在於測試耦合了實作細節，而非行為。

BDD 的核心定位

BDD 是 TDD 的演進，它要求測試描述系統的「行為」而非「實作」。

行為是使用者視角觀察到的系統反應；實作是程式內部的技術細節。這個區別看起來簡單，實際撰寫測試時卻很容易模糊。

BDD 解決三個問題：

測試維護成本高。傳統單元測試緊密耦合實作細節，重構時即使行為沒變，測試仍需大量修改。BDD 讓重構時測試保持穩定。

需求追溯困難。測試充滿技術細節，無法對應業務需求。Given-When-Then 場景即是需求文件，測試即規格。

溝通成本高。開發、測試和業務人員用不同語言描述系統行為。BDD 統一使用業務語言，建立共通溝通基礎。

我們的分工是：Clean Architecture 定義架構分層，TDD 四階段流程定義開發節奏，BDD 定義測試內容和撰寫規範。

Given-When-Then 結構

Given 描述系統的初始狀態，必須明確完整，只包含與此場景相關的資料。常見錯誤是前置條件模糊，或包含大量無關測試資料。

When 描述使用者執行的操作，必須是單一動作，使用業務語言。「呼叫 Repository 的 save 方法」是技術術語；「使用者提交訂單」是業務語言。一個 When 不能包含多個動作。

Then 描述執行後的狀態變化或結果，必須是可觀察的行為。「Repository 的 save 方法被呼叫一次」是實作細節；「訂單成功儲存並回傳訂單編號」是可觀察的行為。

判斷行為還是實作的方法很簡單：使用者能否觀察到？改變實作會影響這個結果嗎？產品經理需要關心嗎？都是「能觀察、不影響、需要關心」就是行為，反之是實作細節。

行為測試和實作測試的差異

測試實作：

1test('OrderRepository.save should call database.insert', () {
2  repository.save(order);
3  verify(database.insert('orders', order.toJson()));
4});

這個測試關注「如何儲存」，替換資料庫或重構儲存邏輯就會失敗。

測試行為：

 1test('使用者提交訂單 - 訂單成功儲存', () async {
 2  // Given: 使用者已選擇商品並填寫完整資訊
 3  final order = validOrder;
 4
 5  // When: 使用者提交訂單
 6  final result = await submitOrderUseCase.execute(order);
 7
 8  // Then: 系統確認訂單已儲存
 9  expect(result.isSuccess, true);
10  expect(result.orderId, isNotEmpty);
11});

這個測試關注「訂單是否成功儲存」，重構儲存機制不會影響結果。

測試描述的視角同樣重要。從技術元件角度：

1test('當 Repository 回傳 null 時 UseCase 拋出例外', () { ... });

從使用者視角：

1test('使用者提交訂單失敗 - 商品庫存不足', () {
2  // Given: 商品庫存為 0
3  // When: 使用者嘗試提交訂單
4  // Then: 系統回應「庫存不足」錯誤
5});

分層測試策略

BDD 不適用所有架構層級，每層特性不同，測試策略也不同。

UseCase 層是 BDD 的核心應用層，代表完整的使用者操作流程，必須使用 Given-When-Then 結構，涵蓋所有業務場景。

Domain 層包含核心業務規則、值物件驗證和實體不變量，需要細緻的邊界條件測試，單元測試更適合。

Behavior 層負責 ViewModel 轉換和事件處理，只有複雜轉換邏輯需要獨立測試，簡單轉換由 UseCase 層覆蓋即可。

UI 層測試成本高，只測試關鍵互動路徑，使用整合測試。

Interface 層只定義契約，沒有實作邏輯，不需要測試。

Mock 策略

核心原則：只 Mock 外層依賴，不 Mock 內層邏輯。

外層依賴（Repository、Service、Event Publisher）透過 Interface 進行 Mock，隔離外部系統。內層邏輯（Domain Entity、Value Object）必須使用真實物件，確保測試涵蓋真實業務邏輯。

正確寫法：

 1test('使用者提交訂單成功', () async {
 2  // Mock Repository（外層依賴）
 3  final mockRepository = MockOrderRepository();
 4  when(mockRepository.save(any))
 5      .thenAnswer((_) async => SaveResult.success('order-123'));
 6
 7  // 使用真實的 Domain Entity（內層邏輯）
 8  final order = Order(
 9    amount: OrderAmount(100),
10    userId: UserId('user-001'),
11  );
12
13  final useCase = SubmitOrderUseCase(repository: mockRepository);
14  final result = await useCase.execute(order);
15
16  expect(result.isSuccess, true);
17  expect(result.orderId, 'order-123');
18});

錯誤寫法是 Mock Domain Entity：

1test('使用者提交訂單成功', () {
2  final mockOrder = MockOrder();
3  when(mockOrder.validate()).thenReturn(true);
4  // 沒有測試到任何真實業務邏輯
5});

與 TDD 階段整合

階段一（功能設計）：從需求識別使用者行為場景。「使用者可以提交訂單」需要提取多個場景：成功提交、庫存不足失敗、金額無效失敗等，每個場景涵蓋正常流程、異常流程和邊界條件。

階段二（測試設計）：將行為場景轉換為可執行的測試程式碼，先建立結構，設置 Mock，再依 Given-When-Then 填入邏輯。

階段三（實作策略）：測試先行。先完成所有測試場景並確認失敗（Red），才開始實作 UseCase 讓測試通過（Green）。

階段四（重構優化）：重構時，行為測試必須保持穩定。重構導致測試需要修改，代表測試耦合了實作。

判斷重構品質的標準很清楚：替換 Repository 實作、改變演算法，不應讓測試失敗；改變業務規則、調整可觀察的錯誤訊息，才應讓測試失敗。

常見挑戰

測試覆蓋率盲點

BDD 強調測試「重要行為」，可能讓某些程式碼未被覆蓋。混合策略解決這個問題：UseCase 層 100% BDD 測試，Domain 層複雜邏輯 100% 單元測試，整體維持 80% 程式碼覆蓋率目標。

學習曲線

從「測試實作」轉向「測試行為」需要思維轉換，初期容易寫出「假行為測試」（實際上還是在測試實作）。建立範例庫和測試模板很有幫助：

 1test('[業務場景描述] - 成功', () async {
 2  // Given: [前置條件]
 3  final input = [準備測試資料];
 4  [設置 Mock 行為];
 5
 6  // When: [觸發動作]
 7  final result = await useCase.execute(input);
 8
 9  // Then: [預期結果]
10  expect(result.isSuccess, true);
11  expect([驗證業務結果]);
12});

邊界條件容易被忽略

業務場景描述容易遺漏技術性的邊界條件（null、異常、極端值）。每個 UseCase 最少需要：一個正常流程、兩個異常流程、三個邊界條件。建立技術性測試檢查清單並在 Code Review 重點確認。

測試設置複雜度

UseCase 層的 BDD 測試需要 Mock 多個依賴，建立 Test Helper 和 Builder Pattern 減少重複：

 1class UseCaseTestHelper {
 2  static MockOrderRepository createMockRepository({
 3    required SaveResult saveResult,
 4  }) {
 5    final mock = MockOrderRepository();
 6    when(mock.save(any)).thenAnswer((_) async => saveResult);
 7    return mock;
 8  }
 9}
10
11class OrderBuilder {
12  int _amount = 100;
13  String _userId = 'user-001';
14
15  OrderBuilder withAmount(int amount) {
16    _amount = amount;
17    return this;
18  }
19
20  Order build() => Order(
21    amount: OrderAmount(_amount),
22    userId: UserId(_userId),
23  );
24}

行為粒度

粒度太粗，失敗時難以定位；太細則接近單元測試，失去 BDD 優勢。採用「一個 UseCase 等於一個核心行為」的原則：UseCase 代表完整業務流程，名稱以動詞開頭（Submit, Cancel, Query），所有測試場景屬於同一個業務流程。

業務需求變更

需求變更時測試場景仍需更新。集中管理業務規則常數減少影響範圍：

1class OrderBusinessRules {
2  static const int freeShippingThreshold = 1000;
3  static const int maxOrderAmount = 100000;
4  static const int minOrderAmount = 1;
5}

完整範例

以「使用者提交訂單」為例：

  1group('SubmitOrderUseCase', () {
  2  late MockOrderRepository mockRepository;
  3  late MockInventoryService mockInventoryService;
  4  late MockEventPublisher mockEventPublisher;
  5  late SubmitOrderUseCase useCase;
  6
  7  setUp(() {
  8    mockRepository = MockOrderRepository();
  9    mockInventoryService = MockInventoryService();
 10    mockEventPublisher = MockEventPublisher();
 11    useCase = SubmitOrderUseCase(
 12      repository: mockRepository,
 13      inventoryService: mockInventoryService,
 14      eventPublisher: mockEventPublisher,
 15    );
 16  });
 17
 18  group('正常流程', () {
 19    test('使用者提交訂單成功', () async {
 20      // Given: 使用者已選擇商品且填寫完整資訊
 21      final order = Order(
 22        amount: OrderAmount(100),
 23        userId: UserId('user-001'),
 24        items: [OrderItem(productId: 'prod-001', quantity: 2)],
 25        shippingAddress: Address(city: '台北市', district: '信義區'),
 26      );
 27      when(mockInventoryService.checkStock('prod-001'))
 28          .thenAnswer((_) async => StockStatus.available);
 29      when(mockRepository.save(any))
 30          .thenAnswer((_) async => SaveResult.success('order-123'));
 31
 32      // When: 使用者點擊「提交訂單」
 33      final result = await useCase.execute(order);
 34
 35      // Then: 系統確認訂單已儲存並回傳訂單編號
 36      expect(result.isSuccess, true);
 37      expect(result.orderId, 'order-123');
 38      verify(mockEventPublisher.publish(any.having(
 39        (e) => e.type, 'event type', EventType.orderCreated,
 40      ))).called(1);
 41    });
 42  });
 43
 44  group('異常流程', () {
 45    test('使用者提交訂單失敗 - 商品庫存不足', () async {
 46      // Given: 選擇的商品庫存為 0
 47      final order = Order(
 48        amount: OrderAmount(100),
 49        userId: UserId('user-001'),
 50        items: [OrderItem(productId: 'prod-001', quantity: 2)],
 51      );
 52      when(mockInventoryService.checkStock('prod-001'))
 53          .thenAnswer((_) async => StockStatus.outOfStock);
 54
 55      // When: 使用者點擊「提交訂單」
 56      final result = await useCase.execute(order);
 57
 58      // Then: 系統回應庫存不足錯誤，不儲存訂單
 59      expect(result.isSuccess, false);
 60      expect(result.error, ErrorType.outOfStock);
 61      verifyNever(mockRepository.save(any));
 62    });
 63
 64    test('使用者提交訂單失敗 - Repository 儲存失敗', () async {
 65      // Given: Repository 無法儲存（網路錯誤）
 66      final order = Order(
 67        amount: OrderAmount(100),
 68        userId: UserId('user-001'),
 69        items: [OrderItem(productId: 'prod-001', quantity: 1)],
 70      );
 71      when(mockInventoryService.checkStock(any))
 72          .thenAnswer((_) async => StockStatus.available);
 73      when(mockRepository.save(any))
 74          .thenAnswer((_) async => SaveResult.failure('網路連線失敗'));
 75
 76      // When: 使用者點擊「提交訂單」
 77      final result = await useCase.execute(order);
 78
 79      // Then: 系統回應訂單提交失敗
 80      expect(result.isSuccess, false);
 81      expect(result.error, ErrorType.saveFailed);
 82    });
 83  });
 84
 85  group('邊界條件', () {
 86    test('使用者提交訂單失敗 - 訂單金額為 0', () async {
 87      final order = Order(
 88        amount: OrderAmount(0),
 89        userId: UserId('user-001'),
 90        items: [],
 91      );
 92      final result = await useCase.execute(order);
 93      expect(result.isSuccess, false);
 94      expect(result.error, ErrorType.invalidAmount);
 95    });
 96
 97    test('建立負數金額訂單拋出例外', () {
 98      expect(
 99        () => Order(amount: OrderAmount(-100), userId: UserId('user-001')),
100        throwsA(isA<InvalidAmountException>()),
101      );
102    });
103
104    test('使用者提交訂單失敗 - 訂單金額超過上限', () async {
105      final order = Order(
106        amount: OrderAmount(1000001),
107        userId: UserId('user-001'),
108        items: [OrderItem(productId: 'prod-001', quantity: 10000)],
109      );
110      final result = await useCase.execute(order);
111      expect(result.isSuccess, false);
112      expect(result.error, ErrorType.amountExceedsLimit);
113    });
114  });
115});

結論

回頭看最初那個重構週期，二十幾個因為替換 Repository 實作而失敗的測試，問題很清楚：測試在監視實作細節，而不是守護業務行為。

切換到 BDD 之後，同樣的重構只需確認業務行為沒有改變，測試套件就能保持穩定。

但 BDD 不是萬靈丹。它需要思維轉換，需要建立明確規範，需要持續 Code Review 維持品質。混合策略（UseCase 層 BDD、Domain 層單元測試、UI 層整合測試）才能真正發揮效果。

行為優先的TDD方法論 - Sociable Unit Tests實踐指南

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

曾經有一段時間，我們團隊對TDD又愛又恨。「寫測試讓我們更有信心」，但「重構時要改一堆測試，還不如不寫」。這種矛盾讓我們反覆懷疑：TDD到底有沒有用？

深入研究Kent Beck的原著和Valentina Jemuović的演講後，才發現問題出在我們誤解了「測試單元」是什麼。

痛苦的根本原因

許多團隊學TDD時，都被教導「每個class寫一個test class，每個method寫一個test method」。這個看似合理的原則，埋下了長期的痛苦。

問題在於，這樣的測試耦合到了程式的結構，而非行為。只要重構——把一個class拆成兩個、把方法提取到新類別——測試就跟著破裂。維護測試的時間甚至超過寫功能本身。

Kent Beck在《Test Driven Development By Example》第一頁就寫道：

“Programmer tests should be sensitive to behavior changes and insensitive to structure changes.”

測試應該對行為的改變敏感，對結構的改變不敏感。如果重構時測試跟著爆炸，原因就在這裡。

測試是可執行的需求規格

需要先轉換一個根本認知：測試不是「驗證實作正確的工具」，而是用程式碼表達的需求規格書。

需求定義系統「應該做什麼」，實作是「怎麼做」的一種方式。需求應該保持穩定，實作可以隨時改變。Martin Fowler在《Refactoring》中說：

“Refactoring is a way of restructuring an existing body of code, altering its internal structure without changing its external behavior.”

重構改變內部結構，不改變外部行為。耦合到行為的測試，在重構時自然保持穩定。

Sociable Unit Tests：把Module當作測試單元

TDD有兩種截然不同的流派。

Classical TDD（Kent Beck、Martin Fowler的做法）把Unit定義為Module——一個或多個協同工作的類別組合，對外提供清晰的Public API。測試只透過這個Public API互動，不知道Module內部有哪些類別、它們如何協作。唯一需要Mock的是真正的外部依賴：資料庫、檔案系統、外部服務。這種風格稱為Sociable Unit Tests。

Mockist TDD（London School）把Unit定義為單一Class，Mock所有協作者。這種風格稱為Solitary Unit Tests。

核心差異在耦合對象：

1Sociable: Test → [Module API] → Module Implementation（黑盒）
2Solitary: Test → Mock(B) → Class A → Class B
3                 Mock(C)           → Class C

Sociable只有一條耦合線，Solitary有多條。每一條耦合線都是日後的維護成本。

重構安全性的驗證

判斷自己的測試是Sociable還是Solitary，有個簡單的驗證方法：

改變Module的內部邏輯、調整類別結構、重新命名內部方法。如果所有測試依然通過，不需要修改，那你寫的是Sociable（正確）。如果任何測試需要跟著改，那你寫的是Solitary（需要重新設計）。

以一個訂單提交的例子來說，Sociable測試看起來像這樣：

 1test('使用者提交訂單成功', () async {
 2  // Given: Mock外部依賴（只Mock Repository）
 3  when(mockRepository.save(any))
 4      .thenAnswer((_) async => SaveResult.success('order-123'));
 5
 6  // When: 透過Use Case API提交訂單
 7  final result = await submitOrderUseCase.execute(order);
 8
 9  // Then: 驗證可觀察的行為結果
10  expect(result.isSuccess, true);
11  expect(result.orderId, 'order-123');
12  // 測試不知道Order內部如何計算、驗證
13  // 測試使用真實的Domain Entities
14});

而Solitary測試會是：

 1test('OrderService.submitOrder calls Repository.save', () async {
 2  // Given: Mock所有協作者
 3  final mockOrder = MockOrder();          // 連Order也Mock了
 4  final mockValidator = MockOrderValidator();
 5  final mockCalculator = MockPriceCalculator();
 6
 7  when(mockValidator.validate(mockOrder)).thenReturn(true);
 8  when(mockCalculator.calculate(mockOrder)).thenReturn(100);
 9  when(mockRepository.save(mockOrder))
10      .thenAnswer((_) async => SaveResult.success('order-123'));
11
12  // Then: 驗證方法呼叫次數（實作細節）
13  verify(mockRepository.save(mockOrder)).called(1);
14  // 這個測試一旦重構OrderService的內部邏輯就會破裂
15});

Test-First的速度優勢

Test-First（先寫測試）比Test-Last（先寫程式再補測試）快，原因是問題被發現的時間點更早。

Test-First的Red-Green-Refactor循環強迫你在寫實作之前先思考介面：「這個功能怎麼用？」、「測試容不容易寫？」介面設計問題在寫測試時（最早期）就暴露，修復成本最低。

Test-Last則是程式寫完了才發現難以測試，這時通常意味著設計有問題，要改動的範圍更大。Kent Beck說TDD更快，指的正是這個。

BDD不是新方法，是修正命名

Dan North在2006年創造「BDD」，目的是修正TDD命名造成的混淆。

他發現「Test」這個詞讓開發人員誤以為要測試每個類別和方法，於是用「Behavior」取代，讓意圖更清楚：測試的是行為，不是程式結構。這和Kent Beck 2003年說的完全一致，只是換了個能讓人更直覺理解的詞。

Google在《Software Engineering at Google》中也驗證同樣的結論：「Don’t write a test for each method. Write a test for each behavior.」

與Clean Architecture的結合

Sociable Unit Tests和Clean Architecture是天然的組合，因為建立在相同原則上：業務邏輯獨立於外部世界。

在Clean Architecture中，Use Cases層是業務邏輯的進入點，對外提供清晰的API，對內只使用Domain Entities和透過介面隔離的外部依賴（Repository、Gateway等）。這個結構天然對應Sociable的需求：Use Cases的Public API就是測試邊界，Domain Entities用真實物件，只有Repository需要Mock。

更重要的是，對Use Cases的Unit Test同時就是業務驗收測試。一個寫著「使用者提交訂單成功」的案例，不需要啟動UI也不需要真實資料庫，但驗證了完整的業務流程。Alistair Cockburn在提出Hexagonal Architecture時說：「Tests are another user of the system.」

並非所有情況都適合Sociable。數學演算法、加密系統這類需要細粒度驗證的場景，精確定位到具體類別比重構穩定性更重要，用Solitary合理。但大多數商業應用不是這類。

結論

我們曾以為TDD很痛苦，但那是因為我們測試的是程式長什麼樣子，而不是它做什麼。

正確的做法只有一句話：測試透過Module的Public API互動，只Mock真正的外部依賴，使用真實的Domain Entities。

這樣的測試在重構時保持穩定，在功能改變時精準報警。Kent Beck、Dan North、Martin Fowler在不同年代說的是同一件事：測試行為，而非結構。

參考資料：

Kent Beck，《Test Driven Development By Example》，2003
Martin Fowler，《Refactoring: Improving the Design of Existing Code》，1999
Dan North，《Introducing BDD》，2006
Google，《Software Engineering at Google》，2020
Valentina (Cupać) Jemuović，TDD and Clean Architecture - Driven by Behaviour

混合測試策略：根據架構層級選擇測試方法

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

開始實踐 TDD 時，我們遇到一個困惑的問題：什麼都測，還是只測部分？

追求覆蓋率，會寫出大量測試 getter 和直接欄位映射的測試，維護成本高，保護力低。不管覆蓋率，又很難有信心說業務邏輯正確。

答案是：測試策略跟著架構走。

問題的根源

全面單元測試的問題是，重構 ViewModel 內部實作時，大量測試跟著壞掉，但行為根本沒變。全面 BDD 的問題是，Domain 層邊界條件很難透過業務語言的場景完整覆蓋。

不同層級的程式碼，用不同的測試方法。

五層架構的測試分工

Layer 1（UI/Presentation） 只針對關鍵互動流程撰寫整合測試。判斷標準：流程失敗是否影響核心業務、是否需要多步驟操作、是否涉及金流或敏感資料。靜態展示頁面、簡單列表交給人工測試。

Layer 2（Application/Behavior） 只針對複雜轉換邏輯撰寫單元測試。判斷標準：轉換是否包含條件判斷、計算邏輯、多個來源資料，或邏輯超過十行。簡單的 DTO 欄位直接映射，不需要獨立測試，由 UseCase 層間接覆蓋。

Layer 3（UseCase） 所有業務場景都必須撰寫 BDD 測試，沒有例外。每個 UseCase 至少涵蓋一個正常流程、兩個異常流程、三個邊界條件。格式使用 Given-When-Then，只 Mock 外層依賴，使用真實的 Domain Entity。

Layer 4（Interface） 不測試。介面只定義合約，沒有可測試的行為。

Layer 5（Domain Implementation） 複雜業務規則必須撰寫單元測試。判斷標準：是否包含業務規則驗證、計算邏輯、狀態轉換、不變量檢查。Email 格式驗證、金額範圍、訂單狀態轉換都需要完整的單元測試。純資料容器的 Entity 不需要獨立測試。

做決策的流程

確定程式碼屬於哪一層（目錄結構直接反映架構層級），然後問一個問題：

UI 層：這是關鍵互動流程嗎？
Behavior 層：這裡有複雜轉換邏輯嗎？
UseCase 層：直接寫 BDD 測試。
Interface 層：不測試。
Domain 層：這裡有複雜業務規則嗎？

答案是就寫，不是就跳過讓上層覆蓋。

技術性測試項目

不分層級都要納入：

Null 值和空集合
邊界值（零、負數、最大值）
異常處理（網路錯誤、儲存失敗）
資料驗證（格式、範圍、必填欄位）

這些容易被忽略，但往往是上線後出問題的地方。

覆蓋率的意義

這套策略讓覆蓋率指標更有意義。UseCase 層要求行為場景覆蓋率 100%，是所有業務場景都有測試，不是追求程式碼行數百分比。Domain 層複雜邏輯要求分支覆蓋率 100%，每個分支都代表一個業務決策。整體新增程式碼維持 80% 以上。

數字背後有實際意義，不是為了報告好看。

測試的穩定性

UseCase 層的 BDD 測試關注行為，重構內部邏輯只要業務行為沒變，測試就不需要動。Domain 層只有規則本身改變才需要更新。Behavior 層只測複雜的轉換邏輯，重構簡單映射不影響測試。

測試應該是開發的保護網，不是阻力。測試因為業務改變而失敗，那很好；因為重構而大量失敗，那是設計問題。

層級架構品質檢查機制 - Clean Architecture 合規性驗證

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

在 Flutter 專案裡導入 Clean Architecture 並不難，難的是讓整個團隊在每一次 commit 都確實遵守它。我們曾有過這樣的經驗：架構設計文件寫得很完整，但三個月後打開 codebase，Widget 裡藏著業務規則、Controller 開始自己做驗證、UseCase 直接依賴了具體的資料庫實作。

問題在於沒有機制讓「做錯事」變得困難。

為什麼架構會悄悄腐化

Clean Architecture 的核心是依賴方向：外層可以依賴內層，但內層絕對不能依賴外層。這個原則說起來簡單，但「快速解決問題」的衝動很容易讓人走捷徑。一個業務驗證邏輯，放在 Widget 裡只要三行；把它搬到正確的 Domain 層，可能需要新增 Entity 方法、更新 UseCase、再補上測試。

在時間壓力下，捷徑獲勝了。

更麻煩的是，這種腐化是漸進的。第一次違規很小；第二次引用了第一次的前例；到了第六次，層級的邊界已經模糊得看不清楚了。

解法是：不依賴自律，改依賴機制。把架構規則轉化為可以自動執行的檢查。

用檔案路徑判斷層級歸屬

我們採用的策略是用檔案路徑作為層級的明確宣告。一個檔案放在什麼目錄，就代表它屬於哪一層：

 1lib/
 2├── ui/                    // 展示層（Layer 1）
 3├── application/           // 應用行為層（Layer 2）
 4├── usecases/              // UseCase 層（Layer 3）
 5├── domain/
 6│   ├── events/            // Domain 事件層（Layer 4）
 7│   ├── interfaces/        // 介面定義層（Layer 4）
 8│   ├── entities/          // Domain 實作層（Layer 5）
 9│   ├── value_objects/     // 值物件（Layer 5）
10│   └── services/          // Domain 服務（Layer 5）
11└── infrastructure/        // 基礎設施層

這讓我們可以用簡單的字串比對判斷：這個 PR 動了哪些層的檔案？一個 Ticket 聲稱只修改展示層，但 diff 裡出現了 lib/domain/ 的檔案，那就是需要解釋的信號。

測試目錄也採用相同的對應結構：

1test/
2├── ui/           // 對應展示層修改
3├── application/  // 對應應用行為層修改
4├── usecases/     // 對應 UseCase 層修改
5└── domain/       // 對應 Domain 層修改

修改了某個層，對應的測試目錄裡就必須有覆蓋。「測試覆蓋率」從一個抽象數字，變成了具體的結構性要求。

三種最常見的違規模式

追蹤了幾十個架構違規案例之後，幾乎都落在以下三種模式。

展示層包含業務邏輯

Widget 直接呼叫過濾、排序、計算這類業務操作：

 1// 違規：Widget 自己做了業務邏輯
 2class BookListWidget extends StatelessWidget {
 3  Widget build(BuildContext context) {
 4    final books = _filterNewBooks(_getAllBooks());
 5    return ListView.builder(...);
 6  }
 7}
 8
 9// 正確：Widget 只負責把 controller 的狀態渲染出來
10class BookListWidget extends StatelessWidget {
11  final BookListController controller;
12  Widget build(BuildContext context) {
13    return ListView.builder(items: controller.filteredBooks);
14  }
15}

「什麼樣的書算新書」是業務邏輯，應該在 Domain 層定義。Widget 只做一件事：把資料渲染成畫面。

Controller 包含業務規則

 1// 違規：Controller 自己在做 ISBN 驗證
 2class BookController {
 3  Future<void> addBook(Book book) async {
 4    if (book.isbn.length != 13) {
 5      throw ValidationException('ISBN 必須為 13 碼');
 6    }
 7    await bookRepository.save(book);
 8  }
 9}
10
11// 正確：Controller 只負責呼叫 UseCase
12class BookController {
13  final AddBookUseCase addBookUseCase;
14  Future<void> addBook(Book book) async {
15    await addBookUseCase.execute(book);
16  }
17}

「ISBN 必須為 13 碼」是業務規則，應該活在 Book Entity 或 Value Object 裡。Controller 的角色是協調，不是決策。

UseCase 依賴具體實作

1// 違規：依賴具體的 SQLite 實作
2class SearchBookUseCase {
3  final SqliteBookRepository repository;
4}
5
6// 正確：依賴抽象介面
7class SearchBookUseCase {
8  final IBookRepository repository;
9}

依賴介面讓 UseCase 在測試時注入 Mock，生產環境注入真實實作，兩者互換自如。

把檢查機制自動化

辨識出違規模式之後，我們做的第一件事是把檢查寫進工具裡。

Pre-commit Hook

1#!/bin/bash
2./scripts/check_single_layer_modification.sh || exit 1
3flutter test --coverage || exit 1

check_single_layer_modification.sh 分析 commit 的 diff，確認被修改的檔案是否都屬於同一個架構層。一個本來只應動展示層的 commit，如果同時修改了 Domain 層的檔案，腳本就會退出並阻止 commit。

CI/CD 整合

Pre-commit Hook 可以被繞過，但 CI/CD 不會：

 1name: PR Architecture Check
 2on: [pull_request]
 3jobs:
 4  architecture_check:
 5    runs-on: ubuntu-latest
 6    steps:
 7      - name: 檢查單層修改原則
 8        run: ./scripts/check_single_layer_in_pr.sh
 9      - name: 執行測試並確認覆蓋率
10        run: flutter test --coverage

架構合規性成為 PR 合併的硬性前置條件。

每次 commit 前的自我檢查

自動化工具處理可以被程式判斷的規則，剩下的需要開發者自己過一遍：

這次修改的檔案，是否都屬於同一個架構層？
import 方向是否正確——只有外層依賴內層？
測試檔案路徑和被測試程式碼是否在對應的層級目錄？
有沒有 Widget 直接做業務計算、Controller 直接做驗證？

三十秒可以過完，但幾乎每次都能在 commit 前抓住一兩個值得重新考慮的決定。

機制比自律更可靠

導入這套機制之後，code review 上花的精力少了很多——大多數架構層面的問題在進入 review 之前就已經被攔截。reviewer 可以把注意力放在邏輯正確性和設計決策上，不用反覆提醒「這段邏輯不應該放在 Widget 裡」。

對新加入的開發者也很友善：不需要先把架構文件背熟才能開始開發，工具會在走錯方向時給出明確的反饋。

架構的生命力在於它能不能在日常開發壓力下被維護下去。

層級隔離：讓每張 Ticket 只做一件層級的事

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

架構圖貼出來，層級畫得漂漂亮亮，但 PR 送進來還是一次動了 UI、Controller、UseCase 和 Entity 四層。

問題不在架構，在派工

Clean Architecture 告訴你「怎麼組織程式碼」，但沒告訴你「怎麼拆 Ticket」。每次 Code Review 都像翻地層，從 Widget 翻到 Entity，不知道從哪開始看；Domain 沒穩定，UI 那層就沒辦法測，整個流程互相等待。

這個銜接點，需要一套專門處理 Ticket 拆法的方法論。

核心原則：一張 Ticket，一個層級

一個 Ticket 只應該修改單一架構層級的程式碼，變更的原因單一且明確。

SRP 說一個類別只有一個改變的原因，我們把它升一層：一張 Ticket 也只有一個改變的原因。

聽起來嚴苛，但實際跑起來好處很直接：Code Review 只需要理解一層的邏輯、測試不需要拉起整個系統、PR 影響範圍可預測，壞掉的時候更容易定位。

我們怎麼定義「五層」

傳統 Clean Architecture 四層中，Interface Adapters 同時處理「事件邏輯」和「資料轉換」，職責太雜，我們把它細分成五層：

Layer 1 — UI/Presentation：純視覺呈現，Widget 長什麼樣。變更原因只有一個：設計稿改了。

Layer 2 — Application/Behavior：事件處理和 UI 邏輯。按鈕點擊怎麼處理、Loading 狀態怎麼切換、Domain Entity 怎麼轉成 ViewModel。Flutter 對應 Controller 和 ViewModel。

Layer 3 — UseCase：業務流程編排。協調多個 Repository 和 Domain Service，把業務步驟串起來。不管 UI 怎麼顯示，也不管資料庫怎麼存。

Layer 4 — Domain Events/Interfaces：定義契約。Repository 抽象介面、Domain Event 結構、跨層 DTO。只定義，不實作。

Layer 5 — Domain Implementation：核心業務邏輯。Entity、Value Object、Domain Service、業務規則驗證。整個系統最穩定的部分。

Infrastructure 層（資料庫、外部 API、EventBus）不納入層級隔離，它的變更驅動是技術決策，不是業務需求，Ticket 設計上本來就獨立對待。

從外而內，而不是從內而外

許多教材說「先設計 Domain 再往外做」，但實際開發時，我們發現從外而內更能控制風險。

原因很簡單：Layer 1 UI 壞掉只影響視覺，Layer 5 Domain 邏輯壞掉影響整個系統的業務規則。從影響最小的地方開始，需求偏差時調整成本低；一開始就動 Domain，到了 UI 才發現需求理解有誤，代價就大得多。

實作順序是 Layer 1 → Layer 2 → Layer 3 → Layer 4 → Layer 5，每層完成後立即驗證。

有幾個例外：架構遷移要先定義 Layer 4 介面契約（Interface-First），讓外層修改有穩定依據；安全性修復從 Layer 5 往外；Bug Fix 從問題根源那層開始。

Ticket 拆分的量化標準

幾個判斷指標：修改檔案數 1 到 3 個（最多 5 個）、預估開發時間 2 到 8 小時（超過一天就拆）、修改層級嚴格限制 1 層、新增程式碼測試覆蓋率 100%。

數字可以商議，但有標準就不用靠直覺判斷「感覺差不多」。

反面教材：

1Ticket：實作書籍收藏功能
2
3變更範圍：
4- lib/ui/pages/book_detail_page.dart       (Layer 1)
5- lib/application/controllers/book_detail_controller.dart  (Layer 2)
6- lib/usecases/add_book_to_favorite_usecase.dart  (Layer 3)
7- lib/domain/entities/favorite.dart        (Layer 5)

這張 Ticket 跨了四層，PR 送出來沒人知道從哪開始審，測試也很難設計。正確做法是拆成四張各自獨立的 Ticket，按依賴順序執行。

如何判斷一段程式碼屬於哪一層

最常模糊的是 Layer 2 和 Layer 3 之間的邊界。判斷流程：

在渲染 UI 元素？→ Layer 1
在處理 UI 事件、控制 UI 狀態、或把 Domain 資料轉成 UI 格式？→ Layer 2（把 Domain Exception 轉成 ErrorViewModel 也是這層的事）
在協調多個 Domain Service 或 Repository、編排業務步驟？→ Layer 3
在定義介面契約或事件結構？→ Layer 4
在實作業務規則或定義 Entity？→ Layer 5
以上都不是 → Infrastructure 層

這套方法論的定位

這是 Clean Architecture 的「派工指南」。Clean Architecture 告訴你程式碼怎麼組織，層級隔離告訴你 Ticket 怎麼拆、按什麼順序做。

它和 Atomic Ticket 方法論也不衝突：Atomic Ticket 強調職責維度（一個 Action 加一個 Target），層級隔離強調層級維度（一個 Ticket 只動一層），兩個維度同時符合才是最完整的 Ticket 設計。

緊急 Hotfix、原型開發、一次性腳本不需要強行套用。但在正常功能開發和重構中，跑起來之後的感覺是：每次把一個大需求拆成按層排好的 Ticket 序列，就等於把架構邊界重新確認了一遍。