支持多个版本的ASP.NET Core Web API
基本配置及说明
版本控制有助于及时推出功能,而不会破坏现有系统。 它还可以帮助为选定的客户提供额外的功能。 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.0DefaultApiVersion
:此选项用于指定在请求中未指定任何版本时要使用的默认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();
文章原地址 support-multiple-versions-of-asp-net-core-web-api
相关文章API-Version-Reader
支持多个版本的ASP.NET Core Web API的更多相关文章
- 在ASP.NET Core Web API中为RESTful服务增加对HAL的支持
HAL(Hypertext Application Language,超文本应用语言)是一种RESTful API的数据格式风格,为RESTful API的设计提供了接口规范,同时也降低了客户端与服务 ...
- asp.net core web api 版本控控制
通过微软的一个库Microsoft.AspNetCore.Mvc.Versioning实现asp.net core web api的版本控制. 以两种形式组织了Controller: 文件夹分开 命名 ...
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)
对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- Docker容器环境下ASP.NET Core Web API应用程序的调试
本文主要介绍通过Visual Studio 2015 Tools for Docker – Preview插件,在Docker容器环境下,对ASP.NET Core Web API应用程序进行调试.在 ...
- Docker容器环境下ASP.NET Core Web API
Docker容器环境下ASP.NET Core Web API应用程序的调试 本文主要介绍通过Visual Studio 2015 Tools for Docker – Preview插件,在Dock ...
- Gitlab CI 自动部署 asp.net core web api 到Docker容器
为什么要写这个? 在一个系统长大的过程中会经历不断重构升级来满足商业的需求,而一个严谨的商业系统需要高效.稳定.可扩展,有时候还不得不考虑成本的问题.我希望能找到比较完整的开源解决方案来解决持续集成. ...
- ASP.NET Core Web API下事件驱动型架构的实现(二):事件处理器中对象生命周期的管理
在上文中,我介绍了事件驱动型架构的一种简单的实现,并演示了一个完整的事件派发.订阅和处理的流程.这种实现太简单了,百十行代码就展示了一个基本工作原理.然而,要将这样的解决方案运用到实际生产环境,还有很 ...
- ASP.NET Core 实战:使用 ASP.NET Core Web API 和 Vue.js 搭建前后端分离项目
一.前言 这几年前端的发展速度就像坐上了火箭,各种的框架一个接一个的出现,需要学习的东西越来越多,分工也越来越细,作为一个 .NET Web 程序猿,多了解了解行业的发展,让自己扩展出新的技能树,对自 ...
随机推荐
- javaCV开发详解之7:让音频转换更加简单,实现通用音频编码格式转换、重采样等音频参数的转换功能(以pcm16le编码的wav转mp3为例)
javaCV系列文章: javacv开发详解之1:调用本机摄像头视频 javaCV开发详解之2:推流器实现,推本地摄像头视频到流媒体服务器以及摄像头录制视频功能实现(基于javaCV-FFMPEG.j ...
- Vue 爬坑之路(二)—— 组件之间的数据传递
Vue 的组件作用域都是孤立的,不允许在子组件的模板内直接引用父组件的数据.必须使用特定的方法才能实现组件之间的数据传递. 首先用 vue-cli 创建一个项目,其中 App.vue 是父组件,com ...
- 如何判断img标签是否有src属性
前几天,写一个小项目,需要判断img标签是否有src属性,想了半天,只能想到用jq实现,如下: if($(".img").attr("src")==undefi ...
- java 局部变量几点笔记
1.局部变量的作用时间很短暂,都被存储在方法的栈内存中:2.(没使用static)非静态变量=实例变量:(使用static)静态变量=类变量3.成员变量:类体内定义的变量:4.局部变量有三种:1)形参 ...
- 使用dom4j讲xml字符串递归遍历成Map
package test; import java.util.ArrayList;import java.util.HashMap;import java.util.Iterator;import j ...
- 移动端车牌识别、行驶证识别OCR为共享汽车APP增添技术色彩
本文主题:移动端车牌识别.行驶证识别OCR为共享汽车APP增添技术色彩 本文关键词:车牌识别,证件识别,移动端车牌识别,行驶证识别,手机车牌识别,驾驶证识别 近两年,随着共享单车以及共享电车的兴起,有 ...
- java源码学习(五)LinkedList
LinkedList [TOC] 一.定义 public class LinkedList<E> extends AbstractSequentialList<E> imple ...
- NoSQL数据库:Redis适用场景及产品定位
传统MySQL+ Memcached架构遇到的问题 实际MySQL是适合进行海量数据存储的,通过Memcached将热点数据加载到cache,加速访问,很多公司都曾经使用过这样的架构,但随着业务数据量 ...
- 2.Smarty的引入和实例化
1.把demo和lib复制出来,并且创建一个test文件夹作为工作的目录 如图所示: 2.这是libs里面的内容,其中smarty.class.php包含了smarty各种方法和功能,需要实例化它还工 ...
- DOCKER 从入门到放弃(一)
前言 关于docker的各种概念已有各位大神珠玉在前,请各位自行查看,本系列的目的是各种详细操作步骤 各种概念特别推荐CloudMan的3篇blog: http://www.cnblogs.com/C ...