SpringBoot入门到精通(二十一)如何优雅的设计 RESTful API 接口版本号,实现 API 版本控制!

简介: 有些人可能会问,为什么我看到很多公司的api接口文档里面,都有/api/v1/ 这样的地址呢?其实,/api 就是为了和一般的业务地址区分,标明这个地址是api 的接口。v1 则代表版本号。可能很多人又会问了,为什么要版本号呢?那么,接下来就聊一聊Restful 接口为什么要加版本号? 如何优雅的设计 Restful API 接口版本号?

前面介绍了Spring Boot 如何快速实现Restful api 接口,并以人员信息为例,设计了一套操作人员信息的接口。

有些人可能会问,为什么我看到很多公司的api接口文档里面,都有/api/v1/ 这样的地址呢?其实,/api 就是为了和一般的业务地址区分,标明这个地址是api 的接口。v1 则代表版本号。

可能很多人又会问了,为什么要版本号呢?那么,接下来就聊一聊Restful 接口为什么要加版本号? 如何优雅的设计 Restful API 接口版本号?

 

一、为什么加版本号

一般来说,api 接口是提供给其他系统或是其他公司使用,不能随意频繁的变更。然而,需求和业务不断变化,接口和参数也会发生相应的变化。如果直接对原来的接口进行修改,势必会影响线其他系统的正常运行。这就必须对api 接口进行有效的版本控制。

例如,添加用户的接口,由于业务需求变化,接口的字段属性也发生了变化而且可能和之前的功能不兼容。为了保证原有的接口调用方不受影响,只能重新定义一个新的接口。

 

Api 版本控制的方式:

  1、域名区分管理,即不同的版本使用不同的域名,v1.api.test.com,v2.api.test.com

  2、请求url 路径区分,在同一个域名下使用不同的url路径,test.com/api/v1/,test.com/api/v2

  3、请求参数区分,在同一url路径下,增加version=v1或v2 等,然后根据不同的版本,选择执行不同的方法。

实际项目中,一般选择第二种:请求url路径区分。因为第二种既能保证水平扩展,有不影响以前的老版本。

 

二、Spring Boot如何实现

实现方案:

1、首先创建自定义的@APIVersion 注解和自定义URL匹配规则ApiVersionCondition。

2、然后创建自定义的 RequestMappingHandlerMapping 匹配对应的request,选择符合条件的method handler。

 

1、创建自定义注解

首先,在com.weiz.config 包下,创建一个自定义版本号标记注解 @ApiVersion。

package com.weiz.config;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
 * API版本控制注解
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
    /**
     * @return 版本号
     */
    int value() default 1;
}

说明:

ApiVersion 为自定义的注解,API版本控制,返回对应的版本号。

 

2、自定义url匹配逻辑

创建 ApiVersionCondition 类,并继承RequestCondition 接口,作用是:版本号筛选,将提取请求URL中版本号,与注解上定义的版本号进行比对,以此来判断某个请求应落在哪个controller上。

在com.weiz.config 包下创建ApiVersionCondition 类,重写 RequestCondition,创建自定义的url匹配逻辑。

package com.weiz.config;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import javax.servlet.http.HttpServletRequest;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public class ApiVersionCondition implements RequestCondition<ApiVersionCondition> {
    private final static Pattern VERSION_PREFIX_PATTERN = Pattern.compile(".*v(\\d+).*");
    private int apiVersion;
    ApiVersionCondition(int apiVersion) {
        this.apiVersion = apiVersion;
    }
    private int getApiVersion() {
        return apiVersion;
    }
    @Override
    public ApiVersionCondition combine(ApiVersionCondition apiVersionCondition) {
        return new ApiVersionCondition(apiVersionCondition.getApiVersion());
    }
    @Override
    public ApiVersionCondition getMatchingCondition(HttpServletRequest httpServletRequest) {
        Matcher m = VERSION_PREFIX_PATTERN.matcher(httpServletRequest.getRequestURI());
        if (m.find()) {
            Integer version = Integer.valueOf(m.group(1));
            if (version >= this.apiVersion) {
                return this;
            }
        }
        return null;
    }
    @Override
    public int compareTo(ApiVersionCondition apiVersionCondition, HttpServletRequest httpServletRequest) {
        return apiVersionCondition.getApiVersion() - this.apiVersion;
    }
}

当方法级别和类级别都有ApiVersion注解时,二者将进行合并(ApiVersionRequestCondition.combine)。最终将提取请求URL中版本号,与注解上定义的版本号进行比对,判断url是否符合版本要求。

 

3、自定义匹配的处理器

在com.weiz.config 包下创建 ApiRequestMappingHandlerMapping 类,重写部分 RequestMappingHandlerMapping 的方法。

package com.weiz.config;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import java.lang.reflect.Method;
public class ApiRequestMappingHandlerMapping extends RequestMappingHandlerMapping {
    private static final String VERSION_FLAG = "{version}";
    private static RequestCondition<ApiVersionCondition> createCondition(Class<?> clazz) {
        RequestMapping classRequestMapping = clazz.getAnnotation(RequestMapping.class);
        if (classRequestMapping == null) {
            return null;
        }
        StringBuilder mappingUrlBuilder = new StringBuilder();
        if (classRequestMapping.value().length > 0) {
            mappingUrlBuilder.append(classRequestMapping.value()[0]);
        }
        String mappingUrl = mappingUrlBuilder.toString();
        if (!mappingUrl.contains(VERSION_FLAG)) {
            return null;
        }
        ApiVersion apiVersion = clazz.getAnnotation(ApiVersion.class);
        return apiVersion == null ? new ApiVersionCondition(1) : new ApiVersionCondition(apiVersion.value());
    }
    @Override
    protected RequestCondition<?> getCustomMethodCondition(Method method) {
        return createCondition(method.getClass());
    }
    @Override
    protected RequestCondition<?> getCustomTypeCondition(Class<?> handlerType) {
        return createCondition(handlerType);
    }
}

 

4、配置注册自定义的RequestMappingHandlerMapping

重写请求过处理的方法,将之前创建的 ApiRequestMappingHandlerMapping 注册到系统中。

package com.weiz.config;
import org.springframework.boot.autoconfigure.web.servlet.WebMvcRegistrations;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
@Configuration
public class WebMvcRegistrationsConfig implements WebMvcRegistrations {
    @Override
    public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {
        return new ApiRequestMappingHandlerMapping();
    }
}

上面四步,把api 版本控制配置完了。代码看着复杂,其实都是重写spring boot 内部的处理流程。

 

三、测试

配置完成之后,接下来编写测试的控制器进行测试。

1、在Controller/api 目录下,分别创建UserV1Controller 和 UserV2Controller

@RequestMapping("api/{version}/user")
@RestController
public class UserV1Controller {
    @GetMapping("/test")
    public String test() {
        return "version1";
    }
    @GetMapping("/extend")
    public String extendTest() {
        return "user v1 extend";
    }
}
UserV2Controller
@RequestMapping("api/{version}/user")
@RestController
@ApiVersion(2)
public class UserV2Controller {
    @GetMapping("/test")
    public String test() {
        return "user v2 test";
    }
}

 

2、启动项目后,输入相关地址,查看版本控制是否生效

测试结果:

v1正常的接口地址:/api/v1/user/test

image.png


v2正常的接口地址:/api/v2/user/test

image.png

v2继承的接口地址:/api/v2/user/extend

image.png

说明:

  上图的前两个截图说明,请求正确的版本地址,会自动匹配版本的对应接口。当请求的版本大于当前版本时,默认匹配当前版本。

  第三个截图说明,当请求对应的版本不存在接口时,会匹配之前版本的接口,即请求/v2/user/extend 接口时,由于v2 控制器未实现该接口,所以自动匹配v1 版本中的接口。这就是所谓的版本继承。


最后

以上,就把Spring Boot 如何优雅的设计 Restful API 接口版本号,实现 API 版本控制介绍完了。版本控制和权限验证是rest api 的基础,虽然看着比较复杂,但是理解了,要实现还是比较简单的。

这个系列课程的完整源码,也会提供给大家。大家关注我的微信公众号(架构师精进),回复:springboot源码。获取这个系列课程的完整源码。




推荐阅读:

SpringBoot从入门到精通(二十)快速构建RESTful Web API 服务

SpringBoot从入门到精通(十九)使用注解实现动态Sql、参数传递

SpringBoot从入门到精通(十八)Mybatis系列之——使用注解的方式实现后台管理功能

SpringBoot从入门到精通(十七)MyBatis系列之——创建自定义mapper 实现多表关联查询!

SpringBoot从小白到精通(十六)使用pagehelper实现分页查询功能

SpringBoot从小白到精通(十五)实现开发环境热部署

SpringBoot从小白到精通(十四)使用JdbcTemplate操作数据库,配置多数据源!

SpringBoot从小白到精通(十三)如何实现事务保存

SpringBoot从小白到精通(十二)logback日志配置

SpringBoot从小白到精通(十一)统一异常处理

SpringBoot从小白到精通(十)使用Interceptor拦截器,一学就会!

SpringBoot从小白到精通(九)使用@Async实现异步执行任务

SpringBoot从小白到精通(八)熟悉@EnableScheduling,一秒搞定定时任务

SpringBoot从小白到精通(七)使用Redis实现高速缓存架构

SpringBoot从小白到精通(六)使用Mybatis实现增删改查【附详细步骤】

SpringBoot从小白到精通(五)Thymeleaf的语法及常用标签

SpringBoot从小白到精通(四)Thymeleaf页面模板引擎

SpringBoot从小白到精通(三)系统配置及自定义配置

SpringBoot从小白到精通(二)如何返回统一的数据格式

SpringBoot从小白到精通(一)如何快速创建SpringBoot项目

 

相关文章
|
19天前
|
缓存 安全 API
RESTful与GraphQL:电商API接口设计的技术细节与适用场景
本文对比了RESTful与GraphQL这两种主流电商API接口设计方案。RESTful通过资源与HTTP方法定义操作,简单直观但可能引发过度或欠获取数据问题;GraphQL允许客户端精确指定所需字段,提高灵活性和传输效率,但面临深度查询攻击等安全挑战。从性能、灵活性、安全性及适用场景多维度分析,RESTful适合资源导向场景,GraphQL则适用于复杂数据需求。实际开发中需根据业务特点选择合适方案,或结合两者优势,以优化用户体验与系统性能。
|
21天前
|
JSON 编解码 API
Go语言网络编程:使用 net/http 构建 RESTful API
本章介绍如何使用 Go 语言的 `net/http` 标准库构建 RESTful API。内容涵盖 RESTful API 的基本概念及规范,包括 GET、POST、PUT 和 DELETE 方法的实现。通过定义用户数据结构和模拟数据库,逐步实现获取用户列表、创建用户、更新用户、删除用户的 HTTP 路由处理函数。同时提供辅助函数用于路径参数解析,并展示如何设置路由器启动服务。最后通过 curl 或 Postman 测试接口功能。章节总结了路由分发、JSON 编解码、方法区分、并发安全管理和路径参数解析等关键点,为更复杂需求推荐第三方框架如 Gin、Echo 和 Chi。
|
4月前
|
XML JSON API
Understanding RESTful API and Web Services: Key Differences and Use Cases
在现代软件开发中,RESTful API和Web服务均用于实现系统间通信,但各有特点。RESTful API遵循REST原则,主要使用HTTP/HTTPS协议,数据格式多为JSON或XML,适用于无状态通信;而Web服务包括SOAP和REST,常用于基于网络的API,采用标准化方法如WSDL或OpenAPI。理解两者区别有助于选择适合应用需求的解决方案,构建高效、可扩展的应用程序。
|
4月前
|
机器学习/深度学习 设计模式 API
Python 高级编程与实战:构建 RESTful API
本文深入探讨了使用 Python 构建 RESTful API 的方法,涵盖 Flask、Django REST Framework 和 FastAPI 三个主流框架。通过实战项目示例,详细讲解了如何处理 GET、POST 请求,并返回相应数据。学习这些技术将帮助你掌握构建高效、可靠的 Web API。
|
5月前
|
搜索推荐 API 开发者
淘宝买家秀API接口(淘宝API系列)
淘宝买家秀API接口为电商运营和产品分析提供宝贵数据,反映消费者真实反馈。通过HTTP GET请求,开发者可获取商品的买家秀信息,包括图片、文字描述、点赞数等,帮助商家改进产品和优化营销策略。Python示例代码展示了如何调用该接口并处理返回数据。需在淘宝开放平台注册并申请权限。
|
4月前
|
JSON API 开发者
1688店铺所有商品API接口(1688API系列)
1688店铺所有商品API接口允许开发者通过输入店铺ID,获取指定店铺内的全部商品信息,包括名称、价格、库存、图片和销售数据等。该接口支持排序和分页参数,返回JSON格式数据,便于解析和应用。Python示例展示了如何使用requests库发送GET请求并处理响应,助力电商数据分析与业务拓展。
|
5月前
|
自然语言处理 数据挖掘 API
淘宝直播间弹幕 API 接口(淘宝 API 系列)
淘宝直播间弹幕API助力电商直播数据分析与优化。通过实时获取弹幕信息(昵称、内容、时间、类型),商家可精准把握消费者需求,优化直播内容;开发者可构建数据分析工具和智能客服系统。接口采用WebSocket协议,支持全双工通信,确保数据实时性。请求需包含直播间ID(room_id),并遵循平台使用规范。示例代码展示了Python调用方法,需安装`websocket-client`库并处理重连与异常。
|
5月前
|
JSON API 开发者
淘宝淘口令转换API接口(淘宝API系列)
淘宝淘口令转换API是用于将淘宝商品或店铺链接与淘口令进行双向转换的接口,支持HTTP POST请求。开发者可通过此API生成或解析淘口令,方便在不同平台传播淘宝内容,吸引更多潜在客户。API返回JSON格式数据,包含转换结果和状态信息。使用前需注册并申请权限,确保调用稳定可靠。示例代码展示了如何通过Python实现淘口令的生成和解析功能。
|
4月前
|
JSON API 数据安全/隐私保护
1688 商品详情API接口(1688API 系列)
1688 商品详情 API 接口是电商应用开发中的关键工具,尤其适用于整合 1688 平台的商品数据。该接口提供商品的基础属性、价格、库存、图片、描述及商家信息等多维度数据,支持 HTTP GET 和 POST 请求方式。通过必填的商品 ID 及可选的语言参数等,开发者能精准获取并展示商品详情,提升用户体验和决策效率。响应数据包括商品名称、类目、品牌、价格区间、库存、图片列表、详细描述及商家信息等,帮助技术员高效集成接口,实现与 1688 平台的无缝对接。供稿者:Taobaoapi2014。
|
5月前
|
JSON API 开发者
小红书商品详情API接口(小红书API系列)
小红书商品详情API接口帮助开发者获取平台上特定商品的详细信息,包括标题、价格、图片、描述、评价数量等。支持HTTP GET/POST请求,返回JSON格式数据。通过传递商品ID及其他可选参数,开发者可以将小红书的商品信息整合到自己的应用中,提供更丰富的购物体验。Python示例代码展示了如何使用requests库发送GET请求并处理响应数据。实际使用需替换为真实接口地址和商品ID,并遵循平台认证要求。