1. 程式人生 > >Spring Boot入門系列(二十一)如何優雅的設計 Restful API 介面版本號,實現 API 版本控制!

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

說明:

 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

UserV1Controller

@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、啟動專案後,輸入相關地址,檢視版本控制是否生效

測試結果:

正確的介面地址

  

 

繼承的介面地址

說明:

  上圖的前兩個截圖說明,請求正確的版本地址,會自動匹配版本的對應介面。當請求的版本大於當前版本時,預設匹配當前版本。

  第三個截圖說明,當請求對應的版本不存在介面時,會匹配之前版本的介面,即請求/v2/user/extend 介面時,由於v2 控制器未實現該介面,所以自動匹配v1 版本中的介面。這就是所謂的版本繼承。

最後

以上,就把Spring Boot 如何優雅的設計 Restful API 介面版本號,實現 API 版本控制介紹完了。版本控制和許可權驗證是rest api 的基礎,雖然看著比較複雜,但是理解了,要實現還是比較簡單的。

這個系列課程的完整原始碼,也會提供給大家。大家關注我的微信公眾號(架構師精進),回覆:springboot原始碼。獲取這個系列課程的完整原始碼。

&n