Interface on Tarragon

0.2 組合優先：小介面與明確依賴

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

Go 組合的核心原則是用小型型別與小介面拼出行為。程式需要什麼能力，就依賴那個能力；型別擁有哪些資料，就把資料明確放在 struct 裡。這種設計讓高併發服務更容易拆解責任，也更容易在選型成立時維持邊界清楚。

為什麼這章在第零章

當你的工作負載本來就適合 Go 時，真正需要確認的就不只是語法，而是 Go 如何幫你把服務邊界維持清楚。組合優先讓 main()、constructor、handler、worker 與 repository 的責任能被直接看見，這是 Go 在服務型專案中很重要的可維護性來源。

組合先描述擁有什麼

struct 的核心責任是把一組資料與依賴放在同一個明確邊界內。Go 不用 class inheritance 表達「某個型別繼承另一個型別」，而是用欄位組合出需要的結構。

1type Logger interface {
2 Info(message string)
3}
4
5type Server struct {
6 addr string
7 logger Logger
8}

Server 擁有一個地址，也依賴一個 logger。這些資訊都在欄位上直接呈現，讀者不需要追蹤隱式容器或父類別初始化順序。

當依賴變多時，struct 仍然應該只保留這個型別真正需要的依賴。把整個 application container 塞進 struct，通常會讓依賴邊界變模糊。

小介面先描述需要什麼

interface 的核心責任是描述呼叫端需要的行為。Go 的介面通常很小，常見的好介面只有一到三個方法。

1type UserFinder interface {
2 FindUser(ctx context.Context, id string) (User, error)
3}
4
5type UserHandler struct {
6 finder UserFinder
7}

UserHandler 不需要知道資料來自資料庫、快取或遠端 API。它只需要「可以用 id 找使用者」這個能力，因此介面只放 FindUser。

介面應由替換、測試或隔離需求推動。只有一個具體型別，而且沒有測試替身或替換需求時，先直接依賴具體型別通常更簡單。過度抽象的代價是把原本簡單的依賴藏成難追蹤的間接關係，反而比直接依賴更難閱讀。

依賴由外層組裝

Go 應用組裝依賴的核心策略是讓外層建立具體型別，內層只接收自己需要的依賴。常見位置是 main() 或專門的 constructor。

 1func NewUserHandler(finder UserFinder) UserHandler {
 2 return UserHandler{finder: finder}
 3}
 4
 5func main() {
 6 db := NewDatabase("postgres://localhost/app")
 7 repository := NewUserRepository(db)
 8 handler := NewUserHandler(repository)
 9
10 http.HandleFunc("/users/", handler.ServeHTTP)
11}

這段程式讓資料流與依賴關係保持可見：repository 依賴 db，handler 依賴 repository 的查詢能力。Go 的組合方式偏好把這些關係寫出來，而不是藏在 framework magic 裡。

行為可以用 embedding 重用

embedding 的核心用途是把一個型別的欄位或方法提升到外層型別。它是組合工具；若需要表達明確擁有關係，named field 會比繼承式心智模型更清楚。

 1type AuditFields struct {
 2 CreatedAt time.Time
 3 UpdatedAt time.Time
 4}
 5
 6type User struct {
 7 ID string
 8 Email string
 9 AuditFields
10}

User 透過 embedding 擁有 CreatedAt 與 UpdatedAt。這適合重用資料欄位，但不代表 User 在概念上「繼承」了 AuditFields 的完整行為。

embedding 應該用在語意自然的地方。若提升方法會讓外層型別出現不該公開的能力，明確寫欄位名稱通常更安全。

組合讓測試替換更自然

組合的測試價值是可以替換依賴，而不需要啟動整個系統。只要 production code 依賴小介面，測試就能提供 fake。

 1type fakeUserFinder struct {
 2 user User
 3 err error
 4}
 5
 6func (f fakeUserFinder) FindUser(ctx context.Context, id string) (User, error) {
 7 if f.err != nil {
 8 return User{}, f.err
 9 }
10 return f.user, nil
11}

測試 handler 時，可以把 fakeUserFinder 傳進去，專注檢查 HTTP response。這種替換的目標是讓測試只覆蓋當前邊界的行為。

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 與測試替身邊界；如果你要先回看語言教材，可以讀：

2.3 interface：用行為定義依賴

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

Go 的 interface 描述的是行為，不是繼承關係。你不需要在 concrete type 上宣告「我實作了某個 interface」；只要方法集合符合，Go 就視為實作。

本章目標

學完本章後，你將能夠：

理解 implicit interface 的設計精神
寫出小而精準的 interface
避免把 concrete type 暴露給不需要的呼叫者
用 interface 改善測試與依賴邊界

【觀察】interface 只描述需要的行為

interface 的核心規則是：只描述呼叫者需要的行為，不描述實作者的完整身份。假設有一個函式要把訊息寫到某個目的地；它不需要知道目的地是檔案、記憶體 buffer，還是網路連線，只需要知道對方能 Write。

1type Writer interface {
2 Write(p []byte) (n int, err error)
3}
4
5func WriteMessage(w Writer, message string) error {
6 _, err := w.Write([]byte(message))
7 return err
8}

這個 interface 很小，只描述一個行為：寫入 bytes。

【判讀】Go interface 是由使用者定義的需求

在 Go 裡，interface 常由「使用者」定義，而不是由「實作者」定義。

這和很多語言不同。你不需要在某個型別上寫：

1// Go 不需要這種宣告
2type File implements Writer

implicit interface 的核心規則是：只要型別有相同方法，就符合 interface，不需要顯式宣告實作關係。

1type MemoryWriter struct {
2 data []byte
3}
4
5func (m *MemoryWriter) Write(p []byte) (int, error) {
6 m.data = append(m.data, p...)
7 return len(p), nil
8}

MemoryWriter 沒有提到 Writer，但它已經符合 Writer。

【策略】interface 越小，依賴越清楚

小 interface 的核心規則是：interface 應由使用端需要的最小行為組成。Go 常見的好 interface 很小：

 1type Reader interface {
 2 Read(p []byte) (n int, err error)
 3}
 4
 5type Writer interface {
 6 Write(p []byte) (n int, err error)
 7}
 8
 9type Closer interface {
10 Close() error
11}

小 interface 的好處是：

呼叫者只依賴自己真正需要的行為
測試替身容易寫
concrete type 可以在不同情境中被重用
未來改內部結構時，外部影響較小

反例是把太多方法塞進一個 interface：

1type UserService interface {
2 CreateUser(User) error
3 UpdateUser(User) error
4 DeleteUser(string) error
5 FindUser(string) (User, error)
6 ListUsers() ([]User, error)
7 ExportUsers() ([]byte, error)
8}

如果某個函式只需要查詢 user，卻依賴整個 UserService，它就知道太多了。

【執行】為查詢需求設計小介面

依賴邊界的核心規則是：使用端只依賴自己需要的方法。假設一個 HTTP handler 只需要查詢使用者名稱：

 1type UserLookup interface {
 2 FindName(userID string) (string, bool)
 3}
 4
 5type Handler struct {
 6 users UserLookup
 7}
 8
 9func NewHandler(users UserLookup) *Handler {
10 return &Handler{users: users}
11}

這個 handler 不知道 user 是存在 map、資料庫、檔案，還是測試假物件裡。它只知道自己需要 FindName。

測試時可以寫一個很小的 fake：

1type fakeUsers map[string]string
2
3func (f fakeUsers) FindName(userID string) (string, bool) {
4 name, ok := f[userID]
5 return name, ok
6}

這就是 Go interface 最實用的地方：它讓依賴變小，讓測試變簡單。

何時先保留 concrete type

interface 的使用邊界是：替換需求或測試替身需求清楚時，再抽出小介面。以下情境通常適合先保留 concrete type：

只有一個 concrete type，而且沒有測試替身需求
interface 只是完整複製 concrete type 的所有方法
你還不確定呼叫者真正需要哪些行為

Go 的常見做法是：先寫 concrete type，等使用端出現明確需求，再抽小 interface。

2.6 struct embedding 與組合式設計

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

struct embedding 的核心用途是組合既有能力。它可以讓欄位與方法被提升到外層型別，但設計重點仍然是清楚表達責任，而不是模擬繼承階層。

預計補充內容

這些組合邊界會在下列章節展開：

Go 入門：組合優先：小介面與明確依賴：先理解 Go 為什麼偏好組合，才能判斷 embedding 是在表達能力，還是在模仿繼承。
Go 入門：interface：用行為定義依賴：這裡會把 embedding 和 interface 的責任分開，避免欄位提升變成隱性耦合。
Go 進階：composition root 與依賴組裝：當組合開始影響 wiring 時，就要看依賴是在哪一層被建立的。

與其他章節的關係

本章承接組合優先：小介面與明確依賴與 interface：用行為定義依賴，後續會連到 composition root 與依賴組裝。

和 Go 教材的關係

這一章承接的是組合、interface 與依賴組裝；如果你要先回看語言教材，可以讀：

6.6 如何新增 repository port

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

新增 repository port 的核心目標是讓 application layer 依賴資料能力，而不是依賴具體儲存技術。先建立 port，才能在 memory、SQLite 或其他資料庫之間替換。

本章目標

學完本章後，你將能夠：

判斷何時需要 repository port
由 usecase 定義小而明確的 repository interface
實作 map + mutex 的 in-memory repository
保留 context、error 與 database-ready 邊界
分開撰寫 usecase fake test 與 repository contract test

【觀察】repository port 表達資料能力

repository port 的核心語意是 usecase 需要哪些資料能力。它應描述 application layer 的讀寫需求，而不是照搬資料庫 CRUD 方法或把所有資料操作塞進同一個巨大 Repository。

例如通知服務的 usecase 可能需要三種能力：

usecase 需求	repository 能力
建立通知	儲存一筆 notification
查詢 topic 通知	依 topic 列出 notification
避免重複建立	依 ID 查詢 notification 是否存在

這些能力可以先用 memory 實作，未來再換成 SQLite、PostgreSQL 或外部服務。usecase 不應知道底層儲存技術。

【判讀】repository 服務共享讀寫邊界

是否需要 repository 的核心判斷是資料是否需要一致的讀寫邊界。暫時變數、單次函式內部結果或不共享的 cache，不一定需要 repository。

適合 repository 的情境：

多個 usecase 需要一致讀寫同一組資料
資料需要被測試替身取代
讀寫規則需要集中
未來可能從 memory 換成資料庫
需要保護 map、slice 或 pointer 不被外部修改

不一定需要 repository 的情境：

只在單一函式內暫存
只是純計算結果
還沒有共享或替換需求
只有一個簡單 struct 可以直接傳遞

repository 是邊界工具，不是成熟專案的儀式。過早建立 repository 會讓小程式變得難讀。

【策略】interface 放在使用端

repository interface 的核心規則是由使用端定義需要的能力。usecase 需要什麼，就在 usecase 所在 package 定義什麼；adapter 或 infrastructure 實作它。

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

方法名稱應該表達業務能力，而不是資料庫操作細節。ListByTopic 比 SelectWhereTopicEquals 更適合 usecase。

先定義 domain model：

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

domain model 不需要 JSON tag。對外 JSON 格式應交給 response struct，repository 儲存的是內部資料。

【執行】usecase 依賴 port，不依賴 implementation

usecase 的核心責任是協調資料能力與行為規則。它接收 repository port，而不是具體 memory repository。

 1type CreateNotificationCommand struct {
 2    ID        string
 3    Topic     string
 4    Title     string
 5    CreatedAt time.Time
 6}
 7
 8type NotificationService struct {
 9    repository NotificationRepository
10}
11
12func NewNotificationService(repository NotificationRepository) *NotificationService {
13    return &NotificationService{repository: repository}
14}

建立通知時，usecase 可以檢查重複與必填欄位：

 1func (s *NotificationService) Create(ctx context.Context, cmd CreateNotificationCommand) error {
 2    if strings.TrimSpace(cmd.ID) == "" {
 3        return fmt.Errorf("notification id is required")
 4    }
 5    if strings.TrimSpace(cmd.Topic) == "" {
 6        return fmt.Errorf("topic is required")
 7    }
 8
 9    if _, exists, err := s.repository.FindByID(ctx, cmd.ID); err != nil {
10        return fmt.Errorf("find notification: %w", err)
11    } else if exists {
12        return fmt.Errorf("notification %s already exists", 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 := s.repository.Save(ctx, notification); err != nil {
23        return fmt.Errorf("save notification: %w", err)
24    }
25
26    return nil
27}

這段 usecase 不知道資料存在 map、SQLite 或遠端 API。它只依賴「可以查詢與儲存 notification」這個能力。

【執行】memory implementation 要保護 map

in-memory repository 的核心責任是提供可用的儲存實作，同時保護共享 map。只要 repository 可能被多個 goroutine 使用，就應該用 mutex 保護。

 1type InMemoryNotificationRepository struct {
 2    mu            sync.RWMutex
 3    notifications map[string]Notification
 4}
 5
 6func NewInMemoryNotificationRepository() *InMemoryNotificationRepository {
 7    return &InMemoryNotificationRepository{
 8        notifications: make(map[string]Notification),
 9    }
10}

Save 寫入時要複製資料：

1func (r *InMemoryNotificationRepository) Save(ctx context.Context, notification Notification) error {
2    r.mu.Lock()
3    defer r.mu.Unlock()
4
5    r.notifications[notification.ID] = notification
6    return nil
7}

FindByID 回傳值與 bool：

 1func (r *InMemoryNotificationRepository) FindByID(ctx context.Context, id string) (Notification, bool, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    notification, ok := r.notifications[id]
 6    if !ok {
 7        return Notification{}, false, nil
 8    }
 9    return notification, true, nil
10}

ListByTopic 回傳新 slice，避免呼叫端修改內部資料：

 1func (r *InMemoryNotificationRepository) ListByTopic(ctx context.Context, topic string) ([]Notification, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    result := make([]Notification, 0)
 6    for _, notification := range r.notifications {
 7        if notification.Topic == topic {
 8            result = append(result, notification)
 9        }
10    }
11    return result, nil
12}

目前 Notification 只有值型別欄位，所以回傳值與新 slice 已足夠。若未來加上 slice、map 或 pointer 欄位，就要補 clone 函式。

【策略】context 和 error 是未來資料庫邊界

repository method 接收 context 的核心原因是未來可能出現 I/O。memory 實作可能不使用 context，但資料庫查詢、遠端 API 或 transaction 會需要取消與逾時。

1Save(ctx context.Context, notification Notification) error

error wrapping 的核心規則是保留失敗位置與原始錯誤：

1if err := s.repository.Save(ctx, notification); err != nil {
2    return fmt.Errorf("save notification: %w", err)
3}

不要過早抽象 transaction。只有當一個 usecase 真的需要多筆寫入同時成功或失敗時，再設計 transaction boundary。否則 repository interface 會提前背負資料庫細節。

【判讀】fake 和 in-memory 用於不同測試

測試替身的核心差異是 fake 服務 usecase 測試，in-memory implementation 服務 repository 行為測試。兩者可以長得像，但用途不同。

usecase 測試可以用簡單 fake：

 1type fakeNotificationRepository struct {
 2    existing map[string]Notification
 3    saved    []Notification
 4    err      error
 5}
 6
 7func (f *fakeNotificationRepository) Save(ctx context.Context, notification Notification) error {
 8    if f.err != nil {
 9        return f.err
10    }
11    f.saved = append(f.saved, notification)
12    return nil
13}
14
15func (f *fakeNotificationRepository) FindByID(ctx context.Context, id string) (Notification, bool, error) {
16    if f.err != nil {
17        return Notification{}, false, f.err
18    }
19    notification, ok := f.existing[id]
20    return notification, ok, nil
21}
22
23func (f *fakeNotificationRepository) ListByTopic(ctx context.Context, topic string) ([]Notification, error) {
24    return nil, nil
25}

這個 fake 只支援測試需要的行為，不必成為完整 repository。

【執行】usecase 測試檢查行為規則

usecase 測試的核心目標是驗證 command 進來後是否呼叫正確資料能力。它不應測 memory map 的 lock 或 copy 行為。

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

重複 ID 測試可以讓 fake 回傳 existing notification：

 1func TestNotificationServiceCreateDuplicate(t *testing.T) {
 2    repo := &fakeNotificationRepository{
 3        existing: map[string]Notification{
 4            "ntf_1": {ID: "ntf_1"},
 5        },
 6    }
 7    service := NewNotificationService(repo)
 8
 9    err := service.Create(context.Background(), CreateNotificationCommand{
10        ID:        "ntf_1",
11        Topic:     "deployments",
12        Title:     "Deploy finished",
13        CreatedAt: time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
14    })
15    if err == nil {
16        t.Fatalf("expected duplicate error")
17    }
18}

這些測試讓 usecase 不依賴具體 repository implementation。

【執行】repository contract test 保護實作行為

repository contract test 的核心目標是讓不同 implementation 遵守同一組行為。memory repository、SQLite repository 或其他實作都可以跑同一套測試。

 1func TestNotificationRepositoryContract(t *testing.T) {
 2    runNotificationRepositoryContract(t, func() NotificationRepository {
 3        return NewInMemoryNotificationRepository()
 4    })
 5}
 6
 7func runNotificationRepositoryContract(t *testing.T, newRepo func() NotificationRepository) {
 8    t.Helper()
 9
10    repo := newRepo()
11    ctx := context.Background()
12    notification := Notification{
13        ID:        "ntf_1",
14        Topic:     "deployments",
15        Title:     "Deploy finished",
16        CreatedAt: time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
17    }
18
19    if err := repo.Save(ctx, notification); err != nil {
20        t.Fatalf("save notification: %v", err)
21    }
22
23    got, ok, err := repo.FindByID(ctx, "ntf_1")
24    if err != nil {
25        t.Fatalf("find notification: %v", err)
26    }
27    if !ok {
28        t.Fatalf("notification should exist")
29    }
30    if got.Topic != "deployments" {
31        t.Fatalf("topic = %q, want deployments", got.Topic)
32    }
33
34    list, err := repo.ListByTopic(ctx, "deployments")
35    if err != nil {
36        t.Fatalf("list notifications: %v", err)
37    }
38    if len(list) != 1 {
39        t.Fatalf("notifications = %d, want 1", len(list))
40    }
41}

contract test 不需要知道實作細節。它只驗證 port 承諾的行為。

【策略】小介面比萬用 repository 穩定

repository interface 的核心風險是變成所有資料操作的大型介面。大型介面會讓每個 usecase、fake 與測試都被迫依賴不需要的方法。

不佳：

1type Repository interface {
2    SaveNotification(ctx context.Context, notification Notification) error
3    ListNotifications(ctx context.Context) ([]Notification, error)
4    SaveJob(ctx context.Context, job JobProjection) error
5    SaveAccount(ctx context.Context, account Account) error
6    AppendEvent(ctx context.Context, event DomainEvent) error
7}

較佳：

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

不同 usecase 可以定義不同 port。若未來多個 port 由同一個 database adapter 實作，那是 adapter 的事，不必讓 usecase 共享巨大介面。

實作檢查清單

新增 repository port 時，可以依序檢查：

是否真的需要共享讀寫邊界
interface 是否由 usecase 需要定義
方法名稱是否表達業務能力
方法是否接收 context.Context
error 是否被包上操作脈絡
in-memory implementation 是否保護 map
回傳 slice/map/pointer 時是否有 copy boundary
usecase 測試是否使用 fake
repository implementation 是否跑 contract test
是否避免把所有資料操作塞進巨大介面

設計檢查

檢查一：repository 來自 usecase 需求

repository 應該來自 usecase 需求。先建一個萬用 Repository，通常會讓介面快速膨脹，測試也變得笨重。

檢查二：interface 放在使用端

若 interface 是由 implementation 定義，usecase 會被迫接受 implementation 想暴露的能力。Go 更常見的做法是讓使用端定義最小需求。

檢查三：memory repository 保護內部資料

回傳內部 slice、map 或 pointer 會讓呼叫端繞過 repository 規則。即使目前只是 memory 實作，也應保護資料擁有權。

檢查四：transaction 和 ORM 等需求出現再抽象

沒有跨多筆寫入一致性需求時，transaction 介面只會增加複雜度。先把 context、error、port 邊界放好，等需求出現再擴展。

本章不處理

本章先處理 repository port 如何表達資料能力；特定資料庫、ORM 與 transaction，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 interface、state 與 application boundary；如果你要先回看語言教材，可以讀：