實時追蹤請求逾時?請遵循重試、回退和狀態規則
當即時追蹤請求逾時時,應將貨件的最新狀態視為未知,而不是延遲、遺失或沒有變化。只可在限定的時間預算內重試,然後顯示清楚標示的最後已知更新,或要求用戶稍後再查。整個過程中,應始終將請求結果、數據的新鮮度及包裹的實際狀態分開處理。

這項區分對面向客戶的追蹤頁面,以及使用追蹤數據觸發通知或支援流程的系統都很重要。逾時只表示答案未能及時到達,並不表示承運商是否有新事件、上游服務是否已處理請求,或包裹是否已移動。
首先,確定是哪一部分逾時
追蹤請求可能在多個環節失敗:瀏覽器可能停止等待你的應用程式、你的應用程式可能停止等待追蹤 API,或者該 API 在聯絡另一項服務時可能逾時。用戶在每種情況下可能看到相同的概括錯誤,但適當的下一步行動各不相同。
- 客戶端逾時:應用程式停止等待,但伺服器端請求可能仍已完成。在發出可能造成重複工作的另一個請求前,先檢查你自己的請求日誌或結果儲存區。
- 網絡或連線失敗:你的系統未收到可用回應。你可能不知道遠端服務是否已處理請求。
- HTTP 504:閘道或代理未能及時收到上游伺服器的回應。這描述的是請求路徑,而不是貨件。
- HTTP 408:伺服器未能在其準備等待的時間內收到完整請求訊息。這不是承運商追蹤狀態。
- HTTP 200 但事件較舊:請求成功,但返回的追蹤資訊可能仍然過時。成功的 HTTP 回應並不保證數據是最新的。
將這些結果記錄為請求診斷資訊。不要將其中任何一項轉換為「運送中」、「異常」或「已送達」等貨件標籤。這些標籤應來自追蹤事件或有文件記錄的狀態欄位,而不是傳輸層。
使用有上限的重試,而不是無限循環
對於唯讀追蹤查詢,逾時後重試通常是合理的,但仍應設有限制。重複請求可能增加處於壓力下的服務負載、延長用戶等待時間,並在多個應用程式層獨立重試時造成重複工作。
- 設定總期限。決定面向用戶的操作最多可花多少時間,包括初次嘗試及任何重試。不要讓每次嘗試都重新獲得完整期限,超出呼叫方可等待的時間。
- 確認操作是否可安全重複。查詢通常不同於登記貨件、更改設定或建立資源的請求。除非供應商合約或你的冪等性控制措施確保安全,否則不要自動重播會改變狀態的請求。
- 謹慎重試暫時性故障。使用小而明確的重試預算,並加入帶有抖動的延遲,而不是讓多個客戶端同時立即重試。
- 遵守適用的伺服器指示。如果回應包含有效的
Retry-After標頭,不要安排更早的重試。同時也要遵守更嚴格的應用程式或供應商特定限制。 - 期限或預算耗盡時停止。切換至後備回應;如果工作流程需要,則另外安排稍後核對。
實際設計可以在剩餘時間足夠時允許一次面向用戶的重試,並將進一步嘗試移至背景更新。這只是政策示例,不是通用 API 規則。應根據服務水平目標、觀察到的延遲及供應商文件選擇限制。同時也要計算 HTTP 程式庫、閘道及工作執行器進行的重試;否則看似適度的應用程式政策可能產生大量上游呼叫。
對於 HTTP 429,應將回應視為速率限制訊號,而不是立即重試的理由。HTTP 503 可能表示暫時無法處理請求,伺服器也可能提供 Retry-After。504 可能是暫時性的,但不保證下一次嘗試會成功。驗證錯誤通常需要檢查憑證或權限,而格式錯誤的請求則需要修正輸入。對於產生「找不到」結果的追蹤識別碼,需要更加謹慎:視乎供應商記錄的行為及貨件階段,可能只是查找記錄為時過早,也可能是識別碼錯誤。不要因為一次這樣的結果,就斷言包裹不存在。
選擇保留已知資訊的後備方案
最安全的後備方案通常是最後一次已驗證的追蹤結果,並附上其事件時間及誠實的新鮮度標籤。將該結果與目前的請求失敗分開。一個頁面可以寫:「最新可用更新:已離開設施。最後檢查時間:[時間]。目前暫時無法取得更新。」只有在系統確實記錄「最後檢查時間」時才加入;它不能代替承運商事件時間。
使用你能夠支持的最精確時間。承運商事件時間描述事件據報發生的時間;系統收到該事件的時間描述數據接收時間;用戶開啟頁面的時間則兩者都不是。如果來源沒有可靠的事件時間或時區,避免自行編造。同樣,如果快取結果沒有記錄取得時間,應稱為「最後可用更新」,而不是聲稱它最近曾更新。
後備方案應遵守三項界線:
- 將快取數據顯示為快取數據。不要將較舊事件呈現為逾時請求的結果。
- 不要根據經過的時間推斷進度。包裹不會僅因為已運送數天,就變成「派送中」。
- 不要隱藏重大不確定性。如果沒有先前結果,應說明追蹤暫時無法使用,而不是顯示虛構的預設狀態。
其他後備路徑可以包括先前同步的追蹤儲存區、獲授權的承運商查詢,或稍後的背景更新。只有在它們適合該貨件、你的權限及數據來源條款時才使用。第二個來源可能有不同的事件名稱或報告延遲,因此應保留來源資料;如沒有相應規則,不要合併互相衝突的記錄。如果客戶可以根據結果採取行動,應提供重試或聯絡支援的方法,而不是讓載入指示器無限顯示。
分開處理請求狀態、數據新鮮度及貨件狀態
這是三個不同欄位,即使使用者介面將它們一同顯示。請求狀態表示查詢是否成功、逾時或收到錯誤。數據新鮮度表示返回或儲存的資訊是在何時觀察到的。貨件狀態表示追蹤來源報告包裹的情況。將它們分開,可防止暫時的 API 故障覆蓋有效的送達事件,或將過時的運送中事件變成當前聲明。
例如,系統可能在較早查詢中保存已驗證的「已送達」事件,而目前更新逾時。送達事件不會消失。正確的組合狀態是:最後可用的貨件狀態為已送達,而最新更新失敗。相反,如果最後事件是「運送中」,逾時並不能確認包裹此刻仍在運送中;它只確認未能取得較新的答案。
當事件以錯誤次序到達時,應套用既定規則。在可行時比較事件識別碼、時間戳記、來源及供應商記錄的狀態語義。不要假設系統接收更新的次序就是貨件事件發生的次序。較遲到達的舊事件也不應自動取代較新的已驗證狀態。不過,修正及例外可能是合法的,因此不要訂立一刀切規則,認為送達後不可能再改變狀態。保留底層事件,並調查矛盾,而不是悄悄改寫歷史。
如果供應商返回 HTTP 202,應按照該端點的合約解讀:接受請求本身並不代表追蹤查詢已完成。同樣,HTTP 200 表示在該端點的語義下 HTTP 請求成功,但不代表每個追蹤欄位都存在或是最新的。只有查閱供應商文件後,才映射供應商特定的回應欄位。
讓營運人員看見故障,但不要令客戶恐慌
有用的營運記錄包括請求 ID、端點或操作、嘗試次數、經過時間、逾時層級、收到的 HTTP 狀態(如有),以及回應來自即時查詢還是後備方案。對於追蹤數據,記錄來源及相關事件或取得時間戳記。應按照組織的存取及保留規則處理追蹤號碼和客戶資訊;診斷用途並不是在不受限制的日誌中暴露完整識別碼的理由。
應觀察模式,而不是依賴單次逾時。某條承運商路線的逾時率上升、反覆收到 429 回應,或承運商事件時間與取得時間之間的差距擴大,可能分別指向不同問題。第一種可能需要調查供應商,第二種可能需要流量控制,第三種可能需要檢查同步或事件傳送。如果應用程式透過如 17TRACK Tracking API 的供應商提供追蹤功能,應在實施這些一般規則前,使用該供應商的文件核實端點特定回應欄位、請求限制及錯誤處理。
面向客戶的訊息應精確而克制:「我們目前無法更新追蹤資訊。以下是最新可用更新。」在有幫助時提供下一步,例如稍後再查;如果貨件已超過賣家或承運商提供的預期派送時間,也可聯絡支援。避免承諾系統無法保證的更新時間。
可安全應對逾時的追蹤流程發布檢查清單
- 確認每個逾時由哪一層施加,以及哪一層負責重試。
- 設定總請求期限及獨立、有上限的重試預算。
- 確認自動重試的操作可以安全重複。
- 遵守速率限制及有效的
Retry-After指示。 - 將請求結果與貨件狀態及事件歷史分開儲存。
- 標示後備數據,並在可用時保留其來源及時間戳記。
- 測試無快取、過時快取、429、503、504 及延遲回應情況。
- 確認逾時不會觸發錯誤的送達通知或刪除已驗證事件。
基本規則很簡單:只有在安全且有用時才重試請求;只使用你能識別的資訊作為後備;永遠不要根據 HTTP 逾時作出貨件狀態聲明。
常見問題
我應否立即重試逾時的追蹤請求?
不要自動重試。先確認操作可以安全重複、整體期限仍留有足夠時間進行另一次嘗試,以及沒有速率限制指示要求等待。對於唯讀查詢,短暫且有上限並帶抖動的重試可能合適;反覆立即重試不是良好預設做法。
HTTP 504 是否表示承運商的追蹤系統已停止運作?
不是。它表示閘道或代理未能及時收到上游回應。問題可能出現在該請求路徑的任何位置。這不能證明承運商整體是否可用,也不能證明包裹的狀況。
逾時後可以顯示最後已知狀態嗎?
可以,但要標示為最新可用資訊,而不是成功的即時更新。在已知時顯示事件時間及取得時間,並清楚說明無法確認較新的更新。
逾時是否應將貨件從「運送中」改為「異常」?
不應。逾時是請求失敗,而不是貨件事件。只有在可信的追蹤來源提供支持該變更的事件或狀態時,才更改貨件狀態。
如果逾時的請求正在建立或登記追蹤記錄,怎麼辦?
不要假設它已失敗。遠端系統可能在回應遺失前已處理請求。再次提交前,先檢查是否已有結果,並使用有文件記錄的冪等機制或供應商批准的恢復程序。
來源
- RFC 9110, HTTP 語義 — HTTP 狀態定義、
Retry-After及重試請求的考慮事項。 - RFC 6585, 額外 HTTP 狀態碼 — HTTP 429 的定義及其與
Retry-After的使用。 - Amazon Builders’ Library,「逾時、重試及帶抖動的退避」 — 關於重試放大、退避及抖動的工程指引。
- 17TRACK Tracking API 文件 — 在實施前核實供應商特定 API 行為的參考資料。


