Asp.Net.Core WebApi 版本控制

前言

在後端Api的開發過程中,無法避免的會遇到接口迭代的過程,如何保證新老接口的共存和接口的向前的兼容呢,這時候就需要對Api進行版本的控制,那如何優雅的控制Api的版本呢？

開始

Microsoft.AspNetCore.Mvc.Versioning 是一個微軟官方推出的一個用於管理Api版本的包,配置簡單,功能強大。 github地址.

新建一個WebApi項目並通過命令引用包。

Install-Package Microsoft.AspNetCore.Mvc.Versioning

最新版本已經支持Core3.1

項目結構如下

在 Startup 的 ConfigureServices 中增加一下配置。

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

• ReportApiVersions:是否在請求頭中返回受支持的版本信息。
• AssumeDefaultVersionWhenUnspecified:請求沒有指明版本的情況下是否使用默認的版本。
• DefaultApiVersion:默認的版本號。

通過QueryString進行版本控制

分別在兩個不同的Controller中添加一個獲取版本信息的接口

<code>namespace version.Controllers.v1
{
    [ApiVersion("1.0")]
    [ApiController]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

<code>namespace version.Controllers.v2
{
    [ApiVersion("2.0")]
    [ApiController]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

HttpContext.GetRequestedApiVersion().ToString() 是用於獲取請求接口的版本信息。

我們通過postman來請求這兩個接口當我們沒有給到具體請求哪個版本的時候會根據在ConfigureServices中配置的默認版本去執行。

指定版本請求結果

在響應頭中會顯示當前支持的所有的Api版本

通過URL Path進行版本控制

一般在Api開發中不會去QueryString的方式去進行版本控制，而是使用URL路徑段的方式來控制版本。

修改兩個Controller中的代碼如下。

<code>namespace version.Controllers.v1
{
    [ApiVersion("1.0")]
    [ApiController]
    [Route("api/v{version:ApiVersion}/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

<code>namespace version.Controllers.v2
{
    [ApiVersion("2.0")]
    [ApiController]
    [Route("api/v{version:ApiVersion}/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

通過postman進行測試

可以看到當我們使用指定的版本是可以正常訪問的時候，但是如果我們去掉了Api版本號就會拋出404,並不能像QueryString一樣調用默認的Api版本，因為URL Path的方式不允許隱式匹配設置的默認Api版本。所以必須申明所有的Api版本。且在請求Api同時必須帶上Api版本號。

通過Media Type進行版本控制

我們還可以使用content-type來實現版本的控制

修改ConfigureServices中的配置

<code>services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new MediaTypeApiVersionReader();
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);

});/<code>

CurrentImplementationApiVersionSelector 如果沒有在content-type中傳遞Api版本好,將默認匹配最新的Api版本

分別修改兩個Controller

<code>namespace version.Controllers.v1
{
    [ApiVersion("1.0")]
    [ApiController]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

<code>namespace version.Controllers.v2
{
    [ApiVersion("2.0")]
    [ApiController]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

使用Postman測試

通過自定義Headers進行版本控制

修改ConfigureServices中的配置

<code>services.AddControllers();
services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.ApiVersionReader = new HeaderApiVersionReader("api_version");
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
});/<code>

api_version 是你Headers中Key的名字。

使用Postman測試

特性

當哪個Api版本不在更新,就需要棄用掉這個版本。當Deprecated值為true時說明該Api版本已經已經棄用,但是棄用不代表不能請求。只是會在響應頭中告知次版本已經已經棄用。

<code>namespace version.Controllers.v1
{
    [ApiVersion("1.0",Deprecated= true)]
    [ApiController]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

項目總有一些功能是不需要版本的控制，所以我們希望它不受版本控制。可以添加[ApiVersionNeutral]特性使Api支持版本控制。

<code>namespace version.Controllers.v1
{
    [ApiVersionNeutral]
    [ApiController]
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

MapToApiVersion 可以將單個Api歸類於任何版本。在一個Controller中可以存在多個版本的Api。我們可以配合Deprecated來靈活的控制我們的Api。

<code>namespace version.Controllers.v1
{
    [ApiVersion("3.0")]
    [ApiVersion("1.0",Deprecated= true)]
    [ApiController]
    [Route("api/v{version:ApiVersion}/[controller]")]
    public class ValuesController : Controller
    {
        [HttpGet("version"), MapToApiVersion("1.0")]
        public string Version() => (HttpContext.GetRequestedApiVersion().ToString());

        [HttpGet("version3"), MapToApiVersion("3.0")]
        public string Version3() => (HttpContext.GetRequestedApiVersion().ToString());
    }
}/<code>

通過postman測試一下。

總結

可以看到Microsoft.AspNetCore.Mvc.Versioning功能還能強大的，基本滿足了大部分的需求，還有一些功能可能沒有在本文中涉及到，可以去這裡.翻閱。