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

 更新时间:2020-06-14 00:02:03   作者:佚名   我要评论(0)

前言


一般来说需要更改我们API的时候才考虑版本控制,但是我觉得我们不应该等到那时候来实现它,我们应该有一个版本策略从我们应用程序开发时就开始制定好我们的

前言

一般来说需要更改我们API的时候才考虑版本控制,但是我觉得我们不应该等到那时候来实现它,我们应该有一个版本策略从我们应用程序开发时就开始制定好我们的策略,我们一直遵循着这个策略进行开发。

我们其实可以通过多种方式进行实现我们API版本的控制,其实对于版本控制没有最好的方式,这完全取决于我们面向的使用者。

API版本控制类型

安装版本控制包

Install-Package Microsoft.AspNetCore.Mvc.Versioning

在Startup.cs中的ConfigureServices方法中进行版本设置,以及在控制器通过特性进行设置版本,这样可以实现版本控制。

services.AddApiVersioning(options => {
  options.DefaultApiVersion = new ApiVersion(1, 0);
  options.AssumeDefaultVersionWhenUnspecified = true;
  options.ReportApiVersions = true;
});
  • options.DefaultApiVersion = new ApiVersion(1,0): 这个设置不是必须的,因为默认情况下给我们设置的是1.0,但是显式的声明出来是一个很好的习惯,当然DefaultApiVersion它会将默认的[ApiVersion("1.0")]添加到控制器上,也就是说它会隐式的绑定API版本,但是为了我们方便理解或者说方便我们后面开发建议显式的设置。
  • options.AssumeDefaultVersionWhenUnspecified = true:默认API版本控制需要将其属性设置为true才可以开启
  • options.ReportApiVersions = true:默认情况下它是禁用的,启用此选项后,来自我们API端点的响应将带有标头,告诉我们的客户端支持或不推荐使用哪个版本(api-supported-versions:1.1,2.0, api-deprecated-versions:1.0)

默认提供了四种版本控制方法:

  • 字符串参数
  • 通过HTTP请求头
  • URL方式
  • 媒体类型(Media Type)

默认方法是使用名为api-version 的查询字符串参数。我们还可以自己定义一个版本控制规则。

API版本约束方式

字符串参数形式

services.AddApiVersioning(options => 
  options.ApiVersionReader = new QueryStringApiVersionReader("v"));

HTTP请求头

services.AddApiVersioning(options => 
  options.ApiVersionReader = new HeaderApiVersionReader("api-version"));

组合方式

services.AddApiVersioning(options => {
  options.ApiVersionReader = ApiVersionReader.Combine(
    new QueryStringApiVersionReader("v"),
    new HeaderApiVersionReader("v"));});

URL方式

services.AddApiVersioning(options => options.ApiVersionReader = 
  new UrlSegmentApiVersionReader());

我们可以更改代表版本的参数名称(例如,在上面的查询字符串方法中,我们使用字母v代替默认的api-version)。

控制器和方法中添加版本信息

选择版本控制策略并在ConfigureServices方法中对其配置后,我们可以开始对API端点进行版本控制,我们可以将这些属性应用于控制器和方法。

  • 控制器的默认可能没有任何API版本属性,并隐式配置的默认API版本。默认配置使用值1.0。
  • 使用[ApiVersion("1.0")]属性注释我们的控制器,意味着该控制器支持API版本1.0
  • 控制器可以支持多个API版本。只需[ApiVersion(...)]在控制器上应用多个属性
  • 为了区分控制器支持的多个版本,我们使用[MapToApiVersion()]属性注释控制器方法。

如果要使用URL路径则可以参考如下代码片段:

[Route("api/v{version:apiVersion}/[controller]")]

API控制器弃用,我们只需要设置

[ApiVersion("1.0", Deprecated = true)]

可通过如下方法方式获取所有API版本信息

var apiVersion = HttpContext.GetRequestedApiVersion();

当然他还支持模型绑定,我们还可以通过模型形式获取

 [HttpGet]
  public string Get(ApiVersion apiVersion) => $"Controller = {GetType().Name}\nVersion = {apiVersion}";
  }

API版本约束

我们除了在方法和控制器上指定我们的版本,我们还可以采用另一种方式

services.AddApiVersioning( options =>
{
  options.Conventions.Controller<HomeController>().HasApiVersion(1, 0);
});

看如上代码我们可以看到我们在这里给HomeController配置版本,这样方便我们集中管理我们的版本。

services.AddApiVersioning( options =>
{
  options.Conventions.Controller<MyController>()  
            .HasDeprecatedApiVersion(1, 0)
            .HasApiVersion(1, 1)
            .HasApiVersion(2, 0)
            .Action(c => c.Get1_0()).MapToApiVersion(1, 0)
            .Action(c => c.Get1_1()).MapToApiVersion(1, 1)
            .Action(c => c.Get2_0()).MapToApiVersion(2, 0);
});

可以同时使用API版本约束和版本控制属性。

当然我们还可以自定义约束,从.NET Core 3.0开始,有一个IControllerConvention用于此目的的接口。

options.Conventions.Add(new MyCustomConvention());

当然我们还可以通过不同命名空间中的接口进行约束

options.Conventions.Add(new VersionByNamespaceConvention());

比如下面这种文件形式

api/v1/UsersController
api/v2/UsersController
api/v2_1/UsersController

映射后的路径如下所示

api/1.0/users
api/2.0/users
api/2.1/users

到此这篇关于ASP.NET Core3.x API版本控制的实现的文章就介绍到这了,更多相关ASP.NET Core3.x API版本控制内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

您可能感兴趣的文章:

  • ASP.NET Core3.X 终端中间件转换为端点路由运行详解
  • ASP.NET Core 3.x 并发限制的实现代码

相关文章

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

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

    前言 一般来说需要更改我们API的时候才考虑版本控制,但是我觉得我们不应该等到那时候来实现它,我们应该有一个版本策略从我们应用程序开发时就开始制定好我们的
    2020-06-14
  • Asp.net Core中实现自定义身份认证的示例代码

    Asp.net Core中实现自定义身份认证的示例代码

    Asp.Net Core中虽然集成了许多常用的身份认证,但很多时候,我们还是需要实现自己的身份认证接口,本文这里就简单的介绍下如何实现自定义身份认证接口。 首先写一个
    2020-06-14
  • ASP.NET Core WebAPI实现本地化(单资源文件)

    ASP.NET Core WebAPI实现本地化(单资源文件)

    在Startup ConfigureServices 注册本地化所需要的服务AddLocalization和 Configure<RequestLocalizationOptions> public void ConfigureServices(IServiceCollec
    2020-06-14
  • 关于.NET Attribute在数据校验中的应用教程

    关于.NET Attribute在数据校验中的应用教程

    前言 Attribute(特性)的概念不在此赘述了,相信有点.NET基础的开发人员都明白,用过Attribute的人也不在少数,毕竟很多框架都提供自定义的属性,类似于Newtonsoft
    2020-06-14
  • ASP.NET开源导入导出库Magicodes.IE完成Csv导入导出的方法

    ASP.NET开源导入导出库Magicodes.IE完成Csv导入导出的方法

    说明 本章主要说明如何使用Magicodes.IE.Csv进行Csv导入导出. 关于Magicodes.IE 导入导出通用库,通过导入导出DTO模型来控制导入和导出,支持Excel、Word、Pd
    2020-06-14
  • .net core 3.1在iis上发布的踩坑记录

    .net core 3.1在iis上发布的踩坑记录

    前言 写这篇文章的目的是希望像我一样喜欢.net 的人在发布 core到 iis上时少走点弯路 网上找了些资料,其实实际操作比较简单,就是有几个坑很恶心 踩坑记录 首先是你
    2020-06-14
  • .NET IoC模式依赖反转(DIP)、控制反转(Ioc)、依赖注入(DI)

    .NET IoC模式依赖反转(DIP)、控制反转(Ioc)、依赖注入(DI)

    依赖倒置原则(DIP) 依赖倒置(Dependency Inversion Principle,缩写DIP)是面向对象六大基本原则之一。他是指一种特定的的解耦形式,使得高层次的模块不依赖低层次的
    2020-06-14
  • asp.net mvc core管道及拦截器的理解

    asp.net mvc core管道及拦截器的理解

    今天来看一下asp.net core的执行管道。先看下官方说明: 从上图可以抛光,asp.net core的执行顺序是,当收到一个请求后,request请求会先经过已注册的中间件,然后
    2020-06-14
  • 聊一聊Asp.net过滤器Filter那一些事

    聊一聊Asp.net过滤器Filter那一些事

    最近在整理优化.net代码时,发现几个很不友好的处理现象:登录判断、权限认证、日志记录、异常处理等通用操作,在项目中的action中到处都是。在代码优化上,这一点是
    2020-06-14
  • xUnit 编写 ASP.NET Core 单元测试的方法

    xUnit 编写 ASP.NET Core 单元测试的方法

    还记得 .NET Framework 的 ASP.NET WebForm 吗?那个年代如果要在 Web 层做单元测试简直就是灾难啊。.NET Core 吸取教训,在设计上考虑到了可测试性,就连 ASP.NET
    2020-06-14

最新评论