當外部 API 延遲時，如何讓 XAUUSD 儀表板仍然可用？

資料型 Web 介面有一個很容易被忽略的問題：資料不一定會在同一時間更新，也不一定每次都能成功取得。

我目前正在開發一個 XAUUSD 黃金資料儀表板，將 MT5、MQL5、Windows Server VPS、Python、WordPress REST API 與前端 JavaScript 串接在一起。這次想分享的不是交易策略，而是當其中一個資料來源延遲或暫時失敗時，如何避免整個介面變成空白。

專案頁面：<copi-tools.com/zh-ha...>

即時，不代表所有資料同時更新

價格資料可能需要較頻繁更新，但新聞、市場背景與技術分析不需要每幾秒重新取得。

如果所有區塊共用一個計時器，會產生幾個問題：

• 價格更新時，新聞也被重複請求

• 一個 API 失敗，整個頁面可能一起顯示錯誤

• 歷史 K 線每次都重新下載，增加資料傳輸量

• 使用者正在閱讀某個區塊時，內容突然被整個替換

因此，我把資料依照更新速度和資料特性分開處理。價格、圖表歷史、新聞、分析與市場背景可以各自擁有不同的更新週期。

我如何區分資料狀態

在前端顯示資料之前，我希望先區分以下幾種狀態：

最新資料

資料在預期時間內成功更新，可以正常顯示最新內容。

快取資料

最新資料暫時無法取得，但系統仍然有上一次通過檢查的有效資料。這時可以保留畫面，並讓使用者知道內容可能不是最新狀態。

更新延遲

資料來源仍然存在，但超過預期時間沒有更新。這和完全沒有資料不同，應該用不同的提示方式處理。

沒有可用資料

系統沒有任何可以安全顯示的內容，這時才顯示明確的空狀態或錯誤訊息。

如果把這些狀態都當成同一種空白畫面，使用者很難判斷到底是資料還在更新、暫時發生錯誤，還是系統根本沒有資料。

保留最後一次正常內容

這個專案目前採用的主要原則是：新資料通過檢查以前，不要先清空舊資料。

在伺服器端，新的行情或分析結果如果格式不完整，就不要覆蓋原本有效的內容。在瀏覽器端，fragment request 失敗時，也先保留目前已經顯示的區塊。

這不代表要隱藏錯誤。系統仍然應該記錄失敗原因，前端也可以顯示「更新延遲」或「目前使用快取資料」等狀態。重點是把錯誤通知和破壞畫面分開處理。

從 MT5 到 WordPress 的資料檢查

`exness-send-price-sw...5` 在 MT5 環境中取得 XAUUSD 的 M1 K 線，再透過 HTTP POST 傳送到 WordPress 的 `gold-bars` API。

接收資料時，需要檢查 symbol、timeframe、時間戳記，以及 open、high、low、close 等欄位。即使 HTTP response 是成功狀態，也不能假設所有欄位都符合預期。

另一個 `gold-analysis-export...5` 流程會輸出 OHLC、EMA、RSI、ATR、MACD 與 Bollinger Bands 等分析資料。VPS 上的 Python 排程讀取 JSON，呼叫 Gemini API 後，先檢查回傳的欄位與格式，再將結果傳送到 `gold-analysis` API。

這樣可以避免分析 API 暫時回傳不完整內容時，直接影響 WordPress 儲存資料或前端畫面。

前端為什麼不直接清空畫面？

前端更新時，我會先取得新資料，檢查 response 和基本結構，再在暫存區完成渲染。只有在新內容可以正常顯示時，才替換目前畫面上的 fragment。

如果請求失敗，則保留目前內容，讓其他區塊繼續運作。比如新聞 API 暫時失敗時，價格圖表仍然可以使用；分析資料延遲時，也不需要讓整個頁面一起消失。

對資料型介面來說，這種 fail-soft 設計比「任何錯誤都顯示空白卡片」更容易讓使用者理解系統目前的狀態。

外部分析結果也需要檢查

AI 回傳的文字即使看起來完整，也不代表它符合程式需要的格式。

因此，在保存分析結果以前，至少要檢查：

• 回應是否存在

• 必要欄位是否存在

• 每個欄位的資料型別是否正確

• symbol 和時間範圍是否符合請求

• 內容是否可以安全地顯示在目前語言介面

如果檢查失敗，應該標記為分析暫時無法使用，而不是自行補上缺少的欄位，或將不完整的回應當成正式結果。

目前的限制

這個流程仍然有可以改善的地方：

• 為每一種 REST payload 建立更明確的 schema

• 統一 MQL5、Python、WordPress 與 JavaScript 的錯誤代碼

• 顯示快取資料的實際更新時間

• 增加不完整 OHLC 與分析回應的測試案例

• 強化 VPS 排程失敗時的重試與通知

Gold Dashboard 目前主要用於資料整理、技術研究與 Web 介面實作展示。資料可能存在延遲、缺漏或暫時無法更新的情況。本專案不提供投資建議、交易訊號、自動交易或獲利保證。

結語

資料更新失敗不一定代表整個頁面都必須停止運作。

把資料來源拆開、在每個系統邊界進行驗證、保留最後一次正常內容，並清楚區分最新資料、快取資料、延遲資料與無資料狀態，可以讓資料型 Web 介面在不完美的網路環境中仍然保持可用。

如果你也有開發 dashboard 或其他資料型 Web 工具，想請教你通常如何處理以下問題：

• API 暫時失敗時，你會保留舊資料多久？

• 你會如何讓使用者知道畫面上的資料可能已經過期？

• 對於外部分析結果，你會在哪一層進行格式驗證？