本章目標

學完本章後，你將能夠：

1. 理解 heap growth、GOGC 與 GC 頻率的關係
2. 判斷 debug.SetMemoryLimit 能解決什麼、不能解決什麼
3. 從環境變數設定服務 memory limit
4. 用 runtime metrics 觀察調整效果
5. 分辨 GC 壓力、長期保留與真正 leak

【觀察】長時間服務的記憶體問題通常是趨勢問題

記憶體診斷的核心觀察是趨勢。Heap 是否持續上升、GC 後是否下降、goroutine 是否增加、某個操作後是否留下無法回收的資料，這些都比「現在用了多少 MB」更重要。

常見現象：

• 啟動後 heap 穩定在某個區間：通常正常。
• 每次高峰後 heap 都能下降：可能是短暫配置。
• GC 後 heap 仍持續上升：可能有長期保留或 leak。
• GC 次數快速增加且 CPU 升高：可能是 allocation 壓力。
• goroutine 與 heap 同時增加：可能是 goroutine leak 或 send buffer 堆積。

Memory limit 可以幫 runtime 更積極控制 heap，但不能替代趨勢判讀。

【判讀】GC 控制的是 heap 成長

Go GC 的核心目標是回收不再被引用的 heap 物件。Runtime 會根據 GOGC 控制下一次 GC 觸發點。

1GOGC=100 go run ./cmd/server

GOGC=100 大致表示 heap 在上次 GC 後成長約 100% 時觸發下一次 GC。數字越小，GC 越頻繁，記憶體通常較低但 CPU 成本較高；數字越大，GC 較少，記憶體通常較高但 CPU 成本較低。

這是取捨，不是調大或調小就一定更好。CPU 緊繃的服務可能不能承受過低 GOGC；記憶體緊繃的服務可能不能承受過高 GOGC。

【判讀】memory limit 是 runtime 軟目標

debug.SetMemoryLimit 的核心用途是告訴 Go runtime 希望整體記憶體使用量靠近某個目標。當 runtime 接近目標時，會更積極回收 heap。

1func configureRuntime() {
2    const limit = 512 << 20 // 512 MiB
3    debug.SetMemoryLimit(limit)
4}

這不是作業系統層級的硬限制。程式仍可能短暫超過這個值，特別是有大量非 Go heap 記憶體、cgo、mmap、大型 byte slice 尖峰或外部 library 配置時。

Memory limit 適合容器、桌面常駐服務、背景 worker、WebSocket server 這類需要避免吃掉過多資源的服務。若部署平台已有 memory limit，Go runtime 的 limit 通常應略低於平台限制，留給非 Go heap 與系統開銷。

【執行】設定值應來自部署環境

Memory limit 的核心配置原則是由部署環境決定，而不是寫死在 library 裡。應用入口可以讀取環境變數，解析後設定 runtime。

 1func ConfigureMemoryLimitFromEnv() error {
 2    raw := os.Getenv("APP_MEMORY_LIMIT_MB")
 3    if raw == "" {
 4        return nil
 5    }
 6
 7    mb, err := strconv.Atoi(raw)
 8    if err != nil {
 9        return fmt.Errorf("parse APP_MEMORY_LIMIT_MB: %w", err)
10    }
11
12    if mb <= 0 {
13        return fmt.Errorf("APP_MEMORY_LIMIT_MB must be positive")
14    }
15
16    debug.SetMemoryLimit(int64(mb) << 20)
17    return nil
18}

錯誤應在啟動時明確失敗。服務若用錯誤設定悄悄運行，後續記憶體行為會很難解釋。

【策略】runtime metrics 用來看調整是否有效

Runtime metrics 的核心用途是驗證調整效果。只改 GOGC 或 memory limit，不看 heap 與 GC 趨勢，容易變成憑感覺調參。

簡單方式可以用 runtime.ReadMemStats：

1func ReadHeapAlloc() uint64 {
2    var stats runtime.MemStats
3    runtime.ReadMemStats(&stats)
4    return stats.HeapAlloc
5}

較完整的服務可以使用 runtime/metrics：

1func ReadRuntimeSamples() []metrics.Sample {
2    samples := []metrics.Sample{
3        {Name: "/memory/classes/heap/objects:bytes"},
4        {Name: "/gc/cycles/total:gc-cycles"},
5        {Name: "/sched/goroutines:goroutines"},
6    }
7    metrics.Read(samples)
8    return samples
9}

觀察時要看趨勢：調整後 heap 峰值是否下降、GC 次數是否合理、CPU 是否上升、goroutine 是否仍持續增加。

【判讀】memory limit 不能修正仍被引用的資料

Memory limit 的核心邊界是它只能影響 GC 行為，不能讓仍被引用的物件消失。若程式把資料一直留在 map、slice、cache、goroutine 或 send buffer 裡，GC 不能回收。

1var cache = map[string][]byte{}
2
3func SavePayload(id string, payload []byte) {
4    cache[id] = payload
5}

如果 cache 沒有大小限制、TTL 或刪除策略，memory limit 只會讓 GC 更常跑，但資料仍被 cache 引用。真正修正是設計 cache 淘汰、分頁、快照大小限制或資料釋放路徑。

因此遇到 heap 持續上升時，下一步是用 pprof 確認誰保留了記憶體。

【策略】判斷是 GC 壓力還是長期保留

記憶體問題的核心分流是：物件被大量配置但很快回收，還是物件被長期保留。

這個分流會決定後續工具。GC 參數能緩解壓力，但保留資料要回到資料結構與 lifecycle 修。

【測試】runtime 設定函式可以獨立測解析

Runtime 本身不需要在單元測試中反覆調參。應把環境解析邏輯獨立出來，測試輸入與錯誤即可。

 1func ParseMemoryLimitMB(raw string) (int64, error) {
 2    if raw == "" {
 3        return 0, nil
 4    }
 5    mb, err := strconv.Atoi(raw)
 6    if err != nil {
 7        return 0, fmt.Errorf("parse memory limit: %w", err)
 8    }
 9    if mb <= 0 {
10        return 0, fmt.Errorf("memory limit must be positive")
11    }
12    return int64(mb) << 20, nil
13}

測試：

1func TestParseMemoryLimitMB(t *testing.T) {
2    got, err := ParseMemoryLimitMB("512")
3    if err != nil {
4        t.Fatalf("parse memory limit: %v", err)
5    }
6    if got != 512<<20 {
7        t.Fatalf("limit = %d, want %d", got, int64(512<<20))
8    }
9}

這讓設定邏輯可測，而不需要在每個測試中真的改 runtime 狀態。

本章不處理

本章先處理單一 Go process 如何判讀 heap、GC 與 memory limit；平台 OOM 與部署合約，會在下列章節再往外延伸：

• Go 進階：Kubernetes、systemd 與 load balancer 合約
• Backend：部署平台與網路入口

和 Go 教材的關係

這一章承接的是 runtime 壓力、allocation 與 pprof 診斷；如果你要先回看語言教材，可以讀：

• Go：資料結構與 allocation 壓力
• Go：goroutine leak 偵測
• Go：狀態管理的安全邊界
• Go：如何新增背景工作流程

小結

GC 控制 heap 回收節奏，memory limit 給 runtime 一個記憶體軟目標。合理設定能降低長時間服務的資源風險，但不能修正 cache、map、slice、goroutine 或 buffer 長期持有資料。診斷時先看趨勢，再用 pprof 區分 GC 壓力與長期保留。

本篇以 PHP 為主要範例（legacy 升級最常見的情境），Node.js 和 Python 的對應工具在各段併列。

相容性評估

升級前要先知道「現有程式碼跟新版本有多少不相容」。不相容的類型分四種：

PHP 相容性掃描

PHPCompatibility 是 PHP_CodeSniffer 的規則集，可以自動掃描程式碼裡哪些寫法在目標版本不相容：

1# 安裝
2composer global require phpcompatibility/php-compatibility
3
4# 掃描：目標版本 8.0
5phpcs --standard=PHPCompatibility \
6  --runtime-set testVersion 8.0 \
7  --extensions=php \
8  -p \
9  src/

掃描結果會列出每一處不相容的位置、原因和嚴重度。常見的命中包括：

1FILE: src/legacy/Database.php
2----------------------------------------------------------------------
3FOUND 3 ERRORS:
4 42 | ERROR | Function mysql_connect() is removed since PHP 7.0
5 89 | ERROR | Function each() is removed since PHP 8.0
6156 | ERROR | Curly brace access syntax is deprecated since PHP 7.4
7----------------------------------------------------------------------

php -l 可以做基本的語法檢查，但它只抓語法錯誤、抓不到 deprecated 函式和行為變更。PHPCompatibility 掃描的覆蓋面更廣。

PHP 升級的高頻修改項

Node.js 相容性掃描

1# 用 nvm 切換版本後跑測試
2nvm install 20
3nvm use 20
4npm test
5
6# 檢查 package.json 的 engines 欄位
7cat package.json | jq '.engines'

Node.js 的 breaking change 集中在 V8 引擎行為（Buffer 建構式、fs 的 callback 簽章）和原生模組的 ABI 相容性。如果專案用了原生模組（node-gyp 編譯的），版本升級後要重新 npm rebuild。

Python 相容性掃描

1# Python 2→3：用 2to3 掃描
22to3 --no-diffs -w src/
3
4# Python 3.x 小版本：用 pyupgrade
5pip install pyupgrade
6pyupgrade --py310-plus src/**/*.py

Python 2→3 的修改量通常很大（print 語法、unicode 處理、dict 方法），是接近重寫等級的升級。Python 3.x 之間的升級相對溫和，主要是 deprecation 移除和 typing 語法的演進。

本地驗證

相容性掃描找出的是靜態分析能偵測的不相容。執行期的行為變更（如字串比較規則改變、排序穩定性改變）只有跑起來才看得到。

建立目標版本的本地環境

用 Docker 建一個精確匹配目標版本的環境：

 1services:
 2  app:
 3    image: php:8.2-apache
 4    volumes:
 5      - ./src:/var/www/html
 6    ports:
 7      - "8080:80"
 8  db:
 9    image: mysql:8.0
10    environment:
11      MYSQL_ROOT_PASSWORD: localdev
12      MYSQL_DATABASE: app

如果不用 Docker，MAMP Pro 或 Laragon 可以切換 PHP 版本。關鍵是本地環境的 runtime 版本要跟升級目標完全一致——PHP 8.0 跟 8.2 之間也有差異。

驗證策略

有測試套件的專案跑測試套件。沒有測試套件的專案（legacy 專案的常態）按照這個優先序手動驗證：

1. 首頁能載入：最基本的 smoke test，確認 PHP 不 fatal error
2. 登入流程：session 處理是版本升級最常出問題的區域
3. 資料庫操作：CRUD 的每一種至少各跑一次
4. 金流 / 第三方 API：callback URL 和 API 呼叫是否正常
5. 表單提交：file upload、驗證邏輯

PHP 升級時把 error_reporting 開到最大：

1// 開發環境設定（不要在 prod 開）
2error_reporting(E_ALL);
3ini_set('display_errors', '1');

所有 notice、warning、deprecation 都要修——它們在下一個版本可能升級為 error。

第三方依賴相容性

1# Composer：檢查哪些套件需要更新
2composer outdated
3
4# 檢查各套件是否支援目標 PHP 版本
5composer why-not php 8.2

composer why-not 會列出哪些套件的 require.php 限制不允許目標版本。這些套件要先升級到支援新版本的版號，才能升 PHP。

如果某個套件已經不再維護且不支援新 PHP 版本，要評估替代方案或 fork 修改。這個評估的工作量可能佔整個升級的大部分時間。

分批部署策略

有獨立環境控制的情境（VPS / 雲端）

最安全的策略是建一套平行環境跑新版本：

1. 用新 PHP 版本建一台新的 VM 或容器
2. 部署相同的程式碼
3. 匯入 prod 資料庫的副本
4. 在新環境跑完整驗證
5. DNS 或 load balancer 切換流量到新環境
6. 舊環境保留一段時間作為 rollback 目標

rollback 是把流量切回舊環境。舊環境在確認新環境穩定之前不要關——保留期至少一週。

面板管理主機（無 SSH）的情境

面板管理主機（cPanel / Plesk）的 PHP 版本切換通常是 per-domain 的設定：

• cPanel：MultiPHP Manager，選域名 → 選 PHP 版本 → Apply
• Plesk：PHP Settings → PHP version 下拉選單

切換是即時生效的，rollback 也是即時的（選回舊版本）。但沒有「平行環境驗證」的能力——除非主機商提供 staging subdomain 可以先測。

面板管理主機的升級策略：

1. 如果有 staging subdomain：先在 staging 切換版本、驗證、再切 prod
2. 如果沒有：選流量最低的時段切換（如凌晨），切換後立刻驗證關鍵流程，出問題立刻切回
3. 切換前備份（FTP mirror + DB dump），確認 rollback 路徑存在

WordPress / 框架的版本矩陣

WordPress 和主流框架有明確的 PHP 版本支援矩陣。升級 PHP 前要先確認框架版本是否支援目標 PHP 版本：

如果框架不支援目標 PHP 版本，要先升級框架。框架升級和 PHP 升級不要同時做——先升框架、驗證穩定、再升 PHP，每一步都有獨立的 rollback 點。

常見的升級陷阱

Session 序列化格式

PHP 的 session 序列化格式在某些版本之間有變更。版本切換後舊 session 檔案可能無法反序列化，使用者會被強制登出。處理方式：

• 在維護窗口切換版本（使用者預期重新登入）
• 或在切換前清除所有 session 檔案

opcache 快取

PHP 的 opcache 會快取編譯後的 bytecode。版本切換後如果 opcache 沒清，可能用舊版本編譯的 bytecode 跑在新版本上。切換後的第一件事：

1# CLI 方式清除（如果有 SSH）
2php -r "opcache_reset();"
3
4# 或重啟 PHP-FPM / Apache
5systemctl restart php8.2-fpm

Composer 的 PHP 版本鎖定

composer.lock 裡的套件版本是根據當時的 PHP 版本解析的。PHP 版本變了之後，要重新 composer update 讓 Composer 用新版本重新解析依賴。但 composer update 可能升級其他套件——較安全的做法是 composer update --lock 只更新 lock file 的 metadata、不升級套件版本。

隱性的行為變更

PHP 8.0 起，字串跟數字的比較規則改了（0 == "foo" 從 true 變 false）。這類變更不會報錯、不會拋例外，程式碼照跑但行為不同。靜態分析抓不到，只有業務邏輯測試能覆蓋。

如果沒有測試套件，至少在切換後的一週內密切監控錯誤日誌和業務指標（訂單數、登入數、API 錯誤率），用業務指標的異常作為行為變更的偵測手段。

時程與管理層溝通

向管理層溝通時要說明：「升級 runtime 版本不只是在伺服器改一個設定。程式碼裡用到的函式和行為在新版本有不同的定義，需要逐一修改和驗證。時程取決於程式碼用了多少舊版本的專屬功能。」

成本參考：PHP 版本升級本身的工具和環境不花錢（PHPCompatibility 開源、Docker 免費、cPanel 版本切換內建）。成本全在工程師時間。

跨分類引用

• → 升級的共通操作框架：四階段模型（評估 → 平行環境 → 切換 → 退役）
• → Legacy PHP 的安全盤點：PHP 版本風險評估與漏洞掃描
• → 程式碼版控與 FTP 部署紀律：升級前的 Git 基準線與 rollback 策略

本章目標

學完本章後，你將能夠：

1. 安全地條件啟用 pprof endpoint
2. 判斷 heap、goroutine、CPU、block、mutex、trace 各自回答什麼問題
3. 用 go tool pprof 取得 profile 並閱讀 top
4. 區分 inuse_space 與 alloc_space
5. 把 profile 結果連回程式設計邊界

【觀察】效能問題需要先問對問題

pprof 診斷的核心起點是先確認你要回答哪個問題。不同 profile 回答不同問題，拿錯工具會讓分析變成猜測。

Profile 不是一次全抓就會自動給答案。先問清楚問題，再抓對應資料，分析成本會低很多。

【判讀】pprof endpoint 是受控診斷入口

pprof endpoint 的核心安全責任是受控地暴露診斷資訊。它可能包含 goroutine stack、函式名稱、路徑、記憶體配置模式與部分請求脈絡；正式服務應把 /debug/pprof/ 放在明確啟用、內部網路或驗證保護之後。

條件啟用範例：

1import _ "net/http/pprof"
2
3func RegisterDebugEndpoints(mux *http.ServeMux) {
4    if os.Getenv("APP_PPROF") != "1" {
5        return
6    }
7
8    mux.Handle("/debug/pprof/", http.DefaultServeMux)
9}

實務上還可以只綁定 localhost、掛在內部管理 port、加上身份驗證，或只在開發與診斷環境啟用。重點是 pprof 要受控，而不是跟公開 API 一起裸露。

【執行】heap profile 看記憶體保留與配置壓力

Heap profile 的核心問題是「哪些物件佔用或配置了記憶體」。當服務記憶體持續上升時，heap profile 是第一個常用工具。

看目前仍被保留的記憶體：

1go tool pprof http://localhost:8080/debug/pprof/heap

進入 pprof 後：

1(pprof) top

inuse_space 代表目前仍被保留的記憶體，適合分析 leak、cache、map、slice、send buffer、長期持有資料。

看累積配置量：

1go tool pprof -alloc_space http://localhost:8080/debug/pprof/heap

alloc_space 代表累積配置量，適合分析 JSON marshal、slice append、短命 object、熱路徑反覆配置造成的 GC 壓力。

【判讀】heap profile 要連回資料結構

Heap profile 的核心解讀是問「誰持有資料」或「誰反覆配置」。看到某個函式在 top 裡，下一步要回到資料結構與生命週期。

常見對應：

Profile 給的是線索，不是最終修正。修正要回到資料模型、copy boundary、buffer policy 或 cache policy。

【執行】goroutine profile 看存活與卡住路徑

Goroutine profile 的核心問題是「哪些 goroutine 還活著，以及它們卡在哪裡」。它常用來診斷 goroutine leak、channel 等待、鎖等待與 network read 阻塞。

互動模式：

1go tool pprof http://localhost:8080/debug/pprof/goroutine

文字 stack：

1curl "http://localhost:8080/debug/pprof/goroutine?debug=2"

若大量 goroutine 卡在同一個 channel receive、send、network read、ticker loop，通常代表某個退出條件、close path、deadline 或 unregister 設計有問題。

Goroutine profile 不只看數量。少量但卡在錯誤位置的 goroutine，也可能代表資源沒有被釋放。

【執行】CPU profile 看熱路徑

CPU profile 的核心問題是「程式把 CPU 時間花在哪裡」。它需要採樣一段時間，適合分析 CPU 使用率高或 request latency 異常。

1go tool pprof "http://localhost:8080/debug/pprof/profile?seconds=30"

常用指令：

1(pprof) top
2(pprof) list Encode

CPU profile 要搭配流量情境解讀。低流量時抓到的 profile 可能沒有代表性；高流量時則要注意診斷本身也會造成額外負擔。

若 top 顯示大量時間花在 JSON encode、sort、lock、regex 或 compression，下一步應回到對應熱路徑，判斷是否可以減少工作、快取結果、改資料結構或降低呼叫頻率。

【策略】block 與 mutex profile 需要先啟用取樣

Block/mutex profile 的核心用途是分析等待，而不是分析 CPU 計算。它們通常需要在程式中設定取樣比例。

1func ConfigureBlockingProfiles() {
2    runtime.SetBlockProfileRate(1)
3    runtime.SetMutexProfileFraction(5)
4}

Block profile 看 goroutine 在同步原語上阻塞的時間，例如 channel send/receive、select、mutex。Mutex profile 看鎖競爭。

啟用取樣有成本，不一定要常駐開最高強度。診斷時可以條件啟用，或在壓測環境中使用。

【執行】trace 看排程與延遲

Trace 的核心用途是觀察 goroutine 排程、network block、syscall、GC pause 與延遲事件。它比單一 profile 更完整，但也更重。

1curl -o trace.out "http://localhost:8080/debug/pprof/trace?seconds=5"
2go tool trace trace.out

Trace 適合用在你已經知道有延遲問題，但 heap、CPU、goroutine profile 都不足以解釋時。它能顯示 goroutine 何時 runnable、何時 blocked、何時被排程。

Trace 檔案可能很大，不適合長時間收集。通常先抓短時間，確認問題窗口後再精準分析。

【策略】診斷流程要先保留現場

pprof 診斷的核心流程是先保留現場，再改程式。若你先重啟服務或調參，可能會清掉最重要的證據。

建議流程：

1. 記錄當下流量、版本、操作、時間區間。
2. 讀 runtime metrics：heap、GC、goroutine、queue 長度。
3. 依問題抓 profile：heap、goroutine、CPU 或 trace。
4. 用 profile 找出函式與 stack pattern。
5. 回到程式碼確認資料結構、goroutine lifecycle 或 hot path。
6. 修改後用相同情境再抓一次 profile 驗證。

這個流程能避免「看到 top 第一名就改」的衝動。Profile 需要和情境一起讀，才不會誤判。

本章不處理

本章先處理單一服務內的 profile 讀法；商用 APM 與分散式 tracing，會在下列章節再往外延伸：

• Go 進階：Observability pipeline、metrics 與 tracing
• Backend：可觀測性平台

和 Go 教材的關係

這一章承接的是 goroutine、allocation 與 runtime metrics；如果你要先回看語言教材，可以讀：

• Go：goroutine：輕量並發工作
• Go：select：同時等待多種事件
• Go：如何新增背景工作流程
• Go：狀態管理的安全邊界

小結

pprof 是診斷工具，不是公開 API。Heap profile 看保留與配置，goroutine profile 看存活與卡住路徑，CPU profile 看熱點，block/mutex profile 看等待，trace 看排程與延遲。好的診斷流程會先問對問題、抓對 profile，再把結果連回資料結構、goroutine lifecycle 與服務行為。

本章目標

學完本章後，你將能夠：

1. 分辨合理長期 goroutine 與 goroutine leak
2. 用 context、done channel、connection close 設計退出路徑
3. 用 pprof goroutine profile 判讀卡住 stack
4. 測試 worker、ticker、WebSocket pump 是否能退出
5. 從 leak pattern 回到 ownership 修正

【觀察】goroutine leak 是生命週期沒有結束

Goroutine leak 的核心定義是某個 goroutine 已經沒有存在價值，卻仍然活著。它可能卡在 channel receive、channel send、network read、ticker、mutex 或永遠不會觸發的 select case。

反模式：

1func StartWorker(jobs <-chan Job) {
2    go func() {
3        for job := range jobs {
4            process(job)
5        }
6    }()
7}

這個 worker 只有在 jobs 被關閉時才會退出。若呼叫端永遠不關閉 jobs，而 worker 也沒有 context，這個 goroutine 可能永久存在。

長期存在不一定是 leak。HTTP server accept loop、metrics exporter、background scheduler 都可能合理存在；問題是它們是否有明確停止條件，且 shutdown 時是否真的會走到。

【判讀】每個 goroutine 都要有退出原因

Goroutine lifecycle 的核心檢查是每個 goroutine 都能回答三個問題：

1. 誰要求它停止？
2. 它如果卡在 channel 或 I/O，如何被喚醒？
3. 它停止後如何讓測試或上層知道？

若三題任一題答不出來，就有 leak 風險。

例如 worker 應該有 context：

 1func RunWorker(ctx context.Context, jobs <-chan Job) {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            return
 6        case job, ok := <-jobs:
 7            if !ok {
 8                return
 9            }
10            process(job)
11        }
12    }
13}

這個 worker 有兩條退出路徑：上層取消 context，或 jobs channel 被關閉。這比只依賴 channel close 更容易整合到服務 shutdown。

【策略】I/O 阻塞需要 deadline 或 close

I/O goroutine 的核心風險是 context 本身不一定能打斷底層阻塞呼叫。WebSocket read、TCP read、file watcher、外部 API call 都要確認是否支援 context、deadline 或 close。

WebSocket read pump 常見退出方式：

 1func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 2    defer func() {
 3        hub.unregister <- c
 4    }()
 5
 6    for {
 7        var message ClientMessage
 8        if err := c.conn.ReadJSON(&message); err != nil {
 9            return
10        }
11        _ = router.Route(ctx, c, message)
12    }
13}

若 ReadJSON 卡住，context 取消不一定直接讓它返回。實務上需要 read deadline、connection close 或 heartbeat 讓 read pump 有機會退出。

【執行】done channel 讓測試能觀察退出

測試 goroutine 是否退出的核心問題是需要可觀察訊號。done channel 可以在 goroutine 結束時 close。

 1func RunWorker(ctx context.Context, jobs <-chan Job, done chan<- struct{}) {
 2    defer close(done)
 3
 4    for {
 5        select {
 6        case <-ctx.Done():
 7            return
 8        case job, ok := <-jobs:
 9            if !ok {
10                return
11            }
12            process(job)
13        }
14    }
15}

測試：

 1func TestRunWorkerStops(t *testing.T) {
 2    ctx, cancel := context.WithCancel(context.Background())
 3    jobs := make(chan Job)
 4    done := make(chan struct{})
 5
 6    go RunWorker(ctx, jobs, done)
 7    cancel()
 8
 9    select {
10    case <-done:
11    case <-time.After(time.Second):
12        t.Fatalf("worker did not stop")
13    }
14}

Timeout 是測試保護，不是功能本身。真正的退出訊號是 done 被關閉。

【執行】ticker 必須停止

Ticker leak 的核心原因是建立 ticker 後沒有呼叫 Stop。Ticker 會持有 runtime 資源；長時間服務若反覆建立不停止，會累積不必要成本。

 1func RunCleanup(ctx context.Context) {
 2    ticker := time.NewTicker(time.Minute)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return
 9        case <-ticker.C:
10            cleanup()
11        }
12    }
13}

defer ticker.Stop() 應緊跟在成功建立 ticker 後。這樣不管函式因 context、錯誤或 channel 關閉退出，ticker 都會被停止。

time.After 在一次性 timeout 很方便，但在高頻迴圈裡反覆建立 timer 可能造成額外配置。需要重複觸發時，優先使用 Ticker 或可重設的 Timer 並明確停止。

【判讀】pprof goroutine profile 看 stack pattern

Goroutine profile 的核心價值是顯示 goroutine stack。當 goroutine 數量持續上升時，先看它們卡在哪裡。

1curl "http://localhost:8080/debug/pprof/goroutine?debug=2"

常見 pattern：

看到 stack 後，下一步是回到對應 lifecycle 設計：誰負責停止，誰負責釋放阻塞點。

【策略】WebSocket pump leak 要看 read/write/unregister 三方

WebSocket goroutine leak 的核心常見原因是 read pump、write pump、hub unregister 沒有形成閉環。

目標流程：

 1read pump error 或 connection close
 2        │
 3        ▼
 4hub unregister
 5        │
 6        ├── close client.send
 7        └── close conn
 8        │
 9        ▼
10write pump exits

若 hub 沒有 close send，write pump 可能一直等。若 connection 沒有 close，read pump 可能卡在 read。若 unregister 不是 idempotent，重複 close 可能 panic。

Goroutine profile 若顯示大量 goroutine 卡在 writePump 的 send receive，通常要檢查 client.send 是否會被 close。若卡在 ReadJSON，要檢查 read deadline、heartbeat 與 connection close。

【測試】用 goroutine 數量做粗略回歸檢查

Goroutine 數量測試的核心用途是粗略檢查是否有明顯 leak。它不是精準證明，因為 Go runtime 與測試環境本身也會有 goroutine。

 1func TestNoObviousGoroutineLeak(t *testing.T) {
 2    before := runtime.NumGoroutine()
 3
 4    ctx, cancel := context.WithCancel(context.Background())
 5    done := make(chan struct{})
 6    go func() {
 7        defer close(done)
 8        RunWorker(ctx, make(chan Job))
 9    }()
10
11    cancel()
12    select {
13    case <-done:
14    case <-time.After(time.Second):
15        t.Fatalf("worker did not stop")
16    }
17
18    eventually(t, time.Second, func() bool {
19        return runtime.NumGoroutine() <= before+2
20    })
21}

這類測試要留緩衝，避免因 runtime 或其他測試 goroutine 造成假失敗。更可靠的測試仍是等待明確 done 訊號。

【判讀】goroutine leak 修正要改停止路徑

Goroutine leak 的核心修正是補上停止路徑。

常見修正：

• 加入 ctx.Done() case。
• 關閉由自己擁有的 output channel。
• 由 coordinator 等 sender 完成再 close。
• 對 network read/write 設定 deadline。
• shutdown 時 close connection。
• ticker 建立後 defer Stop()。
• hub unregister 時 close send channel。

修正後要用測試證明退出路徑真的會發生，再用 pprof 或 goroutine count 驗證趨勢。

本章不處理

本章先處理 goroutine 的啟動、停止與阻塞邊界；更完整的 worker 全域治理，會在下列章節再往外延伸：

• Go 進階：channel ownership 與關閉責任
• Go 進階：bounded worker pool
• Go 進階：select loop 的生命週期設計

和 Go 教材的關係

這一章承接的是 goroutine lifecycle、channel 與 shutdown；如果你要先回看語言教材，可以讀：

• Go：goroutine：輕量並發工作
• Go：channel：資料傳遞與 backpressure
• Go：select：同時等待多種事件
• Go：如何新增背景工作流程

小結

Goroutine leak 是生命週期問題。每個長期 goroutine 都應知道誰能停止它、如何解除阻塞、如何讓測試觀察退出。Context、done channel、deadline、connection close、ticker stop 與 hub unregister 是主要工具。pprof goroutine profile 則用來確認還活著的 goroutine 卡在哪個邊界。

本模組承接前面的並發、WebSocket 與測試可靠性：如果 goroutine lifecycle、send buffer、repository copy boundary 沒設計好，runtime 訊號會在 heap profile、goroutine profile、CPU profile 或 allocation profile 中反映出來。

章節列表

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。範例包含 WebSocket client lifecycle、background worker、repository list、JSON push payload 與 cache。

範例只用來展示 Go runtime 診斷方法，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

• 用 runtime.ReadMemStats 或 runtime/metrics 觀察 heap、GC 與 goroutine 趨勢。
• 用 debug.SetMemoryLimit 給 runtime 軟性記憶體目標。
• 用 pprof 分析 heap、goroutine、CPU、block、mutex 與 trace。
• 用 goroutine profile 找出卡在 channel、network read、ticker、mutex 的路徑。
• 用 alloc_space 與 inuse_space 區分配置壓力與保留記憶體。
• 用資料結構設計降低不必要 allocation，但保留必要 copy boundary。

學習重點

學完本模組後，你應該能判斷：

1. 記憶體問題是 GC 壓力、長期保留，還是短暫尖峰
2. 什麼情境適合調整 memory limit，什麼情境應該找 leak
3. heap、goroutine、CPU、trace 各自回答什麼問題
4. goroutine leak 應回到哪個 lifecycle 邊界修
5. allocation 優化何時值得做，何時會破壞安全邊界

本模組不處理

本模組不討論分散式 tracing 平台、完整監控系統或雲端特定 profiler。這些工具可以接在本模組之後；本模組先建立 Go runtime 原生訊號與 pprof 的診斷思路。後續可接 Observability pipeline、metrics 與 tracing。

學習時間

預計 3-4 小時

目標讀者

• 已完成 Go 入門實戰指南 的工程師
• 想深入理解 Go 並發模型與 runtime 行為的開發者
• 需要維護長時間運行服務的人
• 想把 Go 服務從「能跑」提升到「可觀測、可測、可演進」的人

學習目標

1. 掌握 goroutine、channel、mutex 的進階使用邊界
2. 理解 WebSocket client lifecycle、heartbeat、buffer 與慢客戶端問題
3. 使用 pprof、runtime 記憶體限制與結構化日誌診斷服務
4. 設計 event-driven service 的資料邊界與去重策略
5. 建立並發測試、整合測試與可重現的時間控制
6. 能評估 Go 服務在生產環境的風險與操作策略
7. 知道單一 Go 服務延伸到跨節點與平台整合時，哪些責任會轉移到資料庫、queue、broker、observability pipeline 與部署平台

共用術語

進階篇延續入門篇的 action、command、domain event、repository、port、adapter、projection 等詞彙。若你需要確認這些詞在這套教材中的責任邊界，可以先回到 Go 教材核心術語。

與 Backend 教材的分工

Go 進階篇處理單一 Go 服務內部的高階能力：goroutine lifecycle、WebSocket pump、runtime 診斷、event boundary、race test、graceful shutdown 與 diagnostics endpoint。當內容開始碰到資料庫、Redis、RabbitMQ、Kafka、OpenTelemetry、Kubernetes 或 CI 平台操作時，就應該轉到跨語言的 Backend 服務實務指南。

模組七保留在進階篇裡，因為它要回答「Go 服務在跨出去以前，還需要先把哪些 port、訊號與測試合約準備好」。外部系統本身的選型與部署細節，則放在 Backend，讓不同語言都能共用同一套實作知識。

教學模組

模組一：進階並發模式

從服務實例理解 fan-in、fan-out、取消傳播與 backpressure ，先把並發語意說清楚。

• channel ownership 與關閉責任
• select loop 的生命週期設計
• 非阻塞送出與事件丟棄策略
• 共享狀態與複製邊界
• bounded worker pool
• rate limiting 與 backpressure

模組二：WebSocket 服務架構

把 WebSocket server 的連線、訂閱、推送與錯誤處理拆成可維護的邊界。

• read pump / write pump 模式
• heartbeat、deadline 與連線清理
• 訂閱模型與訊息路由
• 慢客戶端與 send buffer 管理

模組三：Runtime 與效能診斷

理解 Go runtime 如何在長時間運行服務中影響記憶體與排程行為。

• GC 與 memory limit
• pprof 基礎診斷流程
• goroutine leak 偵測
• 資料結構與 allocation 壓力

模組四：架構邊界與事件系統

用事件驅動架構拆解服務責任，讓來源、處理與狀態不再混在一起。

• 事件來源、處理流程與狀態邊界
• 事件去重與語義鍵設計
• Source of Truth：狀態邊界
• 多來源 event 融合

模組五：測試與可靠性

針對並發服務建立能真正揭露風險的測試，而不是只追求覆蓋率。

• 時間注入與狀態轉移測試
• WebSocket integration test
• race condition 檢查
• table-driven test 的設計邊界

模組六：生產操作

把本地服務推向可維護、可診斷、可部署的操作狀態。

• graceful shutdown 與 signal handling
• 健康檢查與診斷 endpoint
• 結構化日誌欄位設計
• 版本偵測與 feature gate

模組七：跨節點與平台整合

承接各章「本章不處理」的延伸邊界，把單一服務往外擴張時必須補上的責任整理成一條清楚路線。

• 資料庫 transaction 與 schema migration
• Durable queue、outbox 與 idempotency
• 跨節點 WebSocket、presence 與重連協定
• Observability pipeline、metrics 與 tracing
• Kubernetes、systemd 與 load balancer 合約
• CI、fuzz、load test 與 chaos testing

學習路徑

路徑 A：並發服務維護者

1模組一 → 模組四 → 模組五

重點：事件流、共享狀態、並發測試。

路徑 B：WebSocket/API 開發者

1模組二 → 模組六 → 模組五

重點：連線生命週期、訊息路由、操作診斷。

路徑 C：效能與可靠性工程師

1模組三 → 模組五 → 模組六

重點：pprof、goroutine leak、race check、服務操作。

路徑 D：完整學習

1模組一 → 模組二 → 模組三 → 模組四 → 模組五 → 模組六 → 模組七

按順序學習，建立完整的 Go 長時間運行服務模型。

主題延伸地圖

進階篇的章節會反覆碰到 log、time、state、event、WebSocket 與 testing。這些主題會在不同服務壓力下承擔不同責任；主題延伸地圖用來幫讀者辨識每一層的分工。

先備知識

本系列假設你已經完成 Go 入門實戰指南 的基礎部分，因為下面這些章節會直接沿用那些概念：

• 模組三：標準庫實戰
• 模組四：並發模型
• 模組五：錯誤處理與測試

每章結構

每章都採用「由淺到深」的結構，先說明問題，再切到設計與實作：

1. 原理層：這個機制解決什麼問題
2. 設計層：在服務架構中如何切責任
3. 實作層：用簡化範例程式碼看具體做法
4. 實戰檢查：維護時要確認哪些風險

文件版本：v0.1.0 最後更新：2026-04-22 系列狀態：核心初稿完成，延伸模組規劃中