🌐 English version · 繁體中文（正本 / canonical）

Go 高併發判準手冊

前置：單機正確性（error 三選一、goroutine 洩漏三典型、nil interface、context 規則、channel vs mutex、專案結構）見 backend-server 的 references/go.md，本手冊不重複。本手冊從「單機跑對了」往上接「同時湧入一萬個請求時還撐得住」。

核心原則

1. 併發是設計決策，不是加速鈕：開 goroutine 前先問「瓶頸真的在這嗎」。沒有瓶頸證據就加併發，只是把 bug 變並行 bug。
2. 任何無界的緩衝都是延後爆炸的 OOM：生產速度可能超過消費速度的每一個邊界，都要有界 + 「滿了怎麼辦」的明確決策（block / drop / reject 擇一）。
3. 高併發問題先看「等待」不是看 CPU：排查順序是 goroutine profile（洩漏/阻塞）→ 鎖競爭 → CPU → trace（排程）。多數「慢」是在等鎖、等下游、等排程，不是算得慢。
4. 「感覺慢」禁止直接改：先 profile 拿到證據再動手；憑感覺加 goroutine / 加 cache / 換資料結構，多半改錯地方還更慢。
5. 上線才爆的問題驗證只能用壓測：單機低流量對「洩漏、鎖競爭、池飽和、GOMAXPROCS 錯配」零證據力——這些要在目標 RPS 的壓力下才現形。

開工分流

紅線（絕對禁止）

• 禁止用無界 channel / 無界 queue / 無限 go func() 當緩衝——生產快於消費時記憶體無上限成長，尖峰直接 OOM，且 OOM 前 GC 壓力先讓全服務變慢。
• 禁止內層 timeout ≥ 外層 timeout——內層等好等滿，外層早已放棄回錯，內層還在跑＝做白工＋佔用資源，取消語意全失效。
• 禁止「感覺慢」就直接改效能——沒有 profile 證據的優化是猜測，改錯地方浪費時間還可能更慢。
• 禁止 worker 數 / 連線池大小拍腦袋填 100——超過下游（DB max_connections、上游 API 限額）容量的並發只會製造排隊與逾時，數字要從下游容量反推。
• 禁止在高併發程式碼省略 -race 驗證——data race 在低流量偶發、在高流量必現且不可重現，-race 是唯一能穩定抓到的手段。
• 禁止重試不加退避與 jitter——下游一抖，所有 client 同步重試形成重試風暴，把短暫故障放大成雪崩。

失敗訊號（該回頭，不是重試）

references 索引

• references/concurrency-patterns.md — 何時「不要」開 goroutine、worker pool sizing、errgroup vs WaitGroup、pipeline/fan-out、semaphore 限並發、singleflight。決定併發結構前讀。
• references/backpressure-limits.md — 有界 channel 與滿了怎麼辦、rate limit 選型、timeout 預算層級、load shedding/circuit breaker 何時真需要、連線池 sizing。接邊界、設限流前讀。
• references/performance-profiling.md — pprof 排查順序、-race、鎖競爭修法優先序、GC/sync.Pool 判準、benchmark 正確姿勢。調效能前讀。
• references/release-checklist.md — 壓測、automaxprocs、ulimit、四金指標、graceful shutdown 排空、重試風暴防護。上高流量前逐條打勾。
• references/test-scenarios.md — 判準測驗集，驗證接手模型是否照走。不給執行中的模型讀。