# Go Concurrency Playbook

> Use when designing or debugging high-concurrency Go services — before adding a goroutine pool / worker pool, wiring backpressure or a bounded channel, choosing errgroup vs WaitGroup, adding rate limit / load shedding / circuit breaker, tuning GOMAXPROCS in containers, or sizing a connection pool; also when facing OOM under load, rising goroutine count, lock contention, p99 latency spikes, retry s…

- **Type:** Skill
- **Install:** `agentstack add skill-tienenwu-fables-go-concurrency`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tienenwu](https://agentstack.voostack.com/s/tienenwu)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tienenwu](https://github.com/tienenwu)
- **Source:** https://github.com/tienenwu/fables/tree/main/go-concurrency

## Install

```sh
agentstack add skill-tienenwu-fables-go-concurrency
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> 🌐 [English version](https://github.com/tienenwu/fables/blob/main/en/go-concurrency/SKILL.md) · 繁體中文（正本 / 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 的壓力下才現形。

## 開工分流

| 情境 | 路徑 | 先讀 |
|------|------|------|
| 想「開幾個 goroutine 加速」 | 先確認瓶頸與是否需要併發，再決定 pool | references/concurrency-patterns.md §1 |
| 要開 worker pool / 限並發 / fan-out | 定 worker 數與界限，選對原語 | references/concurrency-patterns.md |
| 多個子任務要並行 + 錯誤傳播/取消 | errgroup，不是裸 WaitGroup | references/concurrency-patterns.md §3 |
| 高併發讀同一 key + 回源貴 | singleflight 防 cache stampede | references/concurrency-patterns.md §5 |
| 接 channel/queue、怕 OOM、設 timeout | 有界 + 背壓 + timeout 預算逐層遞減 | references/backpressure-limits.md |
| 加 rate limit / 限流 / 熔斷 / 降載 | 選型與「是否真需要」判準 | references/backpressure-limits.md |
| 服務變慢、要調效能 | 先 profile 拿證據，別先改 | references/performance-profiling.md |
| 懷疑鎖競爭 / GC 壓力 | mutex/block profile、修法優先序 | references/performance-profiling.md |
| 出 release / 上高流量前 | 逐條跑必查清單（壓測是硬條件） | references/release-checklist.md |

## 紅線（絕對禁止）

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

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

| 徵兆 | 多半是 | 退回 |
|------|--------|------|
| goroutine 數隨時間單調上漲不回落 | 洩漏（缺 ctx 出口 / 沒人讀的 channel） | go.md §2 洩漏三典型 + profiling §1 |
| 加了 pool 反而更慢或更容易逾時 | worker 數超過下游容量，卡在排隊 | patterns §2 重定 worker 數 |
| 記憶體緩慢上漲最後 OOM | 某個 channel/queue 無界，或洩漏 | backpressure §1 補界限 |
| 每加一個 timeout/重試就冒新逾時 | timeout 層級沒對齊，內層 > 外層 | backpressure §3 重排預算 |
| 縮小臨界區後鎖競爭還在 | 鎖粒度錯（該分片沒分片） | profiling §3 修法優先序 |
| p99 尖峰但 CPU 沒滿 | 在等鎖/等下游/等排程，不是算得慢 | profiling 從 goroutine/block profile 重查 |
| 下游恢復後服務仍雪崩 | 重試風暴 / 沒熔斷 | backpressure §4 退避+jitter+熔斷 |

## 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` — 判準測驗集，驗證接手模型是否照走。不給執行中的模型讀。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tienenwu](https://github.com/tienenwu)
- **Source:** [tienenwu/fables](https://github.com/tienenwu/fables)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tienenwu-fables-go-concurrency
- Seller: https://agentstack.voostack.com/s/tienenwu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.