服務路徑與狀態責任

這條服務路徑是 checkout-api -> order-db -> payment-callback -> reconciliation-job。Checkout 建立訂單時先寫入訂單主檔與付款待確認狀態；payment callback 會更新付款結果；客服後台與對帳 job 會讀取同一筆訂單狀態來判斷是否需要補償、退款或人工處理。

本篇示範的變更是把原本單一 status 欄位中的付款語意拆到 payment_state。這個欄位屬於正式狀態，會影響使用者看到的訂單結果、付款回呼的冪等更新、客服查詢與對帳流程，因此 rollout 的核心是讓新舊狀態語意在過渡期同時成立；DDL 只是其中一個執行動作。

這條路徑的前置概念來自 1.2 schema design 與資料建模、1.3 transaction 與一致性邊界 與 1.6 資料庫轉換實作。1.2 定義欄位責任，1.3 定義哪些更新要在同一個交易邊界內成立，1.6 定義 expand、backfill、cutover 與 contract 的執行節奏。

Rollout 階段

Migration rollout 的責任是把一次高風險資料變更切成多個可驗證階段。每個階段都要有輸入條件、完成訊號與停止條件，讓團隊能在資料漂移擴大前停下來。

這張表的重點是責任轉移。Expand 保護相容性，backfill 保護歷史資料，cutover 保護線上讀取，contract 保護長期維護成本；四者對應不同 evidence，也需要不同 release gate 判讀。

實作基準：先寫出狀態契約

狀態契約的責任是讓 migration 先有可驗證的語意邊界。這篇的範例把 orders.status 裡混合的訂單生命週期與付款語意拆開：訂單仍用 status 表示 created、fulfilled、cancelled 這類流程狀態，付款結果則交給 payment_state 表示 pending、authorized、captured、failed 與 refunded。

這張 mapping table 是 validation query、backfill job 與 incident decision log 的共同語意來源。Mapping table 留在工程師腦中時，後續 mismatch 會變成「資料看起來怪」；mapping table 進入 artifact 後，gate 就能判斷錯誤集中在哪個付款語意，而不是停在總筆數。

Expand：先建立相容窗口

Expand phase 的核心責任是讓新資料結構先進入 production，同時保留舊程式的可運作性。以 payment_state 為例，常見起點是新增 nullable 欄位、補上必要索引，並讓寫入路徑可以在新欄位缺值時仍使用舊 status 判讀付款狀態。

1ALTER TABLE orders
2  ADD COLUMN payment_state text NULL;
3
4CREATE INDEX CONCURRENTLY idx_orders_payment_state
5  ON orders (payment_state)
6  WHERE payment_state IS NOT NULL;

這段 SQL 的用途是示範 artifact 形狀。Nullable 欄位保留舊資料的相容窗口；partial index 讓新讀取路徑能先被驗證，同時避免把尚未 backfill 的歷史資料全部推進新查詢模型。不同資料庫會有不同線上 DDL 能力，release gate 要把 lock 行為、index build 進度與 replication lag 納入 checks。

應用程式在 expand 階段要支援 read compatibility。相容性較高的寫法是讀取時優先使用 payment_state，缺值時 fallback 到舊 status 的付款語意；寫入時則依交易邊界同步更新舊欄位與新欄位，直到 cutover 前都保留一致性檢查。

 1readPaymentState(order):
 2  if order.payment_state is not null:
 3    return order.payment_state
 4  return mapLegacyStatusToPaymentState(order.status)
 5
 6applyPaymentCallback(order, callback):
 7  nextPaymentState = mapCallbackToPaymentState(callback)
 8  update orders
 9    set status = mapPaymentStateToLegacyStatus(nextPaymentState),
10        payment_state = nextPaymentState
11    where id = order.id

這段相容讀寫的重點是「同一個 callback 只產生一個付款判讀」。舊欄位與新欄位可以同時存在，但它們要由同一份 mapping function 產生，否則 payment callback、客服修復與 reconciliation job 會各自形成一套隱性規則。

這裡要特別看 dual write 的風險。雙寫只表示兩個欄位都有被寫入，仍要用 validation query 驗證兩者語意是否一致。若付款回呼、手動退款與對帳修復走不同程式路徑，雙寫函式也要被這些路徑共同使用。

Dual-write divergence schema

Dual-write 的責任不只是「兩邊都寫」、是「兩邊寫的結果一致」。要證明這件事、需要明確的 divergence schema、否則事故當下無法區分 mapping bug 跟 race condition。

最小 divergence 紀錄欄位：

expected_new 跟 new_value 對不上、表示 mapping function 在某些 path 沒被使用、是 mapping bug。legacy_value 跟 new_value 對不上、且 expected_new == legacy_value 對得上、是 dual-write 本身少寫一筆、可能是 race condition 或部分失敗。兩種情況的修法完全不同、不分類會在事故當下亂修。

Dual-write 失敗回退策略：寫舊欄位成功、寫新欄位失敗時、不能直接 retry 新欄位（會跟主寫入競爭）。實務做法是把 divergence 寫進 outbox / repair queue、由 backfill 同類流程補。對應 9.C16 SeatGeek 的 outbox-style 設計。

線上 DDL 的 vendor 差異

Expand 階段加欄位 / 加索引、不同資料庫的 阻塞行為 差異極大、選錯時機會直接讓 production 鎖表。

• PostgreSQL：ALTER TABLE ADD COLUMN ... NULL 是 metadata-only、不重寫 table。ADD COLUMN ... NOT NULL DEFAULT ... 在 PG 11+ 才是 metadata-only。CREATE INDEX CONCURRENTLY 不阻塞寫入、但更慢、且 transaction 中不能用。ALTER TABLE ALTER COLUMN TYPE 通常會重寫整張表、要先評估規模。
• MySQL / Aurora MySQL：ALTER TABLE ... ALGORITHM=INSTANT 是 8.0+ 的 metadata-only、5.7 則靠 ALGORITHM=INPLACE / LOCK=NONE。Aurora MySQL 還有 fast DDL（部分變更秒級完成、不重寫）。判讀重點是 explicitly 指定 ALGORITHM、不要讓 MySQL 自己選（可能掉回 COPY 算法、整張表複製）。
• Spanner：schema change 預設非阻塞、後端 async 補欄位。新欄位 read 在 schema change 完成前可能讀不到、應用層要容忍。
• DynamoDB：表本身沒 schema、但 GSI（Global Secondary Index）創建是 async、可能跑數小時、且新 GSI 在 backfill 完成前查不到完整資料。判讀重點：cutover 不能假設新 GSI 立即可用、要等 IndexStatus = ACTIVE。
• Cosmos DB：document 級別無 schema、新 indexed path 加進 indexing policy 後、後端 re-index 整個 partition、期間 RU consumption 飆升。

各 vendor 的線上 DDL evidence 都要包含：操作開始時間、預估完成時間、是否阻塞讀寫、實際 lock duration。expand gate 通過條件不能只看 DDL 跑完、要看 所有副效應收斂（index status active、re-indexing 完成、replica 同步）。

對應 vendor pages：PostgreSQL、MySQL、Aurora、Spanner、DynamoDB、Cosmos DB 的線上 DDL 段。

Backfill：把歷史資料變成可驗證進度

Backfill phase 的核心責任是把歷史資料補齊成可追蹤、可暫停、可重試的進度。訂單表通常會同時承擔交易查詢、客服查詢與對帳查詢；backfill 若只追求速度，容易和線上流量競爭 I/O、放大 replication lag 或改變查詢計畫。

Backfill job 應以 checkpoint 管理進度。每批選取固定範圍的訂單，轉換 status 到 payment_state，寫入後立刻產生該批 validation query 結果。批次大小要能依延遲、鎖等待、replication lag 與線上錯誤率調整。

1checkpoint:
2  migration_id: orders-payment-state-2026-05
3  last_order_id: 18420000
4  batch_size: 5000
5  started_at: 2026-05-11T02:10:00Z
6  completed_at: 2026-05-11T02:12:40Z
7  rows_scanned: 5000
8  rows_updated: 4921
9  mismatch_count: 3

Checkpoint 的角色是把 backfill 變成可恢復流程。last_order_id 告訴下一批從哪裡繼續，rows_updated 與 mismatch_count 告訴 gate 這批是否可以被納入放行證據，時間欄位則讓 replication lag、slow query 與錯誤率能回到同一個觀察窗口。

Validation query 的責任是證明語意一致。最小集合包含總筆數、已補筆數、缺值筆數、新舊語意不一致樣本、每批耗時、慢查詢與 replication lag。這些查詢要保留 query link 與 time range，後續才能進入 4.20 Observability Evidence Package。

1SELECT
2  count(*) AS total_rows,
3  count(*) FILTER (WHERE payment_state IS NULL) AS missing_payment_state,
4  count(*) FILTER (
5    WHERE payment_state IS NOT NULL
6      AND payment_state <> map_legacy_status_to_payment_state(status)
7  ) AS mismatch_rows
8FROM orders
9WHERE id BETWEEN 18415001 AND 18420000;

Validation query 要和 mapping table 共用同一個語意。資料庫端缺少同一份 mapping function 時，查詢至少要把 mapping 規則展開成明確 CASE expression，並把 query version 保存在 evidence package；這樣事後才能知道 mismatch 是資料錯誤、mapping 規則改變，還是查詢本身落後。

Cutover：先切讀取，再收斂寫入

Cutover phase 的核心責任是把服務判讀權交給新欄位，同時保留可回退窗口。對訂單付款狀態來說，切換順序通常先從低風險讀取路徑開始，例如客服後台與內部對帳，再進入 checkout 查詢與使用者可見狀態；每一批切換都要有自己的 cutover window。

讀取 cutover 的 stop condition 要比寫入 cutover 更早觸發。新欄位讀取後出現 mismatch、客服查詢結果漂移、對帳 job 補償量異常時，先回到 fallback read，讓錯誤限制在判讀層，再重新驗證寫入收斂條件。

寫入 cutover 要確認所有更新來源都已對齊。付款回呼、手動修復、退款、訂單取消與 reconciliation job 都可能更新付款狀態；只切主 checkout 寫入路徑會留下長尾漂移。完成 cutover 前，要用 audit query 確認仍在寫舊欄位的程式路徑已經歸零或被納入例外清單。

Shadow read pattern：cutover 前的讀取驗證

Shadow read 的責任是讓新讀取路徑在 真實流量 下被驗證、但 不影響使用者結果。這跟 dual-write 是對偶機制：dual-write 證寫入收斂、shadow read 證讀取分歧。

實作模式：

1. 每一筆讀取請求、同時用 舊邏輯 跟 新邏輯 查一次。
2. 回給用戶的仍是舊邏輯結果（用戶體驗不變）。
3. 在背景把兩個結果差異寫進 divergence log。
4. 收集足夠樣本後、再決定切換 cutover。

 1readPaymentStateWithShadow(order):
 2  legacy = mapLegacyStatusToPaymentState(order.status)
 3  new_result = order.payment_state ?? legacy
 4  if legacy != new_result:
 5    asyncLogDivergence({
 6      order_id: order.id,
 7      legacy: legacy,
 8      new: new_result,
 9      sample_at: now(),
10      caller: requestContext.caller,
11    })
12  return legacy  // 用戶仍拿舊邏輯結果

Shadow read 的判讀重點：

• 抽樣率：1% / 10% / 100% — 高流量場景全量 shadow 會雙倍 DB 讀取、要先評估容量。Cosmos DB / DynamoDB 的 RU 成本要乘 2。
• 分歧分類：跟 dual-write 一樣、divergence 要分類（mapping bug / race condition / stale read）、不分類無法定位修法。
• 覆蓋條件：要驗證所有 caller path（checkout / support / reconciliation / external API）都跑過 shadow、否則 cutover 後可能踩到沒測試過的 path。
• 退場條件：shadow read 不該長期跑、會增加負載。設明確 sunset deadline、cutover 完成後一週內移除。

對應 9.C20 Zomato TiDB → DynamoDB migration — migration 期間用 shadow read 持續驗證 mapping 規則、抓到 mapping drift。

Dual-write 跟 shadow read 的選擇不是互斥、是依風險組合：

Multi-region 與跨服務協調

Migration 跨越 region 或多個 service 時、rollout 順序錯誤是最常見的失敗模式。Service A 切到新欄位、service B 還在讀舊欄位、結果整條業務流量看到不一致。

Multi-region rollout 順序

跨 region 的 schema migration 要從 最後寫入點 開始 expand、從 最後讀取點 開始 cutover。先 expand 寫端、再 expand 讀端；先 cutover 讀端、再 cutover 寫端。順序反了會在過渡期讀到沒被寫的新欄位、或寫了沒被讀的新欄位。

實務步驟：

1. Schema expand：所有 region 同步加新欄位（先寫端再讀端、不能跳）。確認跨 region replication lag 在新欄位上收斂、再進下一步。
2. Backfill：可以平行跑、但每 region 各自 checkpoint、不共用。某 region backfill stuck 不應該卡住其他 region。
3. Cutover read：region by region 切讀、用 canary region 先試 24-48 小時、再擴散。
4. Cutover write：所有 region 都切完讀、再統一切寫。寫端切換比讀端更敏感、跨 region 寫差異會放大成跨 region inconsistency。

對應 1.11 全球分散式 OLTP 的跨 region consistency 段。

Cross-service migration 協調

當 schema 變更影響多個 service 時、API contract 是 鬆耦合 介面、不該讓所有 service 同步切換。

協調機制：

• 新欄位先在 API 是 optional：API contract 加新欄位、預設 nullable / optional。下游 service 可選擇何時讀。
• 舊欄位保留至少一個版本週期：API 不能跟 DB schema 同步 contract、否則下游沒時間切。實務上保留 1-2 季、給下游充足 cutover 窗口。
• owner-by-owner cutover roster：明確列出每個下游 service 的 owner、預計 cutover 時間、目前狀態。常用工具是共享 dashboard、不是散落的 ticket。
• Contract test：每個下游 service 對新欄位都要有 contract test、在 CI gate 跑過。避免上游 cutover 後下游才發現沒讀對。

對應案例：9.C20 Zomato TiDB → DynamoDB — 跨多個 service 的 access pattern 變更、必須每個 service 各自驗證、不能假設「DB 切了就好」。

Evidence Package

資料庫 migration 的 evidence package 負責證明資料演進是否可判讀。這份 package 要把 validation query、時間窗、資料限制與 owner 包成後續放行與事故判斷可引用的證據，dashboard 只作為摘要入口。

Source 欄位要保留資料來源的能力邊界。Validation query 能證明欄位語意一致，DB metric 能看出 latency 與 lag，job log 能追進度，audit log 能判斷是否有高權限修復行為。把這些來源混在一起會讓下游誤判證據的用途。

Data quality 欄位要直接寫出限制。若查詢只跑 primary、replica lag 還在回復、某些 tenant 因資料遮罩未被抽樣，這些限制要跟 evidence 一起交給 release gate，讓 gate 能以證據完整度決定是否放行。

 1evidence_package:
 2  name: orders-payment-state-cutover-batch-37
 3  source:
 4    - validation_query: q_orders_payment_state_batch_37
 5    - db_metric: replication_lag_orders_primary
 6    - job_log: backfill_orders_payment_state_2026_05
 7  time_range: 2026-05-11T02:10:00Z/2026-05-11T02:20:00Z
 8  owner:
 9    database: data-platform-oncall
10    service: checkout-oncall
11    reconciliation: finance-ops-owner
12  data_quality:
13    replica_freshness: "primary only; replica lag still recovering"
14    sample_completeness: "tenant tier enterprise covered; sandbox tenants excluded"
15  confidence: suspected
16  known_gap:
17    - "manual refund repair path not yet sampled"

這份 package 故意把 confidence 標成 suspected。原因是 evidence 已能支持 backfill 繼續前進，但還不足以支持使用者可見讀取 cutover；這種中間狀態要被明確寫出，gate 才能做分階段決策。

Release Gate

Schema migration 的 release gate 負責判斷下一階段是否可以放行。它接收 evidence package，但決策語言要回到 6.8 Release Gate 與變更節奏：Gate decision、Checks、Stop condition、Rollback window、Owner。

Gate decision 要用服務語言書寫。migration pass 這種結論對下游不夠具體；放行 10% 訂單 backfill、暫停使用者可見讀取 cutover、維持 fallback read 24 小時 才能讓執行團隊知道下一步。

Rollback window 是資料庫 migration 的關鍵欄位。Expand 與 backfill 階段通常能回到舊讀取；cutover 後仍可 fallback；contract 後舊語意被移除，回退會變成資料修復或 fail-forward。gate 要在每階段說清楚目前還剩哪種退路。

 1release_gate:
 2  gate_decision: "allow next 10% backfill; block customer-visible read cutover"
 3  checks:
 4    mismatch_rate: "0.04%, below 0.1% batch threshold"
 5    replication_lag: "p95 12s, below 30s stop condition"
 6    slow_query: "no new support-admin slow query above 500ms"
 7  stop_condition:
 8    - "mismatch_rate >= 0.1% for two consecutive batches"
 9    - "replication_lag >= 30s for 10 minutes"
10    - "support-admin query drift confirmed by reconciliation owner"
11  rollback_window: "fallback read available until contract phase starts"
12  owner: checkout-oncall

這份 gate record 把「繼續 backfill」和「暫緩讀取 cutover」拆成兩個決策。資料庫 migration 常見的判讀問題是 evidence 只支撐下一批資料修補，還支撐不了使用者可見行為切換。

Incident Decision Log

Migration 進入 production 後，pause、rollback 與 fail-forward 都是事故決策。這些決策要同步寫入 8.19 Incident Decision Log，讓事中交班與事後復盤能回放當時的證據與限制。

常見決策包括暫停 backfill、降低 batch size、回到舊讀取、停止 contract、手動修補 mismatch、選擇 fail-forward。每筆都要保留 Timestamp、Decision、Context、Evidence、Owner、Expected effect 與 rollback condition。

例如 cutover 後發現客服查詢 mismatch 升高，decision log 可以寫成：

 1incident_decision:
 2  timestamp: 2026-05-11T03:05:00Z
 3  decision: "rollback support-admin read path to legacy status fallback"
 4  context: "support-admin mismatch increased after internal read cutover"
 5  evidence:
 6    - query: q_orders_payment_state_support_mismatch
 7    - window: 2026-05-11T02:35:00Z/2026-05-11T03:05:00Z
 8    - interpretation: "suspected callback mapping drift"
 9  owner: checkout-incident-commander
10  expected_effect: "support ticket misclassification returns to baseline"
11  rollback_condition: "mismatch remains above threshold after 15 minutes"

這種記錄能避免事後只剩「當時有回退」的模糊敘事。後續 8.23 Control Plane Decision Log and Write-back 實作示範 可承接同一組決策紀錄，把缺少 validation、owner 或 runbook 的地方回寫成改善項。

判讀訊號

判讀訊號的責任是讓讀者知道何時該繼續、何時該停、何時該改路線。Migration 訊號要同時看資料正確性、線上健康度與回退窗口。

這些訊號要放回服務路徑判讀。Mismatch 要看集中在哪個業務入口；若 mismatch 只出現在延遲付款 callback，它代表外部 provider 回呼語意未對齊。Replication lag 要看是否和 backfill 批次對位；若它只在 backfill 批次出現，gate 應調整 migration 節奏，再判斷 schema 設計是否需要修正。

Dual-write 跟 shadow read 的 divergence 要分開看 — 兩者偵測不同層的問題。Dual-write divergence 偏向 mapping bug 或 race condition；shadow read divergence 偏向讀取邏輯漂移或 stale read。混在同一個 dashboard 會讓 reviewer 看不出問題真正在哪一層。

常見誤區

把 schema migration 寫成 DDL 任務，會讓風險集中在切換當下。穩定做法是先建立相容窗口，再用 evidence 證明資料語意已經跟上，最後才收斂舊路徑。

把 validation query 當成事後對帳，也會削弱 rollout 控制。Validation query 適合在 expand、backfill、cutover 每一階段都產生證據，讓 release gate 能在風險擴大前停下來。

把 rollback 寫成單一動作容易誤導團隊。資料庫 migration 的 rollback 會隨階段改變：expand 可回退 schema 使用，backfill 可暫停與重跑，cutover 可回到 fallback read，contract 後多半只能做資料修復或 fail-forward。

把 dual-write 跟 shadow read 當成同一個工具。兩者偵測不同層、結合使用可以互補、互相替代會留下盲點。Dual-write 不跑 shadow read、cutover 後可能踩到沒驗過的讀取 path；shadow read 不跑 dual-write、新欄位可能在某些寫路徑根本沒被寫進去。

把線上 DDL 當「一個 SQL 跑完就好」。各 vendor 的 DDL 語意差異大、PostgreSQL 的 ADD COLUMN NOT NULL DEFAULT 在 PG 10 重寫整張表、PG 11+ 是 metadata-only；MySQL 不指定 ALGORITHM=INSTANT 可能掉回 COPY。Expand evidence 要包含 實際 lock duration、不是只看 DDL 是否回傳成功。

只在主寫入路徑切 cutover、忘記補償流程跟 reconciliation job 也會寫舊欄位。這些長尾寫入會在 contract 階段才暴露、那時候已經沒有 fallback 可走。Cutover 前要 audit 所有寫舊欄位的程式路徑、不只看主流程。

案例回寫

0.C4 營運後技術轉換 可以回寫這篇的決策層。當服務營運後需要拆欄位、拆庫、分片或升級儲存引擎，先用 0.C4 判斷「為什麼要換」，再用本篇判斷「進入 production 後如何證明每一步成立」。

GitHub 2018 Oct21 MySQL Topology Incident 可以回寫這篇的事故層。該事件顯示資料一致性優先時，團隊需要可回放的 fail-forward / fail-back 判準；本篇則把這個需求落到 migration rollout 的 evidence、gate 與 decision log。

這兩個案例共同支撐的是「資料狀態演進需要證據閉環」。0.C4 提供轉換動機與選型壓力，GitHub 事故提供資料一致性與恢復決策的代價；兩者都不直接替代 validation query、release gate 與 decision log 的實作細節。

跨模組路由

1. 與 1.2 的交接：欄位責任、命名與查詢模型回到 schema design。
2. 與 1.3 的交接：付款回呼、手動修復與對帳更新的交易邊界回到 transaction boundary。
3. 與 1.6 的交接：expand、backfill、cutover 與 contract 的執行流程回到 資料庫轉換實作。
4. 與 4.20 / 4.22 的交接：validation query、row count、lag 與 slow query 進入 Observability Evidence Package 與 Checkout API Evidence Package。
5. 與 6.11 / 6.8 / 6.25 的交接：migration 可逆性與放行條件進入 Migration Safety、Release Gate 與 Provider Dependency Release Gate。
6. 與 8.19 / 8.23 的交接：pause、rollback、fail-forward 與 write-back 進入 Incident Decision Log 與 Control Plane Decision Log and Write-back。

下一步路由

要把資料庫 migration 的 evidence 交給 release gate，接著讀 6.25 Provider Dependency Release Gate 實作示範，並把 provider 依賴示範中的 gate 欄位改寫成 migration gate 欄位。要看下一條分類服務路徑，接著進 02 Cache / Redis 模組 的 Cache migration and stampede rollback 服務路徑。

跨 vendor schema migration 深入：

• Spanner interleaved table 的 schema migration — 全球分散式表結構變更的 evidence shape
• Aurora 從自管 PostgreSQL / MySQL 遷入 — schema 比對與 dual-write 證據鏈
• Cosmos DB MongoDB API vs SQL API — multi-API document 在 rollout 階段的相容性 evidence

服務路徑與失敗代價

這條路徑是 product-page -> cache -> product-db/pricing-service。商品頁會同時讀取描述、價格、庫存與促銷標籤，快取需要在低延遲與正確性間平衡。

這篇示範的變更是把舊 key product:{id} 演進到版本化 key product:v2:{region}:{id}。演進動機是支援區域價格與促銷欄位拆分，避免舊序列化格式在多區域路徑下持續膨脹。

失敗代價分三層：描述欄位 stale 主要影響體驗，價格 stale 直接影響交易正確性，回源尖峰會擠壓正式狀態查詢容量。這三層要分別設 freshness、gate 與 rollback 條件。

Key Schema 與相容窗口

Key schema 的責任是讓新舊值可共存，不讓切換變成一次性替換。這條路徑採 dual-read 再 dual-write 再 single-read-v2：

1. 讀取先查 v2，miss 再查舊 key，最後才回源。
2. 回填期間新舊 key 同時寫入，保留可回退窗口。
3. v2 命中穩定後，關閉舊 key 寫入，保留舊 key 讀 fallback 一段時間。

相容窗口的重點是讀語意一致。舊 key 與新 key 的值結構不同時，要先有轉換層，避免同一商品在不同 API path 回傳不同語意。

Freshness Window 與資料分級

Freshness window 的責任是把 stale 代價寫成可執行規則，而不是只寫全域 TTL。

TTL 與事件失效要同時存在。TTL 控上限，事件失效控即時性；只用其一都會造成隱性風險。

Warmup 與回源保護

Warmup 的責任是先建立新 key 的可服務覆蓋率，再擴大流量。這條路徑採分批 warmup：region -> category -> hot key list -> 全量。

Warmup completion 的判讀訊號：

1. v2 命中率在目標區間連續穩定。
2. origin QPS 未突破上限。
3. 熱門 key 的 miss 尖峰已被抹平。

回源保護策略：

1. 以 singleflight 合併同 key 同時 miss。
2. 對回源查詢設 rate limit 與超時。
3. 回源失敗時寫入短 TTL 降級值，避免瞬時重試風暴。
4. 針對熱門 key 在切換前做預熱與分散過期。

Cache 切換引發 stampede 的真實事故結構

對應 2.C9 反例：Cache Stampede Rollout Regression — 看似低風險的 cache key 或 TTL 切換、若回源保護不足、會讓熱門資料同時 miss。事故結構屬「讀取路徑同時失去緩衝」的系統性失敗、不只是單一 key 問題。

切換引發 stampede 的三個放大機制會 疊加、不是獨立失效。在 read-heavy 規模化服務（如 Tinder 47M MAU、Tubi feature store）這類場景、典型疊加順序：重試放大先觸發 → 下游放大跟進 → 應用層放大終結：

• 重試放大：用戶請求 miss、應用層或 client SDK 內建重試、每次重試又 miss、單一用戶請求變多次 origin QPS
• 下游放大：cache miss 同時打到 DB、DB 變慢、應用對 cache 設的 timeout 又觸發新 miss、回到 DB 更慢、形成正向循環
• 應用層放大：等待 cache 的 request 堆積、application thread / connection pool 滿、新請求被拒、被拒的請求觸發更多重試

判讀重點：stampede 的早期訊號通常出現在下游 origin（DB QPS 突然超 baseline 數倍）跟 application（latency p99 拉高、request queue length 增加）、不一定先在 cache 層看到。cache hit rate 顯示異常時、事故通常已在中後段。

切換順序決定 stampede 風險

對應 2.C10 對照：規模差異下的快取策略 — 切換順序（先改 key 結構 vs 先改 TTL）會決定是否出現 stampede 連鎖反應、特別在中型服務同時承受活動流量跟版本切換時。

安全切換順序（dual-read 模式、每步停損點不同）：

1. 新 key 寫入啟用：應用層同時寫舊 key + 新 key、讀路徑不變。停損點是「寫入失敗率」、若雙寫失敗率超基線、回退停止啟用。
2. 新 key 命中觀察：讀路徑加入 v2 first / fallback to v1 邏輯、v2 命中率隨自然回填爬升。停損點是「v2 hit rate 爬升曲線」、若曲線停滯、表示 warmup 沒擴散到熱資料、要先 manual warmup。
3. 舊 key 命中率穩定下降：表示新 key 自然 warmup 完成、可進入下一階段。停損點是「舊 key hit rate 是否真的降到目標」、不能只看 v2 hit rate。
4. 舊 key 寫入停止：只寫 v2、舊 key 自然 TTL 過期。停損點是「v2 唯一寫入是否穩定」、若出現 v2 寫入失敗、回退到雙寫。
5. 舊 key 讀 fallback 移除：完全切到 v2 only。停損點是「v2 hit rate 是否已達切換前舊 key 水位」、否則 fallback 移除後直接回源。

應該注意的反模式（會引發 stampede）：

• 應先 warmup 新 key 再刪除舊 key、避免所有讀立即 miss
• 應拆維度切換（key OR TTL OR 序列化各自獨立）、避免多變化疊加讓 debug 困難
• 應先在低流量 region 試跑、再擴大到全量、避免事故時無回退時間

判讀順序：每次切換只動 一個維度（key OR TTL OR 序列化）、先在低流量 region / tenant 試跑、命中率穩定後再擴大。在 Shopify 序列化遷移（2.C3）類場景、停損 KPI 是「新格式編碼成功率」+「舊格式 fallback 觸發率」；在 Tinder 類 schema 變化頻繁場景、停損 KPI 是「v2 cache hit rate 是否在預估 warmup 時間內達標」。對應 9.C20 Zomato 跟 1.7 Schema Migration Rollout Evidence 的同類 expand-contract 思維。

Schema 變更引發的隱性 cache invalidation（路由：見 2.7）

Cache invalidation 模型 主寫於 2.7 cache copy boundary 的 Invalidation 段；本章從 migration 實作步驟 角度補充：schema migration 是 cache stampede 的隱藏觸發點。9.C6 Tinder 案例的警惕段提出 風險推測：「configurable matching」業務邏輯複雜、快取資料的 schema 變化頻繁、一個 schema 變更可能引發 cache invalidation 風險。

Schema 變化讓 cache 失效的三種模式（屬工程實踐推導、非案例直接揭露）：

• 欄位重命名 / 刪除：舊 cache value 反序列化失敗、application 視為 miss、全部回源
• type 變更（int → string、enum 增 case）：反序列化可能成功但語意錯、業務邏輯踩錯
• 序列化格式換（Marshal → MessagePack）：舊格式無法用新 decoder 讀、對應 2.C3 Shopify 的雙軌策略

Migration 實作步驟（按優先序）：

1. Schema migration 前盤點 cache key（最先）：哪些 cache 包含這個 schema 的資料、估算 invalid 範圍。沒這步無法估算 warmup 計畫規模。
2. 大規模 schema migration 配 cache warmup 計畫：預先 warmup、避免用戶觸發 cache miss。warmup 計畫主寫於本章的「Warmup 與回源保護」段。
3. 新欄位用 versioned key（同步進行）：product:v2:{id} 跟 product:v1:{id} 並存、避免雙寫干擾。對應 2.C3 Shopify 雙軌策略。
4. 降級 fallback（最後保險）：cache miss 後 origin 也準備好被打、避免假設「cache hit rate 永遠維持高水位」。對應本章「回源保護策略」段。

判讀重點：四步應同步落地、缺一個就會在 migration 期間踩 stampede。一致性 invalidation 模型回到 2.7。

Rollout / Cutover / Rollback

Rollout 的責任是把快取切換拆成可停損批次，不把風險一次放大。

Rollback 不是只「切回舊 key」。若新格式已經被下游依賴，回退時要同時保留新舊讀寫相容，避免第二次不一致。

Evidence Package

快取 migration evidence 的責任是證明「效能提升」沒有交換成「來源壓力失控」或「交易資料錯誤」。

這份 evidence 要對齊 4.20 Observability Evidence Package。

Release Gate

Release gate 的責任是決定是否放行下一批切換，而不是只報告觀測結果。

這組欄位要對齊 6.8 Release Gate 與 6.20 Experiment Safety Boundary。

Incident Decision Log

切換過程中的停用新 key、延長 TTL、凍結 invalidation、回退讀路徑都屬於事故決策。每筆決策都要留在 8.19 Incident Decision Log。

 1incident_decision:
 2  timestamp: 2026-05-11T11:42:00Z
 3  decision: "rollback to dual-read and freeze v2-only rollout"
 4  context: "origin QPS exceeded ceiling and stale price ratio increased in TW region"
 5  evidence:
 6    - query: cache_v2_origin_qps_region_tw
 7    - query: stale_price_ratio_by_region
 8  owner: cache-incident-commander
 9  expected_effect: "reduce origin pressure and restore price freshness baseline"
10  rollback_condition: "origin qps or stale ratio does not recover within 15 minutes"

Case Write-back 與邊界

這篇回寫重點對齊 2.C3 Shopify：Cache Serialization Migration 與 2.C9 反例：前者看格式演進與相容窗口，後者看回源尖峰與停損節奏。

這篇不處理分散式鎖正確性、queue replay 或資料庫正式狀態切換。若核心風險在互斥語意、事件重播或資料 schema，路由到 2.4 distributed lock、3.4 consumer 設計與去重 或 1.7 Schema Migration Rollout 證據。

服務路徑與邊界

本篇服務路徑是 client -> checkout-api -> payment-adapter -> order-db。觀測邊界只處理「這條路徑目前是否可判讀」，不處理重試策略與回退決策本身；後者交給 06 與 08。

要先定義 evidence package 的最小欄位：Source、Time range、Query link、Owner、Data quality、Confidence、Known gap。這些欄位在事故期與放行期共用，避免兩套語言。

實作步驟

1. 固定交易路徑的觀測主鍵：trace_id、order_id、tenant_id、region。
2. 建立三組查詢入口：延遲分布（p50/p95/p99）、錯誤率與錯誤類別、下游 payment dependency timeout。
3. 為每組查詢補欄位：時間窗、資料延遲、採樣比例、目前 owner。
4. 在 deploy 前把同一份 evidence package 連到 6.8 Release Gate。
5. 事故期間把同一份 evidence package 連到 8.19 Incident Decision Log。

判讀訊號

常見誤區

把 evidence package 寫成 dashboard 截圖集合，會失去可重跑性。沒有 query link 與時間窗，事故交班時很難重建判讀脈絡。

把 confidence 省略也會導致誤判。事故前期資料常不完整，若不標示 suspected 與 known gap，下游決策容易把猜測當成結論。

案例回寫

這條路徑可用 GCP 2019 Network Incident 回寫。先看跨服務訊號如何失真，再回到本章檢查欄位是否能支撐「先分流、再判斷」。

這個案例主要支撐的是「證據欄位完整度」判讀，不直接支撐 release gate 停損門檻設計；停損規則要回到 6.8。

跨模組路由

1. 與 4.17 的交接：資料限制與偏差回到 Telemetry Data Quality。
2. 與 6.8 的交接：放行判斷使用同一份 evidence package。
3. 與 6.23 的交接：驗證證據欄位對齊 Verification Evidence Handoff。
4. 與 8.19 的交接：事故決策直接引用 evidence link 與 confidence。

下一步路由

要把證據轉成放行條件，接著讀 6.25 Provider Dependency Release Gate 實作示範。

概念位置

Evidence package 位在 dashboard、SLI / SLO 與 post-incident review 之間。Dashboard 提供操作視角，SLO 提供判讀門檻，evidence package 保存支撐判斷的來源、時間窗、查詢入口與限制。

可觀察訊號與例子

系統需要 evidence package 的訊號是同一段事故證據在交班、release gate 或復盤時反覆被重新查證。常見例子是只保存截圖，下一班 on-call 看得到圖表形狀，卻缺少 query、time range、sampling ratio、ingest delay 與 owner，導致決策背景需要重新建立。

設計責任

Evidence package 要包含 source、time range、query link、owner、data quality、confidence、known gap 與 retention。它的責任是讓證據可查、可解釋、可重跑，並能交給 incident decision log、steady state 或 action item closure 使用。