模組七：重構實戰 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 不需要重複教這些技術，只要把它們正確接上即可。

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 會變成依賴組裝的收斂點。重構的目標是讓邏輯邊界與依賴方向更穩定。