ASP.NET Core 3.x API版本控制

前言

通常來講須要更改咱們API的時候才考慮版本控制，可是我以爲咱們不該該等到那時候來實現它，咱們應該有一個版本策略從咱們應用程序開發時就開始制定好咱們的策略，咱們一直遵循着這個策略進行開發。

咱們其實能夠經過多種方式進行實現咱們API版本的控制，其實對於版本控制沒有最好的方式，這徹底取決於咱們面向的使用者。

API版本控制類型

安裝版本控制包

Install-Package Microsoft.AspNetCore.Mvc.Versioning

在Startup.cs中的ConfigureServices方法中進行版本設置，以及在控制器經過特性進行設置版本，這樣能夠實現版本控制。

services.AddApiVersioning(options => {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

• options.DefaultApiVersion = new ApiVersion(1,0): 這個設置不是必須的，由於默認狀況下給咱們設置的是1.0，可是顯式的聲明出來是一個很好的習慣，固然DefaultApiVersion它會將默認的[ApiVersion("1.0")]添加到控制器上，也就是說它會隱式的綁定API版本，可是爲了咱們方便理解或者說方便咱們後面開發建議顯式的設置。
• options.AssumeDefaultVersionWhenUnspecified = true:默認API版本控制須要將其屬性設置爲true才能夠開啓
• options.ReportApiVersions = true:默認狀況下它是禁用的，啓用此選項後，來自咱們API端點的響應將帶有標頭，告訴咱們的客戶端支持或不推薦使用哪一個版本(api-supported-versions:1.1,2.0, api-deprecated-versions:1.0)

默認提供了四種版本控制方法：

• 字符串參數
• 經過HTTP請求頭
• URL方式
• 媒體類型（Media Type）

默認方法是使用名爲api-version 的查詢字符串參數。咱們還能夠本身定義一個版本控制規則。

API版本約束方式

• 字符串參數形式

services.AddApiVersioning(options => 
    options.ApiVersionReader = new QueryStringApiVersionReader("v"));

• HTTP請求頭

services.AddApiVersioning(options => 
    options.ApiVersionReader = new HeaderApiVersionReader("api-version"));

• 組合方式

services.AddApiVersioning(options => {
    options.ApiVersionReader = ApiVersionReader.Combine(
        new QueryStringApiVersionReader("v"),
        new HeaderApiVersionReader("v"));});

• URL方式

services.AddApiVersioning(options => options.ApiVersionReader = 
    new UrlSegmentApiVersionReader());

咱們能夠更改表明版本的參數名稱（例如，在上面的查詢字符串方法中，咱們使用字母v代替默認的api-version）。

控制器和方法中添加版本信息

選擇版本控制策略並在ConfigureServices方法中對其配置後，咱們能夠開始對API端點進行版本控制，咱們能夠將這些屬性應用於控制器和方法。

• 控制器的默承認能沒有任何API版本屬性，並隱式配置的默認API版本。默認配置使用值1.0。
• 使用[ApiVersion("1.0")]屬性註釋咱們的控制器，意味着該控制器支持API版本1.0
• 控制器能夠支持多個API版本。只需[ApiVersion(...)]在控制器上應用多個屬性
• 爲了區分控制器支持的多個版本，咱們使用[MapToApiVersion()]屬性註釋控制器方法。

若是要使用URL路徑則能夠參考以下代碼片斷：

[Route("api/v{version:apiVersion}/[controller]")]

API控制器棄用，咱們只須要設置

[ApiVersion("1.0", Deprecated = true)]

可經過以下方法方式獲取全部API版本信息

var apiVersion = HttpContext.GetRequestedApiVersion();

固然他還支持模型綁定，咱們還能夠經過模型形式獲取

[HttpGet]
   public string Get(ApiVersion apiVersion) => $"Controller = {GetType().Name}\nVersion = {apiVersion}";
    }

API版本約束

咱們除了在方法和控制器上指定咱們的版本，咱們還能夠採用另外一種方式

services.AddApiVersioning( options =>
{
    options.Conventions.Controller<HomeController>().HasApiVersion(1, 0);
});

看如上代碼咱們能夠看到咱們在這裏給HomeController配置版本，這樣方便咱們集中管理咱們的版本。

services.AddApiVersioning( options =>
{
    options.Conventions.Controller<MyController>()	   
                       .HasDeprecatedApiVersion(1, 0)
                       .HasApiVersion(1, 1)
                       .HasApiVersion(2, 0)
                       .Action(c => c.Get1_0()).MapToApiVersion(1, 0)
                       .Action(c => c.Get1_1()).MapToApiVersion(1, 1)
                       .Action(c => c.Get2_0()).MapToApiVersion(2, 0);
});

能夠同時使用API版本約束和版本控制屬性。

固然咱們還能夠自定義約束，從.NET Core 3.0開始，有一個IControllerConvention用於此目的的接口。

options.Conventions.Add(new MyCustomConvention());

固然咱們還能夠經過不一樣命名空間中的接口進行約束

options.Conventions.Add(new VersionByNamespaceConvention());

好比下面這種文件形式

api/v1/UsersController
api/v2/UsersController
api/v2_1/UsersController

映射後的路徑以下所示

api/1.0/users
api/2.0/users
api/2.1/users