可觀察合約

「可觀察合約」是嘗試對 Observable 進行正式定義,您可能會在原始碼文件和本網站的頁面中看到對此的引用。它最初基於 2010 年 Microsoft 發布的 Rx 設計指南 文件,該文件描述了其 ReactiveX 的 Rx.NET 實作。

本頁總結了可觀察合約。

通知

Observable 使用以下通知與其觀察者進行通訊

OnNext
傳達 Observable 向觀察者發射項目
OnCompleted
表示 Observable 已成功完成,並且不會再發射任何項目
OnError
表示 Observable 已因指定的錯誤條件而終止,並且不會再發射任何項目
OnSubscribe (可選)
表示 Observable 已準備好接受來自觀察者的 Request 通知(請參閱下面的背壓

觀察者通過以下通知與其 Observable 進行通訊

Subscribe (訂閱)
表示觀察者已準備好接收來自 Observable 的通知
Unsubscribe (取消訂閱)
表示觀察者不再希望接收來自 Observable 的通知
Request (可選)
表示觀察者希望從 Observable 接收的 OnNext 通知不超過特定數量(請參閱下面的背壓

通知的合約規範

一個 Observable 可以發出零個或多個 OnNext 通知,每個通知代表一個發射的項目,然後可以在這些發射通知之後發出 OnCompleted 或 OnError 通知,但不能兩者都發出。發出 OnCompleted 或 OnError 通知後,之後不得再發出任何其他通知。

一個 Observable 可能完全不發射任何項目。一個 Observable 也可能永遠不會以 OnCompleted 或 OnError 通知終止。也就是說,Observable 可以不發出任何通知,僅發出 OnCompleted 或 OnError 通知,或僅發出 OnNext 通知,都是正確的。

Observable 必須依序(而不是並行)向觀察者發出通知。它們可以從不同的執行緒發出這些通知,但通知之間必須存在正式的先發生關係。

Observable 終止

如果 Observable 尚未發出 OnCompleted 或 OnError 通知,觀察者可以認為它仍處於活動狀態(即使它目前沒有發射項目),並且可以向其發出通知(例如 Unsubscribe 或 Request 通知)。當 Observable 發出 OnCompleted 或 OnError 通知時,Observable 可以釋放其資源並終止,並且其觀察者不應再嘗試與其通訊。

OnError 通知必須包含錯誤的原因(也就是說,使用 null 值呼叫 OnError 是無效的)。

在 Observable 終止之前,它必須先向所有已訂閱它的觀察者發出 OnCompleted 或 OnError 通知。

訂閱和取消訂閱

Observable 可以在收到觀察者的 Subscribe 通知後立即開始向觀察者發出通知。

當觀察者向 Observable 發出 Unsubscribe 通知時,Observable 將嘗試停止向觀察者發出通知。但是,不保證在觀察者發出 Unsubscribe 通知後,Observable 不會向觀察者發出任何通知。

當 Observable 向其觀察者發出 OnError 或 OnComplete 通知時,這將結束訂閱。觀察者不需要發出 Unsubscribe 通知來結束由此 Observable 結束的訂閱。

多個觀察者

如果第二個觀察者訂閱已向第一個觀察者發射項目的 Observable,則由 Observable 決定是否從此向每個觀察者發射相同的項目,或者是否從頭開始向第二個觀察者重播完整的項目序列,或者是否向第二個觀察者發射完全不同的項目序列。不能保證同一個 Observable 的兩個觀察者會看到相同的項目序列。

背壓

背壓是可選的;並非所有 ReactiveX 實作都包含背壓,而且在包含背壓的實作中,並非所有 Observable 或操作符都支援背壓。如果 Observable 偵測到其觀察者實作了 Request 通知並理解 OnSubscribe 通知,則 Observable 可以實作背壓。

如果 Observable 實作了背壓並且其觀察者使用了背壓,則 Observable 不會在訂閱後立即開始向觀察者發射項目。相反,它會向觀察者發出 OnSubscribe 通知。

在收到 OnSubscribe 通知後的任何時間,觀察者都可以向其訂閱的 Observable 發出 Request 通知。此通知請求特定數量的項目。Observable 會回應此 Request,向觀察者發射的項目數不會超過觀察者請求的項目數。但是,Observable 也可以額外發出 OnCompleted 或 OnError 通知,甚至可以在觀察者請求任何項目之前發出此類通知。

不實作背壓的 Observable 應透過發出 OnError 通知來回應觀察者的 Request 通知,該通知表示不支援背壓。

請求是累計的。例如,如果觀察者分別向 Observable 發出三個 Request 通知,分別請求 3、5 和 10 個項目,則該 Observable 最多可以向觀察者發射 18 個項目,無論這些 Request 通知相對於 Observable 發射項目以回應的時間而言何時到達。

如果 Observable 生成的項目多於觀察者請求的項目,則由 Observable 決定是否要捨棄多餘的項目、儲存它們以便稍後發射,或者使用其他策略來處理溢位。

另請參閱