一、版本控制的好處：

（1）有助于及時(shí)推出功能, 而不會破壞現(xiàn)有系統(tǒng)。

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

API 版本控制可以采用不同的方式進(jìn)行控制，方法如下：

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

（2）通過自定義標(biāo)頭和通過接受標(biāo)頭

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

一、創(chuàng)建asp.net core webapi 項(xiàng)目，引用NuGet包：Install-Package Microsoft.AspNetCore.Mvc.Versioning -Version 2.0.0

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

如您所見, 配置了3不同的選項(xiàng)。

• ReportAPIVersions: 這是可選的。但是, 當(dāng)設(shè)置為 true 時(shí), API 將返回響應(yīng)標(biāo)頭中支持的版本信息。
• AssumeDefaultVersionWhenUnspecified: 此選項(xiàng)將用于不提供版本的請求。默認(rèn)情況下, 假定的 API 版本為1.0。
• DefaultApiVersion: 此選項(xiàng)用于指定在請求中未指定版本時(shí)要使用的默認(rèn) API 版本。這將默認(rèn)版本為1.0。

這是所有的配置和設(shè)置。現(xiàn)在, 我們將看到訪問 API 版本的不同方式。

二、通過QueryString來實(shí)現(xiàn)版本控制

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

上面的代碼作為1.0版本。您還可以在不同的命名空間中創(chuàng)建另一個(gè)具有相同名稱的控制器類, 并將 API 版本設(shè)置為2.0版本。如下圖所示：

就這樣?，F(xiàn)在轉(zhuǎn)到瀏覽器并訪問控制器。您應(yīng)該看到 API 版本1.0 控制器的輸出, 因?yàn)樗辉O(shè)置為默認(rèn)值?，F(xiàn)在在 URL 中追加 api-version=2, 您應(yīng)該看到 api 版本2.0 控制器的輸出。

二、通過URL Path Segment來實(shí)現(xiàn)：

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

• api/v1/values
• api/v2/values

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

同樣, 您需要將路由參數(shù)更新到所有適用的位置。使用此更改, 在訪問API 接口時(shí)總是需要有版本號。您可以通過 api/v1/values 訪問到版本 1.0, 通過api/v2/values訪問版本 2.0, 更改 URL 中的版本號。簡單, 看起來更干凈了。

測試結(jié)果如下：

三、通過HTTP Headers來實(shí)現(xiàn)版本控制

在上述兩種方法中, 需要修改 URL 以支持版本控制。但是, 如果您希望 api 的URL 保持干凈, 則 api 版本信息也可以通過附加 HTTP 報(bào)頭來傳遞。要進(jìn)行此工作, 您需要配置 ApiVersionReader 選項(xiàng)。代碼如下：

突出顯示的行告訴我們header "api-version" 現(xiàn)在是 api 版本號的預(yù)期位置。確保路由屬性沒有版本詳細(xì)信息。所以測試它，結(jié)果如下：

當(dāng)您將2.0 作為值提供給 "api 版本" 時(shí), 它將調(diào)用版本2.0 控制器并返回輸出。

簡單, 易于設(shè)置。但是, 現(xiàn)在查詢字符串參數(shù)的方法進(jìn)行版本控制將不起作用。一旦設(shè)置了header, 就不能指定查詢字符串參數(shù)。如果您希望支持這兩種情況, 而不是 HeaderApiVersionReader, 請使用 QueryStringOrHeaderApiVersionReader。代碼如下：

因此, 現(xiàn)在支持查詢字符串參數(shù)和header。默認(rèn)查詢字符串參數(shù)名稱是 api-version, 因此您可以將構(gòu)造函數(shù)留空, 但如果需要其他名稱, 則需要提供。您還可以對查詢字符串參數(shù)和標(biāo)頭使用有不同的名稱。請記住, 我們還將 ReportApiVersions 設(shè)置為 true, 該值返回響應(yīng)標(biāo)頭中的版本信息。見下圖。

現(xiàn)在, 讓我們來看看另外幾個(gè)選項(xiàng)。

MapToApiVersion參數(shù)的用法：

MapToApiVersion 屬性允許將單個(gè) API 操作映射到任何版本。換言之, 一個(gè)支持多個(gè)版本的單控制器?？刂破骺赡苤挥邪姹?支持的 API 操作方法。在這種情況下, 您可以使用 MapToApiVersion?？纯聪旅娴拇a。

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

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

Deprecated參數(shù)的用法：

當(dāng)支持多個(gè) API 版本時(shí), 某些版本最終會隨著時(shí)間的推移而被棄用。要標(biāo)記一個(gè)或多個(gè) api 版本已被廢棄, 只需用Deprecated修飾您的控制器。這并不意味著不支持 API 版本。你仍然可以調(diào)用該版本。它只是一種讓 調(diào)用API 用戶意識到以下版本在將來會被棄用。

上面把Deprecated設(shè)置為TRUE表示，版本1.0將來會被棄用。訪問我們的API接口，可以在響應(yīng)頭中可以看到，下面信息，如下圖所示：

ApiVersionNeutral特性的使用：

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

獲取版本信息（Version Information）

如果你想知道那個(gè)版本的客戶端在被訪問，你可以通過下面的代碼實(shí)現(xiàn)該功能：

綜上所述, 具有多個(gè)版本的 API 可以幫助以一種有效的方式推出增強(qiáng)的功能, 同時(shí)也便于跟蹤更改。在這篇文章中, 我們看到了如何在 ASP.NET coreWEB API 中添加對多個(gè)版本的支持。nuget 包支持通過查詢字符串參數(shù)進(jìn)行版本控制, 在 URL 中添加路徑段和通過標(biāo)頭。它還具有版本單一 API 操作和從版本中選擇退出的功能。

能不能不借助第三方的包來實(shí)現(xiàn)一個(gè)API的版本控制，方法是有的，不賣關(guān)子了，大家接著往下看。

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

新建一個(gè)core API項(xiàng)目：

在VersionControl文件夾下面，新建一個(gè)實(shí)現(xiàn)了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
        };
      }
    }
  }

調(diào)試代碼發(fā)現(xiàn)這種方式只在程序第一次運(yùn)行的時(shí)候會執(zhí)行，之后不會再執(zhí)行多次，因此效率很高。

五、總結(jié)：

通過上面兩種版本控制的實(shí)現(xiàn)和對比，我更偏向通過第三方的包來實(shí)現(xiàn)版本控制，這種方法功能更強(qiáng)大。這純屬于個(gè)人愛好了，大家可以根據(jù)不同的場景來決定使用哪種方式來實(shí)現(xiàn)，好了講到這里，謝謝，希望對你有幫助。也希望大家多多支持腳本之家。

最新評論