debug

# Debug — 系統性除錯 ## 觸發條件 - 出現錯誤訊息或 stack trace - 測試失敗 - 程式行為非預期 - 生產環境出現異常（日誌分析、error spike） ## 除錯流程（6 步驟） 1. **Capture** — 取得完整錯誤訊息、stack trace、重現步驟 2. **Isolate** — 縮小故障範圍（模組、函式、時間點） 3. **Hypothesize** — 形成 2-3 個可能根因假設 4. **Test** — 用證據驗證假設（不要憑感覺猜） 5. **Fix** — 實作最小修復（不要順手清理無關的程式碼） 6. **Verify** — 確認修復有效，並排除引入新問題 ## 快速診斷指令 ```bash # 查看最近哪些變更可能引起問題 git log --oneline -10 git diff HEAD~3 # 搜尋日誌中的錯誤模式 grep -rn "error\|Error\|ERROR" logs/ 2>/dev/null | tail -20 # 執行測試並捕捉輸出 npm test 2>&1 | tail -50 # Node.js pytest -x --tb=short 2>&1 # Python cargo test 2>&1 | tail -50 # Rust go test ./... 2>&1 # Go ``` ## 日誌分析 ```bash # 最近的錯誤與上下文 grep -B 5 -A 10 "ERROR" /var/log/app.log # 統計錯誤類型頻率 grep -oE "Error: [^:]*" app.log | sort | uniq -c | sort -rn # 某時段的錯誤 awk '/2026-04-18 14:/ && /ERROR/' app.log # 找出高頻錯誤 grep "ERROR" app.log | cut -d']' -f2 | sort | uniq -c | sort -rn | head -20 # 錯誤 spike 分析 grep "ERROR" app.log | cut -d' ' -f1-2 | uniq -c | sort -rn ``` ## 常見 Error Pattern | Pattern | 指向 | 行動 | |---------|------|------| | NullPointer / undefined | 缺少 null check | 加入防衛性驗證 | | Timeout | 依賴服務慢 | 加 timeout + retry | | Connection refused | 服務未啟動 | 檢查 health endpoint | | OOM | 記憶體洩漏 | 用 profiler 找洩漏點 | | Rate limit | 請求過多 | 加 backoff + 佇列 | ## 跨系統關聯查詢（SQL） ```sql -- 某 endpoint 的錯誤頻率 SELECT endpoint, count(*) as errors FROM logs WHERE level = 'ERROR' AND time > NOW() - INTERVAL '1 hour' GROUP BY endpoint ORDER BY errors DESC; -- 用 request_id 跨服務追蹤 SELECT service, message, time FROM logs WHERE request_id = 'req-xxxxx' ORDER BY time; ``` ## 輸出格式 ```markdown ## Debug Report **Issue:** [一句話描述問題] **Root Cause:** [實際根因] ### Evidence - [找到的具體證據 1] - [找到的具體證據 2] ### Fix [程式碼或設定的最小修復] ### Verification [如何確認修復有效：指令或測試] ### Prevention [如何預防此問題再次發生] ``` ## Gotcha - **只做最小修復**：debug 不是重構，不要順手改不相關的程式碼 - **假設要有證據**：每個假設必須由工具呼叫驗證，不憑直覺 - **先跑相關測試**：不要跑全套測試套件，先跑最相關的一個測試確認方向 - **記錄 root cause**：修完後把根因和修復方式寫進 commit message，有助於日後 retro 分析