模組六：生產操作 on Tarragon

6.1 graceful shutdown 與 signal handling

Wed, 22 Apr 2026 00:00:00 +0000

Graceful shutdown 的核心目標是服務收到停止訊號後，不再接受新工作，並給既有工作一段時間完成或清理。Go 服務通常用 signal、root context、http.Server.Shutdown、worker context 與 timeout 串起停止流程。

本章目標

學完本章後，你將能夠：

把 OS signal 轉成 root context 取消
用 http.Server.Shutdown 停止接受新 request
讓 worker、hub、WebSocket pump 觀察同一個停止訊號
設計 shutdown timeout 與強制退出邊界
測試 server 與 worker 的停止流程

【觀察】直接結束 process 會留下不確定狀態

Shutdown 的核心風險是停止流程不明確。服務可能正在處理 request、WebSocket client 仍在線、worker 正在寫資料、queue message 尚未 ack、diagnostics 還以為服務可接流量。

不完整停止常見後果：

新 request 在服務即將關閉時仍被接受。
WebSocket client 沒收到 close，server 端 goroutine 殘留。
背景 worker 寫到一半被中斷。
readiness 還是 200，負載平衡器繼續送流量。
測試結束後留下 goroutine 或開放 port。

Graceful shutdown 是讓停止策略可預期。

【判讀】shutdown 是多階段流程

Graceful shutdown 的核心流程是先停止接新工作，再讓既有工作收尾，最後釋放資源。

建議順序：

 1receive SIGINT/SIGTERM
 2        │
 3        ▼
 4cancel root context
 5        │
 6        ├── readiness becomes false
 7        ├── HTTP server stops accepting new requests
 8        ├── workers stop consuming new jobs
 9        ├── WebSocket hub unregisters clients
10        └── diagnostics/log records shutdown reason
11        │
12        ▼
13wait within timeout
14        │
15        ▼
16process exits

不同服務會有不同細節，但核心不變：停止訊號要集中，元件各自完成自己的 cleanup，整體流程要有 timeout。

【執行】signal 轉成 root context

Signal handling 的核心責任是把作業系統訊號轉成應用程式可理解的取消訊號。Go 1.16 之後可以使用 signal.NotifyContext。

1func main() {
2    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
3    defer stop()
4
5    if err := run(ctx); err != nil {
6        log.Fatal(err)
7    }
8}

ctx 是 root context。HTTP server、worker、hub、diagnostics 都應從它派生出自己的 lifecycle，而不是每個元件各自監聽 signal。

Signal handler 不應放大量清理邏輯。它只負責發出停止意圖；實際清理由各元件在自己的 ownership 邊界內完成。

【執行】HTTP server 用 Shutdown 停止接新 request

http.Server.Shutdown 的核心行為是停止接受新連線，並等待既有 request 在 timeout 內完成。它比直接 Close 更適合 graceful shutdown。

 1func RunHTTPServer(ctx context.Context, handler http.Handler) error {
 2    server := &http.Server{
 3        Addr:    ":8080",
 4        Handler: handler,
 5    }
 6
 7    errCh := make(chan error, 1)
 8    go func() {
 9        errCh <- server.ListenAndServe()
10    }()
11
12    select {
13    case <-ctx.Done():
14        shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
15        defer cancel()
16        return server.Shutdown(shutdownCtx)
17
18    case err := <-errCh:
19        if errors.Is(err, http.ErrServerClosed) {
20            return nil
21        }
22        return err
23    }
24}

Shutdown timeout 是必要邊界。沒有 timeout 的 shutdown 可能永遠等待某個卡住 request；timeout 太短則可能讓合理 request 來不及收尾。

【策略】readiness 應先變成 false

Readiness 的核心用途是控制服務是否應接新流量。Shutdown 開始後，readiness 應先變成 false，再停止 server 或等待既有工作。

 1type Lifecycle struct {
 2    shuttingDown atomic.Bool
 3}
 4
 5func (l *Lifecycle) BeginShutdown() {
 6    l.shuttingDown.Store(true)
 7}
 8
 9func (l *Lifecycle) Ready() bool {
10    return !l.shuttingDown.Load()
11}

Signal 收到後：

1lifecycle.BeginShutdown()
2cancel()

這讓負載平衡器或監控能知道服務不應再接新流量。Process 還活著，但 readiness 已經反映操作狀態。

【執行】背景工作要觀察 context

背景 worker 的核心 shutdown 條件是每個 loop 都能觀察停止訊號。Ticker、queue consumer、WebSocket hub 都應該有退出路徑。

 1func RunWorker(ctx context.Context) error {
 2    ticker := time.NewTicker(time.Minute)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return ctx.Err()
 9        case <-ticker.C:
10            if err := RunOnce(ctx); err != nil {
11                return err
12            }
13        }
14    }
15}

若 RunOnce 可能執行很久，也應接收 context。否則外層 loop 看到 cancel，內層 I/O 或計算仍可能卡住。

【策略】WebSocket cleanup 要回到 hub owner

WebSocket shutdown 的核心原則是讓 hub 或 connection manager 統一清理 client。不要讓 signal handler 直接遍歷各種 connection 並隨意 close。

 1func (h *Hub) Run(ctx context.Context) {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            h.closeAllClients()
 6            return
 7        case client := <-h.register:
 8            h.registerClient(client)
 9        case client := <-h.unregister:
10            h.unregisterClient(client)
11        }
12    }
13}

closeAllClients 應透過 hub 的既有 owner 邏輯關閉 send、移除訂閱、關閉 connection。這延續前面模組的 ownership 原則。

【測試】shutdown 測試要觀察明確條件

Shutdown 測試的核心是確認停止訊號能讓元件退出，而不是等待固定時間。

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

HTTP server 測試可以啟動 server 後 cancel context，確認 RunHTTPServer 回傳。測試應使用隨機 port 或 httptest.Server，避免固定 port 造成衝突。

本章不處理

本章先處理服務內部的 shutdown 順序與 cleanup owner；平台 hook、timeout 與 load balancer 合約，會在下列章節再往外延伸：

Go 進階：Kubernetes、systemd 與 load balancer 合約

和 Go 教材的關係

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

小結

Graceful shutdown 是多階段流程：signal 轉成 root context，readiness 先關閉，HTTP server 停止接新 request，worker 和 WebSocket hub 觀察 context 收尾，整體流程受 timeout 保護。停止訊號越集中，元件 ownership 越清楚，服務在部署、測試與本機開發時越不容易留下殘存 goroutine 或未釋放連線。

6.2 健康檢查與診斷 endpoint

Wed, 22 Apr 2026 00:00:00 +0000

健康檢查與診斷 endpoint 的核心差異是使用者與風險不同。/health 給監控或負載平衡器判斷 process 是否活著，/ready 判斷是否應接流量，/debug/... 則給工程師排查問題且必須限制存取。

本章目標

學完本章後，你將能夠：

分辨 health、readiness、diagnostics 的語意
設計快速穩定的 /health
用 /ready 控制是否接新流量
條件啟用 pprof、runtime stats 等診斷入口
測試 status code 與 JSON response 合約

【觀察】所有狀態都塞進 health 會讓監控失真

Health endpoint 的核心風險是語意混亂。若 /health 同時檢查 process、database、queue、外部 API、cache、背景同步，任何依賴短暫波動都可能讓服務被判定死亡。

問題範例：

1/health
2  ├── process alive?
3  ├── database reachable?
4  ├── queue lag small?
5  ├── external API reachable?
6  └── background sync fresh?

這些問題不應全部塞進同一個 endpoint。Process 活著、可接流量、依賴降級、工程診斷，是不同操作訊號。

【判讀】health、ready、diagnostics 回答不同問題

操作 endpoint 的核心設計是每個 endpoint 只回答一個問題。

Endpoint	使用者	回答的問題	失敗影響
`/health`	process monitor	process 是否基本活著	可能重啟 process
`/ready`	load balancer	是否應接新流量	暫停導流
`/debug/...`	工程師	服務內部狀態如何	不應公開
`/metrics`	metrics collector	可聚合監控資料	監控缺資料

這樣切分後，某個外部依賴故障不一定要讓 process 被重啟；服務可能只是不 ready，或處於 degraded 狀態。

【執行】health endpoint 應簡單快速

Health endpoint 的核心責任是快速回答 process 是否能處理基本 HTTP request。它應該簡單、快速、穩定。

 1func HandleHealth(w http.ResponseWriter, r *http.Request) {
 2    if r.Method != http.MethodGet {
 3        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 4        return
 5    }
 6
 7    w.Header().Set("Content-Type", "application/json")
 8    w.WriteHeader(http.StatusOK)
 9    _, _ = w.Write([]byte(`{"status":"ok"}`))
10}

/health 不應執行昂貴查詢，也不應依賴大量下游服務。若健康檢查本身很慢，監控會把診斷工具變成新問題。

【執行】readiness 控制是否接流量

Readiness 的核心責任是回答「服務現在是否應該接新流量」。它可以檢查啟動狀態、必要依賴、shutdown 狀態。

 1type Readiness struct {
 2    ready        atomic.Bool
 3    shuttingDown atomic.Bool
 4}
 5
 6func (r *Readiness) Ready() bool {
 7    return r.ready.Load() && !r.shuttingDown.Load()
 8}
 9
10func HandleReady(readiness *Readiness) http.HandlerFunc {
11    return func(w http.ResponseWriter, r *http.Request) {
12        w.Header().Set("Content-Type", "application/json")
13
14        if !readiness.Ready() {
15            w.WriteHeader(http.StatusServiceUnavailable)
16            _, _ = w.Write([]byte(`{"status":"not_ready"}`))
17            return
18        }
19
20        w.WriteHeader(http.StatusOK)
21        _, _ = w.Write([]byte(`{"status":"ready"}`))
22    }
23}

服務啟動尚未完成、必要背景同步尚未就緒、或 graceful shutdown 已開始時，readiness 應回 503。Process 仍然活著，但不應接新流量。

【策略】dependency check 依照監控語意分層

依賴檢查的核心判斷是故障是否代表 process 應重啟。Database 暫時不可用不一定代表 process 壞掉；重啟可能無法修復，反而造成更多負載。

建議分層：

/health：只確認 process alive。
/ready：確認必要依賴是否足以接新流量。
/diagnostics/dependencies：提供工程師查看細節。

診斷 response 可以包含穩定欄位：

1{
2  "status": "degraded",
3  "dependencies": {
4    "database": "ok",
5    "queue": "lagging"
6  }
7}

監控應依賴 status code 與穩定欄位，工程師再用 body 細節診斷問題。自由文字可以輔助閱讀，但不應成為監控規則的依據。

【執行】diagnostics endpoint 要條件啟用

Diagnostics endpoint 的核心用途是提供工程師排查問題的資料。pprof、runtime metrics、internal queue length、goroutine count 都屬於這類。

 1func RegisterDiagnostics(mux *http.ServeMux, enabled bool) {
 2    if !enabled {
 3        return
 4    }
 5
 6    mux.HandleFunc("/debug/runtime", HandleRuntimeStats)
 7}
 8
 9func HandleRuntimeStats(w http.ResponseWriter, r *http.Request) {
10    var stats runtime.MemStats
11    runtime.ReadMemStats(&stats)
12
13    response := map[string]any{
14        "heap_alloc":  stats.HeapAlloc,
15        "num_gc":      stats.NumGC,
16        "goroutines":  runtime.NumGoroutine(),
17    }
18
19    _ = json.NewEncoder(w).Encode(response)
20}

Diagnostics 可能揭露內部狀態、記憶體資訊、goroutine 數量、路徑與部署細節，不應公開給一般使用者。若需要長期保留，至少應限制在內網、管理 port、認證或防火牆後。

【判讀】status code 是監控合約

健康檢查的核心合約是 status code。監控系統通常先看 HTTP code 與 timeout，不會理解複雜 body。

狀態	意義
`200 OK`	符合該 endpoint 的健康條件
`503 Service Unavailable`	暫時不可用或不應接流量
`405 Method Not Allowed`	呼叫方式錯誤
timeout	endpoint 無法在預期時間內回應

Body 可以提供人類可讀資訊，但不應讓監控依賴自由文字。若要機器讀取，使用穩定 JSON 欄位，例如 status、reason、dependencies。

【測試】endpoint 測試要鎖定 status code

Endpoint 測試的核心是驗證 status code 與穩定 JSON 欄位，而不是完整自由文字。

 1func TestReadyReturnsUnavailableWhenShuttingDown(t *testing.T) {
 2    readiness := &Readiness{}
 3    readiness.ready.Store(true)
 4    readiness.shuttingDown.Store(true)
 5
 6    req := httptest.NewRequest(http.MethodGet, "/ready", nil)
 7    rec := httptest.NewRecorder()
 8
 9    HandleReady(readiness).ServeHTTP(rec, req)
10
11    if rec.Code != http.StatusServiceUnavailable {
12        t.Fatalf("status = %d, want %d", rec.Code, http.StatusServiceUnavailable)
13    }
14}

Diagnostics endpoint 也應測 gate 關閉時不註冊或回 404，避免診斷入口不小心暴露。

本章不處理

本章先處理 health、readiness 與 diagnostics 的語意切分；Prometheus、OpenTelemetry 與平台設定，會在下列章節再往外延伸：

Go 進階：Observability pipeline、metrics 與 tracing

和 Go 教材的關係

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

小結

/health、/ready、diagnostics endpoint 解決不同問題。Health 檢查 process 基本可用性，readiness 控制是否接新流量，diagnostics 支援工程排查且應限制存取。Status code 是監控合約，JSON body 是補充細節；把這些訊號混在一起會讓操作判斷與安全邊界都變模糊。

6.3 結構化日誌欄位設計

Wed, 22 Apr 2026 00:00:00 +0000

結構化日誌欄位的核心目標是讓 log 可查詢、可聚合、可追蹤。Message 給人讀，欄位給系統查；重要資訊應放在穩定欄位，不應只藏在自由文字裡。

本章目標

學完本章後，你將能夠：

設計穩定 log schema
用 layer、request_id、event_type、reason 支援查詢
區分 message 與 structured fields 的責任
避免重複記錄同一個錯誤
避免把敏感資料寫進 log

【觀察】自由文字 log 很難查詢

Log 設計的核心問題是事故發生時需要快速查詢。若所有資訊都在 message 裡，查詢只能依賴模糊字串。

不穩定 log：

1logger.Info("event accepted for user 123 request abc")

這行給人看可以，但系統很難穩定查 request_id=abc 或 user_id=123。不同工程師改字句後，查詢就可能失效。

結構化 log：

1logger.Info("event accepted",
2    "layer", "http",
3    "request_id", requestID,
4    "user_id", userID,
5    "event_type", event.Type,
6)

Message 描述發生什麼事，欄位提供可查詢資料。這是 log schema 的基本分工。

【判讀】log schema 是查詢合約

Log schema 的核心規則是欄位名稱與值集合要穩定。request_id、requestID、rid 混用會讓查詢與儀表板變得困難。

常用欄位：

欄位	用途
`layer`	問題發生在哪個系統層
`request_id`	串起單次 HTTP request
`event_id`	串起事件處理流程
`event_type`	聚合某類 domain event
`client_id`	查 WebSocket client 行為
`topic`	查訂閱或推送範圍
`reason`	聚合失敗原因
`error`	保存錯誤文字

欄位不需要很多，但要一致。穩定欄位能讓除錯從「讀一堆文字」變成「查一組條件」。

【執行】layer 表示發生位置

layer 的核心用途是標示 log 來自哪個系統層，協助工程師快速縮小問題範圍。

1logger.Warn("queue full",
2    "layer", "worker",
3    "queue", "events",
4    "reason", "buffer_full",
5)

常見 layer：

http
websocket
worker
repository
runtime
diagnostics

名稱不需要多，但應穩定。若 worker、background、job_runner 混用，查詢就會變麻煩。

【策略】correlation ID 串起一次流程

Correlation ID 的核心目標是把同一次請求或同一個事件流串起來。HTTP request 常用 request_id，背景事件可以用 event_id 或 trace_id。

1func WithRequestLog(r *http.Request, logger *slog.Logger) *slog.Logger {
2    requestID := r.Header.Get("X-Request-ID")
3    if requestID == "" {
4        requestID = uuid.NewString()
5    }
6
7    return logger.With("request_id", requestID)
8}

後續 handler、service、repository 都使用帶有 request_id 的 logger。查詢單次流程時，不需要靠時間範圍猜哪些 log 相關。

Correlation ID 不應包含敏感資料。它是追蹤用識別碼，不是使用者資料容器。

【執行】reason 欄位讓失敗可統計

reason 的核心用途是把錯誤原因變成可聚合分類。Message 可以給人讀，reason 給查詢與統計使用。

1logger.Warn("reject event",
2    "layer", "http",
3    "reason", "invalid_payload",
4    "event_type", event.Type,
5)

穩定 reason 可以回答「最近一小時最多的拒絕原因是什麼」。如果原因只寫在 message 中，查詢會依賴模糊字串比對。

Reason 值應像 enum 一樣維持小集合，例如：

invalid_payload
queue_full
permission_denied
timeout
client_disconnected
dependency_unavailable

reason 應維持小集合分類，完整錯誤應放在 error 欄位。這樣監控可以穩定聚合原因，工程師仍能從錯誤欄位取得診斷細節。

【判讀】錯誤只在負責處理的邊界記一次

錯誤日誌的核心風險是同一個錯誤被每一層都記一次。這會放大噪音，讓事故時很難看出真正的失敗點。

反模式：

1logger.Error("repository failed", "error", err)
2return fmt.Errorf("save notification: %w", err)

上層又記一次：

1logger.Error("request failed", "error", err)

較清楚的做法是底層 wrap error，上層在決定 response 或重試策略的邊界記錄一次：

1if err := service.Create(ctx, cmd); err != nil {
2    logger.Warn("create notification failed",
3        "layer", "http",
4        "reason", reasonOf(err),
5        "error", err,
6    )
7    writeError(w, err)
8    return
9}

底層若有必要補充脈絡，優先透過 error wrapping 或 structured error，而不是每層都 Error log。

【策略】敏感資料不進 log

Log 欄位設計的核心安全邊界是只記錄診斷必要資料。token、密碼、完整 cookie、完整個資與機密 payload 都屬於應排除資料；結構化 log 很容易被集中保存與搜尋，敏感資料一旦進入 log，清理成本很高。

可以記錄：

1logger.Info("user login",
2    "user_id", user.ID,
3)

應排除：

1logger.Info("user login",
2    "password", password,
3    "token", token,
4)

若需要診斷 payload，可記錄長度、hash、欄位是否存在，而不是完整內容。

1logger.Debug("payload received",
2    "payload_bytes", len(body),
3    "payload_sha256", checksum(body),
4)

所有會被收集或保存的 log 都應遵守同一套資料保護規則。Debug log 也會進入檔案、集中式 log 或診斷封包，因此不能把它當成敏感資料的例外通道。

【測試】log 欄位可以用 handler 驗證

Log schema 的測試核心是確認重要欄位存在，避免未來重構時消失。

 1func TestLogAttrsForEvent(t *testing.T) {
 2    event := DomainEvent{
 3        ID:        "evt_1",
 4        Type:      "notification.created",
 5        SubjectID: "notification_1",
 6    }
 7
 8    attrs := LogAttrsForEvent(event)
 9
10    if !hasAttr(attrs, "event_id", "evt_1") {
11        t.Fatalf("event_id attr missing")
12    }
13    if !hasAttr(attrs, "event_type", "notification.created") {
14        t.Fatalf("event_type attr missing")
15    }
16}

不需要測整行 log 字串。測穩定欄位即可，message 文字可以保留一定調整空間。

本章不處理

本章先處理 Go 服務內部的 structured log schema；集中式平台、欄位標準與隱私治理，會在下列章節再往外延伸：

Go 進階：Observability pipeline、metrics 與 tracing

和 Go 教材的關係

這一章承接的是 structured recording、event log 與 observability pipeline；如果你要先回看語言教材，可以讀：

小結

結構化日誌的價值在於穩定欄位：layer 定位層級，request_id 串起請求，event_id 串起事件，event_type 支援聚合，reason 支援失敗分類。Message 給人讀，欄位給系統查。好的 log schema 能讓除錯從猜測變成查詢，同時避免敏感資料外洩與錯誤重複記錄。

6.4 版本偵測與 feature gate

Wed, 22 Apr 2026 00:00:00 +0000

Feature gate 的核心目標是在外部能力、部署環境或版本不同時，讓服務保留可預期行為。它明確管理功能何時啟用、關閉時如何降級、錯誤時如何回報。

本章目標

學完本章後，你將能夠：

用 config struct 集中載入 feature gate
把外部版本偵測轉成 capability
為 gate 關閉時定義降級、回錯或延後處理策略
避免在程式各處直接讀環境變數
同時測試 feature 開與關兩條路徑

【觀察】新功能上線需要可控行為

Feature gate 的核心需求來自生產環境差異。新功能可能只在部分部署環境可用，外部依賴可能版本不同，某些診斷入口只應在內網啟用，某些即時能力需要先灰度。

沒有 gate 時常見問題：

新功能只能一次性全開或全關。
部署環境不支援時服務直接失敗。
測試只能覆蓋預設路徑。
問題發生時無法快速降級。
程式各處用環境變數判斷，行為難以推理。

Feature gate 的目的是讓行為決策集中、可測、可回滾。

【判讀】feature gate 是行為合約

Feature gate 的核心語意是控制某段行為是否啟用，以及未啟用時系統要做什麼。它不只是 if，而是一個操作合約。

1type Features struct {
2    RealtimePush bool
3    Diagnostics  bool
4    Pprof        bool
5}

開關名稱應描述功能，而不是描述臨時任務。RealtimePush 比 NewCode 更能長期維護；Diagnostics 比 DebugStuff 更清楚。

Gate 應在應用啟動時集中載入，再傳給需要的元件。不要在程式各處反覆直接讀環境變數，否則測試與推理都會變困難。

【執行】集中載入 feature config

Feature config 的核心責任是把環境變數、設定檔或啟動參數轉成明確資料。

1func LoadFeaturesFromEnv() Features {
2    return Features{
3        RealtimePush: os.Getenv("FEATURE_REALTIME_PUSH") == "1",
4        Diagnostics:  os.Getenv("APP_DIAGNOSTICS") == "1",
5        Pprof:        os.Getenv("APP_PPROF") == "1",
6    }
7}

組裝時傳入元件：

 1func main() {
 2    features := LoadFeaturesFromEnv()
 3
 4    mux := http.NewServeMux()
 5    RegisterDiagnostics(mux, features.Diagnostics)
 6
 7    publisher := NewPublisher(PublisherConfig{
 8        RealtimeEnabled: features.RealtimePush,
 9    })
10
11    _ = publisher
12}

這樣功能測試可以直接建構 Features，不必依賴全域環境變數。環境變數解析只需要在 LoadFeaturesFromEnv 的測試中覆蓋。

【判讀】版本偵測要轉成能力

版本偵測的核心原則是不要讓整個程式到處比較版本字串。應把外部版本轉成 capability，內部只判斷能力。

 1type Capabilities struct {
 2    SupportsStreaming bool
 3    SupportsMetadata  bool
 4}
 5
 6func DetectCapabilities(version semver.Version) Capabilities {
 7    return Capabilities{
 8        SupportsStreaming: version.GTE(semver.MustParse("2.0.0")),
 9        SupportsMetadata:  version.GTE(semver.MustParse("2.1.0")),
10    }
11}

內部程式應寫成：

1if caps.SupportsStreaming {
2    return useStreaming(ctx)
3}
4
5return usePolling(ctx)

這比到處寫 if version >= ... 更清楚，也更容易測試。版本字串是外部事實，capability 是內部行為判斷。

【策略】gate 關閉時要有降級策略

Feature gate 的核心問題是關閉時要做什麼。常見策略包括降級、回錯、隱藏入口、排程稍後處理。

策略	行為	適用情境
fallback	使用舊流程	新能力只是效率改善
reject	回明確錯誤	功能沒有安全替代方案
hide	不註冊 endpoint 或不顯示入口	使用者不應看到該功能
store for later	先保存，稍後處理	即時能力暫不可用但資料不能丟

例如即時推送關閉時，可以改成保存待處理資料：

1func (p Publisher) Publish(ctx context.Context, event DomainEvent) error {
2    if p.realtimeEnabled {
3        return p.realtime.Publish(ctx, event)
4    }
5
6    return p.repository.SaveForLater(ctx, event)
7}

降級策略要符合資料語意。不能即時送出不代表可以直接丟掉重要事件。

【執行】HTTP endpoint 可用 gate 控制註冊或行為

HTTP feature gate 的核心選擇是「不註冊 endpoint」或「註冊但回明確錯誤」。兩者語意不同。

不註冊 endpoint：

1if features.Diagnostics {
2    RegisterDiagnostics(mux, true)
3}

適合診斷入口、內部工具或不希望使用者看見的功能。

註冊但回錯：

 1func HandleRealtimeExport(features Features) http.HandlerFunc {
 2    return func(w http.ResponseWriter, r *http.Request) {
 3        if !features.RealtimePush {
 4            http.Error(w, "realtime export is disabled", http.StatusNotImplemented)
 5            return
 6        }
 7
 8        startRealtimeExport(w, r)
 9    }
10}

適合公開 API，讓呼叫端知道功能存在但目前不可用。

【策略】gate 不應散落成巢狀 if

Feature gate 的核心維護風險是判斷散落在多層呼叫中，最後沒人知道功能到底何時啟用。

反模式：

1if os.Getenv("FEATURE_REALTIME_PUSH") == "1" {
2    if version >= "2.0.0" {
3        if user.Enabled {
4            // ...
5        }
6    }
7}

較清楚的做法是先組出 decision：

 1type RealtimeDecision struct {
 2    Enabled bool
 3    Reason  string
 4}
 5
 6func DecideRealtime(features Features, caps Capabilities) RealtimeDecision {
 7    if !features.RealtimePush {
 8        return RealtimeDecision{Enabled: false, Reason: "feature_disabled"}
 9    }
10    if !caps.SupportsStreaming {
11        return RealtimeDecision{Enabled: false, Reason: "streaming_not_supported"}
12    }
13    return RealtimeDecision{Enabled: true}
14}

Decision 物件讓 log、測試與錯誤回應都能使用相同 reason。

【執行】log 要記錄 gate decision

Feature gate 的核心操作需求是知道功能為何啟用或關閉。當 gate 影響行為時，應記錄穩定 reason。

1decision := DecideRealtime(features, caps)
2logger.Info("realtime decision",
3    "feature", "realtime_push",
4    "enabled", decision.Enabled,
5    "reason", decision.Reason,
6)

這能回答「功能為什麼沒有走即時推送」這類問題。Reason 應是小集合，不要塞完整錯誤字串。

【測試】開與關兩條路徑都要測

Feature gate 測試的核心規則是同時測啟用與停用路徑。只測預設值很容易讓另一條路徑壞掉。

停用路徑：

 1func TestHandleRealtimeExportFeatureDisabled(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodPost, "/export", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handler := HandleRealtimeExport(Features{RealtimePush: false})
 6    handler.ServeHTTP(rec, req)
 7
 8    if rec.Code != http.StatusNotImplemented {
 9        t.Fatalf("status = %d, want %d", rec.Code, http.StatusNotImplemented)
10    }
11}

啟用路徑：

 1func TestDecideRealtimeEnabled(t *testing.T) {
 2    decision := DecideRealtime(
 3        Features{RealtimePush: true},
 4        Capabilities{SupportsStreaming: true},
 5    )
 6
 7    if !decision.Enabled {
 8        t.Fatalf("realtime should be enabled, reason %q", decision.Reason)
 9    }
10}

環境變數解析應單獨測 LoadFeaturesFromEnv。功能測試應直接傳入 Features，不要依賴全域環境狀態。

本章不處理

本章先處理服務內部的 gate 行為邊界；遠端 feature flag 平台與灰度流程，會在下列章節再往外延伸：

Backend：部署平台與網路入口

和 Go 教材的關係

這一章承接的是 composition root、handler boundary 與 runtime gate；如果你要先回看語言教材，可以讀：

小結

Feature gate 是生產操作工具，也是程式設計邊界。好的 gate 會集中載入、轉成 capability、定義降級策略、輸出穩定 reason，並同時測試開與關兩條路徑。它控制的是行為合約，不只是把新程式碼藏在 if 後面。