軟體工程與系統設計標準
一套嚴謹且經過實戰驗證的作業指南，涵蓋軟體工程卓越、系統架構、低階設計與分散式系統。
1. 核心運作原則
- 權衡取捨勝於教條：沒有通用的「最佳實務」，只有權衡取捨。每個架構選擇都會以特定成本（延遲、一致性、營運複雜度或認知負擔）換取一組效益。務必說明正在犧牲什麼。
- 可逆性優先：優先考慮雙向門決策（可逆），而非單向門決策（不可逆）。避免過早與特定供應商、框架或分散式拓撲耦合。
- 杜絕架構太空理論：每個抽象化、介面與層級都必須根據具體的現有需求來證明其重量，而不是基於推測的未來需求（YAGNI）。
- 證據導向設計：根據具體的分析數據、測量結果、查詢計畫（
EXPLAIN ANALYZE）與容量限制來制定決策，而非依賴假設。 - 快速失敗與明確邊界：子系統、領域或網路躍點之間的邊界必須具有明確、強型別的合約、驗證、逾時、斷路器與冪等性保證。
2. 高階設計 (HLD) 與架構工作流程
當被要求設計系統、評估架構或重構主要子系統時，執行此六步驟框架：
flowchart TD
Step1["1. 釐清需求與範圍<br>(功能性、非功能性、延遲、可用性、一致性)"]
Step2["2. 容量與規模估算<br>(DAU、QPS、吞吐量、網路頻寬、儲存空間、快取 RAM)"]
Step3["3. 高階架構 (C4 L1/L2)<br>(服務邊界、儲存選擇、入口、快取)"]
Step4["4. 資料模型與介面合約<br>(實體、綱要、主鍵、索引、REST/gRPC API)"]
Step5["5. 深度分析與瓶頸隔離<br>(複寫、分片、並行性、快取病理、熱點)"]
Step6["6. 韌性與 SRE 策略<br>(SLO、斷路器、含抖動的重試、冪等性、DLQ)"]
Step1 --> Step2 --> Step3 --> Step4 --> Step5 --> Step6
詳細 HLD 參考
關於分散式系統定理（CAP、PACELC）、一致性層級、共識（Raft/Paxos）、分片、複寫、Saga 模式與交易型外寄信箱模式，請參閱： 👉 高階系統設計與分散式系統參考
3. 低階設計 (LLD) 與簡潔程式碼標準
在撰寫、審查或重構程式碼時，應遵守以下標準：
3.1 SOLID 規則
- SRP（單一職責）：一個模組只有一個角色/利害關係人需要回應。將持久化、HTTP 序列化與業務邏輯提取到不同的關注點。
- OCP（開放/封閉）：優先使用多型、策略模式或訪客模式，而非使用龐大的
switch/if-else型別分發陳述式。 - LSP（里氏替換）：子型別必須滿足父型別的所有行為不變量。覆寫方法使其拋出
NotImplementedException違反了 LSP。 - ISP（介面隔離）：偏好小型的、針對特定用戶端的角色介面，而非大型的「上帝介面」。
- DIP（依賴反轉）：核心業務規則僅依賴抽象（連接埠），絕不直接依賴外部資料庫函式庫、UI 框架或網路驅動程式。
3.2 模組封裝（Parnas 與 Connascence）
- 模組秘密：模組必須完全隱藏其主要秘密（內部演算法/資料結構）與次要秘密（外部環境/檔案格式）。
- Connascence：最小化動態 connascence（執行順序、時機、值約束），並減少耦合至靜態名稱/型別協議。
詳細 LLD 參考
關於四人幫 (GoF) 設計模式實戰指南、領域驅動設計 (DDD) 戰術建構區塊（實體、值物件、聚合、領域事件）以及重構技巧，請參閱： 👉 低階設計與簡潔程式碼參考
4. API 與資料持久化標準
- RESTful API：
- 嚴格遵守 HTTP 方法語意（
GET是安全且冪等的；PUT/DELETE是冪等的；POST用於建立）。 - 使用 RFC 7807（問題詳情） 來處理結構化錯誤回應。
- 對於大量資料集合，優先使用 索引鍵/游標分頁 而非偏移量/限制分頁。
- 嚴格遵守 HTTP 方法語意（
- 資料庫索引（E-R-S 規則）：
- 複合索引欄位順序：[等值欄位] $\to$ [範圍欄位] $\to$ [排序欄位]。
- 使用涵蓋索引（僅索引掃描）和部分索引，以消除熱門查詢的磁碟頁面查詢。
- 務必使用
EXPLAIN QUERY PLAN或EXPLAIN ANALYZE驗證查詢。
- 非同步訊息與事件：
- 結合至少一次代理傳遞與消費者端冪等性（在儲存中對唯一訊息 ID 進行重複資料刪除），以保證有效一次處理。
- 將無法處理的毒藥訊息路由至死信佇列 (DLQ)，以防止分割區停滯。
詳細 API 與資料參考
5. 效能、容量與可靠性工程
- 粗略估算：
- $1\text{ 天} \approx 10^5\text{ 秒}$（$86,400\text{ 秒}$）。$1\text{M 請求/天} \approx 12\text{ RPS}$。
- 尖峰 QPS = 平均 QPS $\times$ $3\times$。
- 快取 RAM = $20% \times (\text{每日讀取量} \times \text{項目大小})$（帕雷托 80/20 法則）。
- Little's Law：$L = \lambda W$（進行中的並行性 = 到達率 $\times$ 延遲）。
- 快取紀律：
- 切勿設定任意、未經測量的記憶體中 TTL，導致其在正常運作期間過期。
- 根據資料版本/指紋或工作階段時間戳記進行失效。
- 防範快取雪崩（使用互斥鎖/分散式鎖）、快取穿透（布隆過濾器）和快取崩潰（TTL 抖動）。
- 網站可靠性工程 (SRE)：
- 執行明確的 SLO 與延遲預算（$p50$、$p95$、$p99$）。
- 實作斷路器、隔艙模式以及具有完整抖動的指數退避。
詳細可靠性與效能參考
6. 架構決策記錄 (ADR)
使用標準 ADR 格式記錄非平凡技術選擇：
- 背景與驅動因素：問題、營運限制以及延遲/規模目標。
- 考慮過的選項：結構性替代方案及其權衡取捨。
- 決策與結果：與決策驅動因素相關的具體論證。
- 後果：明確的正面效益與所接受的負面成本。