微信号:CodePush

介绍:为程序员提供最优质的博文、最精彩的讨论、最实用的开发资源;提供最新最全的编程学习资料:PHP、Objective-C、Java、Swift、C/C++函数库、.NET Framework类库、J2SE API等等.并不定期奉送各种福利.

.NET Core中的API版本控制

2018-10-10 10:24 程序员大咖


Java编程精选
点击右侧关注,免费入门到精通!


 英文neelbhatt.com

 来源Neel Bhatt

 译文cnblogs.com/lwqlun/archive


简介


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安装这个包。


PMInstall-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(10);

});


代码解释


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



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


DefaultAPIVersion属性即默认版本号


创建多版本API


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



代码解释


  • 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版本号。




现在我们通过以下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(10);

    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<stringGet()

    
{

        return new string[] { "Value1 from Version 1""value2 from Version 1" };

    }

}


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



这段响应的意思就是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://files.cnblogs.com/files/lwqlun/ApiVersioningSample.zip


【点击成为源码大神】

 
程序员大咖 更多文章 年薪30万却因没房被女方家庭嫌弃,程序员:我们可以一起奋斗啊 IT公司老板落水,各部门员工怎么救 重磅!编程进入重庆中小学,连课时都定了 开源作者痛斥京东重量级项目抄袭 程序员在火车站候车室写代码画面曝光,网友:程序员的悲哀
猜您喜欢 Etcd 架构与实现解析 MySQL存储引擎MyISAM与InnoDB的优劣 DaoCloud 与 Linkface 建立合作伙伴关系,聚焦金融行业的新一代人工智能 JVM源码分析之自定义类加载器如何拉长YGC 匆匆六月,匆匆的大学