Skip to main content
首页博客指南实时跟踪请求超时?请遵循重试、回退和状态规则

实时跟踪请求超时?请遵循重试、回退和状态规则

17TRACK

当实时跟踪请求超时时,应将货件的最新状态视为未知,而不是延迟、丢失或未发生变化。仅在限定的时间预算内重试,随后显示明确标注的最近已知更新,或请用户稍后再试。在整个过程中,始终将请求结果、数据的新鲜度与包裹的实际状态分开处理。

实时跟踪请求超时、重试、回退与状态

这一点对于面向客户的跟踪页面,以及使用跟踪数据触发通知或支持流程的系统都很重要。超时只表示答案未能及时返回。它无法说明承运商是否有新的事件、上游服务是否处理了请求,或包裹是否已经移动。

首先,确定发生超时的环节

跟踪请求可能在多个环节失败:浏览器可能停止等待你的应用程序,你的应用程序可能停止等待跟踪 API,或者该 API 在联系其他服务时可能超时。用户在每种情况下看到的可能都是相同的通用错误,但适当的后续操作各不相同。

  • 客户端超时:应用程序停止等待。服务器端请求可能仍已完成。在发起可能导致重复处理的另一个请求之前,请检查你自己的请求日志或结果存储。
  • 网络或连接失败:你的系统未收到可用响应。你可能无法知道远程服务是否处理了该请求。
  • HTTP 504:网关或代理未能及时从上游服务器收到响应。这描述的是请求路径,而不是货件状态。
  • HTTP 408:服务器未能在准备等待的时间内收到完整的请求消息。这不是承运商跟踪状态。
  • HTTP 200 with an old event:请求成功,但返回的跟踪信息可能仍已过时。成功的 HTTP 响应并不保证数据是最新的。

将这些结果记录为请求诊断信息。不要将其中任何一种结果转换为“运输途中”“异常”或“已送达”等货件标签。这些标签应来自跟踪事件或有文档说明的状态字段,而不是传输层。

使用有界重试,而不是无限循环

对于只读跟踪查询,超时后重试通常是合理的,但仍应受到限制。重复请求可能增加故障服务的负载、延长用户等待时间,并在多个应用层分别重试时造成重复处理。

  1. 设置总截止时间。确定面向用户的操作最长可以持续多久,包括初始尝试和任何重试。不要为每次尝试重新分配一个完整的截止时间,使总时间超过调用方能够等待的时长。
  2. 检查操作是否可以安全重复。查询通常不同于注册货件、更改设置或创建资源的请求。除非服务提供商的契约或你的幂等性控制能够确保安全,否则不要自动重放会改变状态的请求。
  3. 谨慎重试瞬时故障。使用较小且明确的重试预算,并加入带抖动的延迟,而不是让许多客户端同时立即重试。
  4. 遵守适用的服务器指令。如果响应包含有效的 Retry-After 标头,不要安排更早的重试。同时也要遵守更严格的应用程序或服务提供商特定限制。
  5. 截止时间或预算耗尽时停止。切换到回退响应;如果工作流需要,另行安排稍后的对账或重新同步。

一种实际设计可以是在剩余时间足够时允许一次面向用户的重试,同时将后续尝试转移到后台刷新。这只是策略示例,并非通用 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 是否意味着承运商的跟踪系统宕机?

不是。它表示网关或代理未能及时收到上游响应。问题可能出现在该请求路径上的任何位置。它不能证明承运商整体是否可用,也不能说明包裹的状况。

超时后可以显示最近已知状态吗?

可以,但应将其标注为最新可用信息,而不是成功的实时刷新结果。在已知时显示事件时间和获取时间,并明确说明无法确认更新的信息。

超时是否应将货件从“运输途中”改为“异常”?

不应。超时是请求失败,而不是货件事件。只有当可信的跟踪来源提供支持该变更的事件或状态时,才应更改货件状态。

如果超时的请求是在创建或注册跟踪记录,该怎么办?

不要假设它失败了。远程系统可能在响应丢失前已经处理了请求。在再次提交之前,请检查是否已有结果,并使用有文档记录的幂等机制或服务提供商批准的恢复流程。

来源