ASP.Net Core中關於WebApi幾種版本控制對比詳解

這篇文章主要介紹了淺談ASP.Net Core WebApi幾種版本控制對比,小編覺得挺不錯的，現在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧

一、版本控制的好處：

（1）有助於及時推出功能, 而不會破壞現有系統。

（2）它還可以協助為選定的客戶提供額外的功能。

API 版本控制可以採用不同的方式進行控制，方法如下：

（1）在 URL 中追加版本或作為查詢字串參數,

（2）通過自訂標題和通過接受標題

在這篇文章中, 讓我們來看看如何支援多個版本的 ASP.NET Core Web API。

一、建立asp.net core webapi 項目，引用NuGet包：Install-Package Microsoft.AspNetCore.Mvc.Versioning -Version 2.0.0

項目和安裝包都好了，接著我們需要在Startup.cs中的ConfigureServices 方法中添加下面的代碼：

如您所見, 配置了3不同的選項。

• ReportAPIVersions: 這是可選的。但是, 當設定為 true 時, API 將返迴響應標題中支援的版本資訊。

• AssumeDefaultVersionWhenUnspecified: 此選項將用於不提供版本的請求。預設情況下, 假定的 API 版本為1.0。

• DefaultApiVersion: 此選項用於指定在請求中未指定版本時要使用的預設 API 版本。這將預設版本為1.0。

這是所有的配置和設定。現在, 我們將看到訪問 API 版本的不同方式。

二、通過QueryString來實現版本控制

開啟我們的控制器，在上面添加ApiVersion特性，如下代碼所示：

上面的代碼作為1.0版本。您還可以在不同的命名空間中建立另一個具有相同名稱的控制器類, 並將 API 版本設定為2.0版本。如所示：

就這樣。現在轉到瀏覽器並存取控制器。您應該看到 API 版本1.0 控制器的輸出, 因為它被設定為預設值。現在在 URL 中追加 api-version=2, 您應該看到 api 版本2.0 控制器的輸出。

二、通過URL Path Segment來實現：

查詢字串參數很有用, 但在長 URL 和其他查詢字串參數的情況下可能會很痛苦。相反, 更好的方法是在 URL 路徑中添加版本。比如：

• api/v1/values

• api/v2/values

還是上面的項目，只不過需要在v1和v2控制器中加入，下面的代碼。如所示：

同樣, 您需要將路由參數更新到所有適用的位置。使用此更改, 在訪問API 介面時總是需要有版本號碼。您可以通過 api/v1/values 訪問到版本 1.0, 通過api/v2/values訪問版本 2.0, 更改 URL 中的版本號碼。簡單, 看起來更乾淨了。

測試結果如下：

三、通過HTTP Headers來實現版本控制

在上述兩種方法中, 需要修改 URL 以支援版本控制。但是, 如果您希望 api 的URL 保持乾淨, 則 api 版本資訊也可以通過附加 HTTP 前序來傳遞。要進行此工作, 您需要配置 ApiVersionReader 選項。代碼如下：

反白的行告訴我們header "api-version" 現在是 api 版本號碼的預期位置。確保路由屬性沒有版本詳細資料。所以測試它，結果如下：

當您將2.0 作為值提供給 "api 版本" 時, 它將調用版本2.0 控制器並返回輸出。

簡單, 易於設定。但是, 現在查詢字串參數的方法進資料列版本設定將不起作用。一旦設定了header, 就不能指定查詢字串參數。如果您希望支援這兩種情況, 而不是 HeaderApiVersionReader, 請使用 QueryStringOrHeaderApiVersionReader。代碼如下：

因此, 現在支援查詢字串參數和header。預設查詢字串參數名稱是 api-version, 因此您可以將建構函式留空, 但如果需要其他名稱, 則需要提供。您還可以對查詢字串參數和標題使用有不同的名稱。請記住, 我們還將 ReportApiVersions 設定為 true, 該值返迴響應標題中的版本資訊。見。

現在, 讓我們來看看另外幾個選項。

MapToApiVersion參數的用法：

MapToApiVersion 屬性允許將單個 API 操作映射到任何版本。換言之, 一個支援多個版本的單控制器。控制器可能只有版本3支援的 API 操作方法。在這種情況下, 您可以使用 MapToApiVersion。看看下面的代碼。

上面代碼的意思是：public string Get()該方法只有在版本1.0中支援，public string Getv3()方法只有在版本3.0中支援。

有圖有真像，很靈活，我很喜歡。

Deprecated參數的用法：

當支援多個 API 版本時, 某些版本最終會隨著時間的推移而被棄用。要標記一個或多個 api 版本已被廢棄, 只需用Deprecated修飾您的控制器。這並不意味著不支援 API 版本。你仍然可以調用該版本。它只是一種讓 調用API 使用者意識到以下版本在將來會被棄用。

上面把Deprecated設定為TRUE表示，版本1.0將來會被棄用。訪問我們的API介面，可以在回應標頭中可以看到，下面資訊，如所示：

ApiVersionNeutral特性的使用：

ApiVersionNeutral 特性定義此 API 不在支援版本控制。無論 支援api 版本控制或不支援 api 版本控制的舊式 api，這對於行為完全相同的 api 非常有用。因此, 您可以添加 ApiVersionNeutral 屬性以從版本控制中退出。

擷取版本資訊（Version Information）

如果你想知道那個版本的用戶端在被訪問，你可以通過下面的代碼實現該功能：

綜上所述, 具有多個版本的 API 可以協助以一種有效方式推出增強功能, 同時也便於跟蹤更改。在這篇文章中, 我們看到了如何在 ASP.NET coreWEB API 中添加對多個版本的支援。nuget 包支援通過查詢字串參數進資料列版本設定, 在 URL 中添加路徑段和通過標題。它還具有版本單一 API 操作和從版本中選擇退出的功能。

能不能不藉助第三方的包來實現一個API的版本控制，方法是有的，不賣關子了，大家接著往下看。

四、終極版本（不藉助任何NuGet包）asp.net core web api版本控制

建立一個core API項目：

在VersionControl檔案夾下面，建立一個實現了IApplicationModelConvention介面的類NameSpaceVersionRoutingConvention代碼如下：

public class NameSpaceVersionRoutingConvention:IApplicationModelConvention  {    private readonly string apiPrefix;    private const string urlTemplate = "{0}/{1}/{2}";    public NameSpaceVersionRoutingConvention(string apiPrefix = "api")    {      this.apiPrefix = apiPrefix;    }    public void Apply(ApplicationModel application)    {      foreach (var controller in application.Controllers)      {                var hasRouteAttribute = controller.Selectors        .Any(x => x.AttributeRouteModel != null);        if (!hasRouteAttribute)        {          continue;        }        var nameSpaces = controller.ControllerType.Namespace.Split('.');        //擷取namespace中版本號碼部分        var version = nameSpaces.FirstOrDefault(x => Regex.IsMatch(x, @"^v(\d+)$"));        if (string.IsNullOrEmpty(version))        {          continue;        }        string template = string.Format(urlTemplate, apiPrefix, version,        controller.ControllerName);        controller.Selectors[0].AttributeRouteModel = new AttributeRouteModel()        {          Template = template        };      }    }  }

調試代碼發現這種方式只在程式第一次啟動並執行時候會執行，之後不會再執行多次，因此效率很高。

五、總結：