XuLaLa.Tech

随着公司业务规模的不断扩大和业务深度的不断扩展，是必会导致技术团队API的不断变化，当这一变化会破坏现有客服端集成时，如何管理API的接口将是一个极大的挑战。对API进行版本化当在API中识别出所需的更改时，版本控制可以帮助我们更快地迭代。

文章目录

• 1 何时版本化？
• 2 如何版本化？
  • 2.1 URI版本控制
  • 2.2 使用自定义请求标头进行版本控制
  • 2.3 使用“Accept” header

何时版本化？

• 一个或多个呼叫的响应数据格式的更改
• 请求或响应类型的更改（即将整数更改为浮点）
• 删除API的任何部分。

更新API的版本时要能够保证API之前的版本是可用的。

如何版本化？

API接口化通常有三种方式：

URI版本控制

使用URI是最直接的方法（也是最常用的方法），尽管它确实违反了URI应该引用唯一资源的原则。您还可以保证在更新版本时中断客户端集成。版本不需要是数字，也不需要使用“v[x]”语法指定。
备选方案包括日期、项目名称、季节或其他标识符，这些标识符对生产API的团队来说足够有意义，并且足够灵活，可以随着版本的变化而变化。

使用自定义请求标头进行版本控制

​ 自定义标头（例如Accept版本）允许您在不同版本之间保留URI，尽管它实际上是现有Accept标头实现的内容协商行为的副本。

使用“Accept” header

可以让您保留一组干净的URL，但您仍然需要处理在某个地方提供不同版本内容的复杂性。
这种负担往往会向上转移到API控制器上，这些控制器负责确定要发送的资源的版本。
结果往往是一个更复杂的API，因为客户端在请求资源之前必须知道要指定哪些标头。

Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0

在现实世界中，API永远不会完全稳定。因此，如何管理这种变化很重要。对大多数API来说，有充分的文档记录并逐步弃用API是可以接受的做法。