追蹤 API 的可擴展性：如何處理旺季流量、速率限制及批量註冊
要在旺季擴展追蹤 API，請將貨件登記置於具持久性的佇列後方，在所有工作程式之間實施供應商限制，只在文件記載的限制內進行批次處理，並以非同步方式處理追蹤更新。將登記吞吐量、重試流量及 webhook 處理視為獨立的容量問題。在未控制對外請求的情況下增加工作程式，可能會加劇限流，而不是清空待處理佇列。
對於將訂單管理系統、倉庫平台或電子商務後端連接至追蹤服務的工程團隊而言，目標並不只是發送更多請求，而是在指定時間窗口內登記貨件、在流量高峰期間保留更新，並在不造成重複工作的情況下從故障中恢復。
圍繞貨件、請求及更新量化工作負載
每日貨件量不足以用作整合規模的依據。倉庫可能在短暫的出貨窗口內釋出大部分追蹤編號，而狀態更新則會在全天陸續到達。請將這些工作負載分開建模。
- 登記到達量：每秒或每分鐘進入系統的新貨件記錄，包括匯入及倉庫釋出高峰。
- 對外 API 流量：登記請求、查詢、修正、對賬呼叫及重試。
- 傳入更新流量：Webhook 傳送及重新傳送（如供應商支援）。
- 下游工作：由每次更新觸發的資料庫寫入、客戶通知、分析事件及訂單狀態變更。
設定內部登記目標，例如從收到追蹤編號到確認其完成登記之間可接受的最長時間。請將此目標與追蹤資料新鮮度分開：成功登記並不代表承運商掃描資料已經可用。
計算有效登記容量
對於受請求數量限制的登記端點，可使用以下規劃關係：
登記容量 = 每秒允許的請求數 × 每個請求的平均記錄數 × 成功記錄比例
這是規劃估算，而非供應商保證。其前提是假設請求限制是主要約束。以記錄為單位的配額、負載大小、延遲及共用帳戶限制，均可能造成更低的上限。
僅作示例，假設某整合每秒允許發出兩個登記請求，而每個請求平均傳送 30 個記錄。在失敗及其他限制因素出現之前，其名義容量為每秒 60 個記錄。如果持續高峰期間的傳入登記平均為每秒 80 個記錄，佇列便會以每秒約 20 個記錄的速度增長。這些數字僅為假設，並非 17TRACK 的限制。
同時也要計算恢復容量。如果新到達量持續為 λ，而有效處理容量為 μ，則當 μ > λ 時，現有的 B 個記錄待處理量約需 B / (μ − λ) 秒才能清空。如果處理容量沒有超過到達量，則在這些條件下待處理量不會清空。
確認供應商實際限制的內容
速率限制與使用配額解決的是不同問題。速率限制控制可以多快提交請求或記錄。使用配額則可能控制帳戶在計費或權益期間內可以消耗多少追蹤活動量。低於其中一項，並不代表符合另一項。
在設定工作程式數量之前，請根據供應商文件及帳戶條款確認以下事項：
- 限制適用於帳戶、API 金鑰、端點、IP 位址還是其他範圍。
- 計算單位是請求、追蹤記錄還是其他操作。
- 各端點是否共用限制，還是擁有獨立配額。
- 單個請求允許的最大記錄數及負載大小。
- 重複提交、無效記錄及重試如何影響使用量。
- 回應是否會提供限流資訊或重試指引。
- 配額耗盡與暫時限流有何不同。
對於 17TRACK 整合，請以官方 Tracking API 頁面及 API 文件作為此配置的起點。在部署前確認適用的端點行為及帳戶限制。本指南中的示例容量是架構示例，並非對 17TRACK 權益、批次大小或服務保證的說明。
在訂單處理與登記之間加入具持久性的佇列
不要讓結帳或倉庫完成流程等待追蹤供應商接受登記。將貨件持久化儲存於本地，可靠地記錄登記任務，並讓背景工作程式處理提交。
實際流程可以是：
- 儲存貨件及其登記意圖。使用交易型 outbox 或等效設計，避免訂單已儲存但背景任務遺失。
- 驗證及正規化輸入。將追蹤編號保留為字串，包括前導零。只有在有充分理由時，才套用承運商專屬的正規化處理。
- 檢查是否已有登記。使用適合供應商及資料模型的穩定識別碼。
- 將符合條件的記錄加入佇列。儲存嘗試次數、下一次符合重試資格的時間，以及足夠的診斷所需內容。
- 透過共用限流器提交。在對外請求前立即取得容量。
- 持久化儲存記錄層級結果。區分已確認成功、可重試失敗、永久拒絕及結果不明。
佇列可以吸收高峰，但不會創造供應商容量。如果其中最早符合條件的記錄持續變得更舊，應調查到達率與處理容量之間的差距，而不是單純增加工作程式數量。
協調各工作程式之間的限制
獨立工作的程式不應各自假設可以消耗完整的帳戶配額。使用協調式速率限制器，或使用分配共用請求預算的調度器。請將排程匯入、營運指令碼及對賬工作納入該預算。
速率與並行數是不同的控制項。限流器控制請求開始的頻率；並行上限控制同時處理中的請求數量。當供應商延遲上升時，兩者都很有用。增加並行數可能有助於受延遲限制的工作負載，但無法繞過對外速率限制。
使用批量登記，同時保留記錄層級控制
如果端點支援每個請求包含多個記錄，批次處理可以減少請求開銷。但它不一定會減少以記錄為單位的使用量，而允許的最大批次也不一定是最佳的營運選擇。
使用兩個觸發條件建立批次：最大記錄數及最長等待時間。任何一項達到時便提交。這樣，繁忙時段可以有效填滿批次，而低流量時段也不會被迫無限期等待。
- 同時遵守負載限制及記錄數限制。選用的中繼資料可能使記錄數相同的批次在位元組數上有很大差異。
- 保留內部批次清單。記錄已提交的本地貨件識別碼，並正確關聯每個返回結果。
- 檢查應用程式層級結果。HTTP 成功回應本身並不能證明每個記錄都已被接受。
- 只重試需要重試的記錄。重播已成功的記錄會造成不必要的流量，並可能帶來使用量影響。
- 將永久驗證失敗路由至修正流程。未變更的無效負載不應在重試佇列中循環。
逾時尤其重要：即使你的客戶端沒有收到回應，供應商仍可能已接受請求。將此結果標記為不明。透過支援的冪等機制、文件記載的重複登記規則，或在可用時進行對賬查詢來解決。不要假設逾時寫入必然失敗。
分開即時流量與歷史匯入
回填不應消耗新出貨貨件所需的全部容量。使用具加權排程或明確容量預留的獨立佇列。允許匯入使用閒置容量，同時為即時登記保留最低分配量。採用老化或其他公平規則，確保低優先級記錄最終得到處理。
讓重試受控、延遲且有上限
HTTP 429 代表「請求過多」。RFC 6585 指明，429 回應可能包含 Retry-After 標頭。RFC 9110 定義該標頭的值可以是 HTTP 日期或以秒為單位的延遲時間。客戶端應解析這兩種格式，而不是假設返回值必然是整數。
當提供有效的重試延遲時，請勿在延遲時間結束前重試。當沒有重試指引時，使用帶抖動的上限指數退避：逐步增加嘗試之間的延遲，並加入隨機性，避免所有工作程式同時重試。重試必須與首次嘗試一樣通過相同的對外限流器。
重試前先將失敗分類：
- 限流：延遲受影響的工作，並在相關限制範圍內降低調度壓力。
- 暫時性網絡或伺服器失敗：在有上限的策略內重試，同時考慮寫入結果不明的情況。
- 驗證或授權失敗：發出警報並暫停受影響的工作，直到憑證或權限得到修正。
- 驗證失敗：修正或隔離記錄，而不是原樣重新傳送。
- 配額耗盡：遵循文件記載的帳戶處理方法，而不是將其視為短暫流量高峰。
同時設定嘗試次數上限及最大重試期限。將耗盡重試次數的項目移至死信佇列，並附上原因、負責人及重播程序。否則，舊有失敗可能會悄悄消耗原本用於新貨件的容量。
獨立擴展 webhook 接收
如果供應商提供合適的 webhook，便可以減少重複輪詢狀態。它們也會產生獨立的傳入工作負載，必須在更新高峰期間保持可用。
讓接收端點專注於以下工作：使用供應商文件記載的機制驗證請求、可靠地儲存事件，並返回所需確認。非同步處理訂單變更、分析及客戶訊息。如果在可靠接受事件前回覆確認會有遺失事件的風險，則不要先確認接收。
除非供應商合約明確另有規定，否則應設計消費者以容忍重複傳送。優先使用文件記載的穩定事件識別碼進行去重。如果不存在，請仔細設計及測試複合識別碼：只使用狀態標籤可能會將不同事件錯誤合併為一個。
同時要防範亂序更新。將事件歷史與衍生出的目前貨件狀態分開儲存。在可用時，套用文件記載的事件時間戳及狀態轉換規則；不要假設到達順序就是事件順序，也不要假設貨件狀態必然以單調遞增的序列變化。
讓對賬工作有針對性並受到速率限制。它可以調查疑似傳送缺口或結果不明的登記，但積極輪詢每個貨件可能會重新造成原本 webhook 用來避免的對外負載。
測試恢復能力，而不只是最大吞吐量
使用供應商模擬器，針對自有元件進行負載測試。若測試會向實際供應商發送大量流量，請先協調安排，並遵守授權限制。成功的測試應證明系統在中斷後可以恢復正常，而不只是能夠接受大量突發流量。
- 重播倉庫式流量高峰，然後加入持續的正常流量。
- 注入限流回應、延遲升高及暫時性伺服器失敗。
- 模擬批次部分拒絕，以及伺服器端接受後發生逾時。
- 傳送重複及亂序的 webhook 事件。
- 中斷資料庫存取，並確認未接受的事件不會被錯誤確認。
- 在即時登記的同時執行回填，並檢查公平性。
- 重播死信項目，但不得繞過速率控制。
監察最早符合條件登記的年齡、接受延遲、記錄層級成功率、限流頻率、重試量、webhook 處理延遲及死信增長。單靠佇列深度並不足夠：大型佇列可能很快清空，而小型佇列可能包含少量反覆失敗但對業務至關重要的貨件。
在旺季前分配營運責任。工程團隊應負責調度控制及恢復工具；整合負責人應確認供應商權益；營運團隊應定義哪些貨件享有優先權。記錄何時暫停匯入、申請額外容量或調查遺失的更新。最強健的設計，是在流量超出即時處理容量時仍能保持可預測。
常見問題
增加 API 金鑰會提高吞吐量嗎？
不一定。多個金鑰可能共用帳戶層級配額。請與供應商確認限制範圍及允許的擴展方式。不要使用金鑰輪換來繞過限制。
每次登記都應使用最大可能批次嗎？
不應如此。較大的批次可以提高請求效率，但在低流量時等待填滿批次會增加延遲。使用文件記載的大小上限及刷新計時器，然後根據實際測量的接受延遲及失敗行為進行調整。
逾時後如何防止重複登記？
使用可靠的本地貨件識別碼，以及供應商文件記載的冪等或重複處理行為。如果結果仍不確定，請在支援的情況下先進行對賬，再重播請求。單靠本地去重無法證明遠端請求是否成功。
成功登記是否代表追蹤資料是最新的？
不是。登記接受、承運商事件可用性、供應商處理及你方更新處理是不同階段。請分開測量，避免將承運商掃描延遲誤認為登記佇列積壓。
團隊何時應申請更多供應商容量？
當預測到達量及所需恢復時間，在剔除可避免的重試、重複提交及低效批次處理後，仍超過已驗證的可用容量時，便應提出申請。更大的配額無法修復被阻塞的消費者或資料庫瓶頸，因此應先找出主要約束。
來源
- 17TRACK Tracking API — API 服務的官方入口。
- 17TRACK API 文件 — 用於查核整合要求、端點行為及適用請求限制的參考資料。
- RFC 6585，第 4 節：429 Too Many Requests — HTTP 限流語義及可選的 Retry-After 指引。
- RFC 9110，第 10.2.3 節：Retry-After — HTTP 日期及延遲秒數格式。
- RFC 9110，第 9.2.2 節：冪等方法 — 請求結果不確定時的重試考慮因素。
