五段處理鏈路

第一段：HTTP endpoint 接收

Collector 對外提供一個 HTTP POST endpoint（例如 /v1/events），接收 SDK 送來的 JSON body。每個 request 可以是單一事件或批次事件陣列。

Endpoint 的職責只有兩件事：驗證 HTTP 層面的基本條件（Content-Type、body size limit、認證 token），然後把 body 傳給下一段。HTTP 層面的錯誤（413 body too large、401 unauthorized）在這裡回應，不進入後續處理。

自用工具場景下，Go 的 net/http 標準庫提供的 HTTP server 已足夠。一個 http.HandleFunc("/v1/events", handler) 加上 json.NewDecoder(r.Body).Decode(&events) 就完成接收。不需要 framework。

第二段：JSON Schema 驗證

收到的 JSON body 用 JSON Schema 驗證結構正確性 — 必要欄位是否存在、型別是否正確、值是否在合法範圍內。驗證失敗的事件被拒絕並記錄原因，通過的事件進入下一段。

Schema 驗證是 collector 的品質閘門。沒有驗證的 collector 會累積格式不一致的資料，查詢時需要處理各種邊界條件。驗證在寫入前攔截問題，比寫入後清理成本低。

驗證的粒度是事件級 — 批次中的一個事件驗證失敗不影響其他事件。回應中標明哪些事件被接受、哪些被拒絕及原因。

Ingestion 回應格式

回應格式把「接受了幾筆、拒絕了幾筆、拒絕原因」三件事用一套一致的結構表達。SDK 端只需要判斷 status code 就知道怎麼處理 buffer。

 1// 200 OK — 單筆成功或批次全部成功
 2{ "accepted": 1 }
 3
 4// 207 Multi-Status — 批次部分失敗
 5{
 6  "accepted": 1,
 7  "rejected": 1,
 8  "errors": [
 9    { "index": 1, "message": "missing required field: type", "fields": ["type"] }
10  ]
11}
12
13// 400 Bad Request — 單筆失敗或批次全部失敗
14{
15  "error": "schema validation failed",
16  "details": [
17    { "field": "type", "message": "missing required field" }
18  ]
19}
20
21// 503 Service Unavailable — 寫入端暫時不可用
22{ "error": "service temporarily unavailable", "retry_after": 5 }

設計選擇：207 的 errors 陣列用 index 標明失敗事件在原始 batch 中的位置（0-based），SDK 可以用 index 對照原始事件做 debug log。合法事件不因部分失敗而被丟棄 — 部分成功是 batch 收集的核心價值。400 和 207 的差異是「全軍覆沒 vs 部分存活」，SDK 端的處理策略不同：400 直接清 buffer（schema 問題重試也不會過），207 只清成功的部分。

Health endpoint 回應

Health endpoint 回傳 collector 自身的運行狀態，不包含事件內容。用途是 SDK 端確認 collector 可達、監控腳本定期探測。

1// GET /health → 200 OK
2{
3  "status": "ok",
4  "uptime_seconds": 3600,
5  "total_events": 1234,
6  "storage_bytes": 5242880,
7  "version": "0.1.0"
8}

total_events 和 storage_bytes 讓監控腳本判斷 collector 的負載趨勢。version 讓 SDK 確認 collector 版本（schema 不匹配時的第一個 debug 線索）。

第三段：儲存

通過驗證的事件寫入 Storage Backend。Collector 使用可插拔的 Storage interface — day-one 預設用 SQLite（零依賴、嵌入式），分析需求觸發時切換到 PostgreSQL。具體的 backend 選擇和功能分層見 功能分層與 Backend 選擇，可插拔架構見 規模演進。

第四段：查詢

儲存的事件透過 CLI 指令或 HTTP 查詢 endpoint 存取。SQLite backend 下用 SQL 查詢；匯出為 JSONL 格式後也可用 grep + jq 做臨時分析。

查詢設計見 查詢 API 設計。

第五段：Rule engine

Rule engine 在事件寫入後觸發，檢查事件是否匹配預定義的規則。匹配時執行對應的動作（發通知、寫 summary、觸發 webhook）。

Rule engine 設計見 Rule engine 設計。

多獨立 client 併發寫入

上述五段鏈路描述的是單一 request 的路徑。實際運行時，多個 SDK 會同時送事件——以下先描述場景，下方並發寫入策略再詳述 collector 如何處理。

常見部署場景中，多個完全獨立的 SDK 實例同時送事件到同一個 collector——不同 process、不同 app、甚至不同語言的 SDK。這和「一個 app 內的多 thread 併發」不同：每個 SDK 有自己的 buffer 和 HTTP 連線，不共享任何狀態。

SDK 端不需要知道其他 SDK 的存在。每個 SDK 獨立 init、獨立 buffer、獨立 flush、獨立 close。SDK 端的唯一接觸點是 collector 的 HTTP endpoint——併發安全由 storage backend 的併發策略保證（見下方並發寫入策略），不需要 SDK 端協調。多 client 同時 flush 時的背壓機制見 Ingestion 背壓與流量管控。

例如 CI pipeline 的多個 job 同時送 build 事件，或微服務架構中多個 service 各自送事件到同一個 collector。另一個具體案例是 Claude Code 的 Hook 系統——多個 Hook 同時觸發時，每個 Hook 是獨立的 Python process，各自初始化 SDK、產生事件、flush 到同一個 collector。

並發寫入策略

Go 的 HTTP server 為每個 request 分配一個 goroutine。多個 SDK 同時 flush 時，collector 同時收到多個寫入請求。Storage Backend 的並發能力決定了這些 goroutine 怎麼協調。

SQLite Backend：單寫者模型

SQLite 的 WAL mode 允許一個 writer 和多個 concurrent reader — 讀寫不互相阻塞，但多個 writer 之間是序列化的。Go 端有兩種處理 pattern：

Single-writer goroutine + channel：所有 Store() 呼叫把事件送進一個 Go channel，由一個專屬的 goroutine 從 channel 讀取並序列寫入 SQLite。HTTP handler 送完 channel 後等待確認（或用 buffered channel 異步）。優點是背壓控制清晰 — channel 滿時 HTTP handler 自然阻塞，可以回 503。缺點是多一層間接。

Busy timeout fallback：不在 Go 層管序列化，讓 SQLite driver 自己處理。設定 _pragma=busy_timeout(5000)，多個 goroutine 同時呼叫 Store() 時，SQLite 讓等待的 goroutine block 直到寫入鎖釋放（最多 5 秒）。優點是實作簡單（不需要 channel 和額外 goroutine）。缺點是背壓不可控 — goroutine 數量可能累積。

自用工具場景推薦 busy timeout（簡單）、寫入量增長到出現超時錯誤時切換到 channel pattern。

PostgreSQL Backend：連線池

PostgreSQL 透過連線池（database/sql 的 SetMaxOpenConns）支援並行寫入。多個 goroutine 可以同時寫入不同的連線，不需要額外的序列化機制。

Go 單一 binary 的設計選擇

Collector 用 Go 編譯成單一 binary，不依賴外部 runtime（JVM、Python interpreter、Node.js）。部署是複製一個檔案，啟動是執行一個指令。

這個選擇在自用工具場景下有特定優勢：server 和 collector 在同一台機器上，部署流程是 scp collector user@host: + ssh user@host ./collector。不需要 package manager、不需要 container registry、不需要 orchestration。

Go 的 net/http 標準庫提供 production-ready 的 HTTP server，JSON 處理用標準庫的 encoding/json，SQLite 用 modernc.org/sqlite（pure Go、無 CGO 依賴）。整個 collector 的核心邏輯可以在 500 行以內完成。

具體的部署步驟（systemd service 檔案、啟動參數、設定檔格式）和 Quick Start（從零到第一筆事件出現在 collector）見 monitor repo 的 deployment guide。

下一步路由

• 功能分層與 Backend 選擇 → 功能分層與 Backend 選擇
• 可插拔 Storage Backend 架構 → 規模演進
• JSONL 匯出與備份格式 → JSONL 儲存設計
• 查詢 API 的設計 → 查詢 API 設計
• Rule engine → Rule engine 設計
• 背壓與流量管控的基礎概念 → DevOps 流量管控
• 端到端資料完整性 → 端到端資料完整性
• Error fingerprint 與去重分群 → Error Fingerprint 與去重分群

Monolith 與 Microservice 的責任差異

Monolith 用「同一個程式碼庫、同一個部署單位、同一個資料庫」換取低協作成本與簡單事務語意。Microservice 用「獨立程式碼庫、獨立部署、獨立資料邊界」換取團隊獨立性、技術選型彈性與局部故障隔離。

讀者要從這張表反推自己的真實壓力來源。如果痛點是「部署互相卡住、發布頻率被別人拖慢」，拆分能解決；如果痛點是「程式碼太亂、新人看不懂」，拆服務只會把亂的範圍擴大成跨服務契約混亂。

這張表是兩端對比、實際系統常落在中間。常見折衷形態：

• Modular monolith（單一部署 + 模組化邊界）：保留 monolith 的部署簡單、用模組邊界防止程式碼互相穿透。Shopify、Basecamp、Stack Overflow 是大規模長期維持的代表 — monolith 不是進化中段、是 valid endgame。
• Macro-services（少量大服務、5-15 個）：避免 microservice 的極端碎片化、保留拆分帶來的部署獨立性。是多數中型團隊的實際終點、不是過渡形態。
• Cell-based architecture（多 cell 各自獨立、跨 cell 共用標準介面）：AWS、Slack、DoorDash 用來控制 blast radius — 把整個系統複製成多個 isolated cell、每個 cell 內可以是 monolith 或 microservice。

拆分不是進化方向、是壓力應對工具。維持 monolith 在某些情境（極小團隊、PMF 前期、無 DevOps 能力）是更負責任的選擇。

拆分軸的判讀

服務邊界不只一條軸。常見的四條軸對應不同的壓力來源，正確的拆法是「壓力在哪裡、就沿那條軸拆」，不是同時動四條軸。

資料邊界

當兩塊業務的資料生命週期不同、一致性需求不同、查詢模式不同時，資料邊界已經形成。例如訂單資料需要強一致性與長期保留，瀏覽紀錄可以最終一致性、定期清理。把這兩類資料放同一個 schema 會讓 backup、migration、index 策略互相干擾。

判讀訊號：同一張表上不同欄位的 read/write QPS 差三個數量級、同一個 transaction 同時寫入多種業務概念、schema migration 一動就要鎖住整個業務的寫入。

團隊邊界

當兩塊業務由不同團隊維護、發布節奏不同、技術棧偏好不同時，團隊邊界已經形成。Conway’s Law 反過來操作：用服務邊界保護團隊邊界，避免一隊改動觸發另一隊重 review。

判讀訊號：PR review 跨團隊比例過半、發版需要協調多個團隊、技術升級（語言版本、framework 升級）因為其他團隊未準備好而被擋住。

部署邊界

當部分功能需要獨立的部署節奏、獨立的擴展策略、獨立的可用性等級時，部署邊界已經形成。背景批次工作要按小時排程、API 服務要 7×24 線上、報表服務只在工作日運行，三者放同一個部署單位會讓最嚴格的可用性要求拖累其他。

判讀訊號：高峰時某個功能擴展速度跟不上、低峰時某個功能浪費資源、單一發版策略覆蓋不了所有功能的風險等級。

流量邊界

當不同功能的流量形狀、失敗代價、SLO 等級不同時，流量邊界已經形成。付款 API 一秒 100 個請求、商品搜尋一秒 10000 個請求、後台報表一天 100 個請求，三者放同一個服務會讓彼此爭資源，付款被搜尋擠掉是業務災難。

判讀訊號：高頻 endpoint 壓爆低頻 endpoint 共用的連線池、不同 endpoint 的 latency 分布同時惡化、無法針對核心交易設定獨立的 SLO 跟 alert。

其他常見拆分軸

上面四條是技術驅動的主要拆分軸。實務上還有其他軸常成為真實驅動力、要一併納入判讀：

• 失敗代價 / blast radius 軸：核心交易（掛了會有業務災難）跟邊緣推薦（掛了沒人在意）的可用性等級差距大、適合拆開降低 blast radius。跟 SLO 軸高相關但不同 — 重點在「失敗時誰受影響」的範圍隔離。
• 變更頻率 / 風險軸：high-velocity 實驗功能跟 stable 核心應拆開、降低實驗對核心穩定性的牽連。跟團隊軸高相關但獨立 — 同一團隊也可能維持兩種變更頻率的程式碼。
• 資料敏感度 / 合規邊界：PCI / PII / 醫療資料的隔離常是合規硬要求（GDPR data residency 強制資料拆境），不是技術選擇。這類軸跟資料邊界相關但服從不同壓力。
• 組織非技術約束：併購整合、外部合規節奏、團隊 reorg、預算切分都會強制拆分 — 比 metric 訊號更早觸發、技術上不一定最佳但無法繞過。

這些軸跟前四條可以同時生效、也可能彼此衝突（合規逼資料拆境、但流量軸建議聚合）。處理衝突時優先順序通常是「合規 > 失敗代價 > 部署 / 流量 > 團隊 > 資料 > 變更頻率」、但每個組織會有自己的權重。

拆分時機的判讀

拆分時機不能等到「已經痛到動不了」才開始，那時候拆分要付的代價最高。也不能在「還沒長出邊界」時提早拆，那會用 microservice 的協調成本懲罰一個還沒到規模的系統。

提早訊號（可以開始準備但不一定立刻動手）：

• 程式碼裡同一份邏輯被三個 PR 同時修改、merge conflict 增加
• 同一個 service 的不同功能開始有不同的擴展需求
• 不同團隊對同一個發版視窗的需求開始衝突

該動手訊號（再拖就要付高昂代價）：

• 任何一個功能改動需要 freeze 整個服務發版
• 局部高峰擴展時整個服務一起擴展，成本翻倍
• 一個團隊的事故會直接影響另一個團隊的營運指標
• 跨團隊 deadlock：A 等 B 改完才能上、B 等 A 改完才能上

過晚訊號（拆分要付遷移代價）：

• 已經出現過跨團隊事故、且復盤結論是「無法分離責任」
• DB 連線池在多個業務間爭搶、無法用 connection pool 隔離解決
• 部署平台跑不動：CI 太慢、build 太大、本地開發無法啟動完整環境

拆分代價與回退路徑

拆分不是免費操作。每多一個服務，就多一份運維成本、跨服務 trace 成本、契約治理成本。讀者要在拆分前認知這些代價，而不是事後才發現。

拆分失敗的回退路徑要在拆分前設計好。常見回退策略：保留原 monolith 程式碼一段時間（雙寫期），新服務出問題可以切回；先拆讀路徑驗證流量，再拆寫路徑；用 feature flag 控制是否走新服務。沒有回退路徑的拆分一旦撞牆，會比不拆更難收拾。

拆分後的通訊優先級：事件 > 同步 RPC

拆完後跨服務通訊有兩條路：同步 RPC（gRPC、REST）跟異步事件（message queue、event bus）。預設應該選事件、保留 RPC 給「真的需要同步回應的查詢」。

理由：

• 失敗代價隔離：服務 A 發事件給 B、B 掛了不影響 A — 事件留在 queue 等。同步 RPC 下、B 掛了 A 也跟著掛
• 流量解耦：事件本身就是 buffer、能吸收 burst。同步 RPC 是 throughput 的硬上限、A 的尖峰 = B 的尖峰
• 可重放：事件可以重放（replay）做資料修補、debug、新服務 backfill。同步 RPC 過了就過了
• 服務獨立演進：事件 schema 可以加欄位向下相容、consumer 慢慢 adapt。RPC interface 改動是 breaking change

該用同步 RPC 的少數場景：使用者請求路徑需要立即回應（「使用者按下查詢、顯示結果」）、且兩個服務都在同一個 latency budget 內。其他都優先事件。

詳見 03 模組訊息佇列 跟 0.3 非同步與事件傳遞選型。

反例：拆分過度的收回

服務拆分的反向動作是合併。當拆分後發現「服務間呼叫太頻繁、近乎同步、跨服務事務太多」時，代表這條邊界拆錯了。處理方式是把這兩個服務合回去，繼續增加跨服務工具只會堆疊複雜度。

判讀「該合併」的訊號：服務 A 與 B 之間每秒幾百次同步呼叫且失敗會連鎖、A 改動必定觸發 B 改動且兩者由同一團隊維護、跨服務事務佔總業務動作比例過高、跨服務 latency 是 SLO 主要消耗者。

合併不是失敗。它代表團隊已經理解這條邊界不該存在，及時收回比硬撐更負責任。Modular monolith（單一部署、模組化邊界）是常見的折衷形態：保留模組邊界、避免分散事務代價、未來壓力出現時再分拆。

判讀訊號

常見誤區

把「technical debt」當成拆分理由。Monolith 程式碼髒亂的解法是重構，不是拆服務。拆服務只是把髒亂從單庫變成跨服務契約混亂，問題並沒有消失。

把「跟風 microservice」當成決策。沒有業務壓力、團隊規模不到位、運維能力不夠的情況下拆服務，新的協作成本會壓垮整個團隊，這比 monolith 的痛苦更大。

把拆分當成單向操作。沒有設計回退路徑、沒有保留合併選項，拆錯了就只能硬撐。成熟的服務演進策略要把「拆」跟「合」當成雙向可逆操作。

定位邊界

本章專注「該不該拆、沿哪條軸拆、拆完怎麼收尾」。當問題進入具體拆分後的部署、流量、觀測責任，分別交給以下模組：

• 服務獨立部署 → 05 deployment platform
• 跨服務交接與事件 → 03 message queue
• 跨服務觀測與 trace → 04 observability
• 跨服務一致性與冪等性 → 03 idempotency-replay + outbox pattern

案例回寫

服務拆分判讀可用以下案例回寫：

• 9.C23 Netflix：把關聯式 DB 統一到 Aurora、效能 +75%、成本 -28% — 反例方向：原本各 microservice 各自 DB 造成運維碎片化、最後做 consolidation；對照本章「拆分過度的收回」段。
• 5.C2 Condé Nast：EKS 平台整併與標準化 — Condé Nast 把多 brand 各自的 K8s cluster 整併到統一 EKS 控制面、降低跨團隊運維分歧。對照本章「拆分代價 / 運維複雜度」段：拆出去快、合回來慢、設計時就要評估這種非對稱性。
• 9.C12 Riot Games：246 個 EKS cluster 的多遊戲多地區治理 — Riot 的拆分軸是「遊戲 × 地區 × 環境」三維交集、246 個 cluster 是這三軸的笛卡兒積取一個 subset。對照本章「拆分軸 / 部署邊界」段：實務上的拆分常常是多軸交集、不是單軸推進。

Netflix Aurora consolidation 是反例最有教學價值的一筆 — 它證明「拆 microservice 各自 DB → consolidation 回 Aurora」是 valid endgame、拆服務不是單向操作。Condé Nast 跟 Riot Games 補充另兩條維度：碎片化的運維代價、多軸交集的設計複雜度。把這三筆放回「拆分時機判讀」框架的不同節點上、能看出拆分決策的本質是「沿哪幾條軸 + 接受哪些代價」的組合。

跨模組路由

1. 與 0.1 後端服務能力地圖 的交接：拆分前要先理解每塊責任屬於哪種能力分類，避免拆出語意混亂的服務。
2. 與 0.5 流量與資料量評估 的交接：流量軸拆分要先有流量基線。
3. 與 03 message queue 的交接：拆分後跨服務通訊優先用事件、不是同步 RPC。
4. 與 9.13 擴展軸 的交接：拆分常常是水平擴展的前提（無狀態服務拆分後才能獨立水平擴展）。

下一步路由

規模成長路線下一站 → 9.13 擴展軸與 Stateless 前提：拆分後接著要為每個服務選擇擴展軸。

其他延伸方向：

• 實作層：服務如何獨立部署 → 5.2 Kubernetes 部署策略
• 事件層：拆分後跨服務通訊設計 → 03 模組訊息佇列

概念位置

四維對照：

典型 LLM 應用的混合：

1User input
2   ↓ Fuzzy（LLM 理解意圖）
3   ↓ Deterministic（DB / API / policy）
4   ↓ Fuzzy（LLM 寫回應）
5   ↓ Deterministic（發送 / 寫入）

設計責任

讀 LLM 應用設計文章或開始設計 production AI 系統時、這個 framing 決定每個 step 的工具選擇。實作判讀：

1. 哪段該 deterministic / 哪段該 fuzzy：規則可窮舉、失敗代價高、需要解釋、需要 byte-exact 重現的 → deterministic；自由文字輸入、生成有風格的輸出、邊界模糊的 → fuzzy。
2. 典範用錯的反模式：deterministic 需求硬用 fuzzy（用 LLM 算稅金）、fuzzy 需求硬用 deterministic（regex 解析自由文字）、邊界混（prompt 內塞算術 / code 內塞意圖分類）。
3. Fuzzy 邊界的四種 guardrail：schema validation、output validator、action gating、distribution monitoring。混用、不同 risk class 分擔不同層。
4. 跟 HITL 的關係：HITL 是 deterministic guardrail 的一種——把人類判斷當 deterministic check 包 fuzzy LLM 行為。
5. 失敗的歸因分層：壞掉時要問「是 prompt / model / context / tool / 還是 deterministic glue 的 bug」。deterministic 軟體歸因單一、fuzzy 軟體要分這幾層查。

完整典範討論見 0.8 Deterministic vs Fuzzy Engineering。

概念位置

Guardrail 是一組控制層。常見形式包含 structured output、validator、allowlist、rate limit、sandbox、human approval、eval、monitoring 與 rollback。它通常包在模型輸出與下游副作用之間。

可觀察訊號與例子

客服分類可以用 enum schema 限制類別；tool use 可以用 allowlist 限制可呼叫工具；production 操作可以要求 human-in-the-loop approval；外部內容進 context 前可以標記為 untrusted，降低 prompt injection 後果。

設計責任

設計 guardrail 時先判斷失敗代價，再選控制強度。低風險任務用 schema 與 retry 即可；高副作用任務要加 permission boundary、sandbox、審查與 audit log。相關基礎見 Deterministic vs Fuzzy engineering。

概念位置

這個決策跨越 three-layer architecture 的所有層：介面可以相同，伺服器與模型位置不同。常見組合是同一個 IDE 介面同時接本地 OpenAI 相容 API 與雲端 API，依任務切換。

可觀察訊號與例子

本地適合私有資料、離線、可控成本、低資料外流風險；雲端適合高難度 reasoning、大型 agent、多模態、需要最新旗艦能力的任務。混合策略常見於 coding：本地做補完、摘要、低風險查詢，雲端處理複雜修復與大型 agent loop。

設計責任

判斷時看五個訊號：資料敏感度、模型能力需求、延遲體感、每月成本、維運能力。當任務失敗代價高且能力要求高，雲端未必可替代人工審查；當資料敏感且任務簡單，本地模型通常更划算。完整框架見 0.6 本地 vs 雲端。

概念位置

跟 multi-call 對照：

三種主流拓樸：

設計責任

讀 agent framework / paper 看到「multi-agent」「orchestrator」「agent-as-tool」就是這層設計。實作判讀：

1. 「先 multi-call、不夠再 multi-agent」：multi-agent 是「特定問題的解法」、不是「更高級的設計」。判讀訊號：role 顯著差異 / 跨產品重用 / 真正平行 / 動態協作 / 團隊熟悉度——四條件全滿足才走 multi-agent。
2. Specialization gain vs orchestration overhead：拆細帶來單一責任、獨立優化、重用、平行；代價是 context 重複傳遞、latency 累積、debug 困難、責任歸屬模糊。
3. 特有失敗模式：循環依賴、責任歸屬模糊、context 重複傳遞、orchestrator 單點瓶頸、agent 互相 hallucinate。每類有對應 guardrail（call stack 監測、trace 全紀錄、shared context、deterministic dispatch rule、schema validation）。
4. 跟 MCP 的關係：MCP 的 tool primitive 視角下、agent-as-tool 可包成 MCP server 暴露、跨組織重用走這條路。

完整 multi-agent 拓樸設計見 4.8 Multi-Agent 拓樸。

概念位置

三層責任分工如下：

1介面層：CLI / IDE plugin / Web UI，負責接收任務與顯示結果
2伺服器層：inference server，負責載入模型、提供 API、跑推論
3模型層：權重檔與 tokenizer，負責提供可被執行的神經網路參數

它跟 OpenAI 相容 API 的關係是：API 是介面層跟伺服器層之間的標準接縫；跟 inference server 的關係是：伺服器層是三層中的中介。

可觀察訊號與例子

看到 Continue.dev、Open WebUI、aider，通常是在介面層；看到 Ollama、LM Studio server、llama.cpp server、vLLM，通常是在伺服器層；看到 GGUF、Safetensors、MLX 權重，通常是在模型層。LM Studio 這類 all-in-one 工具會跨層，但仍可拆成 UI 與 server 兩種責任。

設計責任

排錯或換工具時，先問「問題出在哪一層」。連不上 localhost 是伺服器或網路問題；回答品質差多半是模型或 prompt 問題；IDE 操作不順是介面層問題。完整推導見 0.2 三層架構。

概念位置

LLM 中 activation function 主要出現在 FFN 內、夾在兩個矩陣乘法之間：

1FFN: input → W_up (linear) → activation → W_down (linear) → output
2                              ↑
3                       這裡是 activation function

主流 LLM 用的 activation function 演化：

SwiGLU / GeGLU 是「gated」變體、用兩條線性投影相乘、表達能力比單一 activation 強、是現代 LLM 主流。

設計責任

讀 paper / model card 看到 SwiGLU、ReLU、GELU 等詞、知道它們是 FFN 內部的選擇、影響模型表達能力跟訓練穩定性、不影響「模型怎麼用 / 怎麼 inference」這類使用者面議題。寫 code 場景的判讀：模型用什麼 activation 由模型作者決定、使用者通常不用調；但若要 fine-tune 或自己訓模型、activation 選擇是設計決策之一。

概念位置

Attention 在 Transformer block 中的位置：

1Transformer block：
2  ├── Layer Norm
3  ├── Attention（本卡聚焦）
4  │     ├── Q · K^T → attention score
5  │     ├── softmax → weight
6  │     └── weight · V → output
7  ├── Layer Norm
8  └── FFN 層（或 MoE）

簡化的計算公式：

1attention(Q, K, V) = softmax(Q · K^T / √d) · V

Attention 的常見變體（影響 KV cache 體積跟推論性能）：

設計責任

理解 attention 後可以解釋三個現象：為什麼 LLM 推論的記憶體用量隨 context 長度線性增加（KV cache 是 attention 暫存）、為什麼 KV cache 量化 對品質影響有不對稱性（K 用於 score 比較、V 用於加權平均、誤差累積方式不同）、為什麼不同 attention 變體在同等模型大小下推論速度差異明顯（KV cache 體積跟卡間頻寬需求不同）。

工程實務上、Attention 是 LLM 推論性能跟記憶體需求的最大來源、量化策略、context 上限、併發數設計都圍繞 attention 跟 KV cache 展開。

概念位置

Causal mask 在 attention 計算中的位置：

 1score = Q @ K^T / sqrt(d)     ← shape (seq_len, seq_len)、每對 token 一個分數
 2score = score + causal_mask   ← 加上 mask
 3attention = softmax(score) @ V
 4
 5causal_mask 長這樣（lower triangular、上三角全是 -∞）：
 6        K_0    K_1    K_2    K_3
 7Q_0   [  0    -∞     -∞     -∞ ]   ← token 0 只能看自己
 8Q_1   [  0     0     -∞     -∞ ]   ← token 1 能看 0~1
 9Q_2   [  0     0      0     -∞ ]
10Q_3   [  0     0      0      0 ]

關鍵特性：

1. 訓練時並行有效：所有 token 同時跑 forward pass、causal mask 確保每個 token 只看到該看的範圍。沒 mask 就會「偷看未來」、訓出 cheating 模型。
2. 推論時自動成立：自回歸生成本來就是一個一個生、後面不存在、mask 是隱式的。
3. 跟 KV cache 結合：推論時 cache 只存「過去」的 K/V、causal mask 自然滿足。

跟其他 attention 變體的關係：

設計責任

讀 paper / model card 看到「causal」「decoder-only」「auto-regressive」這幾組詞、就是這個機制。實務上、寫 code 場景的所有主流 LLM 都用 causal mask、所以這個概念是隱式 default、不會主動暴露給使用者；但理解它能解釋為什麼 LLM 是「接龍」、為什麼 bidirectional context 在 LLM 裡不存在（要 bidirectional 要用 encoder 架構）。

概念位置

Embedding layer 在 forward pass 的位置：

1input："Hello world"
2   ↓ tokenizer
3token IDs: [9906, 1917]            ← 整數序列
4   ↓ embedding layer（vocab × hidden 查表）
5embeddings: [[0.1, -0.3, ...], [0.5, 0.2, ...]]   ← 向量序列、(seq_len, hidden_dim)
6   ↓ Transformer block × N
7   ↓ output projection
8logits

跟 embedding model 的差別：

兩者「都產出向量」、但層級跟用途完全不同：embedding layer 是 LLM 內部結構（per-token、給模型 forward pass 用）、embedding model 是外部工具（per-text、給檢索系統用）。

Embedding layer 的大小：

• Gemma 4 31B：vocab=256K、hidden=5120、embedding matrix ≈ 256K × 5120 = 1.3B 參數
• Llama 3 8B：vocab=128K、hidden=4096、embedding matrix ≈ 0.5B 參數

通常跟 output projection（hidden → vocab）相同大小、有些模型 tied（共用權重）、有些 untied。

設計責任

讀模型架構圖看到「token embedding」「embed_tokens」就是這一層。實務意涵：模型大小有非小比例來自 embedding（vocab 越大、embedding 越大）；換 tokenizer 等於整個 embedding 重訓、是 fine-tune 時通常不動的部分。

概念位置

標準 FFN 的計算：

1input（hidden_dim）
2  ↓ W_up（linear、hidden_dim → intermediate_dim、通常放大 4x）
3intermediate vector
4  ↓ activation function（ReLU / GELU / SwiGLU）
5  ↓ W_down（linear、intermediate_dim → hidden_dim）
6output（hidden_dim）

Intermediate dim 通常是 hidden dim 的 4 倍（例如 hidden=4096、intermediate=16384）、所以 FFN 的參數量是 hidden × intermediate × 2 ≈ 8 × hidden²、遠大於 attention 的 4 × hidden²（Q/K/V/O 四個 hidden × hidden 矩陣）。

FFN 變體：

設計責任

理解 FFN 是參數大頭、能解釋幾件事：MoE 為什麼是「把 FFN 換成多個專家、只啟用部分」（因為 FFN 是最值得稀疏化的部分）、MoE CPU offload 為什麼是「把 expert FFN 卸到 RAM」（FFN 大、卸下來省 VRAM）、為什麼模型大小用「參數量」算（FFN 主導）。LoRA fine-tuning 時、通常選擇對 attention 的 Q/V 投影做 LoRA、不對 FFN 動、因為 FFN 太大、LoRA 收益相對小。

概念位置

LayerNorm 在 Transformer block 內的位置（現代主流是 pre-norm）：

1Transformer block（pre-norm 配置）：
2  x
3  ↓ LayerNorm
4  ↓ Self-Attention
5  ↓ + 跟 x 做 residual connection
6  ↓ LayerNorm
7  ↓ FFN
8  ↓ + 跟前一步輸出做 residual connection

主流變體比較：

RMSNorm 比 LayerNorm 簡單、實測訓練穩定性接近、推論更快（少算 mean 跟加 β）、所以現代 LLM 多用 RMSNorm。讀 paper 看到「RMSNorm」就是 LayerNorm 的這個簡化變體。

Pre-norm vs post-norm：

• Pre-norm（LayerNorm 在 attention / FFN 之前）：深度模型訓練較穩、現代主流。
• Post-norm（LayerNorm 在 residual add 之後）：原始 Transformer paper 的設計、深層訓練不穩定。

設計責任

理解 LayerNorm 後可以判讀「深層 LLM 為什麼訓得起來」的部分答案：residual connection + LayerNorm 是讓梯度能穩定流過幾十層 Transformer 的兩根支柱。讀 model card 看到「RMSNorm」「pre-norm」等詞、知道對應的設計選擇跟訓練穩定性意涵。

概念位置

MHA 的計算結構：

1輸入 hidden state（dim = 4096）
2   ↓ 投影成 Q/K/V、每個切成 h 個 head（如 h=32、每個 head 128 維）
3Head 1：Q_1、K_1、V_1 → attention_1（128 維）
4Head 2：Q_2、K_2、V_2 → attention_2
5...
6Head h：Q_h、K_h、V_h → attention_h
7   ↓ concat 所有 head 輸出（h × 128 = 4096）
8   ↓ output projection（4096 → 4096）
9最終輸出

多頭變體：MHA → GQA → MLA 是 KV cache 體積壓縮的演化方向。

設計責任

讀 model card 看到 num_attention_heads: 32、num_key_value_heads: 8 等就是 MHA / GQA 設定（Q=32、K/V=8 表示 GQA、g=4）。寫 code 場景的意涵：GQA / MLA 的 KV cache 體積小、長 context / 高併發場景更友善、是現代 LLM 大量採用的設計。

概念位置

三種 fusion 方式的對比：

1. Early Fusion（最主流）

1image → vision encoder → image tokens ─┐
2                                       ├→ concat 成單一 sequence → 同 LLM Transformer 處理
3text → tokenizer → text tokens ────────┘

• 特性：image token 跟 text token 在同一個 token sequence、共用 LLM 的 attention / FFN
• 代表：LLaVA、Qwen2-VL、Llama 3.2 Vision、Pixtral、GPT-4V 多數變體
• 優點：實作簡單、可重用 LLM 的 weight、訓練資料效率高
• 缺點：image token 佔 context、長對話 / 多圖時 context budget 吃緊

2. Cross-Attention（Flamingo-style）

1image → vision encoder → image features ─┐
2                                          │ Cross-attention 層
3text → tokenizer → tokens → LLM Transformer ──┤  插在每幾層 Transformer 之間
4                                          │ Image features 不進 LLM 主流
5output ←─────────────────────────────────┘

• 特性：image features 不變成 LLM 的 token、透過額外的 cross-attention 層注入
• 代表：Flamingo（DeepMind）、Idefics（Hugging Face）、部分 video LLM
• 優點：text token sequence 不會被 image 撐大、長文字 + 多圖比較友善
• 缺點：架構複雜、訓練難、推論伺服器支援度差

3. Native Multimodal（unified token space）

1image → patchify → discrete image tokens（如 VQ-VAE 編碼）
2text → tokenizer → text tokens
3
4兩者共用 vocab、同一個 Transformer 從頭訓
5（沒有「分開的 vision encoder」、modality 在 vocab level 統一）

• 特性：架構上「圖跟文字是同一種東西」、共用 vocab
• 代表：Chameleon（Meta 研究）、未來 trend
• 優點：理論最 clean、跨模態 generation 自然（生圖 + 生文都同個模型）
• 缺點：訓練極貴、目前研究階段為主、實用 VLM 仍以 early fusion 為主流

主流選擇對比

設計責任

讀 VLM paper / blog 看到「early fusion」「LLaVA-style」「Flamingo-style」「cross-attention adapter」就是這分類。寫 code 場景的判讀：

1. 本地跑 VLM 多半是 early fusion：選 Qwen2.5-VL / Llama 3.2 Vision / Gemma 3 Vision 都是這條路線、推論伺服器（llama.cpp、Ollama、LM Studio）都支援
2. Cross-attention 模型本地跑可能撞牆：推論伺服器對 Idefics 等 cross-attention 模型支援度差、不一定能跑 GGUF
3. 理解 fusion 影響 token 估算：early fusion 下「image token = 真的進 context」、cross-attention 下不算進 context window 主流
4. 未來 trend 是 unified：但現在做 production / 本地工作流不必等、用 early fusion 主流模型即可

概念位置

Residual connection 在 Transformer block 中出現兩次：

 1Transformer block：
 2  x
 3  ├──────────────┐  ← skip connection（保留原始 x）
 4  ↓              │
 5  LayerNorm      │
 6  ↓              │
 7  Self-Attention │
 8  ↓              │
 9  +←─────────────┘  ← residual add：attention output + x
10  │
11  ├──────────────┐  ← skip connection（保留 attention 後的值）
12  ↓              │
13  LayerNorm      │
14  ↓              │
15  FFN            │
16  ↓              │
17  +←─────────────┘  ← residual add：FFN output + previous
18  ↓
19  進入下一個 block

關鍵性質：

1. Gradient 可以走捷徑：Backpropagation 時、gradient 能透過 skip connection 直接傳回淺層、避免 chain rule 累積衰減。
2. Layer 學「殘差」而不是「完整轉換」：每層學「該怎麼微調輸入」、不用學「從零生成輸出」、優化更容易。
3. 跟 LayerNorm 配對：兩者一起是深層 Transformer 訓得起來的基礎。

設計責任

理解 residual connection 後可以判讀 Transformer 能堆幾十層的根本原因（不是因為 attention、是因為 residual + LayerNorm 讓深層仍可訓練）；也能看懂 ResNet、ViT 等其他用 residual 架構的設計。LLM 推論時 residual 不算 bottleneck、但在訓練 / fine-tune 時、residual 是 gradient flow 健康度的關鍵。

概念位置

位置編碼的演化路線：

RoPE 的核心數學（簡化）：

1傳統：token at position m 的 Q 是 Q_m = x_m @ W_Q
2RoPE：Q_m = R(m) × (x_m @ W_Q)  ← R(m) 是依位置 m 決定的旋轉矩陣
3
4attention score = Q_m @ K_n^T
5               = R(m) × q × (R(n) × k)^T
6               = q × R(m - n) × k^T  ← 只依賴相對位置 (m-n)！

關鍵性質：RoPE 算出的 attention score 只依賴相對位置、所以推廣到比訓練長度更長的 context 時有自然的數學基礎、配合 RoPE scaling（YaRN、NTK-aware、Position Interpolation）就能把 8K 訓練的模型擴展到 128K / 1M context。

設計責任

讀 model card 看到 rope_theta: 10000、rope_scaling: {type: yarn, factor: 8} 等就是 RoPE 配置。寫 code 場景的意涵：long context 模型（如 Llama 3 128K）的推廣能力主要靠 RoPE + scaling、不是直接訓練 128K 全長；但聲稱 context 跟「實用 context」仍有差距、長 context 上模型表現會逐步衰減。

概念位置

兩層的職責劃分：

 1Scaffold（建構時、static）：
 2  ├── System prompt 模板（角色、約束、輸出格式）
 3  ├── Tool schema 註冊（read_file / write_file / run_bash 等的 spec）
 4  ├── Subagent 拓樸（main agent + 子 agent 的調用關係）
 5  ├── Skill / playbook 註冊
 6  └── 安全 policy（什麼可寫、什麼要 confirm）
 7
 8   ↓ 編譯 / 載入
 9
10Harness（runtime、dynamic）：
11  ├── Tool dispatch（接 LLM tool call、執行、回 result）
12  ├── Context budget 管理（剪裁歷史、塞新內容、不超 25% 規則）
13  ├── Safety / 中斷（confirm UI、permission boundary、可逆性檢查）
14  ├── Error recovery（tool failed → retry / fallback / escalate）
15  └── Telemetry（trace / metrics / cost）

跟既有概念的關係：

設計責任

讀 coding agent paper / blog 看到「scaffold」「harness」「context engineering」就是這 framing。寫 code 場景的判讀：

1. 看新 coding agent 時、分兩層拆解：scaffold（system prompt、tool list、subagent 結構）是「設計做了什麼」、harness（context 怎麼裁、tool 怎麼 dispatch、安全怎麼擋）是「runtime 怎麼跑」
2. 修改 / 客製 agent 時、看你動的是哪層：改 system prompt = 動 scaffold；改 tool 執行邏輯 = 動 harness
3. 跟 4.17 coding-agent harness 的關係：本卡是定義、4.12 是 coding 場景的工程實務（context budget、scaffold 模式、harness pattern）

概念位置

Self-attention 的計算步驟：

 1輸入 sequence: x_1, x_2, ..., x_n（每個是向量）
 2
 3對每個 token i：
 4  Q_i = x_i × W_Q   ← Query：「我要找什麼樣的資訊」
 5  K_i = x_i × W_K   ← Key：「我提供什麼樣的資訊」
 6  V_i = x_i × W_V   ← Value：「我的實際內容」
 7
 8attention(Q_i, K, V) = softmax(Q_i · K^T / √d) · V
 9                       └─ Q 跟所有 K 算分數、決定權重 ─┘
10                                                       └─ 加權平均所有 V ─┘

關鍵特性：

1. Q / K / V 來源相同：跟 cross-attention 區分；都從同一個輸入 sequence 投影。
2. 每個 token 都跟所有 token 算一次：複雜度 O(n²)、是 long context 痛點根源。
3. Causal mask 在 self-attention 內生效：LLM 的 decoder-only self-attention 加 causal mask、token i 只能看 1~i、不能看 i+1 以後（不能偷看未來）。

設計責任

理解 self-attention 後可以判讀幾件 LLM 設計事：KV cache 為什麼有效（自回歸生成時、過去 token 的 K/V 不變、存下來下次直接用）；MHA / GQA / MLA 等變體在動什麼（共享 / 壓縮 K/V 投影、不動 Q）；為什麼長 context 推論慢（self-attention 的 O(n²) 計算）。

概念位置

Vision encoder 在 VLM 中的位置：

1Input image（如 1024×1024 RGB）
2   ↓ 切 patch（如 14×14 patch、每張圖 ~5000 個 patch）
3   ↓ Vision encoder（ViT 或 CLIP image encoder）
4Image feature vectors（每個 patch 對應一個 768/1024 維向量）
5   ↓ Projection layer（vision dim → LLM hidden dim）
6[Image tokens](/llm/knowledge-cards/image-token/)（變成 LLM 可吃的「視覺 token」）
7   ↓
8跟 text token 混合 → Transformer → output token

主流 vision encoder 設計：

Vision encoder 的關鍵設計取捨：

1. 解析度：固定（224×224 / 336×336）vs 動態（依輸入圖大小）
2. 參數量：vision encoder 0.3B-1B 是主流；太小辨識能力差、太大拖累整體推論速度
3. Pretrain 來源：用 CLIP / SigLIP 預訓練的權重起始、加上 multimodal fine-tune；少數從頭訓
4. 跟 LLM 結合方式：見 multimodal fusion 卡

設計責任

讀 VLM model card 看到「vision tower」「ViT backbone」「image encoder」就是這部分。寫 code 場景的判讀：

1. 解析度影響細節辨識：低解析度（224）對「截圖中的小字 / 細邊框」可能模糊、看不清；高解析度（1024+）能看清楚但 token 用量大
2. Token 用量估算：一張 1024×1024 圖經過 vision encoder 後、產出 ~500-2500 image tokens（依設計）、相當於一段中等長度的文字 prompt
3. 動態解析度模型更實用：Qwen2.5-VL / GPT-4V 等支援動態解析度、不會把高清截圖縮成 224 失去細節
4. Vision encoder 不能單獨 fine-tune：通常跟 LLM 一起訓、單獨換 vision encoder 會破壞 alignment

本章目標

學完本章後，你將能夠：

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

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

事件流程膨脹的常見原因是入口程式碼太方便。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 的可靠性要求不同，不能一律用同一個錯誤策略。

常見策略：

若 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 進階：資料庫 transaction 與 schema migration
• Go 進階：Durable queue、outbox 與 idempotency
• Backend：資料庫與持久化

和 Go 教材的關係

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

• Go：如何新增一個即時訊息 action
• Go：如何新增一種 domain event
• Go：用 interface 隔離外部依賴
• Go：逐步遷移到 ports/adapters 架構

小結

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

本章目標

學完本章後，你將能夠：

1. 判斷 [transaction boundary](/go-advanced/backend/knowledge-cards/transaction-boundary) 應該放在 repository 還是 usecase
2. 理解 migration 為什麼要維持向前相容
3. 分辨 application validation、constraint 與 isolation level 的責任
4. 用 contract test 保護 memory repository 與 database repository 的一致行為
5. 讓 SQL 細節留在 adapter，讓 domain 規則留在 application

前置章節

• Go 入門：如何新增 repository port
• Go 入門：狀態管理的安全邊界
• Go 進階：Source of Truth：狀態邊界
• Backend：Source of Truth
• Backend：Connection Pool

後續撰寫方向

1. Repository method 如何表達交易語意，讓 SQL 細節留在 adapter。
2. 一個 usecase 需要多筆寫入同時成功或失敗時，transaction boundary 應放在哪裡。
3. Migration 如何維持向前相容，避免新舊程式版本互相破壞資料。
4. Isolation level、unique constraint 與 application-level validation 如何分工。
5. Contract test 如何保護 memory repository 與 database repository 的一致行為。

【觀察】transaction 是一致性邊界

transaction 的核心用途是把一組資料庫操作綁成單一一致性單位。判斷重點是：這個 usecase 哪些狀態要一起成功或一起失敗。效能與寫入便利性都應放在一致性需求之後評估。

例如建立訂單時，可能同時需要：

• 寫入 order 主表
• 寫入 order items
• 更新 inventory
• 寫入 outbox event

如果其中一個步驟失敗，整組操作就應回滾，避免 application 狀態和資料庫狀態分裂。

【判讀】transaction boundary 應該跟 usecase 對齊

交易邊界最常見的錯誤，是把 transaction 放得太低或太高。

• 放太低：repository 各自開 transaction，usecase 層看起來成功，實際上無法保證整體一致。
• 放太高：把不需要一致性的讀取、外部 API、長迴圈也包進 transaction，讓連線被占住太久。

一般原則是：

• 要維持同一個 domain 不變式的寫入，應放在同一個 transaction。
• 可以重試或可補償的外部互動，通常應放在 transaction 之外。

【策略】Migration 要讓舊版與新版可以共存

schema migration 的核心是讓部署期間的新舊版本能同時活著。實務上常見的是 Expand / Contract 流程：

1. 先新增欄位、表或索引。
2. 讓新舊程式都能讀寫。
3. 確認流量已切到新版本。
4. 再移除舊欄位或舊邏輯。

這樣做的目的，是避免應用版本與資料庫版本在 rolling deploy 時互相踩到。

【判讀】constraint、validation 與 isolation level 各管不同風險

這三者的責任應清楚分工：

• application validation：在進資料庫前先檢查基本輸入是否合法。
• unique / foreign key / check constraint：在資料庫層保底，防止不合法資料落地。
• isolation level：處理多交易同時進行時的可見性與衝突問題。

如果只靠 application validation，資料庫仍可能被其他路徑寫入不合法資料。如果只靠資料庫 constraint，錯誤回報可能太晚。兩者通常要一起用。

【執行】contract test 檢查 repository 語意一致

當你同時有 memory repository 與 database repository 時，測試重點是它們對外暴露的語意是否一致。SQL 細節屬於 database adapter 的內部實作。

通常要測：

• 找不到資料時怎麼回傳
• 重複寫入時怎麼回傳
• transaction 失敗時是否維持一致狀態
• 欄位驗證與預設值是否相同

這類測試可以讓 repository adapter 保持可替換，讓資料庫替換時 usecase 維持穩定。

本章不處理

本章不會選定特定資料庫或 ORM。真正的重點是 Go application 如何定義資料一致性責任，讓 SQLite、PostgreSQL 或其他儲存技術都能成為可替換 adapter。

和 Go 教材的關係

這一章承接的是 Go 的 repository port 與狀態邊界；如果你要先回看語言教材，可以讀：

• Go：如何新增 repository port
• Go：狀態管理的安全邊界
• Go 進階：Source of Truth

對應到你已經熟悉的雲端世界：ChatGPT 網頁是介面層，OpenAI 的後端服務是伺服器層，GPT-5 模型是模型層。Cursor 是另一個介面層，連到的也是同一批雲端伺服器。介面跟伺服器各自獨立演化，這就是為什麼換介面不用換模型、換模型不用換介面。

本地 LLM 把這三層全部搬到你的 Mac 上，但分層關係不變。看懂這點，後面所有工具關係就清楚。

本章目標

讀完本章後，你應該能：

1. 看到任一個本地 LLM 工具，立刻判斷它屬於哪一層。
2. 理解為什麼可以「介面換、伺服器留」或「伺服器換、介面留」。
3. 看懂 localhost:11434 這類本地 API endpoint 的意義。
4. 對應雲端世界的工具，建立熟悉感橋接。

三層的責任邊界

這張表是後續判讀新工具的基底。任何工具都可以放到這三層的某一格；少數工具同時跨多層（例如 LM Studio 內建介面跟伺服器），但它的功能仍可拆成三層去理解。

介面層：你實際在用的東西

介面層的責任是「人類能舒服地把任務送進去、把結果拿出來」。它本身不跑模型，只是把使用者輸入打包成 API 請求、把 API 回應顯示出來。

接近真實的例子：

• Continue.dev：VS Code 擴充套件，把 Cmd+L 開啟側邊對話框、Cmd+I 觸發 inline 編輯。背後送的是 OpenAI 相容 API 請求，target 可以是本地 Ollama 也可以是雲端 OpenAI。
• aider：CLI 工具，把 git 倉庫狀態跟 prompt 一起打包送進 LLM，再把回應的 diff apply 到本機檔案。背後也是送 API 請求。
• Open WebUI：類 ChatGPT 風格的網頁介面，跑在本機 Docker 裡，連到本地或遠端的 LLM API。
• CLI 直接呼叫：ollama run gemma4:31b 在終端機開一個對話 session，本身也是一個介面層。

介面層的選擇影響日常使用體驗，但完全不影響推論速度或品質。換介面不用換模型，這就是分層的好處。

伺服器層：載入權重與跑推論

伺服器層負責把模型權重從磁碟載入記憶體、接收 HTTP API 請求、處理 prompt、跑推論、把生成的 token 流回客戶端。

接近真實的例子：

• Ollama：最主流的本地推論伺服器、預設聽 localhost:11434、提供 OpenAI 相容 API 與自己的原生 API。內建 model registry、ollama pull gemma4:31b 會自動下載權重檔。
• LM Studio：GUI 工具、內建模型瀏覽器與本地伺服器。可以在 UI 上開啟 server、預設聽 localhost:1234。適合喜歡可視化操作、不熟悉終端機的使用者。
• llama.cpp server：底層推論引擎附帶的 HTTP server、需要手動編譯與配置。Ollama 內部其實是用 llama.cpp 當推論引擎。
• oMLX：建在 MLX 之上的特化伺服器、主打 paged SSD KV cache、針對 coding agent 長 context 場景的首字延遲優化。詳見 0.4 MLX / MTP / oMLX。

伺服器層的選擇影響：

1. 速度：不同伺服器對量化、KV cache、speculative decoding 的支援度不同。
2. 能跑哪些模型：每個伺服器支援的模型格式不同（GGUF、MLX、Safetensors 等）。
3. API 形狀：多數本地伺服器同時提供「OpenAI 相容」跟「自家原生」兩套 API。詳見 0.3 OpenAI 相容 API。

陷阱是把伺服器跟模型混為一談。「Ollama 跑得快不快」這句話離開模型與機器脈絡就難以判讀、要追問「Ollama 跑哪個模型、在哪台 Mac 上、tok/s 多少」才有意義。伺服器是執行引擎、模型是被執行的對象。

模型層：權重檔本身

模型層就是神經網路的權重檔。本身只是一堆數字，沒有伺服器就無法執行；但同一個模型可以被不同伺服器載入，前提是格式相容。

接近真實的例子：

• Gemma 4 31B：Google 釋出的開源模型，31 billion 參數。權重檔可以是 gemma-4-31b-it-Q4_K_M.gguf（GGUF 格式、Q4 量化）或 mlx-community/gemma-4-31b-it-4bit（MLX 格式）。
• Qwen3-Coder 30B：Alibaba 釋出的 coding 專用模型、SWE-bench 等 coding benchmark 上表現強。
• Llama 3.x 系列：Meta 釋出的開源模型，是早期本地 LLM 生態的主力。
• gpt-oss 20B：OpenAI 釋出的開源版本，2025 年發布。

模型層的關鍵屬性：

1. 參數規模（B = billion）：7B、14B、31B、70B 等。規模越大能力越強，但記憶體佔用、推論速度成本也越高。
2. 量化等級：bf16、Q8、Q5_K、Q4_K 等。同模型不同量化，記憶體與品質的取捨不同。
3. 格式：GGUF（llama.cpp 與 Ollama 主流）、MLX（Apple 框架）、Safetensors（Hugging Face 通用）等。不同伺服器支援的格式不同。
4. 訓練目的：base model、instruction-tuned、coding-tuned 等。寫 code 場景下 instruction-tuned + coding 版本通常勝過 base model；base model 適合下游微調研究、直接拿來對話的場景較少。

模型選擇影響能力與速度。同樣 32GB Mac 跑 Gemma 4 31B 跟 Qwen3-Coder 30B，兩個模型擅長的任務不同，速度也不同。詳見 模型選型章節。

拼裝組合：三層的搭配範例

理解三層後，本地 LLM 的所有「組合」都變得簡單。下表是幾個常見組合：

表格中的規格欄位（量化等級、gemma4:31b-coding-mtp-bf16 這類 model tag、Q3 等）含義見 0.5 記憶體預算 與 Ollama model tag 命名規則。

注意三件事：

1. 介面跟伺服器之間用 HTTP API 通訊，所以介面層可以同時連多個伺服器，或一個伺服器服務多個介面層。
2. 同一個介面（如 Continue.dev）可以同時設定本地 Ollama 跟雲端 OpenAI，根據任務切換。
3. LM Studio 自己同時是介面 + 伺服器，所以表上有兩列；但它的伺服器部分也可以對外 expose，讓其他介面（如 Continue.dev）連進來。

雲端對應關係：建立熟悉感橋接

下表把本地三層對應到雲端世界，幫助建立直覺：

這個對應的關鍵啟示是：Cursor 跟 Continue.dev 都是介面層、差別在於 Cursor 預設綁雲端、Continue.dev 預設綁本地、但兩者的責任邊界一樣。換句話說、要在 VS Code 裡接本地 LLM、不需要尋找專屬「本地版的 Cursor」、找一個能設定 OpenAI 相容 endpoint 的介面層就好。

分層失效徵兆：什麼時候三層心智模型會失準

三層架構是教學用的乾淨模型、實務上有幾類工具會跨層或讓邊界模糊、判讀時要對應調整：

1. 同層耦合（介面 + 伺服器綁死）：LM Studio 的 GUI 跟內建 server 同屬一個 app、關掉 LM Studio 視窗 server 就停。這類工具用起來方便、但失去「介面換、伺服器留」的彈性、想常駐 server 時建議改用 Ollama 的 launchd service 模式。
2. 伺服器內嵌引擎（責任邊界模糊）：Ollama 內部用 llama.cpp 當推論引擎、但對使用者展現的是 Ollama API 跟 model tag。看到「Ollama 不支援某個 llama.cpp 新功能」時、要回到 Ollama 的 release notes 看版本 cherry-pick 狀態、不是看 llama.cpp 上游。
3. All-in-one 工具淡化分層：Open WebUI 把介面、user 管理、RAG pipeline 都包進一個 Docker container、看起來像「裝完就能用」、但底層仍要連到一個伺服器層（Ollama / OpenAI）。判讀此類工具時、先問「它的 server 是內建還是外接」、就能放回正確的分層。
4. 「Cursor 是本地工具嗎」常見誤判：Cursor 是介面層、它連的是雲端伺服器層、跑的是雲端模型 — 不是本地工具。對應到本地的是 Continue.dev + Ollama + 本地模型的組合。

判讀新工具的反射動作：先把它拆成三層（這工具負責介面 / 伺服器 / 模型 的哪一段？）、再問「它做了多少跨層耦合、影響什麼彈性」。

下一章

下一章：0.3 OpenAI 相容 API，解釋為什麼三層之間能自由組合，背後是同一套 API 形狀。

為什麼這章在第零章

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

組合先描述擁有什麼

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

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

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

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

小介面先描述需要什麼

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

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

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

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

依賴由外層組裝

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

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

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

行為可以用 embedding 重用

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

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

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

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

組合讓測試替換更自然

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

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

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

本章目標

學完本章後，你將能夠：

1. 分辨 event ID 去重與 domain key 去重的差異
2. 用 subject、event type、source group 與時間窗口設計 DedupKey
3. 避免把不穩定欄位放進去重鍵
4. 設計去重表的過期與清理策略
5. 用 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 或兩者並用。不同層級解決的問題不同。

小型服務可以先使用 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

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

時間窗口不是萬用答案。若事件本身允許短時間內多次發生，就需要更細的 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，會在下列章節再往外延伸：

• Backend：快取與 Redis
• Backend：資料庫與持久化
• Go 進階：Durable queue、outbox 與 idempotency

和 Go 教材的關係

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

• Go：如何新增一種 domain event
• Go：如何新增背景工作流程
• Go：用 interface 隔離外部依賴
• Go：事件去重邏輯的重構策略

小結

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

本章目標

學完本章後，你將能夠：

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

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

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

例如：

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 時，可以依序檢查：

1. event type 是否描述已經發生的事
2. event type 是否是內部穩定語意，而不是外部欄位名稱
3. envelope 是否包含 source、type、subject、occurred/received time
4. payload 是否只放事件特有補充資料
5. raw input 是否先經過 adapter normalize
6. adapter 是否不直接更新 repository
7. validation 是否保護事件基本合約
8. dedup key 是否建立在 domain 語意上
9. 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 融合
• Go 進階：Durable queue、outbox 與 idempotency
• Backend：訊息佇列與事件傳遞

和 Go 教材的關係

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

• Go：如何新增一個即時訊息 action
• Go：如何新增背景工作流程
• Go：用 interface 隔離外部依賴
• Go：事件去重邏輯的重構策略

本章目標

學完本章後，你將能夠：

1. 理解 outbox 為什麼能避免半成功
2. 分辨 domain dedup key 與 idempotency key 的用途
3. 設計可重入的 consumer / processor
4. 用 retry、DLQ 與回補流程處理失敗事件
5. 把事件可靠性寫進資料結構，讓規則可以被程式與測試驗證

前置章節

• Go 進階：非阻塞送出與事件丟棄策略
• Go 進階：事件去重與語義鍵設計
• Go 進階：多來源 event 融合
• Backend：Ack / Nack
• Backend：Retry Policy
• Backend：Dead-Letter Queue
• Backend：Consumer Lag

後續撰寫方向

1. Outbox 如何避免「狀態已寫入，但事件沒送出」的半成功。
2. Idempotency key 如何和 domain dedup key 分工。
3. Consumer retry、dead-letter queue 與 poison message 如何設計處理流程。
4. At-least-once delivery 下，processor 如何保持可重入。
5. Queue lag、retry count、dead-letter count 應如何進入 log 與 metric。

【觀察】outbox 是把資料與事件綁在同一個 transaction

outbox 的核心概念是：先把業務狀態與待發事件一起寫進資料庫，再由獨立 publisher 把 outbox 內容送到 queue 或 broker。這樣即使 process 在寫完資料後當機，也不會丟掉事件。

典型流程是：

1. usecase 開 transaction。
2. 寫入 domain data。
3. 寫入 outbox record。
4. commit。
5. background publisher 讀出未送出的 outbox。
6. 成功後把 outbox 標成已送出。

這個模型的重點是讓「至少會被發現並補送」成為可能。它承認跨 process 傳遞很難保證絕對只送一次，所以後續還要搭配 idempotency。

【判讀】idempotency 是跨 process 的必要邊界

只要事件可能重送，consumer 就要能承受重複訊息。idempotent processor 的核心是讓同一筆事件重複進來時，結果仍然穩定。

常見做法包括：

• 用 event ID 記錄已處理過的訊息
• 用 domain key 去重，讓同一個業務操作不會重複套用
• 用狀態機檢查 transition 是否已發生

【策略】DLQ 是流程的一部分

當事件重試失敗，dead-letter queue 要變成可處理的操作流程。你要知道：

• 為什麼失敗
• 要重試幾次
• 什麼錯誤可以直接放棄
• 什麼錯誤需要人工回補

如果沒有這些規則，DLQ 只會變成看不完的黑洞。

【執行】可重入 processor 的基本形式

可重入的核心要求是同一事件重跑時，不會把資料弄壞。簡化的處理流程通常長這樣：

 1func (p *Processor) Handle(ctx context.Context, evt Event) error {
 2    if p.store.Seen(evt.ID) {
 3        return nil
 4    }
 5
 6    if err := p.store.Apply(ctx, evt); err != nil {
 7        return err
 8    }
 9
10    return p.store.MarkSeen(ctx, evt.ID)
11}

實際實作時，Seen 與 MarkSeen 通常要跟業務狀態放在同一個一致性邊界裡，避免競態。

【延伸】queue lag 與 retry 需要被觀測

只要有 durable queue，就一定會有 backlog、retry 與 failure pattern。這些訊號應進入 log 與 metric，讓工程師知道是 producer 變慢、consumer 壞掉，還是下游依賴正在抖動。

本章不處理

本章不追求 exactly-once 的口號。教材重點會放在 Go 服務如何承認 at-least-once 的現實，並用 idempotent processor、outbox 與可觀測欄位降低風險。

和 Go 教材的關係

這一章承接 Go 的事件邊界與非阻塞送出；如果你要先回看語言教材，可以讀：

• Go 進階：非阻塞送出與事件丟棄策略
• Go 進階：事件去重與語義鍵設計
• Go 進階：多來源 event 融合

本章目標

學完本章後，你將能夠：

1. 設計穩定的 client action envelope
2. 把 router、handler、usecase 與 client state 分開
3. 用訂閱集合表達 client 想收到的 topic
4. 在 broadcast 前檢查訂閱狀態
5. 測試 action routing、payload validation 與 error response

【觀察】client message 很容易變成臨時協定

WebSocket action 的核心風險是前後端快速加功能時，訊息格式變成一堆臨時欄位。若 action 名稱依賴按鈕、畫面或短期 UI 狀態，server 很快會累積難以維護的分支。

不穩定的訊息格式：

1{
2  "button": "watch",
3  "tab": "jobs",
4  "id": "topic_1"
5}

這種訊息描述 UI 發生什麼，不是描述 client 想對服務做什麼。服務端應該接收穩定 action，例如 subscribe_topic、unsubscribe_topic、list_subscriptions。

【判讀】action 是 client intent

Client action 的核心語意是「client 想做什麼」。它不是 domain event，因為它還沒被驗證、授權或套用規則。Domain event 表示已經發生的事，action 表示請求。

 1type ClientAction string
 2
 3const (
 4    ActionSubscribeTopic   ClientAction = "subscribe_topic"
 5    ActionUnsubscribeTopic ClientAction = "unsubscribe_topic"
 6    ActionListTopics       ClientAction = "list_topics"
 7)
 8
 9type ClientMessage struct {
10    Action ClientAction    `json:"action"`
11    Data   json.RawMessage `json:"data,omitempty"`
12}

外層 envelope 穩定，內層 Data 依 action 解析。這讓 read pump 可以先解析 envelope，router 再依 action 決定 payload 型別。

【策略】router 負責分派，不擁有全部規則

Router 的核心責任是把 action 分派到對應 handler。它應該知道有哪些 action，但不應把訂閱規則、權限檢查、資料查詢全部塞在一個巨大 switch 裡。

 1type Router struct {
 2    subscriptions *SubscriptionService
 3}
 4
 5func (r Router) Route(ctx context.Context, client *Client, message ClientMessage) error {
 6    switch message.Action {
 7    case ActionSubscribeTopic:
 8        return r.handleSubscribe(ctx, client, message.Data)
 9    case ActionUnsubscribeTopic:
10        return r.handleUnsubscribe(ctx, client, message.Data)
11    case ActionListTopics:
12        return r.handleListTopics(ctx, client)
13    default:
14        return fmt.Errorf("unknown action: %s", message.Action)
15    }
16}

switch 讓支援的 action 集中可見。真正的訂閱狀態修改可以交給 SubscriptionService 或 client method，避免 router 變成所有規則的聚集地。

【執行】payload validation 在 action 邊界完成

Payload validation 的核心責任是讓內部服務只收到有效 command。訂閱 topic 至少要檢查 JSON 格式、topic 是否空白、topic 名稱是否符合規則。

 1type SubscribeTopicRequest struct {
 2    Topic string `json:"topic"`
 3}
 4
 5type SubscribeTopicCommand struct {
 6    ClientID string
 7    Topic    string
 8}
 9
10func (r Router) handleSubscribe(ctx context.Context, client *Client, raw json.RawMessage) error {
11    var req SubscribeTopicRequest
12    if err := json.Unmarshal(raw, &req); err != nil {
13        return fmt.Errorf("decode subscribe request: %w", err)
14    }
15
16    topic := strings.TrimSpace(req.Topic)
17    if topic == "" {
18        return fmt.Errorf("topic is required")
19    }
20
21    cmd := SubscribeTopicCommand{
22        ClientID: client.ID(),
23        Topic:    topic,
24    }
25
26    return r.subscriptions.Subscribe(ctx, client, cmd)
27}

Request struct 是 wire format，command 是內部意圖。兩者分開後，JSON 命名、驗證錯誤與內部服務規則不會混在同一個型別。

【執行】訂閱集合是連線狀態

訂閱集合的核心語意是「這個 client 目前想收到哪些 topic」。它可以放在 client 上，也可以由 hub 集中保存；重點是 owner 要明確。

Client owner 版本：

 1type Client struct {
 2    id string
 3
 4    mu            sync.RWMutex
 5    subscriptions map[string]struct{}
 6}
 7
 8func (c *Client) Subscribe(topic string) {
 9    c.mu.Lock()
10    defer c.mu.Unlock()
11    c.subscriptions[topic] = struct{}{}
12}
13
14func (c *Client) Unsubscribe(topic string) {
15    c.mu.Lock()
16    defer c.mu.Unlock()
17    delete(c.subscriptions, topic)
18}
19
20func (c *Client) IsSubscribed(topic string) bool {
21    c.mu.RLock()
22    defer c.mu.RUnlock()
23    _, ok := c.subscriptions[topic]
24    return ok
25}