android项目api版本控制,对API进行版本控制的重要性和实现方式

最新推荐文章于 2024-08-09 04:19:27 发布

cyx 22

最新推荐文章于 2024-08-09 04:19:27 发布

阅读量247

点赞数

文章标签： android项目api版本控制

我在API设计中收到的最多见问题之一就是如何对API进行版本控制。虽然并不是全部API都彻底相同，但我发如今API版本控制方面，某些模式和实践适用于大多数团队。我已经将这些内容收集起来，下面将提供一些关于版本控制策略的建议，该策略将帮助大多数API提供商，不管他们是向内部署API，仍是对外的API。git

API版本真的那么重要吗？

API是你与API使用者之间创建的纽带。正常状况下，大家之间的纽带不会轻易的断开。纽带包括URI模式，有效负载结构，字段和参数名称，预期行为以及其余内容。这种方法的最大好处是显而易见的：API使用者的理解不会变动，应用程序能够保证持续有效。github

可是，永久不变是不现实的。有时由于业务变化，你可能须要对API进行重大改变。发生这种状况时，最好的方式是，你确保不会作任何会致使API使用者修复代码的事情。json

打破与不间断的变化

非破坏性变动每每就像是“添加剂”，通常是添加新字段或嵌套资源到资源陈述，又或是增长新的端点，如PUT或PATCH。API使用者从一开始应该构建可以适应这些非破坏性更改的客户端代码。后端

突破性变化包括：

1.名字段或资源路径，一般在API发布后为了统一命名规范。api

2.更改有效负载结构，通常是适应如下内容：app

a.重命名或删除字段

b.将字段从单个值更改成一对多关系(好比从一个账户的一个电子邮件地址移动到这个账户的电子邮件地址列表)。

c.修改了API的URL，致使返回结果不一致的状况。

简而言之，一旦你将API对外公开发布，你就必须保持它是可用的而且不会影响到使用者的。若是您遇到多个项目，则须要对API进行版本控制，以防止破坏现有的API使用者。编辑器

定义API版本策略

任何不断发展变化的API都须要API版本控制策略。你的API版本能够适应根据API使用者的指望而切换不一样版本变得有所不一样。我一般建议将如下API版本控制策略做为总体API管理系统的一部分。工具

1.若是你的API处于早期测试版本中，为了得到消费者的反馈，请创建您的API可能会发生变化的正确指望。在此阶段内，你会保留这个版本一段时间，由于你的API设计可能还会更改。做为消费者，API是不稳定的，所以他们应该预期到可能会发生的变化。测试

2.一旦发布，你的API应被视为契约，若是没有新版本，则不能被替换。设计

3.不间断的更改会致使次要版本出现问题，客户端会自动迁移到最新版本，不会出现任何负面反作用。

4.突破性的变化意味着客户必须迁移到此新版本，由于它包含一个或多个重大更改。你必须与API使用者创建适当的时间表并按期沟通，以确保他们能方便地迁移到新版本。但在某些状况下，这可能没法立刻实现，因此你的团队将会被要求暂时性支持之前的API版本。

什么时候必须实现API版本控制

一旦肯定须要新版本的API，就须要知道如何处理它。实现API版本控制有三种经常使用方法。

1.资源版本控制

该版本是HTTP请求中Accept标头的一部分，例如，Accept:application/vnd.github.v3+json 发送到GET /customers。这考虑了许多版本控制的首选形式，由于资源在版本化的同时须要保持URI相同。若是未在Accept标头中提供，某些API会选择提供最新版本做为默认版本。

2.URI版本控制

该版本是URI的一部分，做为前缀或后缀，例如，/v1/customers 或/customers/v1。虽然URI版本控制不如基于内容的版本控制那么精确，但它每每是最多见的，由于它适用于不支持自定义标头的各类工具。缺点是资源URI随每一个新版本而变化，有些人认为这与拥有永不改变的URI的意图背道而驰。

3.主机名版本控制

该版本是主机名的一部分而不是URI，例如，https://v2.api.myapp.com/customers。当技术限制阻止基于URI或Accept标头到API的正确后端版本时，将使用此方法。

备注：不管您选择哪一个选项，API版本都只应包含主要编号。不须要小数字(即 /v1/customers，不是/v1.1/customers)。

实现版本控制的工具

使用工具和技术能够从根本上实现API版本控制过程。用市场上优秀的API编辑器将使技术开发团队可以在更短的时间内生成并切换更多的API版本，从而不断改进设计决策。

结合工具进行版本控制是大多数开发过程的重要组成部分。API设计领域中也有这种能版本控制的工具，实际上，全球范围内API服务领域中已经存在一些优秀的Web API设计工具。

如今，如EOLINKER、RAML、Swagger，都提供了出色的编辑工具来支持他们的语言。EOLINKER采用的是版本对比和重点标注提示，能够清晰的切换、对比。RAML、Swagger采用的是版本切换，方便程度可能略逊一点。并且只有前者是支持中文的，后两种只支持英文语言。这些API编辑器都能轻松地实现API版本的控制，使得更容易在更短的时间内切换运行版本。