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

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

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

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

本章目標

學完本章後，你將能夠：

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

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

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

反模式示意：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

【執行】processor 負責事件規則

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

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

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

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

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

常見策略：

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

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

【測試】每個邊界分開測

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

processor fake test 範例：

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

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

本章不處理

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

和 Go 教材的關係

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

小結

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

4.2 事件去重與語義鍵設計

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

事件去重的核心規則是用領域語意判斷「哪兩筆事件代表同一件事」。原始 payload、request ID、收到時間和重試次數常常每次都不同，直接拿來比對會讓去重失效。

本章目標

學完本章後，你將能夠：

分辨 event ID 去重與 domain key 去重的差異
用 subject、event type、source group 與時間窗口設計 DedupKey
避免把不穩定欄位放進去重鍵
設計去重表的過期與清理策略
用 table-driven test 驗證去重邊界

【觀察】重複事件不一定長得一樣

重複事件的核心困難是外觀可能不同。HTTP callback 可能每次都有新的 request ID，queue message 可能因 retry 改變 delivery tag，timer 可能在下一輪掃描再次產生類似事件。

兩筆外部輸入可能長這樣：

1{
2  "request_id": "req_1001",
3  "event_id": "provider_7788",
4  "account_id": "acct_1",
5  "event_name": "activated",
6  "timestamp": "2026-04-22T10:00:03Z"
7}

1{
2  "request_id": "req_1002",
3  "event_id": "provider_7788_retry",
4  "account_id": "acct_1",
5  "event_name": "activated",
6  "timestamp": "2026-04-22T10:00:05Z"
7}

如果直接比對整包 JSON，這兩筆不同；如果從 domain 看，它們可能都是「同一個 account 在同一小段時間內變成 active」。

【判讀】去重鍵是語意決策

去重鍵的核心責任是把「相同事件」的定義寫進型別。它不是單純把 payload 做 hash；hash 只能回答 bytes 是否相同，不能回答領域事件是否相同。

1type DedupKey struct {
2    SubjectID string
3    Type      EventType
4    SourceSet string
5    Window    int64
6}

這個 key 表示：同一個 subject、同一種 event type、同一組來源語意、落在同一個時間窗口的事件，視為同一件事。

SourceSet 不一定等於原始來源名稱。多個來源若只是同一件事的不同傳輸管道，可以映射到同一個 source set；若兩個來源代表不同權威資料，則應分開。

【策略】先選擇去重層級

去重層級的核心選擇是 event ID、domain key 或兩者並用。不同層級解決的問題不同。

去重方式	判斷依據	適用情境	風險
event ID	外部或內部 event ID 相同	上游提供穩定唯一 ID	上游 retry 可能換 ID
domain key	subject、type、時間窗口相同	多來源可能描述同一件事	key 設太粗會誤殺事件
兩者並用	event ID 先判斷，再用 domain key 補強	上游 ID 大多可信但不完全穩定	實作與測試較複雜

小型服務可以先使用 domain key。若上游提供可靠 event ID，則 event ID 可以成為第一層快速去重，domain key 作為跨來源重複的保護。

【執行】用內部事件建立 DedupKey

DedupKey 應該建立在 DomainEvent 上，而不是 raw input 上。這能讓 HTTP、queue、timer 進來的同類事件共用去重規則。

 1func NewDedupKey(event DomainEvent, window time.Duration) DedupKey {
 2    return DedupKey{
 3        SubjectID: event.SubjectID,
 4        Type:      event.Type,
 5        SourceSet: sourceSet(event.Source),
 6        Window:    event.OccurredAt.UnixNano() / int64(window),
 7    }
 8}
 9
10func sourceSet(source EventSource) string {
11    switch source {
12    case SourceHTTPCallback, SourceQueue:
13        return "external_delivery"
14    case SourceTimer:
15        return "internal_scan"
16    default:
17        return string(source)
18    }
19}

OccurredAt 通常比 ReceivedAt 更適合事件語意去重。兩筆 retry 可能收到時間不同，但實際描述的發生時間相近；若使用收到時間，系統忙碌或網路延遲就會改變去重結果。

【判讀】哪些欄位不該放進 key

去重鍵的核心限制是不能包含每次都會變的欄位。這類欄位適合用於追蹤、除錯或觀測，不適合用於判斷是否同一事件。

不適合放進 key 的欄位：

request_id：每次 request 都可能不同。
received_at：取決於系統接收時間，不一定是事件語意。
delivery_attempt：重試次數本身就是重複事件的證據。
raw payload hash：欄位順序、metadata 或非語意欄位可能改變。
client IP、瀏覽器識別字串：代表傳輸脈絡，不代表事件本身。

適合放進 key 的欄位：

subject ID：事件作用的對象。
event type：發生了什麼事。
source set：資料權威或來源語意。
occurred time window：同一事件可接受的時間範圍。

【策略】時間窗口是取捨

時間窗口的核心作用是容忍短時間內的重送。窗口越短，越不容易誤殺不同事件；窗口越長，越能吸收延遲與 retry。

1const defaultDedupWindow = 30 * time.Second

窗口大小應該依事件語意決定：

事件類型	可用窗口	理由
account activated	1-5 分鐘	同一 account 短時間重複啟用通常是 retry
notification created	不一定適合時間窗口	使用者可能短時間建立多筆通知
job finished	30 秒-2 分鐘	job 完成事件通常只應發生一次
heartbeat received	不應去重成單一事件	heartbeat 本身就是週期訊號

時間窗口不是萬用答案。若事件本身允許短時間內多次發生，就需要更細的 subject 或 event ID，而不是把窗口調小到碰運氣。

【執行】Deduper 要保護共享 map

in-memory deduper 的核心責任是記住近期看過的 key，並在多 goroutine 下保持安全。只要 processor 可能同時處理事件，就需要 mutex 或單一 goroutine 擁有去重表。

 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, expires time.Duration) *Deduper {
 9    return &Deduper{
10        seen:    make(map[DedupKey]time.Time),
11        window:  window,
12        expires: expires,
13    }
14}
15
16func (d *Deduper) Seen(ctx context.Context, event DomainEvent) (bool, error) {
17    d.mu.Lock()
18    defer d.mu.Unlock()
19
20    key := NewDedupKey(event, d.window)
21    if _, ok := d.seen[key]; ok {
22        return true, nil
23    }
24
25    d.seen[key] = event.ReceivedAt
26    return false, nil
27}

ctx 在 memory 實作中可能用不到，但保留在 port 上能讓未來改成 Redis、資料庫或遠端服務時支援取消與逾時。

【執行】去重表必須清理

去重表的核心風險是無限制成長。只要把 key 放進 map，就必須定義 key 何時過期。

 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}

expires 通常應該大於 window。窗口決定兩筆事件是否可能被視為相同，過期時間決定 key 在記憶體中保留多久；兩者不是同一個概念。

【測試】用 table-driven test 固定語意

去重測試的核心目標是把「什麼算相同」寫成案例。這比只測 map 是否有資料更重要。

 1func TestDedupKey(t *testing.T) {
 2    base := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 3
 4    tests := []struct {
 5        name string
 6        a    DomainEvent
 7        b    DomainEvent
 8        same bool
 9    }{
10        {
11            name: "same subject type and window",
12            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
13            b: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceQueue, OccurredAt: base.Add(5 * time.Second)},
14            same: true,
15        },
16        {
17            name: "different subject",
18            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
19            b: DomainEvent{SubjectID: "acct_2", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
20            same: false,
21        },
22        {
23            name: "outside window",
24            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
25            b: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base.Add(2 * time.Minute)},
26            same: false,
27        },
28    }
29
30    for _, tt := range tests {
31        t.Run(tt.name, func(t *testing.T) {
32            got := NewDedupKey(tt.a, time.Minute) == NewDedupKey(tt.b, time.Minute)
33            if got != tt.same {
34                t.Fatalf("same key = %v, want %v", got, tt.same)
35            }
36        })
37    }
38}

這個測試把來源融合、subject 差異與時間窗口都明確化。未來調整 key 時，測試會提醒你正在改變事件語意，而不只是改一個 struct。

本章不處理

本章先處理單一服務內的事件去重語意；跨節點一致性與 idempotency store，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

事件去重是領域語意設計，不是 payload 比對。好的 DedupKey 會使用 subject、event type、source set 與合適的 occurred time window，並避免 request ID、收到時間與 raw payload hash 這類不穩定欄位。去重表還必須有清理策略，否則事件系統會用記憶體 leak 換取短期正確性。

4.3 Source of Truth：狀態邊界

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

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

本章目標

學完本章後，你將能夠：

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

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

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

反模式示意：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

transition 可以是純函式：

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

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

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

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

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

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

【執行】查詢要回傳 copy

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

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

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

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

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

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

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

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

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

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

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

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

1repository.Apply(ctx, event)

單一 goroutine 版本適合事件流：

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

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

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

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

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

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

本章不處理

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

和 Go 教材的關係

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

小結

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

4.4 多來源 event 融合

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

事件融合的核心目標是讓不同來源的同類事件進入同一套內部規則。HTTP callback、queue message、timer scan 與檔案 reader 都只是輸入方式；進入 processor 前，它們應該被轉成一致的 DomainEvent。

本章目標

學完本章後，你將能夠：

分辨來源差異與 domain 規則差異
為不同來源設計 adapter 與 normalize
用 channel 或直接呼叫收斂事件入口
為突發流量設計 backpressure 策略
決定錯誤應回給上游、重試、丟棄或記錄

【觀察】來源增加後規則容易分裂

事件來源增加的核心風險是每個來源各自實作一套處理規則。HTTP handler 有一套 validation，queue consumer 有一套 retry 判斷，timer worker 又有一套狀態更新；最後同一種 domain event 在不同入口產生不同結果。

反模式示意：

1HTTP callback ──> validate A ──> update state A
2queue message ──> validate B ──> update state B
3timer scan    ──> validate C ──> update state C

這種結構的問題是 domain 規則分裂。新增來源時，應該新增 adapter，不應複製 processor。

【判讀】來源差異應限制在 adapter

事件融合的核心原則是來源差異停在 adapter 與 normalizer。來源可以有不同 authentication、ack、HTTP status、payload 格式與重試語意；但轉成 DomainEvent 後，processor 應該面對一致模型。

目標結構：

1HTTP callback ─┐
2queue message ─┼─> normalize ─> DomainEvent ─> processor
3timer scan    ─┘

這個結構讓新增來源變成局部擴充。你新增一個 adapter 與 normalize test，而不是複製 validation、dedup、repository update 與 publish 邏輯。

【策略】先定義每個來源的責任

來源設計的核心動作是明確寫出每個 adapter 對上游的承諾。不同來源的錯誤回應方式不同，但進入 processor 的事件語意應一致。

來源	adapter 責任	失敗回應
HTTP callback	decode JSON、驗證簽章、normalize	回 4xx/5xx
queue consumer	decode message、控制 ack/nack、normalize	ack、nack 或 retry
timer scan	讀取本地狀態、產生內部事件	記錄錯誤或下次再掃
file reader	讀取增量資料、normalize	記錄 offset 或停下

表格是設計工具。若某一列寫不清楚，代表 adapter 與 processor 的邊界還不清楚。

【執行】HTTP adapter 轉成 DomainEvent

HTTP adapter 的核心責任是處理 HTTP 協定與外部 payload。它可以回應 status code，但不應直接決定狀態如何更新。

 1type HTTPEventHandler struct {
 2    processor *EventProcessor
 3    now       func() time.Time
 4}
 5
 6func (h HTTPEventHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 7    var raw RawHTTPEvent
 8    if err := json.NewDecoder(r.Body).Decode(&raw); err != nil {
 9        writeError(w, http.StatusBadRequest, "invalid_json")
10        return
11    }
12
13    event, err := NormalizeHTTPEvent(raw, h.now())
14    if err != nil {
15        writeError(w, http.StatusBadRequest, "invalid_event")
16        return
17    }
18
19    if err := h.processor.Process(r.Context(), event); err != nil {
20        writeError(w, http.StatusServiceUnavailable, "event_not_accepted")
21        return
22    }
23
24    w.WriteHeader(http.StatusAccepted)
25}

StatusAccepted 表示事件已被系統接收，不一定表示所有下游推送都完成。若 API 語意要求同步完成，就需要在文件與測試中明確定義成功條件。

【執行】queue adapter 控制 ack/nack

queue adapter 的核心責任是把 message lifecycle 對應到 processor 結果。processor 不應知道 ack、nack 或 delivery tag。

 1type QueueMessage struct {
 2    Body        []byte
 3    Ack         func() error
 4    Nack        func(requeue bool) error
 5}
 6
 7type QueueConsumer struct {
 8    processor *EventProcessor
 9    now       func() time.Time
10}
11
12func (c QueueConsumer) Handle(ctx context.Context, msg QueueMessage) error {
13    event, err := NormalizeQueueMessage(msg.Body, c.now())
14    if err != nil {
15        return msg.Nack(false)
16    }
17
18    if err := c.processor.Process(ctx, event); err != nil {
19        return msg.Nack(true)
20    }
21
22    return msg.Ack()
23}

這段程式把 queue 的重試決策留在 adapter。對 processor 來說，事件只是一筆 DomainEvent；對 queue 來說，錯誤需要轉成 ack/nack 策略。

【策略】共用 channel 需要 backpressure

共用 channel 的核心用途是把多個來源收斂到同一個處理 loop。它不是必要架構，但在多來源、突發流量或單一 worker 順序處理時很有用。

1events := make(chan DomainEvent, 1024)

channel 一旦有容量限制，就必須設計滿載策略。沒有滿載策略的 channel 只會把問題延後到 goroutine 堆積或 request 卡住。

 1func EnqueueEvent(ctx context.Context, events chan<- DomainEvent, event DomainEvent) error {
 2    select {
 3    case events <- event:
 4        return nil
 5    case <-ctx.Done():
 6        return ctx.Err()
 7    default:
 8        return ErrEventQueueFull
 9    }
10}

HTTP handler 遇到 ErrEventQueueFull 可以回 503。queue consumer 可以 nack 並 requeue。timer scan 可以跳過本輪。不同來源的上游回應不同，但進入 channel 的事件模型相同。

【執行】processor loop 擁有消費節奏

processor loop 的核心責任是決定事件如何被消費與停止。它應該接受 context，並在 shutdown 時停止讀取新事件。

 1type EventLoop struct {
 2    processor *EventProcessor
 3    events    <-chan DomainEvent
 4    logger    *slog.Logger
 5}
 6
 7func (l EventLoop) Run(ctx context.Context) error {
 8    for {
 9        select {
10        case <-ctx.Done():
11            return ctx.Err()
12        case event := <-l.events:
13            if err := l.processor.Process(ctx, event); err != nil {
14                l.logger.Error("process event failed",
15                    "event_type", event.Type,
16                    "subject_id", event.SubjectID,
17                    "error", err,
18                )
19            }
20        }
21    }
22}

正式實作還要處理 channel close。若事件來源會關閉 channel，讀取時應使用 event, ok := <-l.events；若 channel 由長生命週期服務持有，通常由 context 控制 shutdown。

【判讀】錯誤策略要依來源與資料語意決定

錯誤策略的核心問題是「失敗後誰能重送，重送是否安全」。HTTP、queue、timer 的答案不同。

錯誤位置	HTTP callback	queue message	timer scan
decode 失敗	400，不重試	nack(false) 或 dead-letter	記錄錯誤
normalize 失敗	400，不重試	nack(false) 或 dead-letter	記錄錯誤
processor 暫時失敗	503，可重試	nack(true)	下次再掃
duplicate event	202 或 204	ack	忽略
publisher 失敗	視語意而定	視語意而定	視語意而定

錯誤策略不能只看技術來源，也要看資料語意。若事件已經成功更新狀態但即時推送失敗，HTTP 是否要回錯取決於 API 是否承諾推送已完成。

【策略】觀測欄位要跨來源一致

事件融合後的 log 與 metric 也應使用共同欄位。這讓你能跨 HTTP、queue、timer 比較同一類事件的行為。

 1func LogAttrsForEvent(event DomainEvent) []slog.Attr {
 2    return []slog.Attr{
 3        slog.String("event_id", event.ID),
 4        slog.String("event_type", string(event.Type)),
 5        slog.String("event_source", string(event.Source)),
 6        slog.String("subject_id", event.SubjectID),
 7        slog.Time("occurred_at", event.OccurredAt),
 8        slog.Time("received_at", event.ReceivedAt),
 9    }
10}

adapter 可以額外記錄 HTTP path、queue name 或 timer name，但共同欄位應該來自 DomainEvent。這樣排查問題時，讀者不用先知道事件從哪個來源進來。

【測試】融合測試要驗證同類事件走同一規則

多來源測試的核心目標是確認不同 adapter 產生同一種 DomainEvent，並且 processor 對它們套用同一組規則。

 1func TestHTTPAndQueueNormalizeToSameDomainEvent(t *testing.T) {
 2    receivedAt := time.Date(2026, 4, 22, 10, 0, 10, 0, time.UTC)
 3
 4    httpEvent, err := NormalizeHTTPEvent(RawHTTPEvent{
 5        EventID:   "evt_1",
 6        AccountID: "acct_1",
 7        EventName: "activated",
 8        Timestamp: "2026-04-22T10:00:00Z",
 9    }, receivedAt)
10    if err != nil {
11        t.Fatalf("normalize http event: %v", err)
12    }
13
14    queueEvent, err := NormalizeQueueMessage([]byte(`{
15        "id":"evt_1",
16        "subject":"acct_1",
17        "type":"account.activated",
18        "occurred_at":"2026-04-22T10:00:00Z"
19    }`), receivedAt)
20    if err != nil {
21        t.Fatalf("normalize queue event: %v", err)
22    }
23
24    if httpEvent.Type != queueEvent.Type || httpEvent.SubjectID != queueEvent.SubjectID {
25        t.Fatalf("sources should normalize to same domain semantics")
26    }
27}

這個測試不是要求兩個 event 完全相同。Source 可以不同；重點是 domain semantics 一致，processor 才能共用規則。

本章不處理

本章先處理多來源事件如何在單一服務內融合；queue driver、outbox 與 tracing，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是多來源 adapter、normalize 與 processor 的路線；如果你要先回看語言教材，可以讀：

小結

事件融合的核心是把來源差異限制在 adapter 與 normalizer，讓 processor 只面對一致的 DomainEvent。HTTP、queue、timer 可以有不同的 backpressure 與錯誤回應，但不應複製 domain 規則。當來源增加時，系統應該增加 adapter，而不是增加另一套狀態更新流程。