RESTAPI 版本控制策略【eolink 翻译】

微服务，是现阶段开发建设云原生应用程序的流行趋向。API 版本控制有益于在辨别出所需要的调节时加速迭代更新的速度。

根据微服务架构的关键构件其一，是 API 的设计和规范。针对 API，版本控制是不可或缺的，它能使企业客户能不断运用现阶段有的 RESTAPI ，并在他们做好充分的准备时将他们的应用程序转移到一个新的 API 。

何时要更新新版本？

版本控制帮我们在 API 中启用中断的变化，譬如根据导进强制参数对申请格式实现的调节、响应消息的格式调节或结构优化对响应数据实现的调节，或是不兼容使用 API 来供应加强的作用。

怎么对RESTAPI进行版本控制

有5种不同的方法能做到。

• 根据URI相对路径实现版本控制

• 根据查看参数实现版本控制

• 根据自定义header实现版本控制

• 根据内容讨论实现版本控制

• 根据API管理工具实现版本控制

版本根据URI路径

是为端点实现版本控制的最常见的方法其一。版本无须都是数字，或是 v[x] 格式，您可以用其他的有意义的标识符，如数据或版本号，这有益于 API 生产团队无缝地合并一个新的调节。

http://api.example.com/v1

根据查看参数实现版本控制

另外一种选择是运用版本当做查看参数，这样的方法简单容易实现，除了确立规定的版本，不然我们能够将最新的 API 版本设置成初始版本。

如：

http://api.example.com/customers?version=v1

根据自定义 header 实现版本控制

我们还能根据自定义表头实现版本控制。这有益于防止对 URI 实现其他的填充。

@RestController

@RequestMapping("/")

public class ProductController {

@Autowired
 private ProductRepository repository;

@GetMapping(value= "products", headers = {"X-API-VERSION=v1"})
public List<Product> findAll() {
       return repository.findAll();
 }

 @GetMapping(value= "products", headers = {"X-API-VERSION=v1"})
 public List<Product> findAllV2() {
       return repository.findAll();
 }
}

这样的方法的仅有的主要缺点是它要维护一个 header 以运用 header 的版本和处理。

根据内容讨论实现版本控制

这样的方法能协助企业客户运用 AcceptHeader 专门申请1个版本。倘若客户端不申请相应版本，则能实现服务以供应初始表示。

GET /customers/1234 HTTP/1.1 接受：application/vnd.v1+json
	@RestController
@RequestMapping("/")
public class ProductController {

 @Autowired
 private ProductRepository repository;

    // Find
    @GetMapping(value= "products", headers = {"Accept=application/vnd.v1+json"})
    List<Product> findAll() {
        return repository.findAll();
    }

    @GetMapping(value= "products", headers = {"Accept=application/vnd.v2+json"})
    List<Product> findAllV2() {
        return repository.findAll();
    }

 }

如此一来，我们就开启了包含 Accept 报头的2个版本的 GET/productsendpoint 。当运用 header 值的 v1发出 curl 申请时，响应将根据版本 v1 。

curl -L -X GET 'http://localhost:8080/products' \ -H 'Accept: application/vnd.v1+json'

[    

{      

 "name": "IdeaPad Slim 5 (15, AMD)"  

  } 

]

当运用 header 值的 v2 发出 curl 申请时，响应将根据 v2 版本。

	 curl -L -X GET 'http://localhost:8080/products' \
-H 'Accept: application/vnd.v2+json'

[
{
    "name": "IdeaPad Slim 5 (15, AMD)"
 }
]

当未成功发送 Accept 报头时，它将响应默认版本，就是这里的 v1 版本。

curl -L -X GET 'http://localhost:8080/products'
[
{
    "name": "IdeaPad Slim 5 (15, AMD)"
}
]
	406 Not Acceptable
curl -L -X GET 'http://localhost:8080/products'
-H 'Accept: application/vnd.v3+json'

{
"timestamp": "2021-09-13T14:30:12.263+0000",
"status": 406,
"error": "Not Acceptable",
"message": "Could not find acceptable representation",
"path": "/products"
}

借助 API 管理工具实现版本控制

如今市场上有许多API管理工具，能做到数据可视化实现版本控制，程序流程还都较为简单，像 Eolink：www.eolink.com ， 由于有自动备份更改历史的功能，只要构建版本号，给不一样的更改历史绑定版本号，就能做到版本控制， API 修改后还会自动同步到相匹配版本的接口文档里。

总结

伴随着 API 驱动架构的飞速发展和越来越多的人使用，最重要的是对 API 实现版本控制，以最大程度地降低 API 更改所产生的影响并具备更佳的向后兼容性。以上所述每一种版本控制技术都各有利弊，因此我还是强烈推荐用 API 管理工具 Eolink 。