本文是 RabbitMQ overview 的 implementation-layer deep article、對應 overview「Classic queue vs Quorum queue vs Stream」段。Overview 回答「RabbitMQ 該不該選、跟 Kafka / SQS 差在哪」、本文回答「選了 RabbitMQ 之後、同一個 broker 內三種 queue type 怎麼挑、各自的容量與故障形狀」。

同一個 broker、三套儲存引擎

RabbitMQ 的 queue 由三種 儲存引擎 構成、共用同一套 AMQP 協議與 management 介面。Queue type 決定訊息怎麼持久化、怎麼跨節點複製、消費後是否保留 — 這些差異在宣告 queue 的那一刻就鎖定、之後無法原地切換。選錯 queue type 的代價不是參數調整、是 重建 queue + 遷移 in-flight 訊息。

三種 type 各自承擔不同責任：

• Classic queue：單節點的 durable / transient queue、訊息消費即刪除、是 RabbitMQ 最原始的工作隊列模型。跨節點高可用曾靠 mirrored queue（鏡像複製）達成、但該機制在 3.x 已標記 deprecated、4.0 移除。
• Quorum queue：Raft 共識協議實作的 replicated queue、跨節點維持強一致的訊息狀態、設計目標是 取代 mirrored queue 提供可靠的工作隊列高可用。訊息仍是消費即刪除的隊列語意。
• Stream：3.9 引入的 append-only log、訊息寫入後 不因消費而刪除、多個 consumer 可從各自的 offset 重複讀取、retention 由時間 / 大小上限控制。語意接近 Kafka 的 partition log、但跑在 RabbitMQ 體系內、共用 AMQP 與專屬 stream protocol。

判讀起點是一個問題：訊息被消費後該不該保留。需要 replay、多 consumer 各自進度、長期事件流 → stream；訊息是一次性任務、處理完即丟、要跨節點不丟 → quorum；單節點夠用、可接受節點故障時該 queue 暫時不可用 → classic。

本文用 RabbitMQ 3.13.7（OrbStack 單節點）實機驗證宣告語意差異。生產的跨節點行為（Raft 選舉、replica lag）單節點環境無法重現、相關段落標注來源。

三種 queue type 的宣告語意差異（實機驗證）

Queue type 由宣告時的 x-queue-type argument 決定。三種 type 在同一 broker 宣告後、type 欄位區分清楚：

1rabbitmqadmin declare queue name=q-classic durable=true
2rabbitmqadmin declare queue name=q-quorum  durable=true arguments='{"x-queue-type":"quorum"}'
3rabbitmqadmin declare queue name=q-stream  durable=true arguments='{"x-queue-type":"stream"}'
4
5rabbitmqctl list_queues name type durable leader members

實機輸出（節錄、單節點所以 leader / members 都是同一節點）：

1name       type     durable  leader              members
2q-classic  classic  true
3q-quorum   quorum   true     rabbit@<node>       [rabbit@<node>]
4q-stream   stream   true     rabbit@<node>       [rabbit@<node>]

兩個關鍵差異在這裡浮現。

第一、quorum 與 stream 強制 durable。Classic queue 可宣告為 transient（durable=false、broker 重啟後消失、適合臨時 RPC reply queue）；quorum 與 stream 不允許 transient — 嘗試宣告會直接被拒：

1*** invalid property 'non-durable' for queue 'q-quorum-nondur' in vhost '/'
2*** invalid property 'non-durable' for queue 'q-stream-nondur' in vhost '/'

這個限制反映設計意圖：quorum 與 stream 存在的理由是 資料安全、transient 模式與該目標矛盾、所以從宣告層就封死。Classic queue 保留 transient 選項、是因為它要同時服務「臨時隊列」與「持久隊列」兩種場景。

第二、quorum 與 stream 有 leader / members、classic 沒有。Classic queue 的訊息只存在宣告它的節點上（mirrored policy 另算）；quorum 與 stream 在設計上就是 cluster-aware 的 replicated 結構、leader 處理讀寫、members 列出 replica 所在節點。單節點環境下 members 只有一個、但欄位本身揭露了複製拓樸的存在。

Stream 的 retention 與 segment 參數在宣告時設定、宣告後可查：

1rabbitmqadmin declare queue name=q-stream-ret durable=true \
2  arguments='{"x-queue-type":"stream","x-max-length-bytes":20000000000,"x-max-age":"7D","x-stream-max-segment-size-bytes":100000000}'
3
4rabbitmqctl list_queues name type arguments

1q-stream-ret  stream  [{"x-max-age","7D"},{"x-max-length-bytes",20000000000},
2                       {"x-queue-type","stream"},{"x-stream-max-segment-size-bytes",100000000}]

x-max-age（保留 7 天）與 x-max-length-bytes（保留 20GB）是 stream 獨有的 retention 控制 — classic 與 quorum 沒有這個概念、因為它們消費即刪除、不存在「保留多久」的問題。Quorum queue 對應的是 x-delivery-limit（投遞次數上限、超過進 dead-letter）這類 重試治理 參數、而非 retention：

1q-quorum-dl  quorum  [{"x-delivery-limit",5},{"x-queue-type","quorum"}]

宣告參數的差異就是責任邊界的縮影：stream 的參數圍繞「保留多少歷史」、quorum 的參數圍繞「重試到第幾次放棄」、classic 兩者都精簡。

三軸選型判讀

Queue type 的選擇由三個軸決定：消費後是否保留（retention / replay）、跨節點一致性需求、記憶體與 throughput 成本。

消費後是否保留：retention 與 replay

Stream 與 classic / quorum 的根本分界是訊息生命週期。Classic 與 quorum 是 隊列：訊息被 ack 後從 queue 移除、後到的 consumer 看不到歷史。Stream 是 log：訊息寫入後常駐到 retention 上限為止、consumer 各自維護 offset、可以從 offset 0 重讀整段歷史、也可以從 timestamp 起讀。

實機可觀察到 stream 的訊息在 publish 後保留在 queue 內：

1rabbitmqadmin publish exchange=amq.default routing_key=q-stream payload="msg1"
2rabbitmqadmin publish exchange=amq.default routing_key=q-stream payload="msg2"
3rabbitmqadmin publish exchange=amq.default routing_key=q-stream payload="msg3"
4rabbitmqctl list_queues name type messages messages_ready

1q-stream   stream  3  3

對 classic queue、同樣 publish 後 consumer ack 一次、訊息歸零；對 stream、即使一個 consumer 讀完、messages 仍維持 3、因為訊息保留供其他 consumer 與未來 replay。這個差異決定了選型：需要「新上線的 consumer 補讀歷史事件」「同一份事件流餵給多個下游」「審計與重算」→ stream 是唯一選項；只要「一個任務交給一個 worker 處理一次」→ classic 或 quorum、不要用 stream（log 保留會吃磁碟、且隊列語意更貼合任務分派）。

需要在 RabbitMQ 體系外做大規模事件流（跨團隊 schema 治理、tiered storage、生態工具）時、stream 不是終點、改評估 Kafka。Stream 的定位是「已經在用 RabbitMQ、需要 replay 但不想引入第二套 broker」。

跨節點一致性：mirrored 的退場與 quorum 的接手

Classic queue 在單節點上沒有複製。早期要跨節點高可用、靠 mirrored queue — 一個 master、多個 mirror、master 寫入同步到所有 mirror。這個機制的問題在 3.C30 Runtastic 揭露：mirror 數越多、每筆訊息的網路放大越大、規模化時網路元件先被壓垮。RabbitMQ 3.x 已將 mirrored queue 標記 deprecated、4.0 移除。

Quorum queue 用 Raft 共識取代 mirroring。差異在「同步多少 replica 才算寫成功」：mirrored queue 要求 所有 mirror 同步（全量放大）；Raft 只要求 majority（多數派）寫入即 ack，少數派慢或暫時離線不阻塞寫入。majority 機制讓 quorum queue 在「容忍少數節點故障」與「寫入延遲」之間取得 mirrored 做不到的平衡。

代價是 Raft 的 round-trip 成本：每筆訊息要等多數派落盤、單筆延遲高於 classic 單節點 fsync。所以 quorum queue 適合「不可丟、可接受中等延遲」的工作隊列、不適合追求極致低延遲的場景。

記憶體與 throughput 成本

Classic queue 的歷史包袱是訊息傾向常駐記憶體、queue 堆積時記憶體壓力大（lazy queue 模式可緩解、但仍是 classic 的調校負擔）。Quorum queue 預設 on-disk 為主、記憶體只放 index 與近期訊息、堆積時記憶體曲線比 classic 平緩。Stream 是 append-only log、寫入是順序磁碟 I/O、讀取靠 OS page cache、是三者中記憶體效率最高、throughput 最高的 — 順序寫與批次讀讓它在高吞吐事件流場景接近 Kafka 的量級。

throughput 排序大致是 stream > classic ≈ quorum（quorum 因 Raft round-trip 略低於單節點 classic、但換得一致性）。選型時 throughput 不該是唯一軸：stream throughput 高但語意是 log、用它跑任務隊列會錯配；quorum throughput 中但提供 classic 給不了的高可用。

故障演練

三種 queue type 的故障形狀完全不同。以下四個場景對應實際遷移與運維會踩的坑。

Mirrored queue 的網路放大成本

徵兆：流量暴增期間、RabbitMQ cluster 出現高延遲與間歇中斷、但 CPU 與磁碟未飽和；performance test 指向網路元件被壓垮。這正是 3.C30 Runtastic 2020 lockdown 期間的情況。

根因：mirrored queue 把每筆訊息同步到 所有 mirror。一個 master + 2 mirror 的 queue、每筆 publish 產生 2 份額外的跨節點複製流量；mirror 數與訊息量相乘、網路頻寬隨規模線性放大。可靠性看似免費（多一個 mirror 就多一份備援）、實際成本藏在網路層、平時不顯、流量尖峰才爆。

修法：

1. 量化 mirror 的網路成本：mirror 數不是越多越安全、每個 mirror 都是固定的複製流量稅。生產上 mirror 數很少需要超過總節點的 majority。
2. 遷移到 quorum queue：Raft 的 majority 寫入取代全量同步、把網路放大從「mirror 數」降到「majority round-trip」。Runtastic case 是「為何該遷 quorum」的典型動機。
3. 監控網路而非只看 CPU / 磁碟：mirrored queue 的瓶頸常在網路、用 Prometheus integration 把跨節點複製流量納入告警基線。

Quorum queue 的 quorum loss

徵兆：cluster 有節點故障後、某些 quorum queue 變成不可寫、publisher confirm 卡住超時、rabbitmq-diagnostics check_if_node_is_quorum_critical 報警。

以下跨節點行為依官方文件、單節點環境未實機驗證。

根因：quorum queue 靠 Raft majority 運作。一個 3-replica 的 queue 容忍 1 個節點故障（剩 2 個構成 majority）；故障 2 個節點時、剩 1 個無法構成多數派、queue 進入 無 leader 狀態、拒絕寫入以保證一致性。這是 Raft 的設計選擇：寧可不可用、不可不一致。replica 數設成偶數（如 2 或 4）更糟 — 偶數的 majority 門檻不會提升容錯、反而浪費資源。

修法：

1. replica 數設奇數：3 replica 容忍 1 故障、5 replica 容忍 2 故障。奇數讓 majority 計算最有效率。
2. 監控 quorum critical 狀態：rabbitmq-diagnostics check_if_node_is_quorum_critical 在「再掛一個節點就會失去 quorum」時提前告警、在維護重啟前先確認不會打破 majority。
3. 跨故障域分佈 replica：把 3 個 replica 放在不同 AZ / 機架、避免單一故障域同時帶走多數派。
4. 理解不可用是預期行為：quorum loss 時 queue 拒寫是 正確 的、不是 bug。恢復路徑是把故障節點拉回 cluster 重組 majority、不是強制覆寫。

Stream retention 超量

徵兆：stream queue 所在節點磁碟使用率持續上升、最終觸發 disk alarm、broker 暫停所有 publisher；或 consumer 嘗試讀取較舊的 offset 時拿到「offset 不存在」、發現歷史訊息已被截斷。

根因：stream 是 append-only log、訊息 不因消費而刪除、只靠 retention 上限（x-max-age 時間 / x-max-length-bytes 大小）回收。retention 設太寬、或寫入速率超過預估、log 持續長大直到塞滿磁碟。反過來 retention 設太緊、consumer 還沒讀到的舊訊息就被截斷、replay 場景拿不到完整歷史。Stream 的容量管理是「設定 retention」、不是「靠消費清空」 — 這跟隊列直覺相反。

修法：

1. retention 雙保險：同時設 x-max-age（時間上限、對齊業務 replay 窗口、如 7 天）與 x-max-length-bytes（大小上限、對齊磁碟容量）。先到的條件先觸發截斷、避免單一維度失控。
2. segment 大小對齊回收粒度：x-stream-max-segment-size-bytes 決定 log 分段大小、retention 以 segment 為單位回收。segment 太大、retention 觸發後一次釋放大量空間、磁碟曲線鋸齒；太小、segment 檔案數量爆炸。
3. 容量公式先算再設：預估 寫入速率 × 訊息平均大小 × retention 時間、確認低於節點磁碟可用空間的安全水位（如 70%）、再上線。
4. monitor disk_free_limit：stream 節點的磁碟告警閾值要比一般節點更早、因為 stream 是磁碟密集型、disk alarm 觸發會凍結整個 broker 的 publisher。

Classic → Quorum 遷移的 in-flight message

徵兆：把工作隊列從 classic（或 deprecated mirrored）遷到 quorum 時、切換瞬間有訊息遺失、或重複處理 — queue 重建期間 publisher 已經在發、consumer 還沒接上新 queue。

根因：queue type 無法原地變更、遷移本質是 建新 queue + 切流量 + 排空舊 queue。最大的坑是 in-flight 訊息：舊 classic queue 裡還有未消費的訊息、若直接刪除舊 queue、這些訊息就丟了；若 publisher 提前切到新 queue、舊 queue 的 consumer 還在處理、就出現新舊兩條路徑並存的一致性窗口。3.C27 Zalando 跨版本升級用 federation 過渡、正是為了平滑搬移而非硬切。

修法：

1. 新 queue 先建、binding 並存：用新 routing key 或新 queue 名建立 quorum queue、舊 classic queue 暫不刪。
2. consumer 先切、publisher 後切：先讓 consumer 同時消費新舊兩個 queue、確認新 queue 路徑正常、再把 publisher 切到只發新 queue。順序顛倒（publisher 先切）會讓舊 queue 的 in-flight 訊息沒人消費。
3. 排空舊 queue 再刪：publisher 切換後、等舊 classic queue messages 歸零（用 list_queues name messages 確認）、才刪除舊 queue。
4. 依賴 idempotency 兜底：遷移窗口內訊息可能重複投遞、consumer 端的 idempotency 是最後一道防線（語義誤配的後果見 3.C9）、不要假設遷移零重複。
5. 用 federation / shovel 做大規模搬移：跨 cluster 或跨版本場景、用 federation upstream 把舊 cluster 訊息引流到新 cluster、避免一次性硬切（Zalando case 的做法）。

容量與成本規劃

實務 default：

• 單節點開發 / 臨時隊列：classic、最簡單、transient 模式適合 RPC reply。
• 生產工作隊列、不可丟訊息：quorum、3 replica 跨 AZ、replica 數設奇數。
• 事件流 / 多 consumer / 需要 replay：stream、retention 雙保險、磁碟容量先算。
• 判斷該不該升級到 Kafka：當 stream 場景開始需要跨團隊 schema registry、tiered storage、或成熟的 streaming 生態工具時、stream 是過渡、Kafka 是終點。

整合與下一步

Queue type 的選擇與 RabbitMQ 其他能力交織：

• 回 vendor overview：三種 queue type 的取捨在 RabbitMQ overview「Classic queue vs Quorum queue vs Stream」段有 vendor-level 定位；本文是其 implementation 展開。
• durable queue 能力層：queue type 的持久化語意建立在 3.2 durable queue 的概念上 — quorum 與 stream 強制 durable、正是把「處理即承諾」的可靠性從單節點延伸到跨節點。
• durable queue 知識卡：訊息持久化的概念基礎見 durable queue 知識卡。
• mirrored → quorum 的遷移動機：3.C30 Runtastic 量化 mirrored 網路成本、是遷 quorum 的證據。
• 跨版本 / 跨 cluster 平滑遷移：3.C27 Zalando 用 federation 過渡、是 in-flight message 安全搬移的範本。

何時 revisit queue type 選擇：classic queue 開始出現記憶體壓力或需要跨節點 HA 時、評估 quorum；任何 queue 場景開始需要「補讀歷史」「多 consumer 各自進度」「replay 重算」時、評估 stream；stream 場景開始需要跨團隊事件治理時、評估遷 Kafka。

事故類型：潛伏型設計缺陷、第二個訂閱者出現時才暴露 症狀：Bad state: Stream has already been listened to. 根因：在「StreamController() vs StreamController.broadcast()」這個零成本差異的選擇下、選了限制更高的單訂閱版本——當下只有一個訂閱者、限制沒曝光；新增第二個訂閱者就觸發底層型別契約。設計缺陷的本質是「在零成本差異下不必要地縮小了未來空間」、不是「沒預測到後來需求」。

事故場景

業務背景：POS 的多視角狀態同步

POS 系統本質上是「單一交易狀態 + 多個視角同步呈現」。一筆購物車的變化通常要立刻反映到：

• 收銀員操作的主螢幕
• 給顧客看的副螢幕（純顯示，看商品、總價、找零）
• 廚房或後場的出餐顯示
• 列印機（結帳當下觸發）
• 雲端同步、報表、會員紀錄

這些視角各自關心交易狀態的不同切面，但都需要在狀態變動的當下被通知。在系統設計上，這是個典型的「一個資料源、多個訂閱者」場景，本質就是事件廣播。

原始設計：一個事件來源，一個訂閱者

實作初期，「需要訂閱購物車變動」的角色只有一個——副螢幕。副螢幕在 app 啟動時就訂閱、整個 app 生命週期都在聽，純粹做主畫面的鏡像顯示。

於是負責提供「狀態變更通知」的 service 用了 dart:async 預設的 StreamController 對外發事件。事件 payload 設計成兩段資訊：

1. 當前完整商品列表（給副螢幕這類「鏡像當前狀態」的訂閱者用）
2. 這次變動的具體品項（移除或清空時為 null，預留給「需要知道改了哪一筆」的訂閱者）

第二段資訊當下沒人用，但 service 設計者保留了它，理由是「未來如果有訂閱者需要知道每次具體變動是什麼，不必再改介面」——一個合理的擴充性設計。

幾個月過去，這條 stream 只有副螢幕一個訂閱者，運作正常。

新需求：操作體驗優化

新需求出現：收銀員在尖峰時段連續掃商品，畫面更新太快會分不清剛剛動到的是哪一筆。如果是改價、改數量這類修改更明顯——數字突然變了，但視線焦點不在那一行就會錯過。

業務上希望：每次操作後，被改動的那一行在 UI 上有個視覺標記（高亮、邊框或角標都可），讓收銀員一眼確認剛剛動的是對的品項。標記停在最後一次操作的那行，直到下一次操作才轉移。

這個需求對應 service 已經備妥但尚未被消費的資訊——service 對外的事件 payload 從原始設計就分兩段：一段是「當前完整的商品列表」、另一段是「這次變動的具體品項」。第二段是當初為「需要追蹤單筆變動的訂閱者」預留的擴充欄位、過去幾個月一直沒被消費。新需求只要新增一個訂閱者讀這段資訊、再把它對應到 UI 上的視覺標記即可——介面不需要變動、payload 結構不需要調整、實作範圍只限於新增訂閱端。

第二個訂閱者觸發底層限制

第二個訂閱者寫好、進入收銀頁面當下就 throw：

1The following StateError was thrown building Obx(...):
2Bad state: Stream has already been listened to.

第一反應通常是「我哪裡寫錯了 / 是不是哪邊忘了 cancel」。檢查程式碼會發現新訂閱者寫得沒問題，副螢幕的訂閱也沒問題——問題在底層 stream 的型別契約：整個生命週期內只允許被 listen 一次。

這是 StreamController() 預設建構子的契約：建立的是 single-subscription stream、生命週期內最多承載一個 listener。副螢幕第一個訂閱後佔據了唯一的 listener 位置；新加第二個訂閱者直接違反契約、執行期 throw。

更深一層的觀察是設計層面的不一致：業務需求一直具備廣播語義（多個視角同步呈現）、技術選型卻是「單一管線」的工具。需求初期只有一個訂閱者讓限制沒有可見的影響、但限制一直存在於型別契約裡。第二個訂閱者只是觸發條件、不是根因。

兩種 StreamController 的核心差異

三組行為差異的程式碼驗證

1. 重複監聽

 1final c = StreamController<int>();
 2c.stream.listen(print);
 3c.stream.listen(print);
 4// 錯誤：Bad state: Stream has already been listened to.
 5
 6final b = StreamController<int>.broadcast();
 7b.stream.listen((v) => print('A: $v'));
 8b.stream.listen((v) => print('B: $v'));
 9b.add(1);
10// A: 1
11// B: 1

值得注意的不只是「不能同時兩個 listener」——單訂閱 stream 的限制是整個 lifecycle 只能 listen 一次。即使第一個 listener 已經 cancel()、再呼叫 .listen() 仍會違反契約 throw。要重新訂閱必須重建 StreamController。

對 POS 場景的意義：副螢幕服務在 app 啟動時就建立訂閱、且不會 cancel——換句話說、stream 在啟動時就把唯一的 listener 配額分配給副螢幕、之後沒有可釋出的空間。

2. 監聽前的事件處理

 1final single = StreamController<int>();
 2single.add(1);
 3single.add(2);
 4// 此時還沒有 listener
 5single.stream.listen(print);
 6single.add(3);
 7// 輸出：1, 2, 3 ← 之前的事件被 buffer，listener 接上後補送
 8
 9final broadcast = StreamController<int>.broadcast();
10broadcast.add(1);
11broadcast.add(2);
12// 此時還沒有 listener
13broadcast.stream.listen(print);
14broadcast.add(3);
15// 輸出：3 ← 監聽前的事件全部丟掉

這個差異對應用設計的影響：

• 單訂閱保證 listener 不漏接，適合「資料完整性 > 即時性」（檔案讀取、計算結果序列）
• broadcast 不保留歷史，適合「即時性 > 完整性」（UI 事件、狀態變更通知）

如果改成 broadcast 後，希望「新訂閱者進場時能拿到一次當下的狀態」（例如 controller 進場時想知道當前購物車內容），broadcast 本身做不到，要靠 service 自己保留 latest 或在新訂閱時手動 push 一次。RxDart 的 BehaviorSubject 內建這行為，純 dart:async 沒有。

對 POS 案例：sticky 高亮只關心未來變更，不在意歷史事件——broadcast 的丟棄行為跟這個語義一致、不造成資料缺失。但如果是「副螢幕鏡像當前購物車」這種需求，新副螢幕插入時若需要立即顯示當下狀態，就要在訂閱後手動 read 一次 cart.items。

3. Pause 行為（最反直覺）

1final single = StreamController<int>();
2final sub = single.stream.listen(print);
3sub.pause();
4single.add(1);  // 不會立刻送出
5sub.resume();
6// 輸出：1 ← 暫停期間的事件 resume 後補送

1final broadcast = StreamController<int>.broadcast();
2final subA = broadcast.stream.listen((v) => print('A: $v'));
3final subB = broadcast.stream.listen((v) => print('B: $v'));
4subA.pause();
5broadcast.add(1);
6// 輸出：B: 1   ← B 照收，A 暫存
7subA.resume();
8// 輸出：A: 1   ← A resume 後補回

單訂閱的 pause 等於「整條管線暫停」，上游 add 的資料堆在 controller 內部、記憶體會漲。Broadcast 是 per-listener 暫停，互不影響。

POS 的副螢幕場景如果搭配無界事件源（例如背景條碼掃描器）、用單訂閱且某條路徑沒 resume、會在 controller 內部累積未送出的事件、記憶體佔用持續上升——這是 production OOM 的常見來源之一。

設計缺陷為什麼在初期沒有可見影響

訂閱者單一時、限制處於沉默狀態

副螢幕訂閱寫在 service 啟動時、屬於 app lifetime 訂閱、沒有 cancel / 重新訂閱的情境。在這個訂閱模式下：

1. 副螢幕第一個訂閱 → 佔據 single-subscription 的「唯一 listener」配額
2. 沒有第二個訂閱方 → 違反契約的條件不會出現
3. 限制存在於型別契約裡、但沒有可見的影響

當訂閱者擴增到第二個時、這條 stream 的型別契約「整個生命週期只承載 1 個 listener」才開始產生可見的執行期影響。注意這裡描述的是「契約一直存在、只是沒有觸發違反條件」——不是「契約因為新需求才變成限制」。型別契約是當下選擇 StreamController() 時就確定的、訂閱者數量只決定它何時被觸發。

設計缺陷 vs 需求演化的分界

但「為什麼能算設計缺陷」這個問題值得停下來釐清——當下只有一個訂閱者、需求變了才需要多訂閱、這聽起來不像是「設計缺陷」、更像是「需求演化」。兩者怎麼分？

關鍵不是「有沒有預測到後來的需求」、是「當下的選擇是否在零成本差異下不必要地縮小了未來空間」：

本 case 落在第一格——StreamController() vs StreamController.broadcast() 是 11 字元差、零認知負擔、零維護成本差異。即使當下只有副螢幕一個訂閱者、選 broadcast 也沒付任何代價、卻保留了未來的彈性。寫成 single 不是「對當下需求的精確匹配」、是在零成本差異下不必要地縮小了未來空間——這才是「設計缺陷」這個詞要描述的事。

加上 POS 系統的領域先驗強烈指向「多視角同步」（主螢幕 / 副螢幕 / 廚顯 / 雲端 / 列印是教科書級的 pub-sub 場景）、選 single-subscription 等於假設「這個 service 不會有多訂閱需求」——這個假設跟領域常識矛盾、即使在當下也站不住。

「成本對稱性 / 可逆性 / 領域先驗」三軸框架的完整推導見 設計瑕疵還是避免過度設計？YAGNI 的真實適用條件——本 case 三軸都指向 broadcast、屬於 YAGNI 不適用的標準情境。

為什麼 IDE 與測試抓不到

• Dart 編譯器：型別簽章一樣（Stream<T>），編譯不會錯
• 靜態分析：dart analyze 不會警告 single-subscription 用法的潛在風險
• 單元測試：通常 mock 整條 stream，不會驗證真實 controller 是不是支援多訂閱
• Widget test：只跑單一頁面，不會同時掛多個訂閱模組
• 整合測試：理論上能抓，但成本高，多數專案在這層覆蓋稀疏

要在事前抓到，可行的方式：

• Lint rule：自訂規則檢查 StreamController() 預設用法，要求加註解說明「為何刻意不用 broadcast」
• Code review checklist：service 對外暴露 stream 時，預設假設要 broadcast，single 必須有書面理由
• 架構規範：直接禁用 raw StreamController 在 service 層，強制透過框架的廣播原語（Rx, BehaviorSubject, ValueNotifier）

修復決策過程

選項列舉

事故當下的選項：

為什麼選 A

POS 的這條 stream 語義就是「購物車狀態變更廣播」、多訂閱者本來就符合領域模型。選 B 會讓副螢幕服務變成轉發中樞、跟它「純顯示」的職責衝突。選 C 增加重複資料源、未來容易兩條 stream 不同步。選 D 雖然在架構層更一致、但 scope 過大、不是事故當下適合做的決定。

A 是改一行的 minimal fix，且修正了原本的設計缺陷而不是繞過它。

容易漏的細節：mock 也要改

Service 如果有 mock 實作（測試替身）、mock 端也要同步改成 broadcast。否則會出現「測試環境通過、production 仍然 throw」的不對齊狀況——單元測試（注入 mock）跟 production（真實 service）使用不同的 stream 契約、限制沒被測試覆蓋。

這是「測試環境與 production 配置不對齊」的典型陷阱。事故當下要把「修真實實作」「修 mock」當成同一件事的兩個必做動作，分開做就會漏。比較好的長期策略是把這個約束放進 code review checklist，或在 service 介面層加註解註明「實作不論真假都必須是 broadcast 語義」。

還要檢查：所有寫入路徑都有完整 emit

事故修復不只是改 stream 類型，還要回頭審視「事件 payload 的完整性」。

回到事故場景：事件 payload 第二段（這次變動是哪筆）原本沒人用，所以幾個寫入路徑可能根本沒傳。副螢幕只看第一段（完整列表），傳不傳第二段對它沒差。只有第二個訂閱者開始消費這段資訊時，遺漏才會暴露。

這是廣播設計的一個系統性風險：service 提供「為未來訂閱者保留」的擴充欄位時、這些欄位若沒有當下的消費者、缺漏不會在測試中浮現。第一個真正使用該欄位的訂閱者出現後、才會暴露出某些 mutation 路徑沒填寫該欄位。

修復清單：

• 把 single-subscription 改成 broadcast（真實實作 + mock 雙改）
• 審視所有寫入路徑，確保事件 payload 的每個欄位都正確填寫
• 確認第二個訂閱者的 dispose / cancel 邏輯
• 訂閱者進場時若需要「當下狀態」，要補一次直接讀取（broadcast 不保留歷史）

何時該選哪個

選 StreamController() 的情境

• 確定只有一個消費者，且這個契約被寫進文件 / 介面註解
• 需要保證每個事件都被消費（buffer 是 feature）
• 像 Future 但會發多個值：檔案讀取、HTTP response body chunks、long-running task 進度回報

選 StreamController.broadcast() 的情境

• 有多個訂閱者，或不確定未來會不會多
• 事件是「正在發生」的通知，錯過就算了（UI 事件、狀態變更廣播、event bus、application-level domain events）
• 不在意進場前的歷史事件（如果在意，自己保留 latestValue）

一個粗略的決策法

「如果某天有人想加第二個 listener，這在語義上合理嗎？」

• 合理 → 一開始就用 broadcast
• 不合理 → 用單訂閱，並在註解寫清楚為什麼

應用層的 service 通知絕大多數情境都偏向 broadcast；single-subscription 的甜蜜點在底層 I/O 或一次性 task 進度（兩者都有「單一消費者 + 不能漏接」的明確契約）。

對 POS 場景：service 對外暴露的「狀態變更通知」幾乎都落在 broadcast 區——POS 的本質就是多裝置 / 多視圖共享同一份交易狀態（主螢幕、副螢幕、廚顯、雲端、列印機）。

補救與替代方案

已有 single-subscription stream，想對外提供 broadcast

不用改 controller 類型，可以包一層：

1final singleStream = someController.stream;
2final broadcastView = singleStream.asBroadcastStream();
3
4// 對外公開 broadcastView，原本的 singleStream 內部仍是 single-subscription

asBroadcastStream() 把單訂閱當 source，對外提供 broadcast view。一旦呼叫過一次，後續訂閱者都拿這個 view。

注意：這個方法只能呼叫一次、第二次會 throw。實務上要保留回傳值在 service 內部做 cache。

想要「broadcast + 新訂閱拿最後一次值」

標準 dart:async 沒有這功能。要嘛自己實作：

 1class ReplayLastNotifier<T> {
 2  final _controller = StreamController<T>.broadcast();
 3  T? _latest;
 4
 5  Stream<T> get stream async* {
 6    if (_latest != null) yield _latest as T;
 7    yield* _controller.stream;
 8  }
 9
10  void add(T value) {
11    _latest = value;
12    _controller.add(value);
13  }
14}

要嘛用 RxDart 的 BehaviorSubject，內建這行為。POS 副螢幕鏡像場景特別適合 BehaviorSubject：副螢幕進場時就能立即看到當下購物車內容，不必等下一次變更。

Flutter 生態系的替代

純 StreamController 在 Flutter app 層比較少見，更常用的是：

如果你已經在用某個狀態管理框架，優先用框架的廣播原語，而不是 raw StreamController。StreamController 在 Flutter app 通常是底層 I/O service 才用（藍牙、socket、sensor）。

下一節對其中最常被混用的一組——raw StreamController 跟 GetX 的 Rx / .obs——做完整對比，因為這也是事故當下會考慮「是不是該整個換掉」的對象。

深入比較：raw StreamController vs GetX 的 Rx / .obs

先釐清：Rx 跟 .obs 的關係

在 GetX 裡，Rx<T> 是底層 reactive value container，.obs 是把任何值包成對應 Rx 子類的 syntax sugar：

1// 三種寫法本質等價
2final count1 = 0.obs;            // 推導為 RxInt
3final count2 = RxInt(0);         // 顯式建構特化子類
4final count3 = Rx<int>(0);       // 較少用，因為 RxInt 提供更多 operator overload
5
6count1.value++;  // RxInt 可直接用 ++
7count3.value++;  // Rx<int> 也行，但缺了 RxInt 的算術特化

.obs 對不同型別回傳不同特化子類：

特化子類的核心好處：原生語法的 mutation（+=、list add、string concat）都直接觸發 reactive 通知，不需要手動 notifyListeners() 或 add()。

結論：.obs 跟 Rx 不是兩個不同概念，是同一個機制的兩種建構寫法。後者多了型別推導與特化命名。

概念差異

相同任務的程式碼對比

任務：service 對外暴露一個整數狀態，UI 顯示它且當值變化時自動 rebuild。

 1// ===== Raw StreamController 寫法 =====
 2
 3class CounterService {
 4  int _value = 0;
 5  final _controller = StreamController<int>.broadcast();
 6
 7  int get value => _value;
 8  Stream<int> get stream => _controller.stream;
 9
10  void increment() {
11    _value++;
12    _controller.add(_value);
13  }
14
15  void dispose() => _controller.close();
16}
17
18// UI:
19StreamBuilder<int>(
20  stream: service.stream,
21  initialData: service.value,  // 不帶這個首次 build 是 null
22  builder: (context, snap) => Text('${snap.data}'),
23)

 1// ===== Rx / .obs 寫法 =====
 2
 3class CounterService extends GetxController {
 4  final value = 0.obs;
 5
 6  void increment() => value.value++;
 7
 8  // 不需要寫 dispose；Rx 隨 controller 生命週期自動清理
 9}
10
11// UI:
12Obx(() => Text('${service.value.value}'))

差異一目了然：

• 樣板量約 4-5 倍差距
• StreamController 要自己維護 latest value
• StreamController 要記得寫 dispose
• Obx 自動追蹤所有 .value 讀取，不需要手動 listen/cancel
• StreamBuilder 要處理 initialData 與 snap.data 為 null 的情境，Rx 沒這問題（永遠有值）

Rx 內部其實就是 StreamController + ValueNotifier

Rx<T> 底層用 StreamController.broadcast() 加上一個 _value 欄位。Obx widget 在 build 時開一個訂閱範圍，期間任何 .value getter 會被追蹤；build 結束後對應的 stream 訂閱自動建立，值變化時觸發 widget rebuild。

簡化心智模型：

 1class Rx<T> {
 2  T _value;
 3  final _ctrl = StreamController<T>.broadcast();
 4
 5  Rx(this._value);
 6
 7  T get value {
 8    RxInterface.proxy?.addListener(_ctrl.stream);  // Obx 注入的依賴追蹤代理
 9    return _value;
10  }
11
12  set value(T v) {
13    if (_value == v) return;  // ← 等值不觸發
14    _value = v;
15    _ctrl.add(v);
16  }
17}

（真實實作更複雜，但骨架是這樣。）

換句話說 Rx ≈ broadcast StreamController + ValueNotifier + 自動依賴追蹤 + 特化子類。理解這層之後，後面所有「Rx 為什麼這樣」的問題都能從這個本質推回去。

完整對比表格

Rx 的特殊行為與陷阱

1. 等值不觸發更新

1final name = ''.obs;
2name.value = '';     // 不觸發 listener（'' == ''）
3name.value = 'A';    // 觸發
4name.value = 'A';    // 不觸發（'A' == 'A'）

如果需要「每次 set 都觸發」（例如重新打 API 不管值有沒有變），用 .refresh() 或 .trigger()：

1name.refresh();              // 強制通知所有 listener，不變更 value
2name.trigger('A');           // 強制通知，且 set value

2. 物件內部變動不觸發

1final user = User(name: 'A').obs;
2user.value.name = 'B';                         // 不觸發，reference 沒變
3user.refresh();                                // 強制觸發
4user.value = user.value.copyWith(name: 'B');   // 換新 reference 自然觸發

這跟 immutable 風格（Freezed、Equatable）配合最自然，copyWith 一定產出新 reference。

3. Obx 必須讀到至少一個 .value

1Obx(() => Text('hello'))                  // warning: improper use
2Obx(() => Text('${counter.value}'))       // 正確

Obx 靠 build 期間攔截 .value getter 建立訂閱關係，build callback 內完全沒讀任何 Rx 就不知道要 subscribe 誰。

4. RxList / RxMap 的 mutation 規則

1final items = <int>[].obs;
2items.add(1);          // 觸發（RxList 重寫了 add）
3items.value.add(2);    // 不觸發（操作的是底層 List）
4items[0] = 99;         // 觸發（RxList 重寫了 []=）
5items.refresh();       // 補救

特化集合類別重寫了 add/remove/[]=/clear 等 method 讓它們自動 emit；繞過 wrapper 直接操作 .value 就會跳過這層。

5. .obs 推導出的特化型別可能不是你想要的

1final list = [1, 2, 3].obs;        // RxList<int>
2final list2 = <num>[1, 2, 3].obs;  // RxList<num> — 注意泛型推導
3
4// 自定義型別需明確
5final user = User(name: 'A').obs;  // Rx<User>，不是「RxUser」

Rx 的 worker 類型（service 之間的訂閱模式）

Obx 是 widget 自動訂閱；service 內或 controller 之間的訂閱用 worker：

 1// 每次變化都觸發
 2final disposer = ever(counter, (value) => print('changed to $value'));
 3
 4// debounce — 連續變化只取最後一次
 5debounce(
 6  searchText,
 7  (value) => searchAPI(value),
 8  time: Duration(milliseconds: 500),
 9);
10
11// throttle — 固定間隔最多觸發一次
12interval(
13  scrollPosition,
14  (value) => analytics(value),
15  time: Duration(seconds: 1),
16);
17
18// 只觸發一次後自動移除
19once(loginState, (value) => navigateHome());
20
21// 監聽多個 Rx，任一變動就觸發
22everAll([a, b, c], (_) => recompute());
23
24// 手動清理
25disposer.dispose();

這些 worker 在 GetxController.onInit 裡註冊時會被綁定到 controller 生命週期，controller dispose 時自動清；在 controller 外註冊就要自己 .dispose()。

何時選哪個

選 raw StreamController

• 寫底層 service（藍牙、socket、sensor、background isolate 通訊）
• 需要豐富的 stream operators 鏈（map/where/buffer/distinct/merge/combineLatest…）
• 對外提供的 API 不想綁特定狀態管理框架，要保持框架中立
• 需要 backpressure / pause-resume 等進階流量控制
• 跨 isolate 資料傳遞

選 Rx / .obs

• 寫 UI state 或 application state
• 已在用 GetX，沿用一致
• 需要「保留當前值 + 多訂閱者」這個常見組合
• 想要 widget 自動追蹤，不想手動寫 listen/cancel
• service 內部 latest value 與通知的樣板太多次，懶得繼續寫

把事故場景改寫成 Rx 看看

回到事故場景。如果 service 從一開始就用 reactive value container（如 Rx）來表達它的對外契約，整個問題會以另一種方式消失。

對外契約的轉變：service 不再「對外發送事件」，而是「對外暴露兩個可被觀察的狀態屬性」——當前完整的商品列表、最後一次變動的品項。訂閱方不需要 listen() 一條 stream，而是直接讀取屬性的當前值，並且系統保證屬性變化時觀察者會被通知。

在這個契約下回頭看每個訂閱方的需求：

• 副螢幕（鏡像當前商品列表）：只關心「列表屬性」變動，不在乎是哪一筆變動。它建立一個對列表屬性的觀察，每次變動就重畫
• 收銀主畫面（最後變更項標記）：只關心「最後變動屬性」，每次變動就更新高亮哪一行
• 未來的訂閱方（KDS、列印、雲端、analytics）：各自選關心的屬性建立觀察

兩個訂閱者觀察的是不同屬性，互不干擾；同一個屬性也允許多個觀察者（reactive value 天生是廣播語義）。

事故的兩個技術問題在這個契約下自動消失：

1. single vs broadcast 的選擇問題不存在——reactive value 沒有「單訂閱版本」，每個觀察者天生並存
2. 進場拿不到歷史事件的問題不存在——觀察者進場時可以直接讀屬性的「當前值」，不必等下一次變動

更深一層的觀察：raw stream 是「以時間軸上的事件為一等公民」的工具，適合「事件本身就是有意義的（log、命令、訊息）」場景；reactive value 是「以狀態為一等公民」的工具，適合「下游關心的是當前是什麼，不是過去發生了什麼」場景。POS 多視角同步的本質是後者——副螢幕關心的是「現在購物車裡有什麼」，不是「過去 5 分鐘掃進了哪些商品的時序」。

把這個認知一般化：當業務語義是「多個視角共享當前狀態」時，工具應該是 reactive value（Rx / ValueNotifier / BehaviorSubject）；當業務語義是「事件流的時序」時，工具才是 stream。本案的根因是「業務語義（共享狀態）」跟「工具語義（事件流）」錯配；single-subscription 是錯配關係下第一個被觸發的契約限制、但即使換成 broadcast、仍會在「進場拿不到歷史事件」這個層次暴露語義錯配。

是否該全面改寫成 Rx

事故當下不該。理由：

1. scope 控制：事故修復原則是 minimal change，StreamController() → .broadcast() 一字之差就解決
2. 回歸風險：把 service 介面從 Stream<T> 改成 Rx<T>，所有訂閱方（副螢幕、UI、未來的 KDS / 雲端同步）都要改 listen 方式
3. 耦合代價：如果 service 介面原本是 framework-neutral 的（純 dart:async），改 Rx 等於把 GetX 綁進公開 API，未來要換框架成本變高
4. 測試成本：改 Rx 之後，所有針對該 service 的測試都要改 mock 方式

該重構的時機：

• 整個系統已經 implicit 綁 GetX，介面 framework-neutral 的成本沒實質效益
• 新增 service 時直接用 Rx，舊的 stream-based service 等下次大改一起換
• 發現自己重複寫「_latest + StreamController.broadcast + getter + emit + close」的樣板太多次，Rx 是現成解
• 整理技術債的專屬 sprint，可以系統性換掉

事故修復應該專注 minimal fix；架構改造是另一張單。

除錯思維

Bad state: Stream has already been listened to. 的根因落在 stream 定義端的型別契約、不在訂閱端。檢查順序：

1. 這條 stream 是 single-subscription 還是 broadcast？
   • 從定義端確認（StreamController() vs StreamController.broadcast()）、訂閱端只承載限制、看不出契約類型
2. 若是 single、選 single 的理由有書面記錄嗎？
   • 介面註解 / 設計文件有記錄 → 看理由是否仍成立
   • 沒有記錄 → 屬於「用了預設建構子、沒做選擇」、回到當下三軸判斷
3. 多訂閱在語義上合理嗎？
   • 合理 → 改 broadcast、屬於修正型別契約跟業務語義對齊
   • 不合理 → 第二個訂閱者的需求要重新設計（透過第一個 listener 轉送、或拉新 stream）

把「這條 stream 該不該支援多訂閱」做為設計階段的明確決策、判斷成本（跑三軸）落在當下、且不依賴未來需求是否實際出現。

延伸：POS 場景的多訂閱模式

POS 系統本質上就是「中央交易狀態 + 多視圖/多裝置鏡像」，是 broadcast stream 最自然的應用領域。常見訂閱者：

設計階段先假設「會有多個訂閱者」、「未來訂閱者數量會增加」、「每個訂閱者只關心事件的一部分屬性」——這正是 broadcast 的典型語義；之後新功能要訂閱、設計上會自然容納。

對應的設計建議：

1. Service 對外的事件 stream 預設 broadcast——single-subscription 視為例外、要在介面註解書面說明
2. 事件 payload 設計成 record 或 sealed class——包含「是什麼變動 + 變動的詳細資料」、讓不同訂閱者各取所需
3. 不要假設訂閱者之間的觸發順序——broadcast 的 listener 之間沒有保證順序、訂閱者要假設彼此獨立
4. 進場時若需要初始狀態、提供 currentValue getter——broadcast 不保留歷史、用 explicit getter 補這個缺口

參考資料

• Dart StreamController API doc
• Dart StreamController.broadcast constructor
• Dart Stream.asBroadcastStream method
• Dart language tour - Asynchronous programming: streams
• RxDart BehaviorSubject doc