發行與同步
紀錄如何從 Apple 健康走到你的伺服器、各狀態是什麼意思,以及 Courier 對時機 的承諾(與坦白不承諾的部分)。
觸發源
- 背景投遞 —— Apple 健康收到新睡眠/運動,iOS 短暫喚醒 Courier,讀取 增量並發行。
- 打開 App —— 啟動與回到前景時的前景同步。
- 手動 —— App 內的發行操作,或捷徑的立即發行。
- 批次發行 —— 編輯部 → 批次發行:選日期區間,向任意訂戶補發歷史。
四個入口匯入同一條管線。
項目狀態
每條對外紀錄走一個顯式狀態機,狀態會持久保存——強制結束或重新啟動也不會 失憶:
| 狀態 | 含義 |
|---|---|
queued | 排隊等候 |
awaitingRoute | 戶外運動的 GPS 軌跡還沒從手錶到齊——Courier 寧可等,也不發殘缺紀錄 |
sending | 請求傳送中 |
sent | 已送達(2xx),記入台帳 |
failed | 失敗且你已知悉——永不自動重試,只能手動重發 |
needsAttention | 失敗/不全且未知悉:重試耗盡、軌跡久等不到、或來源資料消失。紅點 + 通知 |
重試
- 前景發行對網路錯誤做指數退避重試(2 s → 4 s → 8 s → 16 s)。
- 背景發行只做單次嘗試、15 秒逾時——iOS 背景時間珍貴,Courier 不賭。 失敗直接排進待處理。
- 一旦進入
failed,絕不自動重試——重發什麼、何時重發,由你掌控。
冪等
每次請求都攜帶 Idempotency-Key 標頭:
- 正常傳送與手動重發用紀錄穩定的 canonical
id——只要端點依鍵去重,同一次 運動無論重試多少遍都只會入庫一次。 - 刻意的複本(「再發一份」)會輪換鍵為
id#2、id#3……讓遵守冪等語意的 端點也能收下你故意要的副本。
只要你的伺服器尊重 Idempotency-Key(或依 data.id upsert),整條管線在 任何環節重試都是安全的。
台帳
編輯部 → 發行台帳記錄每一次發行:時間、訂戶、HTTP 狀態與回應摘要。台帳保留 6 個月,更早的自動清理——送達的內容本身,當然一直在你的端點上。
關於時機,說實話
背景投遞受 iOS 節流。正常延遲幾分鐘到一小時左右,最壞情況要等你下次 打開 App。Courier 在介面文案裡如實說明,而不是假裝立即送達。需要立刻發出? 打開 App,或執行立即發行捷徑。
通知
兩檔(編輯部 → 通知):
- 始終通知 —— 每輪自動發行後給一條彙總,無論成敗。預設。
- 僅失敗時 —— 平時安靜,出事才響。
通知需要系統權限;若在系統層被拒,Courier 會顯示真實狀態並給出前往系統設定的 入口——而不是假裝開關有效。