三問設計法

每個 gate 設計時回答三個問題：

成功時做什麼

Gate 通過後使用者進入下一步。這是最直覺的設計 — 認證成功進入主畫面、網路連線成功開始載入資料、權限授予後啟用功能。

成功路徑通常是設計時最先考慮的，也是最不容易遺漏的。

失敗時做什麼

Gate 未通過時使用者的替代路徑。替代路徑可以是：降級功能（部分功能可用）、替代驗證方式（密碼代替 Face ID）、手動重試（重試按鈕）、放棄操作（返回上一頁）。

失敗路徑是最容易遺漏的。app_tunnel 的 biometric gate 設定 biometricOnly: true，Face ID 不可用時使用者直接被擋住，沒有密碼 fallback、沒有跳過選項、沒有返回路徑（U.C2）。修復只改一個 boolean — biometricOnly: false — 讓系統自動提示輸入裝置密碼。但這個決策應該在企劃階段做，而非實機測試時才發現。

使用者不知道發生什麼時做什麼

Gate 處理中（loading）或結果不確定（timeout）時使用者看到什麼、能做什麼。

使用者不知道發生什麼的情境包括：認證彈窗尚未出現（系統延遲）、網路請求已發但未回應（loading）、權限對話框被系統遮擋（多個 dialog 堆疊）。

在這個狀態下使用者需要的是：知道系統在做什麼（loading 指示）、可以取消等待（取消按鈕）、超過合理時間後有提示（timeout 訊息 + 重試選項）。

Gate 的四種常見類型

認證 Gate

使用者必須驗證身份才能使用功能。生物辨識、密碼、PIN 碼、OAuth 登入。

認證 gate 的 fallback 設計取決於安全需求和使用場景。銀行 app 可能要求生物辨識 + PIN 碼雙重驗證，沒有更低層級的 fallback。自用工具可以接受密碼 fallback，因為使用者本身就是 owner — 可用性優先於認證強度（U.C2）。

網路 Gate

功能需要網路連線才能運作。連線存在但不穩定的場景比完全離線更難處理 — 請求可能成功、可能逾時、可能部分成功。

權限 Gate

App 需要系統權限（相機、位置、通知）才能使用特定功能。

權限 gate 的特殊性在於使用者可以永久拒絕。拒絕後再次請求不會彈出系統對話框 — 必須引導使用者到系統設定手動開啟。

環境 Gate

特定的硬體或軟體條件必須滿足。最低 OS 版本、特定感測器（NFC、深度相機）、特定連接（藍牙已開啟）。

環境 gate 的 fallback 通常有限 — 硬體不存在時無法用軟體模擬。但至少應該告知使用者為什麼功能不可用，而非靜默禁用。

其他常見 Gate

商業 app 還有兩種 gate 在本系列涵蓋範圍之外但實務常見：

付費 Gate（paywall）：功能需要付費才能使用。付費 gate 的 fallback 設計和上述四種不同 — 「失敗」路徑的目標是引導使用者付費而非提供替代功能。試用期、降級功能、付費引導 vs 付費強制的取捨依賴商業模式決策。

版本相容性 Gate：API 版本過舊需要升級 app。Fallback 是提示使用者更新，但強制更新會阻擋無法更新的使用者（舊 OS 版本不支援新版 app）。

Gate 設計表

把三問設計法應用到每個 gate，產出一張設計表：

失敗欄和不確定欄為空的 gate 就是 UX 死胡同的候選 — 和畫面狀態矩陣的退出路徑檢查同樣的邏輯。

三問設計法的具體應用在 Biometric fallback 完整設計中以生物辨識 gate 為例展開。Gate 在開發環境的行為可能和真機不同，開發環境 vs 真機的 gate 行為差異表列出每個 gate 在模擬器和真機上的差異。Gate 設計表的「失敗」欄和畫面狀態矩陣的「退出路徑」欄是同一個問題在不同層級的表達。

連線生命週期 log

連線生命週期 log 記錄的是「流程走到第幾步、每步成功或失敗」。這一層的 log 粒度是步驟級 — 不記錄每一個封包或每一次函式呼叫，只記錄流程中的關鍵節點。

以 app_tunnel 的連線流程為例，連線生命週期包含五步：biometric 認證 → credential 讀取 → WebSocket 連線 → auth token 發送 → stream 訂閱。每步完成時記一條 log，失敗時記一條包含原因的 log。

1[conn] Step 1/5: biometric auth completed (duration: 320ms)
2[conn] Step 2/5: credential loaded (user: admin)
3[conn] Step 3/5: WebSocket connected (url: wss://...)
4[conn] Step 4/5: auth token sent
5[conn] Step 5/5: stream subscribed, ready

app_tunnel 在實機測試前六個核心元件中只有兩個有 log，且全是 W2 修復時事後補上的（T.C4）。W2-002 auth token 問題的 debug 過程中，開發者無法從任何 log 判斷失敗發生在五步中的哪一步。如果有連線生命週期 log，第一次連線就能看到「Step 3 完成，Step 4 未執行」— 直接定位到 auth token 缺失。

連線生命週期 log 在所有模式（debug 和 release）都應該啟用。這層 log 量小（每次連線 5-10 條），不影響效能，但在 production 問題回報時是第一手資訊來源。

Protocol 訊息 log

Protocol 訊息 log 記錄的是通訊協議層面的細節：發送和接收的 frame type、payload 前綴、handshake 參數、逾時值。這一層的粒度比連線生命週期更細 — 每一次 send/receive 都記錄。

1[proto] TX: text frame, payload: {"AuthToken":"base64..."} (42 bytes)
2[proto] RX: text frame, payload prefix: "0" (output data, 128 bytes)
3[proto] TX: binary frame, payload: [72, 101, 108, 108, 111] (5 bytes)

Protocol log 在 debug 時幫助確認「程式碼發送了什麼、收到了什麼」。app_tunnel 的 text/binary frame 問題（T.C1）如果有 protocol log，開發者會在 log 中看到 TX: binary frame 而非預期的 TX: text frame — 直接指向 frame type 問題。

Protocol log 在 release mode 應該能關閉。這層 log 量大（每次鍵盤輸入一條），且 payload 可能包含敏感資訊。Debug mode 預設啟用，release mode 提供開關（例如隱藏設定頁的 toggle）讓進階使用者在回報問題時開啟。

使用者行為 log

使用者行為 log 記錄的是使用者在 UI 上的操作：按鈕點擊、畫面切換、設定變更。這層 log 的粒度是操作級 — 使用者做了一個有意義的動作記一條。

1[ui] screen: HomeScreen, action: tap Connect Terminal
2[ui] screen: TerminalScreen, state: connecting → connected
3[ui] screen: TerminalScreen, action: tap back button
4[ui] screen: HomeScreen, state: returned from terminal

使用者行為 log 在兩個場景有價值：第一，debug 時還原使用者操作路徑 — 「使用者做了什麼導致問題出現」；第二，結合狀態矩陣（ux-design 模組一）做狀態轉換的實際覆蓋率分析 — 哪些狀態轉換在真實使用中經常發生，哪些從未發生。

使用者行為 log 在 release mode 啟用時需要注意隱私。記錄「使用者切換了畫面」是合理的；記錄「使用者輸入了密碼 abc123」需要 redaction 機制（monitoring 模組七 資安）。

三層的關係

三層 log 各自獨立運作，debug 時通常按照從粗到細的順序使用。

粗篩：先看連線生命週期 log，確認流程走到哪一步。如果 Step 3 失敗，問題在 WebSocket 連線層。

細查：切到 protocol 訊息 log，看 Step 3 的連線嘗試中發送和接收了什麼。如果看到 binary frame 發送但沒有回應，問題可能在 frame type。

還原：如果問題和使用者操作有關（例如只在特定操作順序下觸發），看使用者行為 log，還原操作路徑。

三層 log 用同一個時間戳和 correlation ID（例如連線 session ID），讓跨層比對可行。

下一步路由

• 在功能規格中定義 log 點 → 功能規格中的 log 點定義方法
• 事後補 log 和設計產物 log 的品質差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 收集方案選擇 → 自架 log endpoint vs 商業方案
• 事件分類與收集策略 → monitoring 模組一 監控心智模型

四類 log 點

每個功能的 log 點按執行時機分成四類。

啟動 log

功能開始執行時記錄。回答「這個功能是否被觸發了」。

啟動 log 包含觸發來源（使用者操作、系統排程、外部事件）和初始參數（連線目標、操作類型）。如果一個功能從未被觸發，啟動 log 的缺席就是線索。

步驟 log

功能執行過程中的每個關鍵步驟完成時記錄。回答「流程走到哪裡了」。

步驟 log 的粒度依功能複雜度而定。三步驟的功能每步記一條；十步驟的功能可以只記關鍵的三到五步。判斷標準是：如果這一步失敗，開發者是否需要知道失敗點在哪。

錯誤 log

步驟失敗、例外捕獲、非預期狀態出現時記錄。回答「出了什麼問題」。

錯誤 log 必須包含足夠的 context 讓開發者不需要重現問題就能判斷原因。至少包含：哪一步失敗、失敗原因（error message）、當時的關鍵狀態值。

完成 log

功能正常結束時記錄。回答「功能是否成功完成、花了多久」。

完成 log 包含執行結果和耗時。和啟動 log 配對使用 — 有啟動但沒有完成代表功能中途異常退出。

在功能規格中加可觀測性欄位

以 app_tunnel 的「連線到 ttyd 終端機」功能為例，傳統規格只寫：

• 輸入：使用者選擇的伺服器
• 處理：建立 WebSocket 連線、發送 auth token、開始接收 terminal output
• 輸出：終端機畫面顯示 terminal output

加上可觀測性欄位後：

這張表在功能規格階段就能寫出來，因為它只依賴功能的流程設計，不依賴實作細節。功能流程確定後，每一步在哪裡需要 log 點就確定了。

log 點命名規則

統一的命名規則讓 log 可以被 grep、過濾和統計。

階層式命名：{功能}.{步驟}.{事件}。例如 connect.ws.connected、connect.auth.failed。

事件後綴統一：start（啟動）、done（步驟完成）、failed（失敗）、complete（功能完成）。

和程式碼結構對應：log 點名稱對應到程式碼中的函式或模組。connect.biometric.done 對應 BiometricService.authenticate() 的成功路徑。這讓開發者看到 log 名稱就知道去哪裡找程式碼。

log 點規格的 review 檢查

功能規格 review 時，可觀測性欄位的檢查要點：

每步都有 log：流程中的每個步驟在成功和失敗時都有對應的 log 點。遺漏的步驟意味著該步驟出問題時無法從 log 判斷。

錯誤 log 有足夠 context：error log 只寫「連線失敗」不夠；需要寫「連線失敗」加上 error code、目標 URL、已完成的步驟。

敏感欄位有 redaction 標記：密碼、token、個人資料在 log 規格中標記為 redact，實作時用 redaction 機制處理。

啟動和完成配對：每個功能有啟動 log 就應該有完成 log，形成完整的生命週期。

下一步路由

• 三層 log 的詳細設計 → 三層 log 設計
• 事後補 log 和設計產物 log 的差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 中的敏感資訊處理 → monitoring 模組七 資安

原則一：source 標明來源

每筆事件的 source 欄位記錄「這筆事件從哪裡來」。App 名稱、版本、平台、OS 版本 — 這些資訊在事件產生時由 SDK 自動填入，不依賴使用者或開發者手動標記。

source 的設計要點是「足夠區分但不過度」。sdk 和 platform 是必填——sdk 標明事件由哪個 SDK 實作產生（js / flutter / python / go），platform 標明運行平台（ios / android / web / macos）。兩者不能互相推導：同一個 platform（iOS）上可能有不同的 SDK（Flutter SDK 或 Swift 原生 SDK），同一個 SDK（Flutter）可能跑在不同 platform（iOS / Android / Web）。App 名稱和版本能區分「這是哪個 app 的哪個版本送來的事件」。OS 版本用於分析平台特定的問題（「這個 error 只出現在 iOS 17.4」）。

不需要在 source 放裝置 ID 或使用者 ID — 這些屬於個人識別資訊，放在 source 會讓每一筆事件都攜帶 PII，增加去識別化的複雜度。Session ID 用於關聯同次使用的事件，已足夠取代裝置/使用者級別的追蹤。

原則二：data 自由欄位

data 欄位是事件的附加資料區域，接受任意 JSON object。核心欄位（type、name、timestamp、source）有固定的 schema 驗證，data 的內容不做 schema 驗證（或做寬鬆驗證）。

自由欄位的設計理由是「不同事件需要不同的附加資料」。terminal.connect.done 需要 URL 和 duration；auth.biometric.failed 需要 error code 和 fallback 方式。為每種事件定義固定的 data schema 會讓 schema 膨脹且頻繁變動。

自由的代價是查詢時無法保證 data 內某個欄位一定存在。處理策略：查詢時用 optional access（data?.duration_ms），統計時跳過缺少目標欄位的事件。

原則三：v 版本演進

v 欄位是整數版本號，標明「這筆事件是用哪個版本的 schema 產生的」。

版本號解決的問題是 schema 變更時的向後相容。新版本的 SDK 產生 v=2 的事件，舊版本的 SDK 仍在產生 v=1 的事件。Collector 收到事件時根據 v 決定用哪個版本的驗證和處理邏輯。

版本號的遞增規則：

• 新增選填欄位：不需要遞增版本號。舊版事件缺少新欄位，collector 用預設值處理。
• 新增必填欄位：遞增版本號。舊版事件沒有這個欄位，collector 需要區分版本處理。
• 刪除或改名欄位：遞增版本號。collector 需要同時支援新舊版本的事件格式。
• 改變欄位型別：遞增版本號。string 改成 integer 等型別變更需要不同的解析邏輯。

欄位命名慣例

欄位名稱使用 snake_case（duration_ms、error_code），和 JSON 的慣例一致。避免在欄位名稱中編碼單位（duration 不夠明確 — 是秒還是毫秒？），在名稱中加上單位後綴（duration_ms、size_bytes）。

下一步路由

• 完整欄位定義 → event.schema.json 完整欄位解說
• Schema 版本演進的具體策略 → Schema 版本演進策略
• 和 OpenTelemetry 的比較 → 跟 OpenTelemetry 的 schema 差異對照

格式統一性

app_tunnel 在 W2 修復時補的 developer.log 格式不統一（T.C4）。不同元件由不同時間點、不同 debug 需求補上的 log，各自有各自的風格：

有的帶 name: 參數讓 log 可以按元件過濾：

1developer.log('WS connected', name: 'ConnectionManager');

有的不帶，混在全域 log 裡無法過濾：

1developer.log('auth token sent');

有的帶 // i18n-exempt 標記（因為 linter 會對 hardcoded string 報警），有的忘了加。有的把錯誤訊息放在 error: 參數，有的用字串串接。

這些不一致來自事後補 log 的結構性原因：每條 log 是在解決當下問題時加的，沒有統一規範，也沒有 review。加完能定位問題就提交，下次遇到新問題再加新的 log — 格式隨機。

設計產物 log 在產出前就有命名規則和格式規範（見 功能規格中的 log 點定義方法）。所有 log 點走同一個 AppLogger 介面，name、level、結構化欄位在規格階段就定義好，實作時照規格寫。

覆蓋完整性

事後補 log 的覆蓋範圍由「哪些問題已經發生過」決定。W2-002 auth token 問題觸發了 ConnectionManager 和 TerminalScreen 的 log 補充，但 TtydProtocol、BiometricService、CredentialRepository、EnrollmentScreen 四個元件仍然零 log — 因為這四個元件在 W2 的 debug 過程中不是瓶頸。

六個核心元件中四個零 log 的狀態意味著：下次如果問題出在 BiometricService（例如特定 iOS 版本的 biometric API 行為改變），debug 又會回到「手動加 log → 重新編譯 → 插拔裝置」的循環。事後補 log 只覆蓋已知問題的路徑，對未知問題沒有防護。

設計產物 log 的覆蓋範圍由功能流程的步驟數決定。每個功能規格列出所有步驟的 log 點，不管這些步驟是否曾經出過問題。BiometricService.authenticate() 在規格中就有 start/done/failed 三個 log 點，無論是否遇過 biometric 問題。

維護成本

事後補 log 隨 debug 過程累積，沒有統一管理。隨時間推移：

• 某些 log 的觸發條件已經不存在了（被修復的 bug 對應的 log），但沒人清理
• 某些 log 的格式和新加的 log 不一致，但沒人統一
• 某些 log 的 context 資訊不足（當時能定位問題是因為開發者記得 context，半年後換人接手就不夠了）
• 某些 log 在 release build 中不該出現但忘了加條件

設計產物 log 有規格文件作為 source of truth。功能變更時更新規格中的 log 點列表，刪除的步驟對應的 log 點一起刪除，新增的步驟對應的 log 點一起新增。Log 的生命週期和功能的生命週期綁定。

從事後補過渡到設計產物

已有的事後補 log 不需要全部重寫。過渡策略是：

統一入口：建立 AppLogger 封裝，把現有的 developer.log 呼叫改為走 AppLogger。這一步不改 log 內容，只改呼叫方式，讓後續的格式統一和功能切換有統一入口。

補規格：對每個功能寫出 log 點規格表（四類 log 點），比對現有 log 和規格的差距。規格中有但程式碼中沒有的 log 點 = 覆蓋缺口，補上。程式碼中有但規格中沒有的 log 點 = 可能是過時的 debug log，評估是否刪除。

新功能走設計產物流程：從下一個新功能開始，功能規格中包含可觀測性欄位。新功能的 log 從一開始就是設計產物品質。

過渡的第一步是建立統一入口，具體的 log 點規格格式見功能規格中的 log 點定義方法。規格中的每個 log 點屬於哪一層（連線生命週期 / protocol / 使用者行為），在三層 log 設計中定義。收集到 log 之後用自架還是商業方案處理，見自架 log endpoint vs 商業方案的判斷流程。

核心命題：YAGNI 不是「永遠選最受限選項」的原則，是「不為未來投入額外成本」的原則。 判斷工具：成本對稱性、可逆性、領域先驗——三軸框架。

起點：一個常見的工程爭論

「最早的設計者沒考慮到多個監聽需求，這算設計瑕疵，還是避免過度設計？」

這類問題在 code review、事故檢討、技術選型討論裡反覆出現。指控太重會打擊個別工程師的判斷力信心，放任又會讓同類事故反覆發生。

要釐清這個爭論，得先回到 YAGNI 原則的真實定義——很多被當成 YAGNI 的例子根本不在它的射程內。

YAGNI 的真實範圍

YAGNI（You Aren’t Gonna Need It）的原意是：不要投入額外成本去蓋你尚未需要的東西。它防的是這類情境：

• 「我先寫個 plugin 系統，未來可以擴充」（成本：協議設計、抽象層、擴充點測試）
• 「我先做多語系，未來會國際化」（成本：i18n 框架、所有字串外移）
• 「我先支援多資料庫」（成本：repository 抽象、SQL 方言處理）
• 「我先建多租戶切割」（成本：資料 schema 加 tenant 欄位、所有 query 加過濾）

這些選擇的共通特徵是：為了未來付出當下的具體成本——抽象層、額外測試、複雜配置、學習負擔。YAGNI 說：別付，等真正需要再付，因為很可能你永遠不需要。

但很多被指控為「過度設計」的選擇其實沒有 upfront cost 差異。例如：

• Stream 工具用單訂閱版本還是廣播版本：建構子多打 11 個字元
• var 還是 final：3 個字元
• ID 用 int 還是 String（UUID）：抽象層成本一樣
• API 設計成同步還是 async：簽章只差 Future<> 包裝
• Class 預設可繼承還是 sealed：一個 modifier
• Database column 預設 nullable 還是 NOT NULL：一個 keyword

這些不在 YAGNI 的射程內。把它們當成 YAGNI 來防禦會選錯方向。

真正的判斷軸：成本不對稱性

判斷「該不該選更通用的選項」，跑三個軸。

軸 1：成本對稱性

「選擇 A 比選擇 B 多付出多少當下成本？」

• 對稱（成本相當、差幾個字元、無新概念）：選未來更可能需要的那個——這不是過度設計，是合理 default
• 不對稱（一邊明顯較貴、要多寫框架、多加抽象、多學概念）：YAGNI 適用，選便宜的，需要時再升級

軸 2：改變決定的成本

「如果選錯了，未來修正要付出什麼？」

• 可逆（一行改完、無 API 契約變動、無資料遷移）：YAGNI 適用，先選簡單的
• 不可逆 / 修正昂貴（牽動 API 契約、資料庫 schema、客戶端版本相容性、第三方 integration）：偏向預先選擇通用的

軸 3：領域先驗（domain prior）

「這個領域裡、這個模式發生的機率有多高？」——「先驗」（prior）借自 Bayesian 統計、用來指「在沒看到具體證據前、我們對某事發生機率的合理預期」。在工程領域、這個機率來自累積的領域知識（多視角同步、retry、併發、認證⋯⋯這些 pattern 的歷史發生率）。

• 強先驗（教科書級別）：多視角狀態同步是廣播、有用戶系統一定有 logged-in / anonymous 兩種、長時間運行服務一定會有 retry 需求、有交易就會有併發
• 弱先驗（純臆測）：「未來可能會有 plugin 機制吧」「未來可能要換資料庫吧」「未來可能要支援其他平台吧」

三軸的綜合判斷

任一軸顯著偏向「該選通用」，YAGNI 就不適用。

選通用不是過度設計，是對工具屬性與領域常識的尊重。

案例對照：兩個極端

案例 A：Stream 預設選錯

某個事件廣播 service 用了 StreamController() 預設建構子（單訂閱）。當下只有一個訂閱者，運作正常數個月。後來加第二個訂閱者，瞬間 throw Bad state: Stream has already been listened to。

跑三軸：

• 成本對稱性：對稱（差 11 個字元、零認知負擔）
• 可逆性：中等偏高（事故必須在 production 暴露才會發現，要審所有訂閱方、改實作 + mock）
• 領域先驗：強（pub-sub / 事件廣播場景天生多訂閱）

三軸都指向廣播版本。這是設計瑕疵——不是因為「沒考慮多訂閱」，而是在三軸都不利於單訂閱的情況下選了單訂閱。

完整事故重現、單訂閱 vs broadcast 的程式碼對比、修復決策過程：Dart StreamController：single-subscription vs broadcast 的事故實錄。

案例 B：建立 plugin 系統

「我先建個 plugin 系統，未來功能模組可以動態擴充」——典型的 over-engineering 焦慮表現。

跑三軸：

• 成本對稱性：嚴重不對稱（plugin 系統需要設計協議、加載機制、版本管理、隔離測試）
• 可逆性：可逆（之後要做的話成本跟現在做差不多）
• 領域先驗：弱（多數應用程式不會有第三方擴充需求）

三軸都指向「先別做」。這是 YAGNI 的標準適用情境。

兩個案例的對比

兩者表面看都是「未來可能需要」，但三軸框架告訴你它們是完全不同類別的決定。一概而論「該/不該為未來準備」會兩邊都做錯。

為什麼這類瑕疵「可被原諒」

要老實講：指出某個選擇是設計瑕疵，不等於把責任全部推給個別工程師。

同類型瑕疵在實務上極常見，原因往往是系統性陷阱。

1. 語言 / 工具的預設值誤導

很多語言把「需要明確選擇」的東西做成「最少打字的預設」：

• Dart 的 StreamController() 是 single-subscription
• 多數 SQL 的 column 預設 nullable
• JavaScript 的 == 預設寬鬆比對
• 多數語言的 class 預設可繼承
• HTTP 預設不加密
• 多數語言的 mutable 是 default

這些預設都把多數人推向「比較容易出錯但不立即爆」的選項。API 設計把成本均衡的選擇做成「便宜便輸出受限」vs「貴一點輸出通用」是 framework 設計的責任轉嫁——把跨用例的判斷成本丟給用戶。

2. 領域知識需要被觸發過才會內化

很多事是遇過一次才會記得。「stream 預設是單訂閱」「nullable column 之後加 NOT NULL 要 backfill」「同步 API 之後改 async 是 breaking change」——這些不是經驗少的問題，是這些事實需要遇到才會內化進直覺判斷。

新人讀文件不會看到、code review 不會自動 catch、靜態分析不會主動警告——只能等某次遇到。

3. 失敗模式的低調性掩蓋風險

很多設計瑕疵的失敗模式只在特定觸發條件下顯現：

• Stream 多訂閱限制只在第二次 listen() 時暴露
• Mutable shared state 的 race condition 只在高併發下爆
• Cache 失效邏輯只在 cache miss 模式變化時出問題
• API 沒做 idempotent 只在重試時出現重複

平常測試跑都過，給人「沒問題」的錯覺。沒有立即反饋的設計瑕疵 = 隱形的技術債。

4. 工具替代品掩蓋知識需求

有些底層概念被高層框架封裝後，使用者根本不會碰到，所以「應該知道」的知識沒有被反覆強化。例如：

• Flutter 開發者多用 GetX / Riverpod / Bloc，極少碰 raw StreamController
• ORM 用戶多不寫 SQL，極少思考 query plan
• 雲端 SDK 用戶多不思考 retry / backoff，極少接觸底層 HTTP

當有一天必須繞過框架直接用底層工具時，那個事故就會發生。

結論

設計者只承擔最後一棒。要把同類瑕疵變少，修補方向在制度層面。

制度層面的補強

要把「該選通用 default 但選了受限預設」的錯誤變少，個人記憶不可靠，要靠三層機制。

機制 1：介面層的 review checklist

把容易出錯的 default 列入 PR review 檢查清單。例如：

• Service 對外暴露 Stream<T> 時、預設用 broadcast；用 single 要在註解寫明理由
• 資料庫 column 預設用 NOT NULL；nullable 要在註解寫明業務理由
• 公開 API 預設用 async；sync 要寫明理由
• 公開類別預設用 sealed / final；可繼承要寫明理由
• HTTP 預設用 HTTPS；plain HTTP 要寫明理由

把「需要記得」變成「review 強制檢查」。Checklist 不需要多，每個項目對應一個遇過的事故。

機制 2：架構規範把選擇從 default 取消

更徹底的做法是用工具或規範禁掉問題 default：

• App 層 service 禁用 raw StreamController，強制用框架的廣播原語
• 用 lint rule 警告 StreamController() 的無參數呼叫
• DB schema migration 工具預設產出 NOT NULL，nullable 要明確指定
• API gateway 預設 deny，要顯式 allow 才放行

這把選擇從「需要記得」變成「不需要選，做錯會被擋」。是最高效的補強。

機制 3：領域先驗清單

每個團隊應該維護一份「我們的領域裡這些事一定會發生」的清單。範例：

POS 系統：

• 一台主機要服務多視角（多顯示螢幕、多通知模組）
• 會員身份會即時切換
• 有離線運作需求
• 多分店不同設定

電商：

• 商品價格會變動，歷史訂單要保留下單當時的價格
• 庫存會超賣，需要 reserve / commit 機制
• 退款是必然發生的，不是 edge case
• 客戶會有多個收件地址

新功能設計時對照清單——強領域先驗就直接設計進去，不必每次重新評估。新進團隊成員也能快速吸收領域常識。

一個能套到無數情境的 heuristic

把整個討論濃縮成一句話：

當你的選擇「沒有 upfront cost 差異」時、就該選未來自由度高的那個。

這個 heuristic 能套到無數技術決定：

這些都不是「過度設計」，是在零成本差異下選擇未來自由度更高的選項。YAGNI 不適用——YAGNI 的成本門檻在這裡根本不存在。

反向校正：什麼時候該堅持 YAGNI？

為了避免本文被讀成「永遠選通用」，補一個反向案例。

YAGNI 在這些情境是對的：

這些都是為了未來付出當下具體成本——抽象層、新概念、額外測試、配置複雜度。YAGNI 在這些情境會帶你做出對的選擇。

判斷的差異是：這個決定是「選哪個免費選項」，還是「要不要付一筆額外開發成本」？ 前者三軸框架；後者 YAGNI。

總結

YAGNI vs 過度設計的爭論，常常因為兩邊在用不同定義而無法收斂。釐清如下：

YAGNI 適用於「為了未來而付出當下的具體成本」 不適用於「在成本相當的選項中選擇更通用的那個」

判斷時跑三軸：

1. 成本對稱性：兩個選項的 upfront cost 是否相當？
2. 可逆性：選錯的話修正昂貴嗎？
3. 領域先驗：這個模式在領域裡發生機率多高？

任一軸顯著偏向「該選通用」，YAGNI 就不適用，這不是過度設計。

回到開頭問題——「最早的設計者沒考慮到多個監聽需求、這算設計瑕疵還是避免過度設計？」答案取決於這三軸的具體狀況、不能一概而論。

但如果像 Stream 這個案例、三軸全部不利於受限預設、那就是設計瑕疵。只是這類瑕疵反映的是工具預設與領域知識內化的系統性問題、不是個別工程師的判斷力不足——修補方向是制度而非個人責備。

一句話帶走

日常情境中、把三軸壓縮成一個問題就夠用：

「我在多付什麼成本？」

• 多付抽象層、新概念、額外測試 → YAGNI 適用、先別付
• 多付幾個字元、一個關鍵字 → 不是 YAGNI、選通用的

需要更精細的時候、再回頭跑完整三軸框架。