.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" };
        }
    }

代码解释

  • Value1ControllerValue2Controller使用了一样的路由"/api/values"
  • Value1Controller类头部使用ApiVersion特性标记了当前Controller的Api版本号是1.0
  • Value2Controller类头部使用ApiVersion特性标记了当前Controller的Api版本号是2.0
    -Value1ControllerValue2Controller都持有相同方法签名的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 = new QueryStringOrHeaderApiVersionReader("x-api-version");

下面我们通过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-versionsapi-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";
        }
    }

本篇源代码

原文地址:https://www.cnblogs.com/lwqlun/p/9747180.html

时间: 2024-10-08 09:02:52

.Net Core中的Api版本控制的相关文章

【转】ASP.NET Core API 版本控制

几天前,我和我的朋友们使用 ASP.NET Core 开发了一个API ,使用的是GET方式,将一些数据返回到客户端 APP.我们在前端进行了分页,意味着我们将所有数据发送给客户端,然后进行一些data.length操作,以获得items count用于分页逻辑.为了减少HTTP请求的负荷,我们决定在后端(服务器端分页)实现逻辑.在我们这样的情况下,这是没有任何问题的,因为我们在客户端能快速实现.我们在客户端和服务端修改了所有逻辑,并且快速完成所有功能. 但是,您可能会有其他客户端在使用,因为只

[翻译]在 .NET Core 中的并发编程

原文地址:http://www.dotnetcurry.com/dotnet/1360/concurrent-programming-dotnet-core 今天我们购买的每台电脑都有一个多核心的 CPU,允许它并行执行多个指令.操作系统通过将进程调度到不同的内核来发挥这个结构的优点.然而,还可以通过异步 I/O 操作和并行处理来帮助我们提高单个应用程序的性能.在.NET Core中,任务 (tasks) 是并发编程的主要抽象表述,但还有其他支撑类可以使我们的工作更容易. 并发编程 - 异步 v

在.NET Core中使用Jwt对API进行认证

在.NET Core中想用给API进行安全认证,最简单的无非就是Jwt,悠然记得一年前写的Jwt Demo,现在拿回来改成.NET Core的,但是在编码上的改变并不大,因为Jwt已经足够强大了.在项目中分为 DotNetCore_Jwt_Server 以及 DotNetCore_Jwt_Client ,从名字就可以看出来是啥意思,博客园高手云集,我就不多诉说,这篇博客就当是一篇记录. 当然本案例是Server&Client双项目,如果你要合成自己发证的形式,那你就自己改下代码玩. 在Serve

.net core 中api 模型验证

AddControllers/AddMvc方法允许添加自定义ActionFilterAttribute进行过滤 文档中这么定义Filter: 可以创建自定义筛选器,用于处理横切关注点. 横切关注点的示例包括错误处理.缓存.配置.授权和日志记录. 筛选器可以避免复制代码. 例如,错误处理异常筛选器可以合并错误处理. 通过不同的接口定义,筛选器同时支持同步和异步实现. 同步筛选器在其管道阶段之前和之后运行代码. 例如,OnActionExecuting 在调用操作方法之前调用. OnActionEx

谈谈微服务中的 API 网关(API Gateway)

转载至:http://www.cnblogs.com/savorboard/p/api-gateway.html 背景 我们知道在微服务架构风格中,一个大应用被拆分成为了多个小的服务系统提供出来,这些小的系统他们可以自成体系,也就是说这些小系统可以拥有自己的数据库,框架甚至语言等,这些小系统通常以提供 Rest Api 风格的接口来被 H5, Android, IOS 以及第三方应用程序调用. 但是在UI上进行展示的时候,我们通常需要在一个界面上展示很多数据,这些数据可能来自于不同的微服务中,举

Asp.Net Core中使用Swagger,你不得不踩的坑

很久不来写blog了,换了新工作后很累,很忙.每天常态化加班到21点,偶尔还会到凌晨,加班很累,但这段时间,也确实学到了不少知识,今天这篇文章和大家分享一下:Asp.Net Core中使用Swagger,你不得不踩的坑. 这篇文章着重讲几点: swagger 跨层注释问题 swagger Get请求传多个参数的问题 swagger Enum 注释问题 swagger api文档版本控制 第一步:搭建一个webapi项目或者mvc项目,引入swagger nuget 我创建项目,习惯性的先创建一个

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

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

API版本控制

译者注:本文主要描述了几种API版本控制的方法.用户可以查询原始的API,或者添加定制的头文件来接收特定的版本.如果应用程序收到一个重大修订,将URI修改为V2.在进行迭代改进时,将创建与更改日期相一致的端点,并允许用户将日期信息附加.然后,可以选择保留旧版本的时间.而且在设计和版本化API时,您可以应用许多不同的理念.以下为译文 API设计是一个"火辣热门"的话题!关于API的最佳结构和版本的方法已经有很多优秀的文章介绍过了.在这篇文章中,我们将会深入研究不同的API设计之间有哪些冲

NET Core中怎么使用HttpContext.Current

NET Core中怎么使用HttpContext.Current 阅读目录 一.前言 二.IHttpContextAccessor 三.HttpContextAccessor 回到目录 一.前言 我们都知道,ASP.NET Core作为最新的框架,在MVC5和ASP.NET WebForm的基础上做了大量的重构.如果我们想使用以前版本中的HttpContext.Current的话,目前是不可用的,因为ASP.NET Core中是并没有这个API的. 当然我们也可以通过在Controller中访问