基本配置及说明

版本控制有助于及时推出功能,而不会破坏现有系统。 它还可以帮助为选定的客户提供额外的功能。 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();

文章原地址 support-multiple-versions-of-asp-net-core-web-api

相关文章API-Version-Reader

支持多个版本的ASP.NET Core Web API的更多相关文章

  1. 在ASP.NET Core Web API中为RESTful服务增加对HAL的支持

    HAL(Hypertext Application Language,超文本应用语言)是一种RESTful API的数据格式风格,为RESTful API的设计提供了接口规范,同时也降低了客户端与服务 ...

  2. asp.net core web api 版本控控制

    通过微软的一个库Microsoft.AspNetCore.Mvc.Versioning实现asp.net core web api的版本控制. 以两种形式组织了Controller: 文件夹分开 命名 ...

  3. 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)

    对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...

  4. 在ASP.NET Core Web API上使用Swagger提供API文档

    我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...

  5. Docker容器环境下ASP.NET Core Web API应用程序的调试

    本文主要介绍通过Visual Studio 2015 Tools for Docker – Preview插件,在Docker容器环境下,对ASP.NET Core Web API应用程序进行调试.在 ...

  6. Docker容器环境下ASP.NET Core Web API

    Docker容器环境下ASP.NET Core Web API应用程序的调试 本文主要介绍通过Visual Studio 2015 Tools for Docker – Preview插件,在Dock ...

  7. Gitlab CI 自动部署 asp.net core web api 到Docker容器

    为什么要写这个? 在一个系统长大的过程中会经历不断重构升级来满足商业的需求,而一个严谨的商业系统需要高效.稳定.可扩展,有时候还不得不考虑成本的问题.我希望能找到比较完整的开源解决方案来解决持续集成. ...

  8. ASP.NET Core Web API下事件驱动型架构的实现(二):事件处理器中对象生命周期的管理

    在上文中,我介绍了事件驱动型架构的一种简单的实现,并演示了一个完整的事件派发.订阅和处理的流程.这种实现太简单了,百十行代码就展示了一个基本工作原理.然而,要将这样的解决方案运用到实际生产环境,还有很 ...

  9. ASP.NET Core 实战:使用 ASP.NET Core Web API 和 Vue.js 搭建前后端分离项目

    一.前言 这几年前端的发展速度就像坐上了火箭,各种的框架一个接一个的出现,需要学习的东西越来越多,分工也越来越细,作为一个 .NET Web 程序猿,多了解了解行业的发展,让自己扩展出新的技能树,对自 ...

随机推荐

  1. javaCV开发详解之7:让音频转换更加简单,实现通用音频编码格式转换、重采样等音频参数的转换功能(以pcm16le编码的wav转mp3为例)

    javaCV系列文章: javacv开发详解之1:调用本机摄像头视频 javaCV开发详解之2:推流器实现,推本地摄像头视频到流媒体服务器以及摄像头录制视频功能实现(基于javaCV-FFMPEG.j ...

  2. Vue 爬坑之路(二)—— 组件之间的数据传递

    Vue 的组件作用域都是孤立的,不允许在子组件的模板内直接引用父组件的数据.必须使用特定的方法才能实现组件之间的数据传递. 首先用 vue-cli 创建一个项目,其中 App.vue 是父组件,com ...

  3. 如何判断img标签是否有src属性

    前几天,写一个小项目,需要判断img标签是否有src属性,想了半天,只能想到用jq实现,如下: if($(".img").attr("src")==undefi ...

  4. java 局部变量几点笔记

    1.局部变量的作用时间很短暂,都被存储在方法的栈内存中:2.(没使用static)非静态变量=实例变量:(使用static)静态变量=类变量3.成员变量:类体内定义的变量:4.局部变量有三种:1)形参 ...

  5. 使用dom4j讲xml字符串递归遍历成Map

    package test; import java.util.ArrayList;import java.util.HashMap;import java.util.Iterator;import j ...

  6. 移动端车牌识别、行驶证识别OCR为共享汽车APP增添技术色彩

    本文主题:移动端车牌识别.行驶证识别OCR为共享汽车APP增添技术色彩 本文关键词:车牌识别,证件识别,移动端车牌识别,行驶证识别,手机车牌识别,驾驶证识别 近两年,随着共享单车以及共享电车的兴起,有 ...

  7. java源码学习(五)LinkedList

    LinkedList [TOC] 一.定义 public class LinkedList<E> extends AbstractSequentialList<E> imple ...

  8. NoSQL数据库:Redis适用场景及产品定位

    传统MySQL+ Memcached架构遇到的问题 实际MySQL是适合进行海量数据存储的,通过Memcached将热点数据加载到cache,加速访问,很多公司都曾经使用过这样的架构,但随着业务数据量 ...

  9. 2.Smarty的引入和实例化

    1.把demo和lib复制出来,并且创建一个test文件夹作为工作的目录 如图所示: 2.这是libs里面的内容,其中smarty.class.php包含了smarty各种方法和功能,需要实例化它还工 ...

  10. DOCKER 从入门到放弃(一)

    前言 关于docker的各种概念已有各位大神珠玉在前,请各位自行查看,本系列的目的是各种详细操作步骤 各种概念特别推荐CloudMan的3篇blog: http://www.cnblogs.com/C ...