模組六：實戰指南 on Tarragon

6.1 如何新增一個即時訊息 action

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

新增即時訊息 action 的核心流程是先定義 client 意圖，再把 action 轉成 application command。WebSocket handler 負責傳輸邊界，domain state 的修改交給 usecase 或 processor。本章用一個簡化的 topic subscription action 示範完整路徑。

本章目標

學完本章後，你將能夠：

用 action type 表達 client intent
用 request struct 定義 JSON payload 邊界
把 WebSocket message 轉成 application command
設計穩定的 response 與 error 格式
把 router、usecase 與 WebSocket integration test 分層測試

【觀察】action 表達 client intent

action 的核心語意是 client 想要系統做什麼。它是 client 和 server 之間的訊息合約，命名應描述行為意圖，而不是 UI 按鈕或 handler 函式名稱。

例如即時通知服務可能有三種 action：

action	client 意圖
`subscribe_topic`	訂閱某個 topic 的即時通知
`unsubscribe_topic`	取消某個 topic 的訂閱
`get_snapshot`	取得目前狀態快照

用字串常數定義 action，可以避免 handler 到處散落 magic string：

1const (
2    ActionSubscribeTopic   = "subscribe_topic"
3    ActionUnsubscribeTopic = "unsubscribe_topic"
4    ActionGetSnapshot      = "get_snapshot"
5)

action 名稱應該描述行為意圖。subscribe_topic 比 ws_subscribe 更穩定，因為未來同一個 usecase 也可能被 HTTP endpoint 或 background job 呼叫。

【判讀】外部訊息先進入 envelope

WebSocket message 的核心邊界是 envelope。client 傳來的 JSON 應該先被解析成一個共同外殼，再根據 action 解析 payload。

1type ClientMessage struct {
2    ID      string          `json:"id"`
3    Action  string          `json:"action"`
4    Payload json.RawMessage `json:"payload"`
5}

ID 是 client message ID，可用來讓 response 對應原始 request。Action 決定路由方向。Payload 使用 json.RawMessage，讓 router 可以先看 action，再把 payload 解成對應 struct。

例如 client 可以送出：

1{
2  "id": "msg_1001",
3  "action": "subscribe_topic",
4  "payload": {
5    "topic": "deployments",
6    "includeHistory": true
7  }
8}

這種 envelope 設計讓新 action 可以共用同一套外層格式。新增 action 時，不需要改整個 WebSocket 讀取流程，只要新增 payload struct 與路由分支。

【策略】payload struct 要表達資料語意

payload struct 的核心責任是把外部 JSON 轉成明確的 Go 型別。必填欄位、可選欄位與相容性都應該在 struct 與驗證函式中清楚表達。

1type SubscribeTopicRequest struct {
2    Topic          string `json:"topic"`
3    IncludeHistory bool   `json:"includeHistory,omitempty"`
4}

Topic 是必填欄位，因為沒有 topic 就無法訂閱。IncludeHistory 是可選欄位，零值 false 可以代表「不要求歷史資料」。這裡使用 omitempty 是在表達：輸出 response 或轉送資料時，這個欄位可以省略；它不是必填資料。

驗證規則應該靠明確函式完成，讓 router 分支只負責呼叫驗證與轉換：

1func (r SubscribeTopicRequest) Validate() error {
2    if strings.TrimSpace(r.Topic) == "" {
3        return fmt.Errorf("topic is required")
4    }
5    return nil
6}

外部資料進入系統後，要先完成解碼與驗證，才轉成 application command。這可以避免 usecase 同時處理 JSON 格式、欄位缺漏與業務規則。

【執行】router 只做解析、驗證與轉換

message router 的核心責任是把 client message 轉成 application command。router 只處理傳輸邊界，狀態修改與訂閱規則交給 usecase。

先定義 usecase 需要的 command：

1type SubscribeTopicCommand struct {
2    ClientID       string
3    Topic          string
4    IncludeHistory bool
5}

command 是 application layer 的輸入模型，只描述 usecase 需要的資料。它不需要 JSON tag，因為外部傳輸格式已經停在 request struct。

接著定義 usecase 介面：

1type SubscriptionUsecase interface {
2    SubscribeTopic(ctx context.Context, cmd SubscribeTopicCommand) error
3}

這個介面小而明確，只描述 router 目前需要的能力。不要一開始就建立大型 Service 介面，把所有 action 都塞進去。

router 可以這樣組裝：

1type MessageRouter struct {
2    subscriptions SubscriptionUsecase
3}
4
5func NewMessageRouter(subscriptions SubscriptionUsecase) *MessageRouter {
6    return &MessageRouter{subscriptions: subscriptions}
7}

處理入口接收原始 JSON bytes，回傳可序列化的 response：

 1func (r *MessageRouter) Handle(ctx context.Context, clientID string, data []byte) ServerMessage {
 2    var msg ClientMessage
 3    if err := json.Unmarshal(data, &msg); err != nil {
 4        return ErrorMessage("", "invalid_json", "message must be valid JSON")
 5    }
 6
 7    switch msg.Action {
 8    case ActionSubscribeTopic:
 9        return r.handleSubscribeTopic(ctx, clientID, msg)
10    default:
11        return ErrorMessage(msg.ID, "unknown_action", "action is not supported")
12    }
13}

Handle 不知道 WebSocket connection 怎麼讀寫，也不處理網路錯誤。這讓 router 可以被普通單元測試覆蓋。

subscribe_topic 的分支負責 payload 解碼、驗證與 command 建立：

 1func (r *MessageRouter) handleSubscribeTopic(ctx context.Context, clientID string, msg ClientMessage) ServerMessage {
 2    var req SubscribeTopicRequest
 3    if err := json.Unmarshal(msg.Payload, &req); err != nil {
 4        return ErrorMessage(msg.ID, "invalid_payload", "payload must match subscribe_topic schema")
 5    }
 6
 7    if err := req.Validate(); err != nil {
 8        return ErrorMessage(msg.ID, "invalid_payload", err.Error())
 9    }
10
11    cmd := SubscribeTopicCommand{
12        ClientID:       clientID,
13        Topic:          req.Topic,
14        IncludeHistory: req.IncludeHistory,
15    }
16
17    if err := r.subscriptions.SubscribeTopic(ctx, cmd); err != nil {
18        return ErrorMessage(msg.ID, "subscribe_failed", "topic subscription failed")
19    }
20
21    return OKMessage(msg.ID, map[string]string{
22        "topic": req.Topic,
23    })
24}

這段程式保留了清楚的轉換路徑：JSON message -> request struct -> command -> usecase。每一層只處理自己的責任。

【判讀】response 也需要穩定格式

response 格式的核心目標是讓 client 能穩定判斷一個 action 的結果。成功、輸入錯誤與不支援 action 都應該使用同一個外層格式。

1type ServerMessage struct {
2    ReplyTo string `json:"replyTo,omitempty"`
3    OK      bool   `json:"ok"`
4    Code    string `json:"code,omitempty"`
5    Message string `json:"message,omitempty"`
6    Data    any    `json:"data,omitempty"`
7}

成功 response 可以用 helper 建立：

1func OKMessage(replyTo string, data any) ServerMessage {
2    return ServerMessage{
3        ReplyTo: replyTo,
4        OK:      true,
5        Data:    data,
6    }
7}

錯誤 response 也應該用 helper 建立：

1func ErrorMessage(replyTo string, code string, message string) ServerMessage {
2    return ServerMessage{
3        ReplyTo: replyTo,
4        OK:      false,
5        Code:    code,
6        Message: message,
7    }
8}

WebSocket action 失敗不一定要關閉連線。JSON 格式錯誤、未知 action 或 payload 驗證失敗，通常可以回一筆 error message，讓 client 修正下一次請求；只有協定嚴重錯誤、授權失效或連線狀態不可恢復時，才考慮關閉連線。

【策略】WebSocket handler 聚焦 connection I/O

WebSocket handler 的核心責任是 connection I/O。它可以讀 message、呼叫 router、寫 response；每種 action 的業務規則交給 router 後方的 usecase。

簡化後的連線處理可以像這樣：

 1func handleClientMessage(ctx context.Context, router *MessageRouter, clientID string, data []byte) []byte {
 2    resp := router.Handle(ctx, clientID, data)
 3
 4    encoded, err := json.Marshal(resp)
 5    if err != nil {
 6        fallback := ErrorMessage("", "encode_failed", "response could not be encoded")
 7        encoded, _ = json.Marshal(fallback)
 8    }
 9
10    return encoded
11}

真實 WebSocket server 會有 read loop、write loop、heartbeat 與 slow client 處理。這些都屬於連線生命週期，應和 action routing 分開維護。

【執行】router 測試先覆蓋協定行為

router 測試的核心目標是確認 message 進入後會產生正確 command 與 response。這類測試不需要啟動真實 WebSocket server。

先建立 fake usecase：

 1type fakeSubscriptionUsecase struct {
 2    got SubscribeTopicCommand
 3    err error
 4}
 5
 6func (f *fakeSubscriptionUsecase) SubscribeTopic(ctx context.Context, cmd SubscribeTopicCommand) error {
 7    if f.err != nil {
 8        return f.err
 9    }
10    f.got = cmd
11    return nil
12}

成功案例測試可以檢查 command 是否正確：

 1func TestMessageRouterSubscribeTopic(t *testing.T) {
 2    fake := &fakeSubscriptionUsecase{}
 3    router := NewMessageRouter(fake)
 4
 5    data := []byte(`{
 6        "id": "msg_1",
 7        "action": "subscribe_topic",
 8        "payload": {
 9            "topic": "deployments",
10            "includeHistory": true
11        }
12    }`)
13
14    resp := router.Handle(context.Background(), "client_1", data)
15
16    if !resp.OK {
17        t.Fatalf("response OK = false, want true")
18    }
19    if fake.got.ClientID != "client_1" {
20        t.Fatalf("client ID = %q, want %q", fake.got.ClientID, "client_1")
21    }
22    if fake.got.Topic != "deployments" {
23        t.Fatalf("topic = %q, want %q", fake.got.Topic, "deployments")
24    }
25    if !fake.got.IncludeHistory {
26        t.Fatalf("include history = false, want true")
27    }
28}

輸入錯誤案例應該測 response code。錯誤文案可以調整，code 才是較穩定的協定欄位：

 1func TestMessageRouterUnknownAction(t *testing.T) {
 2    router := NewMessageRouter(&fakeSubscriptionUsecase{})
 3
 4    resp := router.Handle(context.Background(), "client_1", []byte(`{
 5        "id": "msg_1",
 6        "action": "missing_action",
 7        "payload": {}
 8    }`))
 9
10    if resp.OK {
11        t.Fatalf("response OK = true, want false")
12    }
13    if resp.Code != "unknown_action" {
14        t.Fatalf("code = %q, want %q", resp.Code, "unknown_action")
15    }
16}

這些測試保護的是 action 協定。未來 WebSocket library、connection manager 或 repository 改變時，router 行為仍然能被快速驗證。

【判讀】usecase 測試要離開傳輸格式

usecase 測試的核心目標是驗證行為規則，而不是 JSON 格式。當 router 已經把 message 轉成 command，usecase 測試就應該直接餵 command。

 1func TestSubscriptionServiceSubscribeTopic(t *testing.T) {
 2    repo := NewInMemorySubscriptionRepository()
 3    service := NewSubscriptionService(repo)
 4
 5    cmd := SubscribeTopicCommand{
 6        ClientID:       "client_1",
 7        Topic:          "deployments",
 8        IncludeHistory: true,
 9    }
10
11    if err := service.SubscribeTopic(context.Background(), cmd); err != nil {
12        t.Fatalf("subscribe topic: %v", err)
13    }
14
15    if !repo.IsSubscribed("client_1", "deployments") {
16        t.Fatalf("client should be subscribed")
17    }
18}

這裡不需要出現 JSON、WebSocket 或 ClientMessage。usecase 只關心訂閱規則與 repository 狀態。

實作檢查清單

新增 action 時，可以依序檢查：

action 名稱是否描述 client intent
是否有獨立 request struct
必填欄位是否有驗證
router 是否只做解析、驗證與 command 轉換
usecase 是否不依賴 WebSocket 型別
response 是否有穩定 ok、code、message 格式
錯誤 action 是否回 error message，而不是直接關閉連線
router 測試是否覆蓋成功、未知 action、invalid JSON、invalid payload
usecase 測試是否直接使用 command

設計檢查

檢查一：handler 只處理傳輸邊界

handler 只處理讀寫、編碼與連線狀態，可以讓 HTTP API、CLI 或背景工作共用同一個 usecase。handler 直接改 map、slice 或 repository 時，傳輸協定和業務規則會綁在一起。

檢查二：payload 轉成明確 command

map[string]any 適合短暫承接未知 JSON，不適合傳進 usecase。usecase 應該接收明確 command，讓欄位、型別與驗證規則可讀可測。

檢查三：action 失敗和連線失敗分開處理

單一 action payload 錯誤不代表 WebSocket 連線壞掉。多數 client input error 應該用 error response 表達，避免 client 因小錯誤被斷線。

檢查四：router interface 跟著 usecase 成長

router 依賴的 interface 應該由當下需要的 usecase 定義。過早建立大型 service interface，會讓每個測試都被迫實作不相關方法。

本章不處理

本章先處理單一 server 內的 action routing 與 response contract；完整 WebSocket lifecycle 與跨節點推送，會在下列章節再往外延伸：

和 Go 教材的關係

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

6.2 如何新增一種 domain event

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

新增 domain event 的核心流程是先定義事件語意，再決定哪些外部來源可以轉成這個事件。事件是系統內部對「發生了什麼」的穩定合約，常數清單只是其中一種表達方式。

本章目標

學完本章後，你將能夠：

判斷 event type 是否代表穩定 domain fact
用 DomainEvent envelope 承接不同外部來源
把 raw input 轉成內部事件，而不是直接更新狀態
設計 validation 與 dedup key
把 normalize、processor 與 repository 測試分開

【觀察】event type 代表已經發生的事

domain event 的核心語意是「某件對系統有意義的事已經發生」。command 表達意圖，event 表達事實；兩者的命名與處理責任要分開。

例如：

名稱	類型	語意
`subscribe_topic`	command/action	client 想訂閱 topic
`notification.created`	event	一筆通知已建立
`job.started`	event	一個 job 已開始
`account.status_changed`	event	account 狀態已改變

event type 應該用過去式或事實語氣。notification.created 比 notification.create 更能表達事件語意。這個命名差異會影響後續設計：事件處理器應該處理已發生事實，授權與意圖判斷則留在 command/usecase。

用 typed constant 可以集中 event type：

1type EventType string
2
3const (
4    EventNotificationCreated EventType = "notification.created"
5    EventJobStarted          EventType = "job.started"
6    EventAccountStatusChanged EventType = "account.status_changed"
7)

若 event type 只是為了對應外部欄位名稱，還沒有內部語意，應先把外部 raw input normalize，再判斷它是否真的代表一個穩定事實。

【判讀】DomainEvent 是內部事件合約

DomainEvent 的核心責任是提供統一 envelope，讓不同來源的事件進入系統後使用同一種語意模型。HTTP callback、client action、timer 或 queue message 都可以被 adapter 轉成 DomainEvent。

 1type EventSource string
 2
 3const (
 4    SourceClientCommand EventSource = "client_command"
 5    SourceHTTPCallback  EventSource = "http_callback"
 6    SourceTimer         EventSource = "timer"
 7)
 8
 9type SubjectKind string
10
11const (
12    SubjectNotification SubjectKind = "notification"
13    SubjectJob          SubjectKind = "job"
14    SubjectAccount      SubjectKind = "account"
15)
16
17type DomainEvent struct {
18    ID            string          `json:"id"`
19    Source        EventSource     `json:"source"`
20    Type          EventType       `json:"type"`
21    SubjectID     string          `json:"subjectId"`
22    SubjectKind   SubjectKind     `json:"subjectKind"`
23    CorrelationID string          `json:"correlationId,omitempty"`
24    CausationID   string          `json:"causationId,omitempty"`
25    OccurredAt    time.Time       `json:"occurredAt"`
26    ReceivedAt    time.Time       `json:"receivedAt"`
27    SchemaVersion int             `json:"schemaVersion"`
28    Payload       json.RawMessage `json:"payload,omitempty"`
29}

SubjectID 和 SubjectKind 用來描述事件作用在哪個對象上。OccurredAt 表示事件實際發生時間，ReceivedAt 表示系統收到事件的時間。這兩個時間不能混用，因為外部事件可能延遲送達。

CorrelationID 用來串起同一個使用者操作或 request 造成的一串事件。CausationID 用來記錄這筆事件是由哪個 command 或事件引起。初期可以先保留欄位，不必一開始就建立完整 tracing 系統。

【策略】payload 是補充資料

event envelope 的核心語意應該放在固定欄位。Payload 適合存事件特有資料，事件分類、主體、時間與來源則應維持在第一層欄位。

例如通知建立事件的 payload 可以是：

1type NotificationCreatedPayload struct {
2    Topic string `json:"topic"`
3    Title string `json:"title"`
4}

建立 event 時，把穩定欄位放在 envelope：

 1func NewNotificationCreatedEvent(id string, notificationID string, payload NotificationCreatedPayload, now time.Time) (DomainEvent, error) {
 2    data, err := json.Marshal(payload)
 3    if err != nil {
 4        return DomainEvent{}, fmt.Errorf("marshal notification payload: %w", err)
 5    }
 6
 7    return DomainEvent{
 8        ID:            id,
 9        Source:        SourceClientCommand,
10        Type:          EventNotificationCreated,
11        SubjectID:     notificationID,
12        SubjectKind:   SubjectNotification,
13        OccurredAt:    now,
14        ReceivedAt:    now,
15        SchemaVersion: 1,
16        Payload:       data,
17    }, nil
18}

這個函式把事件建立規則集中起來。未來若要補 schema version、correlation ID 或預設時間，也不需要在每個呼叫端重複組 struct。

【執行】adapter 負責 raw input 轉換

adapter 的核心責任是把外部格式轉成內部事件。repository 更新交給 processor 或 usecase，raw payload 也應先轉成內部穩定模型再進入 domain layer。

假設外部 HTTP callback 長這樣：

1type RawNotificationCallback struct {
2    EventID        string `json:"event_id"`
3    NotificationID string `json:"notification_id"`
4    EventName      string `json:"event_name"`
5    Topic          string `json:"topic"`
6    Title          string `json:"title"`
7    Timestamp      string `json:"timestamp"`
8}

normalize 函式可以把它轉成 DomainEvent：

 1func NormalizeNotificationCallback(raw RawNotificationCallback, receivedAt time.Time) (DomainEvent, error) {
 2    occurredAt, err := time.Parse(time.RFC3339, raw.Timestamp)
 3    if err != nil {
 4        return DomainEvent{}, fmt.Errorf("parse callback timestamp: %w", err)
 5    }
 6
 7    payload := NotificationCreatedPayload{
 8        Topic: raw.Topic,
 9        Title: raw.Title,
10    }
11
12    data, err := json.Marshal(payload)
13    if err != nil {
14        return DomainEvent{}, fmt.Errorf("marshal callback payload: %w", err)
15    }
16
17    event := DomainEvent{
18        ID:            raw.EventID,
19        Source:        SourceHTTPCallback,
20        Type:          EventNotificationCreated,
21        SubjectID:     raw.NotificationID,
22        SubjectKind:   SubjectNotification,
23        OccurredAt:    occurredAt,
24        ReceivedAt:    receivedAt,
25        SchemaVersion: 1,
26        Payload:       data,
27    }
28
29    if err := event.Validate(); err != nil {
30        return DomainEvent{}, err
31    }
32
33    return event, nil
34}

這段程式把外部欄位名稱、時間格式與 payload 組裝限制在 adapter 內。下游 processor 只需要理解 DomainEvent，不需要知道 callback 原始格式。

【判讀】validation 保護事件合約

event validation 的核心目標是確保事件語意完整。缺少 ID、type、subject 或時間的 event 進入 processor 後，狀態更新與去重都會失去依據。

 1func (e DomainEvent) Validate() error {
 2    if strings.TrimSpace(e.ID) == "" {
 3        return fmt.Errorf("event id is required")
 4    }
 5    if e.Type == "" {
 6        return fmt.Errorf("event type is required")
 7    }
 8    if strings.TrimSpace(e.SubjectID) == "" {
 9        return fmt.Errorf("subject id is required")
10    }
11    if e.SubjectKind == "" {
12        return fmt.Errorf("subject kind is required")
13    }
14    if e.OccurredAt.IsZero() {
15        return fmt.Errorf("occurred at is required")
16    }
17    if e.ReceivedAt.IsZero() {
18        return fmt.Errorf("received at is required")
19    }
20    if e.SchemaVersion <= 0 {
21        return fmt.Errorf("schema version must be positive")
22    }
23    return nil
24}

validation 應該檢查事件 envelope 的基本合約。更細的 payload 規則可以在 normalize 或 processor 中處理，依資料來源與用途決定。

【策略】去重鍵應建立在 domain 語意上

event dedup 的核心規則是使用語意鍵。不同來源可能用不同格式描述同一件事，但只要 subject、type 與時間窗口相同，就可能是重複事件。

 1type DedupKey struct {
 2    SubjectKind SubjectKind
 3    SubjectID   string
 4    Type        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        Type:        event.Type,
13        Window:      event.OccurredAt.UnixNano() / int64(window),
14    }
15}

去重鍵應排除 ReceivedAt、raw metadata 或 request ID 這類每次都可能不同的欄位。那些欄位適合記錄觀測資訊，不適合作為「是否同一件事」的判斷依據。

若事件 ID 由可靠上游產生，可以優先用 event ID 去重。若上游 ID 不穩定，才需要 domain dedup key。這個選擇應該寫成明確規則，讓 map key 的組成方式對應可理解的去重語意。

【執行】processor 負責套用事件規則

event processor 的核心責任是驗證、去重、更新狀態與發布結果。processor 不負責讀 HTTP request，也不負責解析 WebSocket message。

 1type EventRepository interface {
 2    Apply(ctx context.Context, event DomainEvent) error
 3}
 4
 5type EventPublisher interface {
 6    Publish(ctx context.Context, event DomainEvent) error
 7}
 8
 9type Deduper interface {
10    Seen(event DomainEvent) bool
11}

processor 可以依賴這些小介面：

 1type EventProcessor struct {
 2    repository EventRepository
 3    publisher  EventPublisher
 4    deduper    Deduper
 5}
 6
 7func NewEventProcessor(repository EventRepository, publisher EventPublisher, deduper Deduper) *EventProcessor {
 8    return &EventProcessor{
 9        repository: repository,
10        publisher:  publisher,
11        deduper:    deduper,
12    }
13}

處理流程保持短而明確：

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

這個 processor 不知道資料來自哪裡，也不知道 repository 是 memory map 還是資料庫。這種邊界讓新增 event source 時不需要重寫狀態規則。

【執行】normalize 測試要固定外部輸入

normalize 測試的核心目標是確認 raw input 會被轉成正確內部事件。這類測試應該固定時間，避免測試依賴真實現在時間。

 1func TestNormalizeNotificationCallback(t *testing.T) {
 2    receivedAt := time.Date(2026, 4, 22, 10, 1, 0, 0, time.UTC)
 3    raw := RawNotificationCallback{
 4        EventID:        "evt_1",
 5        NotificationID: "ntf_1",
 6        EventName:      "notification_created",
 7        Topic:          "deployments",
 8        Title:          "Deploy finished",
 9        Timestamp:      "2026-04-22T10:00:00Z",
10    }
11
12    event, err := NormalizeNotificationCallback(raw, receivedAt)
13    if err != nil {
14        t.Fatalf("normalize callback: %v", err)
15    }
16
17    if event.Type != EventNotificationCreated {
18        t.Fatalf("event type = %q, want %q", event.Type, EventNotificationCreated)
19    }
20    if event.SubjectID != "ntf_1" {
21        t.Fatalf("subject ID = %q, want %q", event.SubjectID, "ntf_1")
22    }
23    if !event.ReceivedAt.Equal(receivedAt) {
24        t.Fatalf("received at = %v, want %v", event.ReceivedAt, receivedAt)
25    }
26}

這個測試不需要 repository，也不需要 publisher。它只保護 adapter 的轉換規則。

【執行】processor 測試要隔離外部來源

processor 測試的核心目標是確認事件規則被正確套用。測試應該直接建立 DomainEvent，讓 HTTP 或 WebSocket 解析留在 adapter 測試。

 1type fakeEventRepository struct {
 2    applied []DomainEvent
 3}
 4
 5func (f *fakeEventRepository) Apply(ctx context.Context, event DomainEvent) error {
 6    f.applied = append(f.applied, event)
 7    return nil
 8}
 9
10type fakeEventPublisher struct {
11    published []DomainEvent
12}
13
14func (f *fakeEventPublisher) Publish(ctx context.Context, event DomainEvent) error {
15    f.published = append(f.published, event)
16    return nil
17}
18
19type neverSeenDeduper struct{}
20
21func (neverSeenDeduper) Seen(event DomainEvent) bool {
22    return false
23}

成功案例可以確認 repository 與 publisher 都被呼叫：

 1func TestEventProcessorProcess(t *testing.T) {
 2    repo := &fakeEventRepository{}
 3    publisher := &fakeEventPublisher{}
 4    processor := NewEventProcessor(repo, publisher, neverSeenDeduper{})
 5
 6    event := DomainEvent{
 7        ID:            "evt_1",
 8        Source:        SourceHTTPCallback,
 9        Type:          EventNotificationCreated,
10        SubjectID:     "ntf_1",
11        SubjectKind:   SubjectNotification,
12        OccurredAt:    time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
13        ReceivedAt:    time.Date(2026, 4, 22, 10, 1, 0, 0, time.UTC),
14        SchemaVersion: 1,
15    }
16
17    if err := processor.Process(context.Background(), event); err != nil {
18        t.Fatalf("process event: %v", err)
19    }
20
21    if len(repo.applied) != 1 {
22        t.Fatalf("applied events = %d, want 1", len(repo.applied))
23    }
24    if len(publisher.published) != 1 {
25        t.Fatalf("published events = %d, want 1", len(publisher.published))
26    }
27}

processor 測試使用 fake repository、publisher 或 deduper，就能隔離事件規則。真實 message broker 或資料庫屬於 adapter integration test。

實作檢查清單

新增 domain event 時，可以依序檢查：

event type 是否描述已經發生的事
event type 是否是內部穩定語意，而不是外部欄位名稱
envelope 是否包含 source、type、subject、occurred/received time
payload 是否只放事件特有補充資料
raw input 是否先經過 adapter normalize
adapter 是否不直接更新 repository
validation 是否保護事件基本合約
dedup key 是否建立在 domain 語意上
normalize、processor、repository 是否分開測試

設計檢查

檢查一：command 和 event 分開命名

create_notification 是想做某件事，notification.created 是某件事已發生。把兩者混在一起，會讓 processor 不清楚自己是在判斷授權、執行行為，還是在套用事實。

檢查二：raw payload 停在 adapter

raw payload 會帶有外部來源格式、命名與缺漏。domain layer 應該面對內部穩定模型，外部格式應該停在 adapter。

檢查三：穩定欄位放在 envelope

如果 type、subject、time 都藏在 payload，processor、deduper、repository 都必須解析 payload 才能做事。這會讓事件系統難測，也難以演進 schema。

檢查四：事件順序使用發生時間

ReceivedAt 是系統看到事件的時間，不一定是事件發生時間。狀態轉移通常應該優先看 OccurredAt，再根據延遲與來源可靠度設計補償規則。

本章不處理

本章先處理 domain event 的定義、轉換與發布；event store 與 broker 傳遞，會在下列章節再往外延伸：

和 Go 教材的關係

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

6.3 如何擴展狀態投影欄位

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

擴展狀態投影欄位的核心流程是先確認欄位屬於 domain state、read model 還是 response view。欄位加在哪一層，會決定寫入規則、相容性與測試方式。

本章目標

學完本章後，你將能夠：

分辨 domain state、read model 與 response view
判斷新欄位的零值是否有語意
把狀態轉移集中在 repository 或 state owner
用 copy boundary 保護內部 slice/map
測試 state transition、repository copy 與 JSON response

【觀察】先判斷欄位屬於哪一層

狀態欄位的核心問題是「這個欄位代表哪一種資料責任」。同一個欄位放在不同層，代表不同寫入規則與相容性承諾。

層次	意義	範例
domain state	影響業務規則與狀態轉移	job 是否 running、failed、completed
projection/read model	方便查詢、列表或即時顯示	最近更新時間、目前進度百分比
response view	只影響對外輸出格式	顯示文字、前端用 badge 顏色

例如「job 狀態」是 domain state，因為它會影響是否能重試、取消或完成。相反地，「狀態顯示文字」通常是 response view，因為它只是把內部狀態轉成 client 更容易顯示的文字。

本章使用一個簡化的 job 狀態投影作為範例。事件進入系統後，repository 會把事件套用成目前 projection，再由 response layer 輸出給 client。

【判讀】domain state 要用明確型別

domain state 的核心規則是用型別表達可用狀態，而不是讓任意字串在系統裡流動。當欄位會影響規則時，應該優先考慮 typed constant。

1type JobStatus string
2
3const (
4    JobStatusPending   JobStatus = "pending"
5    JobStatusRunning   JobStatus = "running"
6    JobStatusSucceeded JobStatus = "succeeded"
7    JobStatusFailed    JobStatus = "failed"
8)

接著定義狀態投影：

1type JobProjection struct {
2    ID         string
3    Status     JobStatus
4    Progress   int
5    UpdatedAt  time.Time
6    FinishedAt time.Time
7}

Status 是 domain state。Progress 可以是 read model 欄位，代表目前顯示用進度。FinishedAt 需要進一步判斷：如果完成時間會影響重試、保留時間或排序，它就不只是 response 欄位。

零值也要有語意。FinishedAt 的零值可以代表「尚未完成」，但這個語意必須被程式明確處理；若零值會造成混淆，可以改用 pointer：

1type JobProjection struct {
2    ID         string
3    Status     JobStatus
4    Progress   int
5    UpdatedAt  time.Time
6    FinishedAt *time.Time
7}

pointer 在這裡的用途是區分「沒有值」和「有一個零值」。時間、數字與 bool 欄位最常遇到這個問題。

【策略】狀態轉移要集中在同一個入口

狀態轉移的核心規則是所有寫入都經過同一組方法。handler、worker 或 WebSocket router 應把狀態變更交給 repository 或 state owner，而不是自行修改 map 或 projection 欄位。

先定義內部 event：

1type JobEvent struct {
2    JobID      string
3    Type       string
4    Progress   int
5    OccurredAt time.Time
6}

repository 可以集中套用事件：

 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}

Apply 是狀態寫入入口：

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

這段程式讓狀態轉移規則集中在 repository。未來如果要禁止 failed job 重新變成 running，或要求 progress 不可倒退，可以在同一個入口加規則與測試。

【判讀】read model 可以為查詢服務

read model 的核心用途是讓查詢與顯示更直接。它不一定等同完整 domain state，而是為某種讀取需求整理出的投影。

例如列表頁可能只需要 summary：

1type JobSummary struct {
2    ID        string
3    Status    JobStatus
4    Progress  int
5    UpdatedAt time.Time
6}

repository 可以提供查詢方法：

 1func (r *JobRepository) ListSummaries() []JobSummary {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    result := make([]JobSummary, 0, len(r.jobs))
 6    for _, job := range r.jobs {
 7        result = append(result, JobSummary{
 8            ID:        job.ID,
 9            Status:    job.Status,
10            Progress:  job.Progress,
11            UpdatedAt: job.UpdatedAt,
12        })
13    }
14    return result
15}

這個方法回傳新 slice，而不是暴露 repository 內部資料。若 read model 包含 slice、map 或 pointer，也要確認呼叫端不能修改內部狀態。

【執行】讀取方法要保護 copy boundary

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

單筆查詢可以回傳值與 bool：

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

若 struct 內含 pointer，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}

這個 clone 看似瑣碎，但它保護了 repository 的擁有權。呼叫端拿到資料後，即使修改 FinishedAt 指向的時間，也不會影響 repository 內部狀態。

【策略】response view 負責對外格式

response view 的核心責任是把內部狀態轉成外部 contract。JSON tag、omitempty、顯示文字與相容性都應該在 response struct 中處理，讓 domain model 保持在業務狀態語意上。

1type JobResponse struct {
2    ID          string     `json:"id"`
3    Status      JobStatus  `json:"status"`
4    Progress    int        `json:"progress"`
5    UpdatedAt   time.Time  `json:"updatedAt"`
6    FinishedAt  *time.Time `json:"finishedAt,omitempty"`
7    DisplayText string     `json:"displayText,omitempty"`
8}

轉換函式可以集中 response 規則：

 1func NewJobResponse(job JobProjection) JobResponse {
 2    return JobResponse{
 3        ID:          job.ID,
 4        Status:      job.Status,
 5        Progress:    job.Progress,
 6        UpdatedAt:   job.UpdatedAt,
 7        FinishedAt:  job.FinishedAt,
 8        DisplayText: displayText(job.Status),
 9    }
10}
11
12func displayText(status JobStatus) string {
13    switch status {
14    case JobStatusPending:
15        return "Waiting"
16    case JobStatusRunning:
17        return "Running"
18    case JobStatusSucceeded:
19        return "Completed"
20    case JobStatusFailed:
21        return "Failed"
22    default:
23        return "Unknown"
24    }
25}

DisplayText 是 response view，負責呈現用文字。若未來前端改文案，response 轉換函式可以調整，repository 狀態轉移規則應保持穩定。

【判讀】`omitempty` 是相容性語意

omitempty 的核心語意是欄位在某些情境中可以不存在。它在對外 contract 中表示「這個欄位可能不存在」，而不是只為了縮短 JSON。

例如 FinishedAt 只有 job 完成或失敗後才有值：

1FinishedAt *time.Time `json:"finishedAt,omitempty"`

舊 client 如果不知道 finishedAt，通常會忽略新欄位。新 client 如果需要這個欄位，也必須處理它不存在的情況。

必填欄位的 JSON contract 應保持穩定輸出。id 或 status 這類欄位消失會讓 client 無法理解資料，因此它們屬於必要欄位，應維持固定輸出。

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

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

 1func TestJobRepositoryApplySucceeded(t *testing.T) {
 2    repo := NewJobRepository()
 3    finishedAt := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 4
 5    err := repo.Apply(JobEvent{
 6        JobID:      "job_1",
 7        Type:       "job.succeeded",
 8        OccurredAt: finishedAt,
 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 != JobStatusSucceeded {
19        t.Fatalf("status = %q, want %q", job.Status, JobStatusSucceeded)
20    }
21    if job.Progress != 100 {
22        t.Fatalf("progress = %d, want 100", job.Progress)
23    }
24    if job.FinishedAt == nil || !job.FinishedAt.Equal(finishedAt) {
25        t.Fatalf("finished at = %v, want %v", job.FinishedAt, finishedAt)
26    }
27}

這個測試保護的是狀態規則，而不是輸出 JSON 格式。

【執行】copy boundary 測試要嘗試修改回傳值

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

 1func TestJobRepositoryGetReturnsCopy(t *testing.T) {
 2    repo := NewJobRepository()
 3    finishedAt := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 4
 5    _ = repo.Apply(JobEvent{
 6        JobID:      "job_1",
 7        Type:       "job.succeeded",
 8        OccurredAt: finishedAt,
 9    })
10
11    job, ok := repo.Get("job_1")
12    if !ok {
13        t.Fatalf("job should exist")
14    }
15
16    changed := finishedAt.Add(time.Hour)
17    job.FinishedAt = &changed
18
19    again, _ := repo.Get("job_1")
20    if again.FinishedAt == nil || !again.FinishedAt.Equal(finishedAt) {
21        t.Fatalf("repository state was modified through returned value")
22    }
23}

這種測試對 map、slice、pointer 特別重要。值型別欄位通常不需要額外 clone，但一旦 struct 包含可變參照，就要測邊界。

【執行】response JSON 測試要檢查 contract

response 測試的核心目標是確認對外 JSON 欄位符合 contract。測試應該解析 JSON 或檢查欄位存在性，而不是只比對整段字串。

 1func TestJobResponseOmitsFinishedAtWhenNil(t *testing.T) {
 2    response := NewJobResponse(JobProjection{
 3        ID:        "job_1",
 4        Status:    JobStatusRunning,
 5        Progress:  40,
 6        UpdatedAt: time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
 7    })
 8
 9    data, err := json.Marshal(response)
10    if err != nil {
11        t.Fatalf("marshal response: %v", err)
12    }
13
14    var body map[string]any
15    if err := json.Unmarshal(data, &body); err != nil {
16        t.Fatalf("unmarshal response: %v", err)
17    }
18
19    if _, ok := body["finishedAt"]; ok {
20        t.Fatalf("finishedAt should be omitted when nil")
21    }
22}

這個測試是測對外承諾的欄位語意。

實作檢查清單

擴展狀態投影欄位時，可以依序檢查：

欄位屬於 domain state、read model 還是 response view
零值是否有明確語意
是否需要 typed constant
寫入是否集中在 repository 或 state owner
handler、router、worker 是否沒有直接修改內部 map/slice
查詢是否回傳 copy
response 是否使用正確 JSON tag
omitempty 是否真的代表可選欄位
測試是否分成 state transition、copy boundary、response JSON

設計檢查

檢查一：顯示欄位放在 response view

顯示文字、顏色或前端 badge 通常是 response view。只有影響業務規則的欄位，才需要進入 domain state。

檢查二：handler 透過狀態入口修改 projection

handler 透過 repository 或 state owner 修改 projection，可以讓狀態規則集中。handler 直接改 projection 時，新增第二個入口容易漏掉同一套規則。

檢查三：回傳資料保護 copy boundary

只要呼叫端能修改 repository 內部資料，狀態邊界就失效。回傳值時要檢查是否需要 clone。

檢查四：`omitempty` 對應可選欄位

必填欄位加上 omitempty 會讓 response contract 變模糊。欄位是否可省略，應由資料語意決定，而不是由欄位零值方便性決定。

本章不處理

本章先處理狀態欄位如何影響 response contract；資料庫 migration 與前端相容性策略，會在下列章節再往外延伸：

和 Go 教材的關係

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

6.4 如何新增背景工作流程

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

新增背景工作流程的核心規則是先定義生命週期，再定義資料流。worker 是有 context、輸入、輸出、錯誤處理與 shutdown 協定的長期元件。

本章目標

學完本章後，你將能夠：

判斷一段工作是否適合做成 worker
用 Run(ctx) 設計 worker 生命週期
用 channel 和 ticker 表達資料流與週期性工作
處理 queue full、shutdown 與錯誤記錄
分開測試 SyncOnce、Run(ctx) 與 channel 行為

【觀察】worker 是有生命週期的元件

worker 的核心定義是長時間運行、可被啟動、可被取消、會消費輸入或定期執行工作的元件。任意程式碼包進 go func() 只能產生背景 goroutine，還需要生命週期協定才會成為可維護的 worker。

適合做成 worker 的工作通常有三種：

工作類型	範例	worker 責任
queue consumer	從 channel 讀取外部事件	驗證、轉送 processor
periodic task	每 30 秒同步一次外部狀態	產生 command 或 event
cleanup task	定期清理過期資料	呼叫 repository 或 usecase 的清理方法

本章使用「通知同步 worker」作為範例。它定期向外部來源取得通知更新，轉成 domain event，再交給 EventProcessor 處理。

【判讀】worker 責任要先寫清楚

worker 責任的核心問題是它消費什麼、產生什麼、交給誰處理。worker 應聚焦在資料取得、格式轉換與轉交處理器，業務規則、狀態更新與 client 推送要留給對應的 usecase 或 processor。

先定義外部來源：

 1type NotificationSource interface {
 2    FetchUpdates(ctx context.Context) ([]RawNotificationUpdate, error)
 3}
 4
 5type RawNotificationUpdate struct {
 6    ID             string
 7    NotificationID string
 8    Topic          string
 9    Title          string
10    OccurredAt     time.Time
11}

再定義 worker 會呼叫的處理器：

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

worker 的責任是把外部更新取回來、normalize 成 DomainEvent、交給 processor。repository 寫入與推送規則仍然留在 processor 或 usecase 裡。

【策略】把單次工作獨立成 `SyncOnce`

worker 的核心設計技巧是把「單次工作」和「長時間迴圈」分開。SyncOnce 負責做一次同步，Run(ctx) 負責週期性呼叫它。

 1type SyncWorker struct {
 2    source    NotificationSource
 3    processor EventProcessor
 4    logger    *slog.Logger
 5}
 6
 7func NewSyncWorker(source NotificationSource, processor EventProcessor, logger *slog.Logger) *SyncWorker {
 8    return &SyncWorker{
 9        source:    source,
10        processor: processor,
11        logger:    logger,
12    }
13}

SyncOnce 可以像普通函式一樣測試：

 1func (w *SyncWorker) SyncOnce(ctx context.Context) error {
 2    updates, err := w.source.FetchUpdates(ctx)
 3    if err != nil {
 4        return fmt.Errorf("fetch notification updates: %w", err)
 5    }
 6
 7    for _, update := range updates {
 8        event, err := NormalizeNotificationUpdate(update, time.Now())
 9        if err != nil {
10            w.logger.Warn("skip invalid notification update", "id", update.ID, "error", err)
11            continue
12        }
13
14        if err := w.processor.Process(ctx, event); err != nil {
15            return fmt.Errorf("process notification update %s: %w", update.ID, err)
16        }
17    }
18
19    return nil
20}

這裡的 time.Now() 先展示基本寫法；如果測試需要固定時間，可以把 clock 注入進 worker。時間注入會在後面測試章節更完整處理。

【執行】`Run(ctx)` 管理長時間生命週期

Run(ctx) 的核心責任是等待 ticker、呼叫單次工作、尊重取消訊號。它應該在 context 被取消時退出，並釋放 ticker。

 1func (w *SyncWorker) Run(ctx context.Context, interval time.Duration) error {
 2    ticker := time.NewTicker(interval)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return ctx.Err()
 9        case <-ticker.C:
10            if err := w.SyncOnce(ctx); err != nil {
11                w.logger.Error("sync worker failed", "error", err)
12            }
13        }
14    }
15}

這個版本把單次同步錯誤記錄下來，但不讓 worker 退出。這是策略選擇：若外部來源短暫失敗，worker 可以等待下一輪；若錯誤代表設定失效或授權失效，則可以選擇 return error 讓上層重啟或停止服務。

worker 錯誤策略應該明確。暫時性錯誤通常要記錄後等待下一輪；致命設定錯誤則可以回傳給上層，讓服務決定重啟或停止。

【判讀】channel worker 要設計 backpressure

channel worker 的核心問題是接收端跟不上時要怎麼辦。buffer 大小、blocking send、non-blocking send 都是在回答 backpressure 策略。

假設外部 HTTP callback 會把 raw update 送進 worker queue：

 1type QueueWorker struct {
 2    updates   chan RawNotificationUpdate
 3    processor EventProcessor
 4    logger    *slog.Logger
 5}
 6
 7func NewQueueWorker(processor EventProcessor, logger *slog.Logger, bufferSize int) *QueueWorker {
 8    return &QueueWorker{
 9        updates:   make(chan RawNotificationUpdate, bufferSize),
10        processor: processor,
11        logger:    logger,
12    }
13}

送入 queue 可以選擇 blocking 或 non-blocking。若呼叫端不能被背景處理拖慢，可以用 non-blocking send 並回傳錯誤：

 1var ErrQueueFull = errors.New("notification update queue full")
 2
 3func (w *QueueWorker) Enqueue(update RawNotificationUpdate) error {
 4    select {
 5    case w.updates <- update:
 6        return nil
 7    default:
 8        return ErrQueueFull
 9    }
10}

這個設計很誠實：queue 滿了就是系統忙碌。上層可以記錄 log、回 503，或告訴 client 稍後重試。

【執行】queue worker 要同時監聽輸入與取消

queue worker 的核心生命週期是等待 update 或 context cancel。Run(ctx) 裡應用 select 同時處理這兩件事。

 1func (w *QueueWorker) Run(ctx context.Context) error {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            return ctx.Err()
 6        case update, ok := <-w.updates:
 7            if !ok {
 8                return nil
 9            }
10            if err := w.handleUpdate(ctx, update); err != nil {
11                w.logger.Error("handle notification update failed", "id", update.ID, "error", err)
12            }
13        }
14    }
15}

handleUpdate 負責單筆資料轉換與處理：

1func (w *QueueWorker) handleUpdate(ctx context.Context, update RawNotificationUpdate) error {
2    event, err := NormalizeNotificationUpdate(update, time.Now())
3    if err != nil {
4        return fmt.Errorf("normalize update: %w", err)
5    }
6    return w.processor.Process(ctx, event)
7}

這裡仍然遵守同一條邊界：worker 不直接改 repository，只把事件交給 processor。

【策略】shutdown 是否 drain queue 要先決定

shutdown 的核心決策是取消時要立刻停止，還是處理完 queue 中既有資料。兩種策略都合理，但語意不同。

策略	做法	適用情境
立即停止	收到 `ctx.Done()` 就 return	即時通知、可重試資料
drain queue	停止接收新資料，處理已排隊資料	不可輕易丟棄的資料

立即停止比較簡單：

1case <-ctx.Done():
2    return ctx.Err()

drain queue 則需要另一個停止接收的協定，例如由擁有送出端的一方關閉 channel，再讓 worker range 到 channel 關閉。channel close 的所有權要留在送出端，因為送出端最清楚是否還會送資料。

這裡的核心區分是「取消 context」和「關閉 channel」代表不同訊號。context 表示這件工作該停了；channel close 表示不會再有新資料。兩者可以搭配，但語意不同。

【判讀】worker 使用服務生命週期 context

worker context 的核心規則是：長時間 worker 使用服務生命週期 context，單次工作可以另外接收 request context。某個 HTTP request 的 context 只適合控制該次請求；request 結束後 context 會被取消。

1func (w *QueueWorker) Enqueue(update RawNotificationUpdate) error {
2    select {
3    case w.updates <- update:
4        return nil
5    default:
6        return ErrQueueFull
7    }
8}

Enqueue 不把 request context 存起來。真正處理 update 時，worker 使用自己的 Run(ctx) context 控制生命週期。

若某筆 update 需要保留 request ID 或 correlation ID，應把它放進明確欄位，而不是依賴 context value 在背景工作中長期存在。

【執行】`SyncOnce` 測試要隔離時間與外部來源

SyncOnce 測試的核心目標是確認單次工作會把外部資料交給 processor。測試重點放在單次同步，不需要等待真實 ticker。

 1type fakeNotificationSource struct {
 2    updates []RawNotificationUpdate
 3    err     error
 4}
 5
 6func (f fakeNotificationSource) FetchUpdates(ctx context.Context) ([]RawNotificationUpdate, error) {
 7    if f.err != nil {
 8        return nil, f.err
 9    }
10    return f.updates, nil
11}
12
13type recordingProcessor struct {
14    events []DomainEvent
15}
16
17func (p *recordingProcessor) Process(ctx context.Context, event DomainEvent) error {
18    p.events = append(p.events, event)
19    return nil
20}

測試單次同步：

 1func TestSyncWorkerSyncOnce(t *testing.T) {
 2    source := fakeNotificationSource{
 3        updates: []RawNotificationUpdate{
 4            {
 5                ID:             "evt_1",
 6                NotificationID: "ntf_1",
 7                Topic:          "deployments",
 8                Title:          "Deploy finished",
 9                OccurredAt:     time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
10            },
11        },
12    }
13    processor := &recordingProcessor{}
14    worker := NewSyncWorker(source, processor, slog.Default())
15
16    if err := worker.SyncOnce(context.Background()); err != nil {
17        t.Fatalf("sync once: %v", err)
18    }
19
20    if len(processor.events) != 1 {
21        t.Fatalf("processed events = %d, want 1", len(processor.events))
22    }
23}

這個測試不需要 goroutine。先把單次工作測清楚，再測長時間生命週期。

【執行】`Run(ctx)` 測試要能快速取消

Run(ctx) 測試的核心目標是確認 worker 會尊重取消訊號。測試應該使用已取消或很短的 context，讓測試快速結束。

 1func TestSyncWorkerRunStopsWhenContextCanceled(t *testing.T) {
 2    source := fakeNotificationSource{}
 3    processor := &recordingProcessor{}
 4    worker := NewSyncWorker(source, processor, slog.Default())
 5
 6    ctx, cancel := context.WithCancel(context.Background())
 7    cancel()
 8
 9    err := worker.Run(ctx, time.Hour)
10    if !errors.Is(err, context.Canceled) {
11        t.Fatalf("error = %v, want context.Canceled", err)
12    }
13}

這個測試用 time.Hour 當 interval，因為 context 已經取消，Run 應該立刻退出，不需要等 ticker。

【執行】queue full 測試要固定 buffer

queue full 測試的核心目標是確認 backpressure 策略。buffer 設成 1，先塞滿，再確認第二次 enqueue 回錯。

 1func TestQueueWorkerEnqueueFull(t *testing.T) {
 2    worker := NewQueueWorker(&recordingProcessor{}, slog.Default(), 1)
 3
 4    err := worker.Enqueue(RawNotificationUpdate{ID: "evt_1"})
 5    if err != nil {
 6        t.Fatalf("first enqueue: %v", err)
 7    }
 8
 9    err = worker.Enqueue(RawNotificationUpdate{ID: "evt_2"})
10    if !errors.Is(err, ErrQueueFull) {
11        t.Fatalf("error = %v, want ErrQueueFull", err)
12    }
13}

這個測試不啟動 worker，所以 channel 裡第一筆資料不會被消費，第二筆必然遇到 full。這比用 sleep 製造滿載狀態穩定。

實作檢查清單

新增 background worker 時，可以依序檢查：

worker 責任是否明確：消費什麼，產生什麼，交給誰
是否有 Run(ctx) 作為生命週期入口
單次工作是否拆成 SyncOnce 或 handleUpdate
worker 是否尊重 ctx.Done()
ticker 是否 defer Stop()
channel buffer 是否有明確 backpressure 策略
queue full 是否回錯或記錄，而不是靜默丟棄
worker 是否呼叫 usecase/processor，而不是直接改 repository
測試是否避免真實長時間 sleep

設計檢查

檢查一：goroutine 要有停止條件

長時間 goroutine 需要 context、channel close 或其他退出條件。缺少停止條件時，服務運行越久，越容易累積難以診斷的資源問題。

檢查二：worker 透過 processor 或 usecase 修改狀態

worker 透過 processor 或 usecase 修改狀態，可以讓背景流程和即時流程共用同一套規則。worker 直接改 repository 時，狀態規則容易分散。

檢查三：queue full 要有明確策略

資料可以丟時，應明確記錄 log 或 metric；資料需要保留時，應 blocking 或回錯。queue full 策略明確，後續追蹤才有依據。

檢查四：測試隔離真實時間

測試優先測 SyncOnce，再用已取消 context 測 Run 的退出行為。真實 ticker 等待數秒會讓測試慢且不穩。

本章不處理

本章先處理單一背景工作如何啟動、停止與回報；cron、queue、retry 與 outbox，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 goroutine 生命週期與 event processing；如果你要先回看語言教材，可以讀：

6.5 如何新增結構化記錄欄位

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

新增結構化記錄欄位的核心規則是先判斷這筆資訊是給工程師除錯、給系統重播，還是給使用者查詢。不同用途對應不同記錄邊界，資料應依用途進入 log、event log 或 repository。

本章目標

學完本章後，你將能夠：

分辨 structured log、domain event log 與 state repository
設計穩定的 log 欄位名稱
判斷哪些資料不應寫進 log
用 EventLog.Append 表達事件記錄邊界
測試穩定欄位，而不是測自由文字

【觀察】先判斷記錄用途

記錄邊界的核心問題是資料要服務誰。工程師除錯、系統重播、使用者查詢是三種不同用途，對應三種不同儲存與格式責任。

記錄類型	用途	範例
structured log	操作診斷、除錯、聚合查詢	queue full、event rejected、worker failed
domain event log	記錄已發生事實、audit、replay	`notification.created`、`job.failed`
state repository	查詢目前狀態或投影	job current status、notification summary

structured log 服務操作診斷，event log 保存 normalized fact，state repository 回答目前狀態。先分清楚用途，才知道欄位該放哪裡。這個用途判斷比選擇哪個 logging package 更關鍵 — 工具決定怎麼寫，用途決定寫什麼、放哪裡。

【判讀】structured log 是操作訊號

structured log 的核心用途是讓工程師知道系統正在發生什麼，並且能用欄位查詢。它應該記錄操作訊號，而不是完整業務資料。

1logger.Info(
2    "event accepted",
3    "layer", "adapter",
4    "event_type", string(event.Type),
5    "event_id", event.ID,
6    "subject_id", event.SubjectID,
7    "correlation_id", event.CorrelationID,
8)

message 給人讀，欄位給查詢工具使用。若未來要查某種事件是否大量進入系統，event_type 欄位比文字搜尋更可靠。

常見 log 欄位可以先定義成 helper，避免不同地方拼出不同名稱：

 1func LogAttrsForEvent(event DomainEvent) []any {
 2    return []any{
 3        "event_id", event.ID,
 4        "event_type", string(event.Type),
 5        "subject_kind", string(event.SubjectKind),
 6        "subject_id", event.SubjectID,
 7        "correlation_id", event.CorrelationID,
 8        "schema_version", event.SchemaVersion,
 9    }
10}

使用時可以展開欄位：

1logger.Info("event accepted", LogAttrsForEvent(event)...)

這個 helper 保護的是 log schema。欄位名稱穩定，查詢與 dashboard 才能穩定。

【策略】reason 欄位要像 enum

reason 的核心語意是可聚合的原因分類。它應使用小集合穩定值；完整錯誤訊息則放在 error 欄位協助診斷。

1const (
2    ReasonInvalidPayload = "invalid_payload"
3    ReasonQueueFull      = "queue_full"
4    ReasonDuplicateEvent = "duplicate_event"
5    ReasonTimeout        = "timeout"
6)

記錄拒絕事件時：

1logger.Warn(
2    "event rejected",
3    "layer", "adapter",
4    "reason", ReasonInvalidPayload,
5    "event_type", string(event.Type),
6    "error", err,
7)

reason 用來統計，error 用來診斷，message 用來讓人快速理解。這三者不要混成一個大字串。

【判讀】event log 記錄 normalized fact

domain event log 的核心責任是保存已正規化的 domain event。它記錄的是系統承認的事實；raw request、debug log 與目前狀態分別屬於不同記錄邊界。

先定義 port：

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

memory implementation 可以先這樣寫：

 1type InMemoryEventLog struct {
 2    mu     sync.Mutex
 3    events []DomainEvent
 4}
 5
 6func NewInMemoryEventLog() *InMemoryEventLog {
 7    return &InMemoryEventLog{}
 8}
 9
10func (l *InMemoryEventLog) Append(ctx context.Context, event DomainEvent) error {
11    l.mu.Lock()
12    defer l.mu.Unlock()
13
14    l.events = append(l.events, cloneDomainEvent(event))
15    return nil
16}

event log 應該保存 DomainEvent envelope 中的穩定欄位，例如 event ID、type、subject、schema version、occurred/received time。它不需要保存 adapter 的 raw input，除非你已經明確設計 raw audit log。

【執行】event log 要保護 copy boundary

event log 的核心資料也是內部狀態。若 event 包含 slice、map 或 json.RawMessage，append 與讀取時都要避免外部修改內部資料。

1func cloneDomainEvent(event DomainEvent) DomainEvent {
2    cloned := event
3    if event.Payload != nil {
4        cloned.Payload = append(json.RawMessage(nil), event.Payload...)
5    }
6    return cloned
7}

若要提供查詢方法，也要回傳複製資料：

 1func (l *InMemoryEventLog) List() []DomainEvent {
 2    l.mu.Lock()
 3    defer l.mu.Unlock()
 4
 5    result := make([]DomainEvent, len(l.events))
 6    for i, event := range l.events {
 7        result[i] = cloneDomainEvent(event)
 8    }
 9    return result
10}

這裡展示的是教學用記錄邊界。真正 event store 還需要持久化、排序、[schema migration](/go/backend/knowledge-cards/schema-migration)、重播策略與交易語意。

【策略】state repository 保存目前狀態

state repository 的核心責任是回答目前狀態。它可以由 event 更新，但用途不同於保存所有歷史事實的 event log。

例如：

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

event log 和 state repository 可以在 processor 中各自被呼叫：

 1type RecordingEventProcessor struct {
 2    eventLog   EventLog
 3    repository JobRepository
 4    logger     *slog.Logger
 5}
 6
 7func (p *RecordingEventProcessor) Process(ctx context.Context, event DomainEvent) error {
 8    if err := p.eventLog.Append(ctx, event); err != nil {
 9        return fmt.Errorf("append event log: %w", err)
10    }
11
12    if err := p.repository.Apply(ctx, event); err != nil {
13        return fmt.Errorf("apply state projection: %w", err)
14    }
15
16    p.logger.Info("event processed", LogAttrsForEvent(event)...)
17    return nil
18}

這段程式展示三種記錄邊界：event log 保存事實，repository 更新目前狀態，structured log 記錄操作訊號。

【判讀】記錄位置要跟錯誤發生層一致

記錄位置的核心規則是在哪一層能提供最多上下文，就在哪一層記錄。同一個錯誤通常選擇一個主要層次記錄，避免 log 被重複訊號淹沒。

常見位置：

發生位置	應記錄內容
adapter	raw input decode/normalize 失敗
router/usecase	command 被拒絕、權限不足、狀態不允許
processor	event validation、dedup、projection apply 結果
worker	queue full、外部來源失敗、重試結果

例如 adapter 解碼失敗：

1logger.Warn(
2    "callback rejected",
3    "layer", "adapter",
4    "reason", ReasonInvalidPayload,
5    "payload_bytes", len(body),
6)

這裡記錄 payload 大小即可診斷資料是否異常；完整 payload 可能包含敏感資料或過大內容。

【策略】敏感資料預設不進 log

敏感資料邊界的核心規則是 log 會被保存、轉發與搜尋，所以 token、password、完整 payload、完整個資應排除在 log 之外。

可以記錄：

ID 或 opaque identifier
payload byte length
schema version
欄位是否存在
hash 或 checksum

不應記錄：

password
access token
cookie
完整 request body
完整 personal data

若需要追蹤同一筆資料，可以記錄安全識別碼：

1logger.Debug(
2    "payload received",
3    "payload_bytes", len(body),
4    "payload_sha256", sha256Hex(body),
5)

debug log 也需要遵守同樣規則；只要可能被集中收集，就要先控制敏感資料。

【執行】log helper 測試只測穩定欄位

log helper 測試的核心目標是保護欄位名稱與值。log message 文案是給人讀的內容，通常保留調整空間。

 1func TestLogAttrsForEvent(t *testing.T) {
 2    event := DomainEvent{
 3        ID:            "evt_1",
 4        Type:          EventNotificationCreated,
 5        SubjectKind:   SubjectNotification,
 6        SubjectID:     "ntf_1",
 7        CorrelationID: "corr_1",
 8        SchemaVersion: 1,
 9    }
10
11    attrs := LogAttrsForEvent(event)
12    got := attrsToMap(attrs)
13
14    if got["event_id"] != "evt_1" {
15        t.Fatalf("event_id = %v, want evt_1", got["event_id"])
16    }
17    if got["event_type"] != string(EventNotificationCreated) {
18        t.Fatalf("event_type = %v, want %s", got["event_type"], EventNotificationCreated)
19    }
20}

測試輔助函式可以把 key-value slice 轉成 map：

 1func attrsToMap(attrs []any) map[string]any {
 2    result := make(map[string]any)
 3    for i := 0; i+1 < len(attrs); i += 2 {
 4        key, ok := attrs[i].(string)
 5        if !ok {
 6            continue
 7        }
 8        result[key] = attrs[i+1]
 9    }
10    return result
11}

這個測試直接檢查 helper 輸出，不需要真的寫 log 或解析 logger output。

【執行】event log 測試要保護 append 與 copy

event log 測試的核心目標是確認事件被 append，且外部無法透過原始 payload 或回傳值修改內部紀錄。

 1func TestInMemoryEventLogAppendCopiesPayload(t *testing.T) {
 2    log := NewInMemoryEventLog()
 3    payload := json.RawMessage(`{"topic":"deployments"}`)
 4
 5    event := DomainEvent{
 6        ID:            "evt_1",
 7        Type:          EventNotificationCreated,
 8        SubjectKind:   SubjectNotification,
 9        SubjectID:     "ntf_1",
10        OccurredAt:    time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
11        ReceivedAt:    time.Date(2026, 4, 22, 10, 1, 0, 0, time.UTC),
12        SchemaVersion: 1,
13        Payload:       payload,
14    }
15
16    if err := log.Append(context.Background(), event); err != nil {
17        t.Fatalf("append event: %v", err)
18    }
19
20    payload[0] = '['
21
22    events := log.List()
23    if string(events[0].Payload) != `{"topic":"deployments"}` {
24        t.Fatalf("payload was modified through original slice")
25    }
26}

json.RawMessage 本質是 []byte，所以需要 copy。這類細節很容易被忽略，測試可以把邊界固定下來。

實作檢查清單

新增結構化記錄欄位時，可以依序檢查：

這筆資料是給除錯、重播，還是查詢
structured log 是否只保存操作訊號與安全欄位
event log 是否保存 normalized domain event
state repository 是否只保存目前 projection
log 欄位名稱是否穩定
reason 是否是小集合分類
是否避免完整 payload 與敏感資料
event log 是否保護 copy boundary
測試是否檢查穩定欄位，而不是自由文字

設計檢查

檢查一：log 服務操作診斷

log 是操作診斷訊號，不是穩定查詢 API。需要使用者查詢的目前狀態，應該進 repository 或 read model。

檢查二：event log 保存 normalized fact

event log 記錄的是 normalized fact。若把暫時性錯誤、debug 訊息與 raw payload 全塞進 event log，重播與 audit 會變得不可信。

檢查三：欄位名稱維持一致

event_id、eventID、id 混用會讓查詢失效。欄位 schema 要像 API 一樣維持穩定。

檢查四：完整 payload 需要明確策略

完整 payload 可能包含敏感資料，也可能非常大。除非有明確安全與保存策略，否則只記錄大小、hash、ID 與必要欄位。

本章不處理

本章先處理 log、event log 與 repository 的分工；集中式 log 平台與可重播事件系統，會在下列章節再往外延伸：

和 Go 教材的關係

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

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；如果你要先回看語言教材，可以讀：

6.7 Go 常見服務場景總覽

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

這一章先整理 Go 常見會被用到的服務場景。對剛從 PHP 或 Python 轉來的讀者來說，先知道 Go 最常做哪些事，會更容易理解前面那些語言特性為什麼重要。

本章目標

學完本章後，你將能夠：

看出 Go 常見的服務落點
理解每種場景通常需要哪些核心能力
判斷哪些場景值得進一步用 Go 實作
把後續的實戰章節放回正確脈絡
分辨即時服務、背景 worker 與 API service 的不同責任

【觀察】Go 很常出現在服務邊界

Go 最常出現在需要長時間運行、協調 I/O、維持清楚邊界的服務層：

場景	Go 常扮演的角色
WebSocket service	長連線、事件傳遞、訂閱與廣播
background worker	背景處理、批次同步、事件消費
API gateway	路由、聚合、驗證與轉送
notification system	推播、排程與重試
event processor	事件解碼、去重、派送與狀態更新

這些場景共通點都是：工作量大多是 I/O 與協調，CPU 單點重運算通常只占一小部分。

【判讀】即時服務需要穩定的生命週期

WebSocket、SSE 或其他長連線服務，通常需要處理：

連線建立與關閉
heartbeat
事件路由
慢 client
backpressure

這些都和 goroutine、channel、context、timeout 直接相關，所以 Go 很自然會出現在這裡。

【判讀】背景 worker 需要明確的停止條件

queue consumer、cron worker、event relay 或同步流程，通常都需要：

可取消
可重試
可觀測
可限流

這類工作很適合 Go，因為 runtime、context 與標準庫已經把這些邊界鋪好了。

【策略】API 聚合與服務編排

有些 Go 服務的主要角色是協調與整合：

把多個下游資料聚合成一個 response
在多個服務之間轉送 command
在進入 domain 前先做 request normalization

這類工作通常會出現在微服務環境裡，Go 的清楚邊界與簡單部署會很有價值。

小結

Go 的常見場景很少是「單純做一個頁面」，更多是即時、背景、事件、聚合與服務邊界。先知道 Go 常被放在哪裡，後面的實戰章節就會更容易理解。

6.8 高併發下的 Redis 與 SQL 使用原則

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

這一章從 Go 服務的角度整理資料存取原則。重點在於：當併發增加時，Go 端要用明確邊界使用 Redis 或 SQL，讓下游維持可承受的請求節奏。

本章目標

學完本章後，你將能夠：

理解高併發下最常見的資料存取風險
區分 Redis 與 SQL 各自適合的角色
用 connection pool、timeout 與批次策略控制壓力
避免 cache stampede 與慢查詢連鎖
在 Go 服務內設計可控的下游存取邊界

【觀察】Go 端要先控住請求節奏

高併發時，資料存取風險通常來自請求節奏超過下游承受能力。你可以有很多 goroutine，但 Redis 與 SQL 不會因為 goroutine 多就自動變快。

Go 端通常要先做的是：

限制同時對下游發出的請求數
設定明確 timeout
避免無限 fan-out
在壓力過高時拒絕新工作

【判讀】Redis 適合快取、狀態與短生命週期資料

Redis 在 Go 服務裡常見用途包括：

cache
session
counter
rate limit
idempotency key
queue / stream

Go 端使用 Redis 時要注意：

問題	風險
熱 key	單點壓力過大
cache miss 擁塞	大量 goroutine 同時打到後端
pipeline 太大	buffer 與記憶體壓力增加
缺少 timeout	慢 request 會堆積成連鎖問題

【判讀】SQL 適合正式狀態與一致性資料

SQL 在 Go 服務裡通常承接的是：

最終狀態
查詢
交易
可追蹤資料

Go 端最重要的原則是共用 *sql.DB，讓 connection pool 真正發揮作用，並讓每個 query 都有 context 與 timeout。

需要特別注意的是：

太高的同時連線數會壓垮資料庫
太長的 transaction 會卡住連線池
慢查詢會把 goroutine 一起拖住

【策略】Go 端要用邊界保護下游

高併發下的資料存取，通常要搭配以下做法：

sql.DB 與 Redis client 長期共用
所有操作都帶 context
用 worker pool 或 semaphore 控制同時請求數
對 cache miss 做去重或保護
對寫入高峰做批次或排隊

這些做法是讓高併發系統能長時間穩定運行的基本條件。

模組六：實戰指南 on Tarragon

6.1 如何新增一個即時訊息 action

本章目標

【觀察】action 表達 client intent

【判讀】外部訊息先進入 envelope

【策略】payload struct 要表達資料語意

【執行】router 只做解析、驗證與轉換

【判讀】response 也需要穩定格式

【策略】WebSocket handler 聚焦 connection I/O

【執行】router 測試先覆蓋協定行為

【判讀】usecase 測試要離開傳輸格式

實作檢查清單

設計檢查

檢查一：handler 只處理傳輸邊界

檢查二：payload 轉成明確 command

檢查三：action 失敗和連線失敗分開處理

檢查四：router interface 跟著 usecase 成長

本章不處理

和 Go 教材的關係

6.2 如何新增一種 domain event

本章目標

【觀察】event type 代表已經發生的事

【判讀】DomainEvent 是內部事件合約

【策略】payload 是補充資料

【執行】adapter 負責 raw input 轉換

【判讀】validation 保護事件合約

【策略】去重鍵應建立在 domain 語意上

【執行】processor 負責套用事件規則

【執行】normalize 測試要固定外部輸入

【執行】processor 測試要隔離外部來源

實作檢查清單

設計檢查

檢查一：command 和 event 分開命名

檢查二：raw payload 停在 adapter

檢查三：穩定欄位放在 envelope

檢查四：事件順序使用發生時間

本章不處理

和 Go 教材的關係

6.3 如何擴展狀態投影欄位

本章目標

【觀察】先判斷欄位屬於哪一層

【判讀】domain state 要用明確型別

【策略】狀態轉移要集中在同一個入口

【判讀】read model 可以為查詢服務

【執行】讀取方法要保護 copy boundary

【策略】response view 負責對外格式

【判讀】omitempty 是相容性語意

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

【執行】copy boundary 測試要嘗試修改回傳值

【執行】response JSON 測試要檢查 contract

實作檢查清單

設計檢查

檢查一：顯示欄位放在 response view

檢查二：handler 透過狀態入口修改 projection

檢查三：回傳資料保護 copy boundary

檢查四：omitempty 對應可選欄位

本章不處理

和 Go 教材的關係

6.4 如何新增背景工作流程

本章目標

【觀察】worker 是有生命週期的元件

【判讀】worker 責任要先寫清楚

【策略】把單次工作獨立成 SyncOnce

【執行】Run(ctx) 管理長時間生命週期

【判讀】channel worker 要設計 backpressure

【執行】queue worker 要同時監聽輸入與取消

【策略】shutdown 是否 drain queue 要先決定

【判讀】worker 使用服務生命週期 context

【執行】SyncOnce 測試要隔離時間與外部來源

【執行】Run(ctx) 測試要能快速取消

【執行】queue full 測試要固定 buffer

實作檢查清單

設計檢查

檢查一：goroutine 要有停止條件

檢查二：worker 透過 processor 或 usecase 修改狀態

檢查三：queue full 要有明確策略

檢查四：測試隔離真實時間

本章不處理

和 Go 教材的關係

6.5 如何新增結構化記錄欄位

【判讀】`omitempty` 是相容性語意

檢查四：`omitempty` 對應可選欄位

【策略】把單次工作獨立成 `SyncOnce`

【執行】`Run(ctx)` 管理長時間生命週期

【執行】`SyncOnce` 測試要隔離時間與外部來源

【執行】`Run(ctx)` 測試要能快速取消