前言

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

開始

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

新建一個WebApi專案並通過命令引用包。

Install-Package Microsoft.AspNetCore.Mvc.Versioning

最新版本已經支援Core3.1

專案結構如下

在 Startup 的 ConfigureServices

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

• ReportApiVersions:是否在請求頭中返回受支援的版本資訊。
• AssumeDefaultVersionWhenUnspecified:請求沒有指明版本的情況下是否使用預設的版本。
• DefaultApiVersion:預設的版本號。

通過QueryString進行版本控制

分別在兩個不同的Controller中新增一個獲取版本資訊的介面

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

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

HttpContext.GetRequestedApiVersion().ToString() 是用於獲取請求介面的版本資訊。

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

指定版本請求結果

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

通過URL Path進行版本控制

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

修改兩個Controller中的程式碼如下。

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());
    }
}

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());
    }
}

通過postman進行測試

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

通過Media Type進行版本控制

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

修改ConfigureServices中的配置

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

});

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

分別修改兩個Controller

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

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

使用Postman測試

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

修改ConfigureServices中的配置

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

api_version 是你Headers中Key的名字。

使用Postman測試

特性

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

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());
    }
}

專案總有一些功能是不需要版本的控制，所以我們希望它不受版本控制。可以新增[ApiVersionNeutral]特性使Api支援版本控制。

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

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

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());
    }
}

通過postman測試一下。

總結

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