前言

一般來說需要更改我們API的時(shí)候才考慮版本控制，但是我覺得我們不應(yīng)該等到那時(shí)候來實(shí)現(xiàn)它，我們應(yīng)該有一個(gè)版本策略從我們應(yīng)用程序開發(fā)時(shí)就開始制定好我們的策略，我們一直遵循著這個(gè)策略進(jìn)行開發(fā)。

我們其實(shí)可以通過多種方式進(jìn)行實(shí)現(xiàn)我們API版本的控制，其實(shí)對(duì)于版本控制沒有最好的方式，這完全取決于我們面向的使用者。

API版本控制類型

安裝版本控制包

Install-Package Microsoft.AspNetCore.Mvc.Versioning

在Startup.cs中的ConfigureServices方法中進(jìn)行版本設(shè)置，以及在控制器通過特性進(jìn)行設(shè)置版本，這樣可以實(shí)現(xiàn)版本控制。

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

• options.DefaultApiVersion = new ApiVersion(1,0): 這個(gè)設(shè)置不是必須的，因?yàn)槟J(rèn)情況下給我們?cè)O(shè)置的是1.0，但是顯式的聲明出來是一個(gè)很好的習(xí)慣，當(dāng)然DefaultApiVersion它會(huì)將默認(rèn)的[ApiVersion("1.0")]添加到控制器上，也就是說它會(huì)隱式的綁定API版本，但是為了我們方便理解或者說方便我們后面開發(fā)建議顯式的設(shè)置。
• options.AssumeDefaultVersionWhenUnspecified = true:默認(rèn)API版本控制需要將其屬性設(shè)置為true才可以開啟
• options.ReportApiVersions = true:默認(rèn)情況下它是禁用的，啟用此選項(xiàng)后，來自我們API端點(diǎn)的響應(yīng)將帶有標(biāo)頭，告訴我們的客戶端支持或不推薦使用哪個(gè)版本(api-supported-versions:1.1,2.0, api-deprecated-versions:1.0)

默認(rèn)提供了四種版本控制方法：

• 字符串參數(shù)
• 通過HTTP請(qǐng)求頭
• URL方式
• 媒體類型（Media Type）

默認(rèn)方法是使用名為api-version 的查詢字符串參數(shù)。我們還可以自己定義一個(gè)版本控制規(guī)則。

API版本約束方式

字符串參數(shù)形式

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

HTTP請(qǐng)求頭

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());

我們可以更改代表版本的參數(shù)名稱（例如，在上面的查詢字符串方法中，我們使用字母v代替默認(rèn)的api-version）。

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

選擇版本控制策略并在ConfigureServices方法中對(duì)其配置后，我們可以開始對(duì)API端點(diǎn)進(jìn)行版本控制，我們可以將這些屬性應(yīng)用于控制器和方法。

• 控制器的默認(rèn)可能沒有任何API版本屬性，并隱式配置的默認(rèn)API版本。默認(rèn)配置使用值1.0。
• 使用[ApiVersion("1.0")]屬性注釋我們的控制器，意味著該控制器支持API版本1.0
• 控制器可以支持多個(gè)API版本。只需[ApiVersion(...)]在控制器上應(yīng)用多個(gè)屬性
• 為了區(qū)分控制器支持的多個(gè)版本，我們使用[MapToApiVersion()]屬性注釋控制器方法。

如果要使用URL路徑則可以參考如下代碼片段：

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

API控制器棄用，我們只需要設(shè)置

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

可通過如下方法方式獲取所有API版本信息

var apiVersion = HttpContext.GetRequestedApiVersion();

當(dāng)然他還支持模型綁定，我們還可以通過模型形式獲取

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

API版本約束

我們除了在方法和控制器上指定我們的版本，我們還可以采用另一種方式

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

看如上代碼我們可以看到我們?cè)谶@里給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);
});

可以同時(shí)使用API版本約束和版本控制屬性。

當(dāng)然我們還可以自定義約束，從.NET Core 3.0開始，有一個(gè)IControllerConvention用于此目的的接口。

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

當(dāng)然我們還可以通過不同命名空間中的接口進(jìn)行約束

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

到此這篇關(guān)于ASP.NET Core3.x API版本控制的實(shí)現(xiàn)的文章就介紹到這了,更多相關(guān)ASP.NET Core3.x API版本控制內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論