深入讲解.Net Core中的Api版本控制

前言

.NET Core 是指 .NET Core 运行时和 .NET Core SDK,它包含开发应用程序所需的工具。 .NET Core SDK 可与任何以前版本的 .NET Core 运行时一起使用。

本文主要介绍了关于.Net Core Api版本控制的相关内容,下面话不多说了,来一起看看详细的介绍吧

原文链接:API Versioning in .Net Core

作者:Neel Bhatt

简介

Api的版本控制是Api开发中经常遇到的问题, 在大部分中大型项目都需要使用到Api的版本控制

在本篇博客中,我们将说明一下如何在.Net Core Api项目中使用Api版本控制。

本篇博客中测试项目的开发环境:

  • Visual Studio 2017
  • .Net Core 2.1 SDK

.Net Core Api中使用Api版本控制

创建一个Api项目

首先我们创建一个.NET Core Api项目

使用Nuget安装Api版本控制库

.NET Core Mvc中,微软官方提供了一个可用的Api版本控制库Microsoft.AspNetCore.Mvc.Versioning。 这里我们可以使用Nuget安装这个包。

PM> Install-Package Microsoft.AspNetCore.Mvc.Versioning

修改Startup类

Microsoft.AspNetCore.Mvc.Versioning库安装完成之后,下一步我们来添加Api版本控制服务。

这里我们需要在Startup类的ConfigureService方法中添加以下代码。

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

代码解释

ReportApiVersion 属性是一个布尔类型,如果设置为true, 在Api请求的响应头部,会追加当前Api支持的版本, 例

Response Header
api-supported-versions: 1.0
content-type: application/json; charset=utf-8
date: Sat, 06 Oct 2018 05:24:21 GMT
server: Kestrel
status: 200
x-powered-by: ASP.NET

AssumeDefaultVersionWhenUnspecified属性是为了标记当客户端没有指定版本号的时候,是否使用默认版本号
DefaultApiVersion属性即默认版本号

创建多版本Api

这里为了测试.Net Core Mvc的Api版本控制库,我们创建如下2个Controller。

 [ApiVersion("1.0")]
 [Route("api/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
 [HttpGet]
 public IEnumerable<string> Get()
 {
  return new string[] { "Value1 from Version 1", "value2 from Version 1" };
 }
 } 

 [ApiVersion("2.0")]
 [Route("api/values")]
 [ApiController]
 public class ValuesV2Controller : ControllerBase
 {
 [HttpGet]
 public IEnumerable<string> Get()
 {
  return new string[] { "value1 from Version 2", "value2 from Version 2" };
 }
 }

代码解释

  • Value1Controller和Value2Controller使用了一样的路由"/api/values"
  • Value1Controller类头部使用ApiVersion特性标记了当前Controller的Api版本号是1.0
  • Value2Controller类头部使用ApiVersion特性标记了当前Controller的Api版本号是2.0
    -Value1Controller和Value2Controller都持有相同方法签名的Get方法, 只是2个Get中返回了不同的字符串

现在我们启动项目,得到的结果如下,说明当没有指定Api版本号时,项目自动使用1.0版本的Api, 即ValuesV1Controller中的Get方法。

如何在查询字符串(Query String)中使用版本控制

Microsoft.AspNetCore.Mvc.Versioning支持以QueryString的形式指定请求Api的版本号。开发人员可以在Url中指定api-version参数来选择调用的Api版本号。

以当前项目为例

当请求https://localhost:44319/api/values?api-version=2.0时, 返回结果

["value1 from Version 2","value2 from Version 2"]

当请求https://localhost:44319/api/values?api-version=1.0时, 返回结果

["Value1 from Version 1","value2 from Version 1"]

如何使用路由约束中指定请求Api的版本

Microsoft.AspNetCore.Mvc.Versioning还支持使用路由约束指定请求Api的版本号。

例: [Route(“api/{v:apiVersion}/Values”)]

我们对之前2个Controller的代码作如下修改。

 [ApiVersion("1.0")]
 [Route("api/{v:apiVersion}/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "Value1 from Version 1", "value2 from Version 1" };
  }
 } 

 [ApiVersion("2.0")]
 [Route("api/{v:apiVersion}/values")]
 [ApiController]
 public class ValuesV2Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "value1 from Version 2", "value2 from Version 2" };
  }
 }

现在我们通过以下2个Url请求Api, 返回的结果如下 :

/api/2.0/values

["value1 from Version 2","value2 from Version 2"]

/api/1.0/values

["Value1 from Version 1","value2 from Version 1"]

如何在请求头(HTTP Header)中使用版本控制

以上的2种方式需要修改请求的Url, 如果你不喜欢这2种方式,Microsoft.AspNetCore.Mvc.Versioning还提供了第三种指定Api版本号的方式,即在HTTP请求头中添加版本号参数。

为了启用这种方式,我们首先需要在Startup.cs中修改Microsoft.AspNetCore.Mvc.Versioning的配置, 代码如下:

 services.AddApiVersioning(o =>
 {
  o.ReportApiVersions = true;
  o.AssumeDefaultVersionWhenUnspecified = true;
  o.DefaultApiVersion = new ApiVersion(1, 0);
  o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
 });

这里通过ApiVersionReader属性指定了Api版本号是从请求头部的x-api-version属性来的。

Tips: 一旦你使用o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");, 在查询字符串中指定版本号的方式将不再可用,如果你希望同时支持2种方式,请改用o.ApiVersionReader = ApiVersionReader.Combine(new QueryStringApiVersionReader(), new HeaderApiVersionReader() { HeaderNames = { "x-api-version" }});(多谢seamaswang的更正)

下面我们通过Postman来请求2.0的Api, 结果正确返回了。

其他特性弃用Api(Deprecated)特性

有些时候,我们需要标记一些过时的Api为弃用状态,但是我们又不希望完全移除这个版本的Api, 我们可以使用Deprecated特性。

例:我们当前希望弃用ValuesV1Controller, 我们可以指定Deprecated特性的值为true

 [ApiVersion("1.0", Deprecated = true)]
 [Route("api/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "Value1 from Version 1", "value2 from Version 1" };
  }
 }

当我们请求在此请求这个api的时候, 在响应头中会出现api-deprecated-versions和api-supported-versions2个属性。

Response Header
api-deprecated-versions: 1.0
api-supported-versions: 2.0
content-type: application/json; charset=utf-8
date: Sat, 06 Oct 2018 06:32:18 GMT
server: Kestrel
status: 200
x-powered-by: ASP.NET

这段响应的意思就是1.0版本的Api已经过期了,2.0版本中有相同的Api, 可以换用2.0版本的Api。

使用ApiVersionNeutral指定不需要版本控制的Api

在编写Api的时候,对于一些非常简单的Api, 我们可能不需要指定Api版本号, 例如健康检查Api。我们可以使用ApiVersionNeutral特性,将它从Api版本控制中排除掉。

例:

 [ApiVersionNeutral]
 [Route("api/[controller]")]
 [ApiController]
 public class HealthCheckController : ControllerBase
 {
  public string Get()
  {
   return "Good";
  }
 }

本篇源代码 (本地下载)

总结

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,如果有疑问大家可以留言交流,谢谢大家对我们的支持。

(0)

相关推荐

  • 浅谈ASP.Net Core WebApi几种版本控制对比

    一.版本控制的好处: (1)有助于及时推出功能, 而不会破坏现有系统. (2)它还可以帮助为选定的客户提供额外的功能. API 版本控制可以采用不同的方式进行控制,方法如下: (1)在 URL 中追加版本或作为查询字符串参数, (2)通过自定义标头和通过接受标头 在这篇文章中, 让我们来看看如何支持多个版本的 ASP.NET Core Web API. 一.创建asp.net core webapi 项目,引用NuGet包:Install-Package Microsoft.AspNetCore

  • .Net Core Api 使用版本控制详解

    Api的版本控制是Api开发中经常遇到的问题, 在大部分中大型项目都需要使用到Api的版本控制 在本篇博客中,我们将说明一下如何在.Net Core Api项目中使用Api版本控制. 本篇博客中测试项目的开发环境: Visual Studio 2017 .Net Core 2.1 SDK 1,安装Microsoft.AspNetCore.Mvc.Versioning NET Core Mvc中,微软官方提供了一个可用的Api版本控制库Microsoft.AspNetCore.Mvc.Versio

  • 深入讲解.Net Core中的Api版本控制

    前言 .NET Core 是指 .NET Core 运行时和 .NET Core SDK,它包含开发应用程序所需的工具. .NET Core SDK 可与任何以前版本的 .NET Core 运行时一起使用. 本文主要介绍了关于.Net Core Api版本控制的相关内容,下面话不多说了,来一起看看详细的介绍吧 原文链接:API Versioning in .Net Core 作者:Neel Bhatt 简介 Api的版本控制是Api开发中经常遇到的问题, 在大部分中大型项目都需要使用到Api的版

  • .NET Core 中的并发编程

    并发编程 - 异步 vs. 多线程代码 并行编程是一个广泛的术语,我们应该通过观察异步方法和实际的多线程之间的差异展开探讨. 尽管 .NET Core 使用了任务来表达同样的概念,一个关键的差异是内部处理的不同. 调用线程在做其他事情时,异步方法在后台运行.这意味着这些方法是 I/O 密集型的,即他们大部分时间用于输入和输出操作,例如文件或网络访问. 只要有可能,使用异步 I/O 方法代替同步操作很有意义.相同的时间,调用线程可以在处理桌面应用程序中的用户交互或处理服务器应用程序中的同时处理其他

  • ASP.Net Core中的日志与分布式链路追踪

    目录 .NET Core 中的日志 控制台输出 非侵入式日志 Microsoft.Extensions.Logging ILoggerFactory ILoggerProvider ILogger Logging Providers 怎么使用 日志等级 Trace.Debug 链路跟踪 OpenTracing 上下文和跟踪功能 跟踪单个功能 将多个跨度合并到一条轨迹中 传播过程中的上下文 分布式链路跟踪 在不同进程中跟踪 在 ASP.NET Core 中跟踪 OpenTracing API 和

  • .NET实现API版本控制

    目录 1. 优点 2. API版本控制 2.1 安装组件 2.1.1 常用配置 2.2 QueryString来实现版本控制 2.2.1 ConfigureServices中配置 2.2.2 控制器设置版本 2.2.3 特定方法设置版本 2.2.4 设置不受版本控制 2.3.5 访问地址 2.3 URL Path Segment来实现版本控制 2.3.1 ConfigureServices中配置 2.3.2 控制器设置版本 2.3.3 特定方法设置版本 2.3.4 设置不受版本控制 2.3.5

  • 运用.net core中实例讲解RabbitMQ高可用集群构建

    目录 一.集群架构简介 二.普通集群搭建 2.1 各个节点分别安装RabbitMQ 2.2 把节点加入集群 2.3 代码演示普通集群的问题 三.镜像集群 四.HAProxy环境搭建. 五.KeepAlived 环境搭建 一.集群架构简介 当单台 RabbitMQ 服务器的处理消息的能力达到瓶颈时,此时可以通过 RabbitMQ 集群来进行扩展,从而达到提升吞吐量的目的.RabbitMQ 集群是一个或多个节点的逻辑分组,集群中的每个节点都是对等的,每个节点共享所有的用户,虚拟主机,队列,交换器,绑

  • 运用.net core中实例讲解RabbitMQ

    目录 一.RabbitMQ简介 (1) AMQP协议 (2)AMQP专业术语 (3)RabbitMQ整体架构 二.安装RabbitMQ 三.RabbitMQ六种队列模式在.NetCore中使用 (1)简单队列 (2)工作队列模式 (3)发布订阅模式 (4)路由模式(推荐使用) (5)主题模式 (6)RPC模式 总结 一.RabbitMQ简介 是一个开源的消息代理和队列服务器,用来通过普通协议在完全不同的应用之间共享数据,RabbitMQ是使用Erlang(高并发语言)语言来编写的,并且Rabbi

  • ASP.NET Core 6最小API中使用日志和DI示例详解

    目录 在ASP.NET Core 6的最小API中使用日志和DI 如何在ASP.NET Core 6的最小API中实现日志.从配置系统中读取并使用依赖注入 CI/CD?持续集成和持续交付解释 在Visual Studio 2022中创建一个ASP.NET Core minimal web API项目 运行一个最小的网络API 为一个最小的网络API配置多个端口 在最小的Web API中使用日志记录 在最小的API中从配置系统中读取 在最小的网络API中使用依赖性注入 在一个最小的Web API中

  • .NET Core中本地化机制的深入讲解

    前言 ASP.NET Core中提供了一些本地化服务和中间件,可将网站本地化为不同的语言文化. ASP.NET Core中我们可以使用Microsoft.AspNetCore.Localization库来实现本地化. 在.NET Core 2.0以上版本, Microsoft.AspNetCore.Localization已经包含在了Microsoft.AspNetCore.All中,所以我们并不需要手动引入其他的类库. 创建一个MVC网站 为了测试ASP.NET Core的本地化,我们首先在V

  • ASP.NET Core3.x API版本控制的实现

    前言 一般来说需要更改我们API的时候才考虑版本控制,但是我觉得我们不应该等到那时候来实现它,我们应该有一个版本策略从我们应用程序开发时就开始制定好我们的策略,我们一直遵循着这个策略进行开发. 我们其实可以通过多种方式进行实现我们API版本的控制,其实对于版本控制没有最好的方式,这完全取决于我们面向的使用者. API版本控制类型 安装版本控制包 Install-Package Microsoft.AspNetCore.Mvc.Versioning 在Startup.cs中的ConfigureSe

随机推荐