asp.net core web api 版本控控制
通过微软的一个库Microsoft.AspNetCore.Mvc.Versioning实现asp.net core web api的版本控制。
以两种形式组织了Controller:
- 文件夹分开
- 命名不同但是路由是一样的
需要注意的是，Microsoft.AspNetCore.Mvc.Versioning版本必须是>=3.1.0，不然相同路由会出现以下这样的错误：
URL Path Segment
在 URL 路径中添加版本，类似这样：
/api/v1/product
/api/v2/product
怎么实现呢？
在Startup下的ConfigureServices方法加如下的配置：
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddApiVersioning(option =>
{
option.ReportApiVersions = true;
option.AssumeDefaultVersionWhenUnspecified = true;
option.DefaultApiVersion = new ApiVersion(1, 0);
});
}
我们的Controller路由需要配置成如下,[ApiVersion("1.0")]控制访问当前的版本：
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/product")]
[ApiController]
public class ProductV1Controller : ControllerBase
{
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "Huwei Phone V1", "Xiaomi Phone V1", "Vivo Phone V1" };
}
}
Startup的配置参数也要改一下：
services.AddApiVersioning(option =>
{
option.ReportApiVersions = true;
option.ApiVersionReader = new QueryStringApiVersionReader("api-version");
option.AssumeDefaultVersionWhenUnspecified = true;
option.DefaultApiVersion = new ApiVersion(1, 0);
});
可以看到效果：
QueryString
通过url参数的方式也可以实现版本控制：
/api/production?api-version=1
/api/production?api-version=2
与上面不同的是controller只要用ApiVersion特性就够了，
[ApiVersion("1.0")]
[Route("api/[controller]")]
[ApiController]
public class ProductionController : ControllerBase
{
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "Huwei Phone V1", "Xiaomi Phone V1", "Vivo Phone V1" };
}
}
Head
版本信息可以放在url的参数中，可以放在url路径中，也可放在请求的header里，这样显的接口干净利索感知不到版本的存在。
和使用QueryString的实现方式大体一样，只是在配置中不一样，Contrller无需改动：
services.AddApiVersioning(option =>
{
option.ReportApiVersions = true;
//option.ApiVersionReader = new QueryStringApiVersionReader("api-version");
option.ApiVersionReader = new HeaderApiVersionReader("api-version");
option.AssumeDefaultVersionWhenUnspecified = true;
option.DefaultApiVersion = new ApiVersion(1, 0);
});
三种实现方式对比
无论是什么配置都是支持Url Path Segement
根据option.ApiVersionReader参数的不同支持的会分别支持QueryString和Header两种方式。
Microsoft.AspNetCore.Mvc.Versioning
各种特性的在不同场景的用法
ApiVersion
定义了当前Controller的版本，可以支持多个。
其中有个Deprecated参数：用于表示当前版本是否弃用的信息，当然接口还是可以正常调用的。
MapToApiVersion
如果一个Controller下有多个版本，有接口支持V1版本，有的接口支持V2版本，可以使用MapToApiVersion实现具体的哪个接口支持哪个版本调用，这个特性是打在具体的接口方法上的。
ApiVersionNeutral
如果你想一个Controller任意版本都可以调用，则可以加上该特性
