细说RESTFul API之版本管理

Posted 2022-05-27 nuccch

目录

• 接口实现版本管理的意义
• 如何实现接口的版本管理
• 项目实战

接口实现版本管理的意义

API版本管理的重要性不言而喻，对于API的设计者和使用者而言，版本管理都有着非常重要的意义。
首先，对于API的设计和实现者而言，需要考虑向后兼容性，但是随着业务的发展或需求的变更往往会导致兼容性实现非常复杂，因此引入API版本管理将能解决这个尴尬。此时可以提供多个版本的API实现，不需要再为了向后兼容性而绞尽脑汁。
其次，对于API的使用者而言，也可以灵活选择使用不同版本API，而不用担心API的兼容性问题。

如何实现接口的版本管理

对API进行版本管理目前已经有许多成熟的做法，比如：将版本信息放在URL中，或者放在HTTP消息头中，甚至可以放在URL参数或者消息体中（将版本信息放在HTTP消息头里，版本信息作为URL参数或放在消息体中这三种方式无本质区别）。不同的版本管理方式实现难易程度各异，各有利弊。

• 将版本信息放在URL中虽然破坏了REST的架构风格，但是因版本不同而带来的变化在URL中就能体现，更加直观。
• 将版本信息方在HTTP请求头，URL参数甚至消息体中，好处是保持URL不变，但是API实现者需要解析传递的版本参数调用不同的实现方法。

项目实战

在基于Spring MVC（如Spring Boot）的项目中使用将版本信息放在URL中的方式进行版本管理，这样做是基于如下几点考虑：

1. API的变化直接在URL中体现，直观明了，也不用解析版本参数。
2. 对应不同版本的URL可能需要传递不同的参数，这样对于API实现者而言是在不同的Controller方法中解析的，不用考虑在解析请求参数时的兼容性，实现简单；而且从设计模式上可以实现拥抱变化。
3. Spring MVC框架对于在URL中体现版本信息这种方式原生支持就比较好，不需要做其他适配工作。

【参考】
https://segmentfault.com/a/1190000006165182 RESTful API版本控制策略
http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/ How are REST APIs versioned?
https://blog.csdn.net/hengyunabc/article/details/20506345 Web API 版本控制的几种方式
https://juejin.im/post/5a0bd3e3f265da431047eabf 怎么做 Web API 版本控制？