下线旧 API 的正确方式

大家好。

在开始今天的介绍之前，想跟大家介绍一个定律：隐式接口定律。

API 可以认为是我们对外承诺的开放能力，而接口中对应的字段都有相应的作用，但是使用方并不一定会按提供方提供的使用方式进行使用，而这就会造成 API 在迁移或者下线过程中并没有那么容易。

当你在工作中需要更换或者下线一个新的 API，而这个 API 能够更好的解决之前 API 提供的能力，那如何安全可靠的更换这个 API，同时不对你的调用方造成损害呢？

以下是一个可供参考的处理方式：

1、做好计划

首先先思考几个问题，你是否有对 API 的调用方做监控，如果没有则加上；监控是否显示已经没有调用方在调用了，如果是就没必要做 API 的下线计划了，直接下线即可。

另外要下线的 API 的功能是否能通过新的 API 满足，如果可以，则可直接进行相应的转换，避免下线和迁移。

如果以上情况都不是，那你就需要做一个 API 下线计划，计划需要考虑以下三个核心问题：

a、你希望调用方做哪些改动？比如更新为其他 API、使用其它替代服务等。

b、调用方需要什么时候开始迁移 API？你推荐的迁移方式已经准备就绪了吗？

c、迁移的截止时间是？

2、与调用方沟通

通过公开的方式通知你的调用方，方式可以是文档、邮件、社交网络等。另外一个就是你需要在你的 API 中声明 API 已经不推荐使用（Deprecation）了。比如 HTTP 的调用，可以在 HEADER 中加入如下字段：

3、渐进式关闭 API

到这一步已经过了你之前声明的截止时间，而你也不需要立马将 API 进行关闭，因为可能有部分调用方错过了迁移的截止时间。而渐进式的关闭 API 只是给这些调用方最后一次迁移的机会，当然你最开始做计划的时候要考虑这部分时间。

渐进式关闭 API 的方式一般是降低 API 的一些服务能力，让调用方能够感知到。

比如在 2018 年 GitHub 采用的一种方式是先关闭 API 一小时，然后再恢复，然后彻底在两周后关闭。

2015 年 Android 通过逐步将 API 的调用时长增加到 16 秒的方式逐步关闭 API。

4、最终关闭，删除代码

到这步就完成了整体的 API 下线工作，可以完成代码删除了。

以上就是全部介绍，希望能对你有所帮助。

开源书籍&资料：点击

开源 Go/Java/Python 趋势：点击

点如下卡片后台回复：1，与我交流开源项目&小程序开发等内容。