WEEX WebSocket 重新連線:恢復訂單更新
WEEX WebSocket 重新連線:恢復訂單更新
WEEX WebSocket 斷線後,請使用新的時間戳記與簽章恢復私有連線,重新訂閱 orders,並確認訂閱成功。接著使用 REST 查詢,對帳中斷期間的訂單狀態,確認資料無誤後,再讓策略依賴這些資料。
例如,某筆訂單在斷線前仍處於開啟狀態,但可能已在重新連線前成交。光是收到新的更新,並不足以得知中斷期間發生的所有狀況。復原時必須同時處理連線問題,以及本機訂單紀錄與帳戶實際狀態之間可能存在的差異。
保留復原所需資訊
監控連線關閉、網路錯誤和心跳回應失敗的情況。發生中斷時,記錄最後一次成功接收資料的時間,並保留已知的訂單 ID、用戶端訂單識別碼和本機狀態。之後查詢訂單時會用到這些資訊。
將訂單狀態標記為等待對帳,並暫停需要完整資訊才能安全執行的自動化操作。使用設有上限的退避延遲並加入隨機抖動來重新連線,避免多個工作程序同時反覆嘗試。文件列出的限制包括每個 IP 每 5 分鐘最多發出 300 次連線請求、每個 IP 最多同時建立 20 個連線,以及每個連線每小時最多執行 240 次訂閱操作。設定退避參數時,請將這些限制納入考量。
為正確的私有連線重新驗證
訂單更新會使用相應產品的私有頻道:
| 產品 | 私有 WebSocket 位址 |
|---|---|
| 現貨 | wss://ws-spot.weex.com/v3/ws/private |
| 期貨 | wss://ws-contract.weex.com/v3/ws/private |
握手需要 User-Agent、ACCESS-KEY、ACCESS-PASSPHRASE、ACCESS-TIMESTAMP 和 ACCESS-SIGN。請使用毫秒時間戳記,並確保其值與簽章中的時間戳記一致。文件指出時間戳記會在 30 秒後過期,因此每次建立新連線時都要產生新的驗證資訊。
WebSocket 簽章訊息如下:
timestamp + "/v3/ws/private"使用 SecretKey 執行 HMAC-SHA256,然後將結果以 Base64 編碼,作為 ACCESS-SIGN。此處採用的是 WebSocket 簽章格式,而非完整的 REST 請求建構方式。連線詳情請參閱現貨 WebSocket 文件和期貨 WebSocket 文件。
重新訂閱 orders 並確認回覆
在新的私有連線上傳送以下請求:
{"method":"SUBSCRIBE","params":["orders"],"id":1}{"result":true,"id":1}透過 id 將回覆與訂閱請求配對;若失敗,請檢查 msg。這是請求識別碼,不是訂單 ID。若只記錄「WebSocket 已連線」,就會忽略連線成功後訂閱失敗的情況。
連線也需要處理 WEEX 應用程式層級的心跳。私有 ping 的格式如下:{"type":"ping","time":"1693208170000"};公有頻道則使用 event。文件列出的回覆如下:
{"method":"PONG","id":1}函式庫處理協定層級的 ping 和 pong,並不能取代對這些 JSON 訊息的處理。文件指出,若超過 10 次 ping 未收到回覆,伺服器就會中斷連線;但文件沒有提供通用的心跳間隔,因此無法據此計算固定的斷線時間。
透過 REST 進行對帳,包括已不再開啟的訂單
訂單事件開始恢復傳入時,先將事件暫存,同時查詢開啟中的訂單、訂單歷史紀錄,以及已知訂單的詳細資料。比對狀態、累計成交量和更新時間。這是用戶端處理中斷期間可能遺漏變更的一種復原方式;請勿假設伺服器會重新傳送所有歷史訊息。
| 待對帳資訊 | 現貨 GET 路徑 | 期貨 GET 路徑 |
|---|---|---|
| 開啟中的訂單 | /api/v3/openOrders | /capi/v3/openOrders |
| 訂單歷史紀錄 | /api/v3/allOrders | /capi/v3/order/history |
| 單筆訂單詳情 | /api/v3/order | /capi/v3/order |
只查詢開啟中的訂單會漏掉一種重要情況:訂單可能在中斷期間成交或取消,因此不再出現在查詢結果中。這就是為什麼復原流程必須納入訂單歷史紀錄,以及已知訂單的詳細資料。
請留意各端點的時間範圍、必填欄位和分頁方式。例如,現貨 allOrders 需要 symbol,期貨歷史紀錄則提供 page 和 limit。請遵循現貨歷史紀錄和期貨歷史紀錄的規則,在合併暫存事件前取得相關紀錄。
重複事件不應觸發重複的帳務處理或業務操作,較舊的事件也不應覆蓋較新的已確認狀態。如果 REST 與串流更新不一致,請再次查詢。訊息欄位 v 定義為帳戶版本;文件並未保證訂單序號連續,也未提供重播游標。因此,僅憑版本落差無法判斷是否遺漏訂單。
若仍未收到更新,請依症狀排查
| 症狀 | 檢查事項 |
|---|---|
握手回傳 403 | 檢查 User-Agent,再檢查其他驗證欄位。官方 FAQ 指出,防火牆會封鎖缺少此標頭的連線。 |
| 已連線,但未收到成功的訂閱確認 | 確認私有位址、orders 請求,以及確認回覆中是否有任何錯誤。 |
| 已訂閱,但沒有新的訂單事件 | 檢查心跳和帳戶是否有實際活動。如果沒有新的訂單變更,串流暫時沒有訊息也可能是正常情況。 |
| SDK 已重新連線,但本機狀態仍不一致 | 檢查中斷期間的 REST 對帳。自動重新連線並不代表訂單狀態已完成對帳。 |
復原期間,請勿將未收到回覆視為訂單失敗的證據,也不要重新送出所有訂單。先確認帳戶的實際狀態並解決差異,再恢復依賴該狀態的策略。
如需進一步協助,請透過官方 API FAQ中的支援連結聯絡我們,並提供連線時間、狀態碼和已清理敏感資訊的日誌,以便說明復原流程中止的位置。