迁移

在切换之前映射各服务商之间的错误代码

在迁移中,成功响应获得了大部分关注,因为它们是演示所展示的内容,也是第一轮测试通常检查的内容。错误响应得到的关注则少得多,而这恰恰本末倒置,因为当提供商在应用底层发生变化时,错误处理代码往往是在生产环境中最先出问题、而且最显眼的部分。

每个地理编码和位置数据提供商都有自己表示失败的惯例:有些只使用 HTTP 状态码,有些在状态为 200 的 JSON 响应中嵌入一个 status 字段,有些用不同的代码区分“未找到结果”和“请求无效”,还有些则把两者合并为一个通用错误。应用的重试逻辑、面向用户的错误消息和监控告警,通常都是围绕某一个特定提供商的错误惯例构建的,有时根本没有人明确记录这种依赖关系。

在切换提供商之前,值得在旧提供商与新提供商的错误响应之间建立一张明确的映射表,至少涵盖:

  • 有效但无匹配的查询未找到结果,并与格式错误或无效的请求区分开来
  • 超出速率限制,以及响应中是否包含何时重试的信息
  • 认证失败,包括凭据过期、缺失或格式错误
  • 提供商一侧的服务器端错误,并与客户端请求错误区分开来
  • 您的代码按名称或编号明确检查的任何提供商特有状态值

My Geocode 在 /docs/errors/ 记录了其错误响应和状态惯例,并且每个响应都带有配额响应头:X-Quota-LimitX-Quota-UsedX-Quota-Free-RemainingX-Quota-Network-UsedX-Credits-RemainingX-Key-IPs-UsedX-Key-IPs-LimitX-Quota-Reset,它们涵盖了一类信息,即配额和速率状态,而有些提供商把这类信息埋在错误响应正文中,而不是直接在响应头中公开。检查您当前的重试逻辑是从响应正文还是从响应头中解析配额信息,是值得加入迁移检查清单的一个具体项目,因为基于响应头的配额信息通常更容易读取,而无需触及用于实际数据的响应解析路径。

建立映射表的一个实用方法,是在测试环境中针对新旧两个提供商刻意触发每一种错误情况,而不是只依赖文档,因为对任何提供商来说,文档与实际行为都不一定完全一致。发送一个格式错误的请求,刻意耗尽一个小的测试配额,再发送一个无效密钥,然后准确记录每个提供商在每种情况下返回的内容。

这类错误映射工作很少出现在迁移的项目计划中,因为它不会产生可见的功能,但它对迁移事后如何被人记住的影响却大得不成比例。一次干净地改变了成功响应、却让错误处理失灵的迁移,在切换后的最初几周内产生的支持工单,往往远多于一次只把理想路径部分做对的迁移。