Monite 的 API 版本管理

Monite 的 API 版本管理

我们都喜欢拥有闪亮的新工具，但却厌烦不断更新它们的麻烦。这适用于所有东西：操作系统、应用程序、API、Linux 包。代码因为更新而停止工作是痛苦的，尤其是当更新并不是我们主动发起时，更是双倍的痛苦。

在 Web API 开发中，每次更新都可能破坏用户的代码。如果你的产品是 API，那么这些更新每次都可能令人恐惧。Monite 的主要产品是我们的 API 和白标 SDK。作为一家以 API 为核心的公司，我们非常注重保持 API 的稳定性和易用性。因此，避免 破坏性更改 是我们优先考虑的问题之一。

一个常见的解决方案是向客户发布弃用警告，并且尽量少发布破坏性更改。突然之间，你的发布可能需要几个月时间，有些功能必须隐藏或甚至在下一个版本发布之前不能合并。这会减缓开发进度，并迫使用户每隔几个月就更新他们的集成。

如果你加快发布频率，用户将不得不频繁更新他们的集成。如果你延长发布间隔，你的公司将发展较慢。你为用户制造的麻烦越多，对你来说就会越方便，反之亦然。这显然不是最优的方案。我们希望以自己的节奏前进，而不破坏现有客户的系统，这在常规的弃用方法下是不可能实现的。这就是为什么我们选择了另一种解决方案：API 版本管理。

这是一个相当简单的想法：在任何时间发布破坏性更改，但将它们隐藏在一个新的 API 版本下。这样你可以享受到两全其美的好处：用户的集成不会被经常破坏，而你可以以任何你喜欢的速度前进。用户可以在他们愿意的时候迁移——没有任何压力。

考虑到这个想法的简单性，它似乎适合任何公司。这是你在典型的工程博客中会期待阅读的内容。遗憾的是，这并不简单。

警惕成本

API 版本管理是困难的，非常困难。其虚假的简单性在你开始实施时很快就会消失。遗憾的是，互联网从未真正警告你，因为关于这个话题的资源惊人地少。绝大多数资源讨论了将 API 版本放在哪里，但只有少数文章尝试回答：“我们如何实施它？”常见的方法包括：

• 将不同版本的相同 Web 应用程序放入单独的部署中
• 复制在版本间发生更改的单个路由
• 为每个版本复制整个版本化应用程序

单独的部署可能非常昂贵且难以维护，复制单个路由在大规模更改时扩展性不好，而复制整个应用程序会产生大量额外代码，几乎会在几个版本后淹没你。

即使你尝试选择最便宜的方法，版本管理的负担也会很快显现。起初，它会显得简单：在这里添加另一个模式，在业务逻辑中添加另一个分支，最后复制几个路由。但随着版本的增加，你的业务逻辑将迅速变得无法管理，你的开发人员可能会混淆应用程序版本和 API 版本，甚至开始对数据库中的数据进行版本管理，从而使你的应用程序变得难以维护。

你可能希望同时不会有超过两个或三个 API 版本；你可以每隔几个月删除旧版本。如果你只支持少量的内部消费者，这是真的。但来自组织外部的客户不会喜欢被迫每隔几个月就升级一次的体验。

API 版本管理很快可能成为你基础设施中最昂贵的部分，因此在此之前进行细致的研究是至关重要的。如果你只支持内部消费者，那么使用 GraphQL 这样的工具可能会简单一些，但它也可能迅速变得和版本管理一样昂贵。

如果你是一家初创公司，建议将 API 版本管理推迟到开发的后期阶段，当你有资源来做好它时。在此之前，弃用和 增量更改策略 可能足够了。你的 API 可能不会总是表现出色，但至少你可以通过避免明确的版本管理来节省大量资金。

我们如何实施 API 版本管理？

经过几次试验和许多错误后，我们处于十字路口：我们之前提到的版本管理方法维护成本太高。由于我们的挣扎，我制定了以下要求，作为一个完美版本管理框架所需的条件：

1. “维护大量版本很容易” 以确保版本管理不会减缓我们的功能开发
2. “删除旧