迁移

迁移服务器端集成而不改动客户端

设计良好的后端架构有一个很令人愉快的特性:提供商迁移可以完全在内部 API 边界之后进行,对使用您服务的任何 Web 或移动客户端都不可见。能否做到这一点,与要迁移到的具体提供商关系不大,更多地取决于在迁移开始之前,这个边界是否已经在您的代码库中干净地存在。

关键的设计原则是:客户端应用,包括 Web 前端、移动应用和其他内部服务,应当与您自己的 API 通信,由它返回您自己的规范化响应结构,而不是直接与第三方地理编码提供商通信,或者接收直接透传的该提供商的原始响应结构。当这个边界存在时,提供商迁移只会涉及您自己端点背后的实现,而该端点的每个使用方都不会受到影响,这是设计使然,而不是运气。

如果这个边界还不存在,也就是说客户端目前确实接收某个特定提供商的原始响应格式,那么迁移正是引入它的合适时机,即使这会在前期增加一些额外工作。步骤大致如下:

  1. 定义您自己的规范化响应格式,选择对您的应用有意义的字段名称,而不是照搬某个特定提供商的惯例
  2. 构建从当前提供商的实际响应到该规范化格式的内部映射,并更新每个客户端,使其使用规范化格式,而不是提供商的原始响应
  3. 一旦每个客户端都已更新为使用规范化格式并完成部署,这个边界之后的实际提供商迁移就变成了仅涉及后端的更改,完全不需要与客户端协调

第一次这样做确实工作量更大,但在之后的每次迁移中都会得到回报,因为今后任何提供商变更都只需要第 3 步。

由于 My Geocode 的兼容主机保留了熟悉的提供商的确切响应结构,尚未构建这一规范化层的团队可以把兼容主机作为过渡步骤,无需重写现有的映射代码,从而争取时间在以后妥善构建规范化层,而不会因为紧迫的截止日期被迫现在就匆忙做出一个版本。兼容主机概览介绍了所有可用的兼容主机。

后端服务本身的认证支持 X-API-Key 请求头、Authorization: Bearer 请求头、HTTP Basic 认证或查询参数,您可以选择最符合后端现有出站请求惯例的方式。每次调用都可以通过响应头看到配额用量,相关文档见 /docs/rate-limits/,您的后端可以集中监控这些信息,而任何客户端都无需知道配额这一概念的存在。

对客户端不可见的服务器端迁移并不是什么特殊技巧,它只是一个已经具备合理边界的架构的自然结果。即使在迁移压力之下,构建这个边界也是值得的投资,正是因为它让此后的每次迁移都不再需要与客户端协调。