支持多个版本的ASP.NET Core Web API
2017-07-25 14:22
1056 查看
基本配置及说明
版本控制有助于及时推出功能,而不会破坏现有系统。 它还可以帮助为选定的客户提供额外的功能。 API版本可以通过不同的方式完成,例如在URL中添加版本或通过自定义标头和通过Accept-Header作为查询字符串参数。 在这篇文章中,我们来看看如何支持多版本的ASP.NET Core Web API创建一个ASP.NET Core Web API应用程序。通过 NuGet 安装此软件包:
Microsoft.AspNetCore.Mvc.Versioning,打开
Startup.cs,修改
ConfigureServices方法,代码如下:
public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.AddApiVersioning(option => { option.ReportApiVersions = true; option.AssumeDefaultVersionWhenUnspecified = true; option.DefaultApiVersion = new ApiVersion(1, 0); }); }
你可以看到配置了3个不同的选项:
ReportAPIVersions:这是可选的。 但是当设置为true时,API会在响应头中返回受支持的版本信息。
AssumeDefaultVersionWhenUnspecified:此选项将用于在没有版本的情况下提供请求。 假定的API版本默认为1.0
DefaultApiVersion:此选项用于指定在请求中未指定任何版本时要使用的默认API版本。 这将默认版本为1.0
这就是配置和设置。 现在我们将看到访问API版本的不同方法。
Via Query String(通过查询字符串)
打开Controller类,然后用ApiVersion属性装饰控
Controller类。 像下面这样,
namespace MultipleAPIVersions.Controllers { [ApiVersion("1.0")] [Route("api/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value1" }); } }
以上版本被设置为1.0,你还可以设置API版本为2.0,为此你需要在不同命名空间中创建具有相同名称的另一个
Controller类。 像下面这样,
namespace AspNetCoreWebApi.Controllers2 { [ApiVersion("2.0")] [Route("api/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value2" }); } }
现在去浏览器并访问控制器。 您应该看到API版本1.0控制器的输出,因为默认访问为1.0的版本。 现在在URL中附加api-version = 2,你应该看到API 2.0版控制器的输出。
Via URL Path Segment(通过URL路径)
查询字符串参数是有用的,但在长URL和其他查询字符串参数的情况下可能会很痛苦。 相反,更好的方法是在URL路径中添加版本。 像这样,api/v1/values
api/v2/values
所以要做到这一点,我们需要把版本放在route属性中:
namespace MultipleAPIVersions.Controllers { [ApiVersion("1.0")] [Route("api/v{version:apiVersion}/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value1" }); } }
同样,您需要将路由参数更新到所有请求中。 通过此更改,API端点始终需要具有版本号。 您可以通过
api/v1/values导航到版本1.0,要想访问2.0版本,更改URL中的版本号。 简单,看起来更干净
Via HTTP Headers(通过HTTP头传递)
在上述两种方法中,需要修改URL以支持版本控制。 但是,如果您希望您的API URL保持干净,那么API版本信息也可以通过附加HTTP头传递。 为了使其工作,您需要配置ApiVersionReader选项
services.AddApiVersioning(option => { option.ReportApiVersions = true; option.ApiVersionReader = new HeaderApiVersionReader("api-version"); option.DefaultApiVersion = new ApiVersion(1, 0); option.AssumeDefaultVersionWhenUnspecified = true; });
打开Postman添加
header api-version测试
当您将2.0作为值提供给
api-version时,它将调用2.0版
Controller并返回输出
简单易用的设置。 但是,现在查询字符串参数(query string parameter)将无法正常工作。 设置
header后,不能指定查询字符串参数(query string parameter)。 如果你希望支持,请使用
ApiVersionReader.Combine
option.ApiVersionReader = ApiVersionReader.Combine ( new QueryStringApiVersionReader("api-version"), new HeaderApiVersionReader("api-version") );
现在,查询字符串参数和
header都支持
请记住,我们还将
ReportApiVersions设置为
true,返回响应头中的版本信息。 见下图
现在,让我们来看看另外几个选项
MapToApiVersion
MapToApiVersion特性允许将单个API
action映射到任何版本。 换句话说,支持多个版本的单个
Controller
namespace MultipleAPIVersions.Controllers { [ApiVersion("1.0")] [ApiVersion("3.0")] [Route("api/v{version:apiVersion}/[controller]")] public class ValuesController : Controller { [HttpGet] public IActionResult Get() => Ok(new string[] { "value1" }); [HttpGet, MapToApiVersion("3.0")] public IActionResult GetV3() => Ok(new string[] { "value3" }); } }
Deprecated(弃用)
当支持多个API版本时,一些版本最终将被淘汰。 要想标明一个或多个API版将被弃用,只需将准备弃用的API版本标记。 这并不意味着不支持API版本,这些被标记的API仍然可以调用。 这只是让用户意识到以后版本将被废弃的一种方式[ApiVersion("1.0", Deprecated = true)]
ApiVersionNeutral(版本中立)
ApiVersionNeutral特性定义该API是版本中立的。 这对于行为方式完全相同的API非常有用,不论是支持API版本的
Controller还是不支持API版本的
Controller。 因此,你可以添加
ApiVersionNeutral特性以退出版本控制
[ApiVersionNeutral] [RoutePrefix( "api/[controller]" )] public class SharedController : Controller { [HttpGet] public IActionResult Get() => Ok(); }
访问版本信息
如果你想知道哪个版本的客户端正在尝试访问,那么你可以从中获取该信息:public string Get() => HttpContext.GetRequestedApiVersion().ToString();
相关文章推荐
- 支持多个版本的ASP.NET Core Web API
- 打造属于自己的支持版本迭代的Asp.Net Web Api Route
- ASP.Net Core WebApi几种版本控制对比
- ASP.Net Core WebApi几种版本控制对比
- Asp.net Core WebApi 支持json/xml格式的数据返回
- ASP.Net Core WebApi几种版本控制对比
- ASP.Net Core WebApi几种版本控制对比
- 在ASP.NET Core Web API中为RESTful服务增加对HAL的支持
- 浅谈ASP.Net Core WebApi几种版本控制对比
- ASP.Net Core WebApi几种版本控制对比
- ASP.NET Core MVC/WebAPi 模型绑定探索
- asp.net core webapi项目配置全局路由
- ASP.NET Web API RC版本新特性:Web API的帮助文档制作
- 使用Visual Studio Code开发Asp.Net Core WebApi学习笔记(二)-- Web Api Demo
- asp.net core WebAPI实现CRUD
- Gitlab CI 自动部署 asp.net core web api 到Docker容器
- Asp.net WebAPI对Ajax和Angularjs跨域的支持
- 在docker中运行ASP.NET Core Web API应用程序
- 用Middleware给ASP.NET Core Web API添加自己的授权验证
- ASP.NET Core Web API下事件驱动型架构的实现(二):事件处理器中对象生命周期的管理