RESTful API如何进行版本控制

Stella981
• 阅读 871

RESTful API如何进行版本控制

本文将帮助您理解为什么需要版本控制,以及如何对REST API进行版本控制。我们将讨论4种版本控制的方法,并比较不同的方法。

您将学到

  • 为什么我们需要对RESTful API 进行版本控制?

  • 可用的版本控制有哪些?

  • 如何实现基于 Restful 的版本控制?

为什么我们需要对RESTful API进行版本化

最好的版本控制方法是不进行版本控制。只要不需要版本控制,就不要版本控制。

构建向后兼容的服务,以便尽可能避免版本控制!

然而,在许多情况下我们都需要进行版本控制,然我们看看下面具体的例子:

最初,你有个这个版本的Student服务,返回数据如下:

{   "name": "Bob Charlie" }

后来,您希望将学生的名字拆分,因此创建了这个版本的服务。

{   "name": {     "firstName": "Bob",     "lastName": "Charlie"   } }

您可以从同一个服务支持这两个请求,但是随着每个版本的需求多样化,它会变得越来越复杂。

在这种情况下,版本控制就成必不可少,强制性的了。

接下来让我们创建一个简单的SpringBoot的maven项目,并理解对 RESTful 服务进行版本控制的4种不同方法。

`
 
  org.springframework.boot
  spring-boot-starter
 

 
  org.springframework.boot
  spring-boot-starter-web
 

 
  org.projectlombok
  lombok
 

 
  org.springframework.boot
  spring-boot-starter-test
  test
 


`

几个用于实现版本控制的Bean

第一个版本的 Bean

@Data @AllArgsConstructor public class StudentV1 {     private String name; }

第二个版本的 Bean

@Data public class StudentV2 {     private Name name; }

StudentV2使用的Name实体

@Data @AllArgsConstructor public class Name {     private String firstName;     private String lastName; }

Restful 版本控制的方法

我们希望创建两个版本的服务,一个返回 StudentV1,另一个返回 StudentV2。

让我们来看看创建相同服务版本的4种不同方法。

通过 URI 进行版本控制

`@RestController
public class StudentUriController {

    @GetMapping("v1/student")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping("v2/student")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }

}
`

请求:http://localhost:8080/v1/student

响应:{"name":"javadaily"}

请求:http://localhost:8080/v2/student

响应:{"name":{"firstName":"javadaily","lastName":"JAVA日知录"}}

通过请求参数进行版本控制

版本控制的第二种方法是使用请求参数来区分版本。请求示例如下所示:

  • http://localhost:8080/student/param?version=1

  • http://localhost:8080/student/param?version=2

实现方式如下:

`@RestController
public class StudentParmController {

    @GetMapping(value="/student/param",params = "version=1")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping(value="/student/param",params = "version=2")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }
}
`

请求:http://localhost:8080/student/param?version=1

响应:{"name":"javadaily"}

请求:http://localhost:8080/student/param?version=2

响应:{"name":{"firstName":"javadaily","lastName":"JAVA日知录"}}

通过自定义Header进行版本控制

版本控制的第三种方法是使用请求头来区分版本,请求示例如下:

  • http://localhost:8080/student/header

  • headers=[X-API-VERSION=1]

  • http://localhost:8080/student/header

  • headers=[X-API-VERSION=2]

实现方式如下所示:

`@RestController
public class StudentHeaderController {

    @GetMapping(value="/student/header",headers = "X-API-VERSION=1")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping(value="/student/header",headers = "X-API-VERSION=2")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }
}
`

下图展示了我们如何使用Postman执行带有请求头的Get请求方法。

请求:http://localhost:8080/student/header
header:X-API-VERSION = 1

RESTful API如何进行版本控制

请求:http://localhost:8080/student/header
header:X-API-VERSION = 2

RESTful API如何进行版本控制

通过媒体类型进行版本控制

最后一种版本控制方法是在请求中使用Accept Header,请求示例如下:

  • http://localhost:8080/student/produce

  • headers=[Accept=application/api-v1+json]

  • http://localhost:8080/student/produce

  • headers=[Accept=application/api-v2+json]

实现方式如下:

`@RestController
public class StudentProduceController {

    @GetMapping(value="/student/produce",produces = "application/api-v1+json")
    public StudentV1 studentV1() {
        return new StudentV1("javadaily");
    }

    @GetMapping(value="/student/produce",produces = "application/api-v2+json")
    public StudentV2 studentV2() {
        return new StudentV2(new Name("javadaily", "JAVA日知录"));
    }
}
`

下图展示了我们如何使用Postman执行带有请求Accept的Get方法。

请求:http://localhost:8080/student/produce
header:Accept = application/api-v1+json

RESTful API如何进行版本控制

请求:http://localhost:8080/student/produce
header:Accept = application/api-v2+json

RESTful API如何进行版本控制

影响版本选择的因素

以下因素影响版本控制的选择

  • URI 污染 - URL版本和请求参数版本控制会污染URI空间。

  • 滥用请求头 - Accept 请求头并不是为版本控制而设计的。

  • 缓存 - 如果你使用基于头的版本控制,我们不能仅仅基于URL缓存,你需要考虑特定的请求头。

  • 是否能在浏览器直接执行 ? - 如果您有非技术消费者,那么基于URL的版本将更容易使用,因为它们可以直接在浏览器上执行。

  • API文档 - 如何让文档生成理解两个不同的url是同一服务的版本?

事实上,并没有完美的版本控制解决方案,你需要根据项目实际情况进行选择。

下面列表展示了主要API提供商使用的不同版本控制方法:

  • 媒体类型的版本控制

  • Github

  • 自定义Header

  • Microsoft

  • URI路径

  • Twitter,百度,知乎

  • 请求参数控制

  • Amazon

以上,希望对你有所帮助!

End

干货分享

这里为大家准备了一份小小的礼物,关注公众号,输入如下代码,即可获得百度网盘地址,无套路领取!

001:《程序员必读书籍》
002:《从无到有搭建中小型互联网公司后台服务架构与运维架构》
003:《互联网企业高并发解决方案》
004:《互联网架构教学视频》
006:《SpringBoot实现点餐系统》
007:《SpringSecurity实战视频》
008:《Hadoop实战教学视频》
009:《腾讯2019Techo开发者大会PPT》

010: 微信交流群

近期热文top

1、关于JWT Token 自动续期的解决方案

2、SpringBoot开发秘籍-事件异步处理

3、架构师之路-服务器硬件扫盲

4、基于Prometheus和Grafana的监控平台 - 环境搭建

5、RocketMQ进阶 - 事务消息

RESTful API如何进行版本控制

我就知道你“在看”

RESTful API如何进行版本控制

本文分享自微信公众号 - JAVA日知录(javadaily)。
如有侵权,请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。

点赞
收藏
评论区
推荐文章
blmius blmius
3年前
MySQL:[Err] 1292 - Incorrect datetime value: ‘0000-00-00 00:00:00‘ for column ‘CREATE_TIME‘ at row 1
文章目录问题用navicat导入数据时,报错:原因这是因为当前的MySQL不支持datetime为0的情况。解决修改sql\mode:sql\mode:SQLMode定义了MySQL应支持的SQL语法、数据校验等,这样可以更容易地在不同的环境中使用MySQL。全局s
Easter79 Easter79
3年前
swap空间的增减方法
(1)增大swap空间去激活swap交换区:swapoff v /dev/vg00/lvswap扩展交换lv:lvextend L 10G /dev/vg00/lvswap重新生成swap交换区:mkswap /dev/vg00/lvswap激活新生成的交换区:swapon v /dev/vg00/lvswap
皕杰报表之UUID
​在我们用皕杰报表工具设计填报报表时,如何在新增行里自动增加id呢?能新增整数排序id吗?目前可以在新增行里自动增加id,但只能用uuid函数增加UUID编码,不能新增整数排序id。uuid函数说明:获取一个UUID,可以在填报表中用来创建数据ID语法:uuid()或uuid(sep)参数说明:sep布尔值,生成的uuid中是否包含分隔符'',缺省为
待兔 待兔
5个月前
手写Java HashMap源码
HashMap的使用教程HashMap的使用教程HashMap的使用教程HashMap的使用教程HashMap的使用教程22
Jacquelyn38 Jacquelyn38
3年前
2020年前端实用代码段,为你的工作保驾护航
有空的时候,自己总结了几个代码段,在开发中也经常使用,谢谢。1、使用解构获取json数据let jsonData  id: 1,status: "OK",data: 'a', 'b';let  id, status, data: number   jsonData;console.log(id, status, number )
Wesley13 Wesley13
3年前
mysql设置时区
mysql设置时区mysql\_query("SETtime\_zone'8:00'")ordie('时区设置失败,请联系管理员!');中国在东8区所以加8方法二:selectcount(user\_id)asdevice,CONVERT\_TZ(FROM\_UNIXTIME(reg\_time),'08:00','0
Wesley13 Wesley13
3年前
00:Java简单了解
浅谈Java之概述Java是SUN(StanfordUniversityNetwork),斯坦福大学网络公司)1995年推出的一门高级编程语言。Java是一种面向Internet的编程语言。随着Java技术在web方面的不断成熟,已经成为Web应用程序的首选开发语言。Java是简单易学,完全面向对象,安全可靠,与平台无关的编程语言。
Stella981 Stella981
3年前
Django中Admin中的一些参数配置
设置在列表中显示的字段,id为django模型默认的主键list_display('id','name','sex','profession','email','qq','phone','status','create_time')设置在列表可编辑字段list_editable
Wesley13 Wesley13
3年前
MySQL部分从库上面因为大量的临时表tmp_table造成慢查询
背景描述Time:20190124T00:08:14.70572408:00User@Host:@Id:Schema:sentrymetaLast_errno:0Killed:0Query_time:0.315758Lock_
Python进阶者 Python进阶者
10个月前
Excel中这日期老是出来00:00:00,怎么用Pandas把这个去除
大家好,我是皮皮。一、前言前几天在Python白银交流群【上海新年人】问了一个Pandas数据筛选的问题。问题如下:这日期老是出来00:00:00,怎么把这个去除。二、实现过程后来【论草莓如何成为冻干莓】给了一个思路和代码如下:pd.toexcel之前把这