本章目標

學完本章後，你將能夠：

1. 說明 Go 為什麼偏好顯式控制流程
2. 看懂入口程式中依賴組裝的意圖
3. 區分「程式碼短」和「認知負擔低」
4. 用 Go 的風格閱讀現有服務

為什麼這章在第零章

如果工作負載、架構與 runtime 條件已經顯示 Go 是合適選項，接下來就要理解 Go 為什麼會長成現在這種樣子。簡單、顯式、少魔法是讓高併發服務在多人維護時仍能被快速理解的工程策略。

【觀察】Go 程式的入口通常很直

一個簡化的通知程式，入口可能會做幾件明確的事：

1events := make(chan Event, 128)
2notifications := make(chan Notification, 128)
3
4repo := NewNotificationRepository()
5worker := NewWorker(repo, events, notifications)
6server := NewHTTPServer(repo, notifications)

這段程式沒有依賴注入框架，也沒有隱式容器。所有元件的建立順序、依賴關係、資料流向都直接寫在入口。

這種寫法特別適合服務型應用：當系統需要處理很多並發請求、背景工作或外部事件時，入口越清楚，就越容易確認誰負責什麼、失敗時會停在哪裡。

【判讀】簡單是少猜幾件事

對維護者來說，入口程式的主要工作是回答三個問題：

1. 哪些元件存在？
2. 元件彼此怎麼連接？
3. 程式關閉時誰負責停止？

Go 偏好把這些答案留在表面。當你看到 NewWorker(repo, events, notifications)，你不需要先理解框架規則，就能知道 worker 依賴 repository，從事件 channel 讀資料，輸出通知到另一個 channel。抽象的責任是讓資料流更容易判讀；抽象若讓讀者需要猜測背後規則，就削弱了 Go 在長期維護上的主要價值。

【策略】閱讀 Go 程式先找資料流

讀 Go 應用時，可以用以下順序降低認知負擔：

這個順序先建立系統地圖，再深入單一函式，避免一開始就陷入細節。

【執行】用入口程式畫出資料流

即時通知服務可以先整理成這張資料流：

1file / HTTP / timer ──> events ──> Worker ──> notifications
2                                      │
3                                      ▼
4                                  Repository
5                                      │
6                                      ▼
7                                   HTTP API

這張圖比逐行閱讀更重要。它先回答「系統如何運作」，再讓你回到個別函式確認細節。

9.1–9.4 講了怎麼寫 Go 工具。這一章退一步，看什麼時候該寫這個工具、什麼時候該升級既有工具。決策錯了，寫得多好都沒用。本章介紹 tripwire 決策法、WRAP 框架在技術決策的套用、以及用 blog 工具鏈選型作為 concrete instance。

為什麼需要 tripwire

「什麼時候升級」本身是決策。如果不做預設，會發生兩件事：

太早升級：每次問「該不該升」的時候都說「升吧反正不會錯」。結果工具複雜度爆炸，維護成本拖慢產品開發。

太晚升級：每次都說「regex 再撐一下就好」。結果工具的誤判累積，作者開始手動 override、skip lint、加例外，工具信譽破產。

Tripwire 是事前約定：「當以下條件之一命中，就重新評估是否升級」。這把「該不該升」從臨時直覺變成有根據的再評估。

這個概念在 Chip 與 Dan Heath 的《Decisive》裡有詳細討論 — tripwire 的要點是用事前的明確條件，取代事後的模糊直覺。

WRAP 框架套用到工具決策

WRAP = Widen options / Reality-test / Attain distance / Prepare to be wrong。對應到技術決策：

Widen options：不要只在「Go 還是 Python」之間選。多選項至少要有：

• 現有工具撐著（regex + shell）
• 半自動化（Python + regex，50 行腳本）
• 自訂工具（Python / Go + 適當 parser）
• 買服務（買現成 linter SaaS）
• 不解決（接受這個問題）

Reality-test：用數字跟樣本驗證假設。「regex 夠用」是假設，數字可能說「每 100 個 match 裡 15 個誤判」。

Attain distance：退一步看，如果這個工具三年後可能被捨棄，現在投入多少才合理。

Prepare to be wrong：先設 tripwire，萬一決策錯了也能及時 pivot，不會沉沒到底。

blog 的工具鏈決策用這個框架跑過一次，結論是 Go + goldmark。過程紀錄在 mdtools 設計，這裡只提煉可複用的決策 pattern。

三個實戰 tripwire

以下三組 tripwire 對多數內部工具都適用。遇到其中一個命中時，該花一小時重新評估現有工具是否夠用。

Tripwire 1：從 shell one-liner 升級到腳本

訊號：

• 同樣的 shell 指令在三個以上地方重複貼過
• 指令超過 3 個 pipe 或巢狀 subshell
• 指令的行為要根據環境（CI vs local）分支

升級方向：寫成 20-50 行 Python 或 Bash script，放進 scripts/。

反例：每次寫新 shell 命令都起腳本檔。常用的一行 grep 不需要變 script。

Tripwire 2：從 regex 升級到 parser / AST

訊號：

• Regex 需要「上下文判斷」（這個 match 在 code block 內嗎？在 HTML tag 內嗎？）
• 規則要處理嵌套結構（表格內的 link、code block 內的 heading）
• 誤報率超過 1% 或每週出現
• 新規則要知道「父節點」「子節點」（MD024 siblings_only 就是這類）
• 跨檔案的 graph 需求出現（backlink 分析、broken link 偵測）

升級方向：引入該格式的官方 parser（markdown → goldmark；YAML → gopkg.in/yaml.v3；Go → go/parser）。

反例：簡單的「每行開頭是 # 就當 heading」這類規則，regex 永遠夠用。不要為了「學 AST」硬上。

Tripwire 3：從腳本語言升級到 Go

訊號：

• 需要 parse 有官方 Go 實作的格式（goldmark、go/ast、protobuf 等）
• 需要跨平台分發單一 binary
• Python / Node 的啟動時間在 pre-commit 的 accumulated cost 已感
• 要整合到 Go 生態系（產生 Go 程式碼、讀 Go 原始碼）
• 團隊主要語言是 Go，Python 腳本的維護者變成單一瓶頸

升級方向：Go。

反例：臨時的資料轉換、一次性的 data migration、快速 prototyping — Python 永遠比 Go 快動筆。

實戰紀錄：blog 的三層升級

blog 的 markdown 品質工具鏈在一個 session 內走完三層升級。把這個時間線攤開當案例。

Layer 0：沒工具，靠 markdownlint IDE extension

狀況：IDE 裝 markdownlint extension，作者寫稿時看到 yellow underline 手動改。

出現什麼 tripwire：內容規模長大後，reviewer 收到 PR 發現 20 個 MD026 違規，手動改成 cognitive burden。更糟的是紅隊教材有平行結構（13 個案例各有 ### 弱點環節），被 MD024 誤判為重複，作者開始 ignore 警告。

升級驅動：Tripwire 2 命中（規則需要父標題上下文，siblings_only 規則 IDE 沒有）。決策：升級到自訂工具。

Layer 1 候選：Python + regex

狀況：50 行 Python 腳本，逐行 match。

為什麼沒選：兩個跨檔需求已經浮現 — 卡片雙向完整性、L1 link 驗證。這是 graph 需求，regex 做不到 (Tripwire 2 的後半段命中)。加上 blog 本身用 Hugo（Go 寫的，markdown 由 goldmark parse），用 Python 的 markdown parser 會有 render 跟 lint 判讀不一致的長尾風險。

這個評估花了約 15 分鐘，記錄在決策文件裡 — 重點是評估本身有 artefact 可追溯。

Layer 2：Go + goldmark

狀況：選 Go，因為 (a) goldmark 是 Hugo 的 parser，lint 結果跟 render 必然一致；(b) 跨檔 graph 分析用 Go struct 乾淨；(c) 單一 binary 方便接 pre-commit hook 跟 CI，不用擔心 Python 環境。

如何驗證決策正確：看三個月後的狀態 — 工具有沒有被 bypass？新規則加起來順不順？CI 有沒有反覆失敗？作者有沒有開始覺得工具阻礙產出？這些訊號都沒出現，表示決策有效。若有出現，就是 Tripwire 3 的反向觸發（「該降級回 Python」或「該拆成多個專門工具」），又要重新評估。

延遲決策的具體成本

常見反論：「不急，等真的需要再升」。問題是延遲本身有成本：

• Technical debt 複利：regex 工具越長越大，每條新 rule 都變難，最後要重寫時要一次 migration 所有 rule。
• 誤報侵蝕信譽：使用者每週看到工具報錯、檢查後發現是誤判，開始忽略工具。信譽一旦壞，再好的工具也沒用。
• Option value 流失：跨檔分析、graph 視覺化、CI 整合這些 downstream feature 都要在 AST 基礎上才能做；延遲升級等於延遲 feature 路徑。
• 機會成本複利：每週花 30 分鐘手動改 lint 誤判，一年累積 26 小時 — 比升級工具的 8 小時多 3 倍。

時間視角變長，升級的 NPV 幾乎永遠正。延遲不是零成本的預設，是要主動合理化的選擇。

為什麼 blog 不走「先 Python 再 Go」的雙階段

有個常見建議：「先用 Python 快速做出雛形，驗證概念後再用 Go 重寫」。這個建議對不確定需求的情境有效（「我們不知道要什麼工具」），對已知需求的情境是浪費。

blog 的狀況是已知：

• 要 markdown lint + 跨檔 graph + pre-commit + CI — 四個需求都很明確
• 目標語言（Go）已經確定（Hugo 生態、單一 binary 需求）
• 第三方 parser 選擇（goldmark）已經是最優解

在這些條件下，寫 Python 原型的唯一價值是「學 AST 概念」。但同樣學習也能直接用 Go + goldmark 完成。花兩倍時間寫兩遍只為了「先驗證」，邏輯不成立。

判準：需求越明確、目標語言越確定，雙階段越浪費；需求越模糊、選型還在評估，雙階段越值得。

決策的副作用：artefact

不管最終選什麼，決策過程本身要留下 artefact。blog 案例裡的 artefact：

• mdtools 設計紀錄：為什麼是 Go、為什麼是 goldmark、tripwire 怎麼設的
• 什麼是 AST：AST vs regex 的概念說明
• markdown 寫作規範：工具要滿足的契約

三個文件加起來約 900 行，寫作時間不到半天。

為什麼留 artefact 比決策本身更重要：

• 半年後同樣問題再浮現時，不會重跑一遍評估
• 新加入的協作者能快速跟上決策脈絡
• Tripwire 條件寫下來才能被驗證（「三個月後有沒有命中？」）
• 反面證據出現時（例如發現 goldmark 有 bug），有清楚的位置記錄 revised decision

沒 artefact 的決策基本上等於沒做過。決策是動作，artefact 才是沉澱。

常見陷阱

把 tripwire 設太低

「每週誤判一次就升級」實務上等於「每週升級」。Tripwire 要設在真的造成信譽或產出瓶頸的位置。

把 tripwire 設太高

「等到 50% 誤判才升級」就太晚了 — 信譽早就垮了。合理範圍是 1-5% 誤判，或每週一次以上。

用 tripwire 取代日常 review

Tripwire 是「提醒重新評估」，不是「自動升級」。命中時要花時間評估，可能發現「還不該升，因為還有 X 原因」。Tripwire 是重新思考的觸發，不是自動化決策。

忽視已命中的 tripwire

「這個誤判已經出現第四週了，但我還是覺得先不要升」— 這是在告訴自己原本的 tripwire 設錯了，不是在等更好的時機。重新評估 tripwire 本身，不是 ignore。

擴充路徑

• Decision log 範本：把團隊的決策過程寫成 template，讓下次不用從零開始
• Post-mortem of decisions：決策後三個月回頭看，把「當時怎麼想」跟「現在怎麼看」對照
• Pre-mortem 技巧：決策前假設「三個月後這決定被推翻，最可能的原因是什麼」，當成補充 tripwire

下一步

9.6 pre-commit hook 與 CI 整合 回到工程落地，看工具怎麼從 binary 變成 commit 與 CI 流程裡的執行體。

實戰章節的重點是練習 Go 的判斷方式：何時只需要 struct，何時需要 method，何時需要 interface，何時需要 goroutine，何時應該把狀態集中管理。大型架構模板留到壓力出現後再評估；服務設計只是這些語言概念的應用場景。

章節列表

本模組的教學主軸

• 資料先有語意：struct 欄位、JSON tag、zero value 與 omitempty 都要表達資料意義。
• 邊界先小後大：先用函式與 struct 整理行為，只有在替換、測試或隔離需求出現時才引入 interface。
• goroutine 要有生命週期：背景工作必須能取消、停止與測試；只把工作丟進 go func() 會讓 shutdown、錯誤回報與測試邊界變模糊。
• 記錄要按用途分流：log 用於操作診斷，event log 用於事實記錄，repository 用於目前狀態。
• 架構來自壓力：domain package、repository port、event envelope 是服務變大後的自然拆分，不是入門程式的預設起點。

章節粒度說明

本模組每一章都是「完成一個常見開發任務」的完整流程，所以篇幅會比語法章長。章節會同時包含資料定義、邊界判斷、簡化實作、測試與設計檢查；這是為了讓讀者看到一次修改如何穿過 Go 服務的多個層次。

細節主題會在後續模組拆開深入：

本模組使用的範例主題

• 即時通知服務的 action route
• domain event envelope
• 任務狀態 projection 更新
• 背景 worker 啟動與停止
• structured log 欄位
• repository port 與 memory implementation

學習時間

預計 2-3 小時

本章目標

學完本章後，你將能夠：

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

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

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

這些場景共通點都是：工作量大多是 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 常被放在哪裡，後面的實戰章節就會更容易理解。

本章目標

學完本章後，你將能夠：

1. 辨認 handler、state、interface 與 adapter 的壓力訊號
2. 了解什麼時候該先拆函式，什麼時候該拆 package
3. 用小步遷移方式保持行為穩定
4. 將重構與測試保護綁在一起
5. 讓服務變大時仍能維持可讀性

【觀察】壓力通常先出現在局部

Go 服務變大後，最先冒出來的問題通常是局部壓力：

• handler 開始太厚
• state 太分散
• event 語意不清
• 依賴越來越多
• 測試開始很脆弱

這些訊號表示該重構，但不代表要一次重寫。

【判讀】先保行為，再搬結構

重構的基本順序應該是：

1. 先讓行為有測試或觀察點
2. 再把大函式拆成小函式
3. 再把責任拆到 package 或 interface
4. 最後才引入更清楚的 adapter 邊界

這樣可以降低重構風險，也比較符合 Go 的漸進式習慣。

【策略】先拆最有壓力的邊界

最值得先處理的通常是這幾種：

這些動作不一定同時做，而是按壓力大小逐步處理。

【執行】composition root 是最後的收斂點

當系統開始出現明確的 application、domain 與 adapter 時，composition root 會變成依賴組裝的收斂點。重構的目標是讓邏輯邊界與依賴方向更穩定。

預計補充內容

這些工具使用邊界會在下列章節展開：

• Go 入門：從入口程式看應用啟動流程：先看 go run 與 go build 如何對應入口 package，才能理解 Go 專案真正的執行起點。
• Go 入門：testing 基礎：先建立最小回歸檢查的習慣，再談 go test ./... 在流程中的角色。
• Backend：可靠性驗證流程：CI 與自動化驗證的責任在這裡展開，不應塞進語言章節。
• Backend：部署平台與網路入口：容器建置、發布門檻與平台合約屬於部署層，不是 toolchain 本身。

與 Backend 教材的分工

本章只處理 Go toolchain。CI pipeline、container build、部署前 gate 與 release artifact 會放在 Backend：可靠性驗證流程 與 Backend：部署平台與網路入口。

和 Go 教材的關係

這一章承接的是入口流程、測試與設定讀取；如果你要先回看語言教材，可以讀：

• Go：從入口程式看應用啟動流程
• Go：testing 基礎
• Go：flag、os/env 與設定邊界
• Go：composition root 與依賴組裝