Spring Boot入门系列（二十一）如何优雅的设计 Restful API 接口版本号，实现 API 版本控制！

前面介绍了Spring Boot 如何快速实现Restful api 接口，并以人员信息为例，设计了一套操作人员信息的接口。不清楚的可以看之前的文章：https://www.cnblogs.com/zhangweizhong/category/1657780.html。

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

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

一、为什么加版本号

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

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

• http://localhost:8080/api/v1/user
• http://localhost:8080/api/v2/user

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;
}