一、版本控制的好處：

（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  core WEB API 中添加對多個版本的支持。nuget 包支持通過查詢字符串參數進行版本控制, 在 URL 中添加路徑段和通過標頭。它還具有版本單一 API 操作和從版本中選擇退出的功能。

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

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

新建一個core API項目：

在VersionControl文件夾下面，新建一個實現了IApplicationModelConvention接口的類NameSpaceVersionRoutingConvention   代碼如下：

 1  public class NameSpaceVersionRoutingConvention:IApplicationModelConvention
 2     {
 3         private readonly string apiPrefix;
 4         private const string urlTemplate = "{0}/{1}/{2}";
 5         public NameSpaceVersionRoutingConvention(string apiPrefix = "api")
 6         {
 7             this.apiPrefix = apiPrefix;
 8         }
 9 
10         public void Apply(ApplicationModel application)
11         {
12             foreach (var controller in application.Controllers)
13             {
14                 
15                 var hasRouteAttribute = controller.Selectors
16                 .Any(x => x.AttributeRouteModel != null);
17                 if (!hasRouteAttribute)
18                 {
19                     continue;
20                 }
21                 var nameSpaces = controller.ControllerType.Namespace.Split('.');
22                 //獲取namespace中版本號部分
23                 var version = nameSpaces.FirstOrDefault(x => Regex.IsMatch(x, @"^v(\d+)$"));
24                 if (string.IsNullOrEmpty(version))
25                 {
26                     continue;
27                 }
28                 string template = string.Format(urlTemplate, apiPrefix, version,
29                 controller.ControllerName);
30                 controller.Selectors[0].AttributeRouteModel = new AttributeRouteModel()
31                 {
32                     Template = template
33                 };
34             }
35         }
36     }

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

五、總結：

通過上面兩種版本控制的實現和對比，我更偏向通過第三方的包來實現版本控制，這種方法功能更強大。這純屬于個人愛好了，大家可以根據不同的場景來決定使用哪種方式來實現，好了講到這里，謝謝，希望對你有幫助。

覺得可以的話，希望點下推薦哈~你們的推薦是我的動力。

多謝@光陰四濺 及時指出我的錯誤，很感謝！

代碼下載地址：WebApiVersionControl.rar