快捷導(dǎo)航

深入講解.Net Core中的Api版本控制

更新時(shí)間：2018年10月11日 10:18:07 作者：LamondLu

這篇文章主要給大家介紹了關(guān)于.Net Core中Api版本控制的相關(guān)資料，文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧

前言

.NET Core 是指 .NET Core 運(yùn)行時(shí)和 .NET Core SDK，它包含開發(fā)應(yīng)用程序所需的工具。 .NET Core SDK 可與任何以前版本的 .NET Core 運(yùn)行時(shí)一起使用。

本文主要介紹了關(guān)于.Net Core Api版本控制的相關(guān)內(nèi)容，下面話不多說了，來一起看看詳細(xì)的介紹吧

原文鏈接：API Versioning in .Net Core

作者：Neel Bhatt

簡介

Api的版本控制是Api開發(fā)中經(jīng)常遇到的問題, 在大部分中大型項(xiàng)目都需要使用到Api的版本控制

在本篇博客中，我們將說明一下如何在.Net Core Api項(xiàng)目中使用Api版本控制。

本篇博客中測(cè)試項(xiàng)目的開發(fā)環(huán)境：

Visual Studio 2017
.Net Core 2.1 SDK

.Net Core Api中使用Api版本控制

創(chuàng)建一個(gè)Api項(xiàng)目

首先我們創(chuàng)建一個(gè).NET Core Api項(xiàng)目

使用Nuget安裝Api版本控制庫

.NET Core Mvc中，微軟官方提供了一個(gè)可用的Api版本控制庫Microsoft.AspNetCore.Mvc.Versioning。這里我們可以使用Nuget安裝這個(gè)包。

PM> Install-Package Microsoft.AspNetCore.Mvc.Versioning

修改Startup類

Microsoft.AspNetCore.Mvc.Versioning庫安裝完成之后，下一步我們來添加Api版本控制服務(wù)。

這里我們需要在Startup類的ConfigureService方法中添加以下代碼。

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

代碼解釋

ReportApiVersion 屬性是一個(gè)布爾類型，如果設(shè)置為true, 在Api請(qǐng)求的響應(yīng)頭部，會(huì)追加當(dāng)前Api支持的版本, 例

Response Header
api-supported-versions: 1.0
content-type: application/json; charset=utf-8
date: Sat, 06 Oct 2018 05:24:21 GMT
server: Kestrel
status: 200
x-powered-by: ASP.NET

AssumeDefaultVersionWhenUnspecified屬性是為了標(biāo)記當(dāng)客戶端沒有指定版本號(hào)的時(shí)候，是否使用默認(rèn)版本號(hào)
DefaultApiVersion屬性即默認(rèn)版本號(hào)

創(chuàng)建多版本Api

這里為了測(cè)試.Net Core Mvc的Api版本控制庫，我們創(chuàng)建如下2個(gè)Controller。

 [ApiVersion("1.0")]
 [Route("api/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
 [HttpGet]
 public IEnumerable<string> Get()
 {
  return new string[] { "Value1 from Version 1", "value2 from Version 1" };
 }
 } 

 [ApiVersion("2.0")]
 [Route("api/values")]
 [ApiController]
 public class ValuesV2Controller : ControllerBase
 {
 [HttpGet]
 public IEnumerable<string> Get()
 {
  return new string[] { "value1 from Version 2", "value2 from Version 2" };
 }
 }

代碼解釋

Value1Controller和Value2Controller使用了一樣的路由"/api/values"
Value1Controller類頭部使用ApiVersion特性標(biāo)記了當(dāng)前Controller的Api版本號(hào)是1.0
Value2Controller類頭部使用ApiVersion特性標(biāo)記了當(dāng)前Controller的Api版本號(hào)是2.0
-Value1Controller和Value2Controller都持有相同方法簽名的Get方法, 只是2個(gè)Get中返回了不同的字符串

現(xiàn)在我們啟動(dòng)項(xiàng)目，得到的結(jié)果如下，說明當(dāng)沒有指定Api版本號(hào)時(shí)，項(xiàng)目自動(dòng)使用1.0版本的Api, 即ValuesV1Controller中的Get方法。

如何在查詢字符串(Query String)中使用版本控制

Microsoft.AspNetCore.Mvc.Versioning支持以QueryString的形式指定請(qǐng)求Api的版本號(hào)。開發(fā)人員可以在Url中指定api-version參數(shù)來選擇調(diào)用的Api版本號(hào)。

以當(dāng)前項(xiàng)目為例

當(dāng)請(qǐng)求https://localhost:44319/api/values?api-version=2.0時(shí), 返回結(jié)果

["value1 from Version 2","value2 from Version 2"]

當(dāng)請(qǐng)求https://localhost:44319/api/values?api-version=1.0時(shí), 返回結(jié)果

["Value1 from Version 1","value2 from Version 1"]

如何使用路由約束中指定請(qǐng)求Api的版本

Microsoft.AspNetCore.Mvc.Versioning還支持使用路由約束指定請(qǐng)求Api的版本號(hào)。

例： [Route(“api/{v:apiVersion}/Values”)]

我們對(duì)之前2個(gè)Controller的代碼作如下修改。

 [ApiVersion("1.0")]
 [Route("api/{v:apiVersion}/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "Value1 from Version 1", "value2 from Version 1" };
  }
 } 

 [ApiVersion("2.0")]
 [Route("api/{v:apiVersion}/values")]
 [ApiController]
 public class ValuesV2Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "value1 from Version 2", "value2 from Version 2" };
  }
 }

現(xiàn)在我們通過以下2個(gè)Url請(qǐng)求Api, 返回的結(jié)果如下 :

/api/2.0/values

["value1 from Version 2","value2 from Version 2"]

/api/1.0/values

["Value1 from Version 1","value2 from Version 1"]

如何在請(qǐng)求頭(HTTP Header)中使用版本控制

以上的2種方式需要修改請(qǐng)求的Url, 如果你不喜歡這2種方式，Microsoft.AspNetCore.Mvc.Versioning還提供了第三種指定Api版本號(hào)的方式，即在HTTP請(qǐng)求頭中添加版本號(hào)參數(shù)。

為了啟用這種方式，我們首先需要在Startup.cs中修改Microsoft.AspNetCore.Mvc.Versioning的配置, 代碼如下:

 services.AddApiVersioning(o =>
 {
  o.ReportApiVersions = true;
  o.AssumeDefaultVersionWhenUnspecified = true;
  o.DefaultApiVersion = new ApiVersion(1, 0);
  o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
 });

這里通過ApiVersionReader屬性指定了Api版本號(hào)是從請(qǐng)求頭部的x-api-version屬性來的。

Tips: 一旦你使用o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");, 在查詢字符串中指定版本號(hào)的方式將不再可用，如果你希望同時(shí)支持2種方式，請(qǐng)改用o.ApiVersionReader = ApiVersionReader.Combine(new QueryStringApiVersionReader(), new HeaderApiVersionReader() { HeaderNames = { "x-api-version" }});(多謝seamaswang的更正)

下面我們通過Postman來請(qǐng)求2.0的Api, 結(jié)果正確返回了。

其他特性棄用Api(Deprecated)特性

有些時(shí)候，我們需要標(biāo)記一些過時(shí)的Api為棄用狀態(tài)，但是我們又不希望完全移除這個(gè)版本的Api, 我們可以使用Deprecated特性。

例：我們當(dāng)前希望棄用ValuesV1Controller, 我們可以指定Deprecated特性的值為true

 [ApiVersion("1.0", Deprecated = true)]
 [Route("api/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "Value1 from Version 1", "value2 from Version 1" };
  }
 }

當(dāng)我們請(qǐng)求在此請(qǐng)求這個(gè)api的時(shí)候, 在響應(yīng)頭中會(huì)出現(xiàn)api-deprecated-versions和api-supported-versions2個(gè)屬性。

Response Header
api-deprecated-versions: 1.0
api-supported-versions: 2.0
content-type: application/json; charset=utf-8
date: Sat, 06 Oct 2018 06:32:18 GMT
server: Kestrel
status: 200
x-powered-by: ASP.NET

這段響應(yīng)的意思就是1.0版本的Api已經(jīng)過期了，2.0版本中有相同的Api, 可以換用2.0版本的Api。

使用ApiVersionNeutral指定不需要版本控制的Api

在編寫Api的時(shí)候，對(duì)于一些非常簡單的Api，我們可能不需要指定Api版本號(hào), 例如健康檢查Api。我們可以使用ApiVersionNeutral特性，將它從Api版本控制中排除掉。

例：

 [ApiVersionNeutral]
 [Route("api/[controller]")]
 [ApiController]
 public class HealthCheckController : ControllerBase
 {
  public string Get()
  {
   return "Good";
  }
 }

本篇源代碼（本地下載）

總結(jié)

以上就是這篇文章的全部內(nèi)容了，希望本文的內(nèi)容對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，如果有疑問大家可以留言交流，謝謝大家對(duì)腳本之家的支持。

您可能感興趣的文章: