大家好,我是张飞洪,感谢您的阅读,我会不定期和你分享学习心得,希望我的文章能成为你成长路上的垫脚石,让我们一起精进。
为了了解ASP.NET Core Web API的版本控制,我们必须了解API中的一些版本控制策略,然后将API版本控制与OpenAPI集成,以便我们可以在Swagger UI中看到版本化的API。
API版本控制的目的是为了解决接口运维的问题。随着时间推移,我们希望对那些调用API的前端人员,都有一个固定不变的API调用规则和策略。因为需求会变化,业务会增长,如果我们对API的设计没有进行版本控制,那么依赖API的用户将变得无所适从,加上团队人员的变迁,这会大大降低我们的联调效率。
这就是我们为什么要进行API版本控制的目的所在。那么,我们如何对API进行版本化呢?
我们这里讨论三种最常用的API版本控制策略。
1)URI路径版本控制
URI路径策略很受欢迎,因为它更易于实现。一般我们会在URI路径的某个地方插入一个版本指示符,如v1或v2,如下所示:https://iot.com/api/v1/products
以上是版本1,如果要升级为版本2,我们直接将v1改成v2即可:https://iot.com/api/v2/products
注意在切换API版本时,为了获得正确的API返回的内容,原来的URI作为缓存键可能会失效。基于路径的版本控制很通用,几乎大部分的平台或者语言都支持这种方法,几乎成为了一种默认的标准,我们的案例代码默认也是采用这种策略。
2)Header版本控制
使用Header(头部)进行版本控制,头部一个谓词,并且有一个头部值,该值就是调用者需要分辨的版本号,如以下示例内容:GET /api/products HTTP/1.1 Host: localhost:5001 Content-Type: application/json x-api-version: 2
此策略有个好处是它不会损坏URI。但是,在客户端使用这些类型的API会比较麻烦一些。
3)查询字符串版本控制
查询字符串(Query string)根据API的使用者的需要,使用查询字符串指定API的版本。,如果请求中没有查询字符串,则应该具有API的隐式默认版本。我们看一个示例:https://iot.com/api/products?api-version=2
以上三种策略都有各自的使用场景,具体应该选择哪一个,取决于消费方法以及未来的规划。
我们可能会碰到一种需求,就是希望告知API调用方,哪些API不再推荐使用。比如一旦某个API版本在未来几个月没有人使用,我们希望删除该API:[ApiVersion("1.0", Deprecated = true)]
具体使用很简单,这是Microsoft.AspNetCore.Mvc名称空间下的使用方式,凡是加上这种特性的API都会别废弃使用。
以上我们了解API版本控制的一些理论介绍,接下来我们通过代码来实现版本控制,以及如何将它们与OpenAPI集成方便在Swagger UI中查看。
本文是基于我视频的项目代码,所以在下面的代码连贯性上可能对您会有影响,但是整体上不影响您的理解。
如果您想查看完整的代码,可以订阅我的视频,不胜感觉。
为了通过代码实现版本控制,我们需要切换到Iot.WebApi项目下进行,我们先在该项目下安装两个NuGet包:
dotnet add package Microsoft.AspNetCore.Mvc.Versioningdotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
第一个包是基于ASP.NET Core Mvc的版本服务,第二个包用于查找URL和HTTP方法、查找Controller(控制器)和Action元数据的一些功能。
接着,我们在Controller目录下创建两个文件夹,v1和v2,我们原先创建的控制器全部默认迁移到v1下,并修改一下相关的名称空间,原来是:Iot.WebApi.Controllers
现在改成:Iot.WebApi.Controllers.v1
然后,我们修改抽象基类ApiContoller头部的特性:
[ApiVersion("1.0")][ApiController][Route("api/v{version:apiVersion}/[controller]")]public abstract class ApiController : ControllerBase{ private IMediator _mediator; protected IMediator Mediator => _mediator ??= HttpContext.RequestServices.GetService<IMediator>();}
我们添加了一个ApiVersion特性,并指定版本号,更新Route为动态API版本,所有继承该基类的控制器都会标记上版本号。
我们还可以通过Deprecated来弃用WeatherForecast接口:
namespace Travel.WebApi.Controllers.v1 { [ApiVersion("1.0", Deprecated = true)] public class WeatherForecastController : ApiController { …} }
废弃了一个接口,我们一般会创建一个新的接口版本,我们在v2文件夹下创建一个新的WeatherForecast.cs文件,代码如下所示:
namespace Travel.WebApi.Controllers.v2 { [ApiVersion("2.0")] [ApiController] [Route("api/v{version:apiVersion}/[controller]")] public class WeatherForecastController : ControllerBase { … [HttpPost] public IEnumerable<WeatherForecast> Post(string city) { var rng = new Random(); return Enumerable.Range(1,5).Select(index => new WeatherForecast { … City = city}).ToArray(); } } }
新旧接口的主要区别是HTTP方法,在版本1中,必须发送一个GET请求以获取日期和温度数据,而在版本2中,必须使用查询参数city发送一个POST请求。
因此,API必须具有版本控制,以避免中断第一个版本的API导致的问题。
带有查询的POST请求不是好的做法,因为它是非幂等的,而GET、PUT和DELETE用于幂等请求。这里先将就用着。
我们先在Iot.WebApi的根目录中创建一个新文件夹并命名为Helpers。然后创建两个C#文件,SwagerOptions.cs和SwaggerDefaultValue.cs,ConfigureSwaggerOptions.cs如下所示:
using System; using Microsoft.AspNetCore.Mvc.ApiExplorer; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Options; using Microsoft.OpenApi.Models; using Swashbuckle.AspNetCore.SwaggerGen; namespace IoT.WebApi.OpenApi { public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions> { … public void Configure(SwaggerGenOptions options) {…} private static OpenApiInfo CreateInfoForApiVersion (ApiVersionDescription description) {…} } }
这里有两个方法:Configure和OpenApiInfo,下面是Configure方法的代码块:
public void Configure(SwaggerGenOptions options) { foreach (var description in _provider.ApiVersionDescriptions) options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description)); }
Configure方法的作用是为每个新发现的API版本添加一个Swagger文档。下面是OpenApiInfo方法的代码块:
private static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description){ var info = new OpenApiInfo { Title = "Travel Tour", Version = description.ApiVersion.ToString(), Description = "Web Service for Travel Tour.", Contact = new OpenApiContact { Name = "IT Department", Email = "developer@traveltour.xyz", Url = new Uri("https://traveltour.xyz/support") } }; if (description.IsDeprecated) info.Description += " <strong>This API version of Travel Tour has been deprecated.</strong>"; return info;}
此代码用于Swagger相关信息设置,如应用程序的标题、版本、描述、联系人姓名、联系人电子邮件和URL。
我们再看下SwaggerDefaultValues.cs:
public class SwaggerDefaultValues : IOperationFilter{ public void Apply(OpenApiOperation operation, OperationFilterContext context) { // }}
SwaggerDefaultValues 会重写并替换Startup.cs中的services.AddSwaggerGen()。下面是Apply方法的代码:
var apiDescription = context.ApiDescription;operation.Deprecated |= apiDescription.IsDeprecated(); if (operation.Parameters == null) return; foreach (var parameter in operation.Parameters){ var description = apiDescription.ParameterDescriptions.First( pd => pd.Name == parameter.Name); parameter.Description ??= description.ModelMetadata.Description; if (parameter.Schema.Default == null && description.DefaultValue != null) parameter.Schema.Default = new OpenApiString(description.DefaultValue.ToString()); parameter.Required |= description.IsRequired;}
Apply方法允许Swagger生成器添加API资源管理器的所有相关元数据。
接下来我们更新一下Startup.cs文件,在ConfigureServices中找到AddSwageGen方法,然后使用下面代码进行替换:
services.AddSwaggerGen(c =>{ c.OperationFilter<SwaggerDefaultValues>();});
这里使用过滤器配置我们之前创建的SwaggerDefaultValue。接下来在AddSwaggerGen方法后面给ConfigureSwaggerOptions设置服务生命周期:
services.AddTransient<IConfigureOptions, ConfigureSwaggerOptions>();
我们还要添加对ApiVersioning的注册(Microsoft.AspNetCore.Mvc.Versioning):
services.AddApiVersioning(config =>{ config.DefaultApiVersion = new ApiVersion(1, 0); config.AssumeDefaultVersionWhenUnspecified = true; config.ReportApiVersions = true;});
上面的代码在服务集合中添加了版本控制,包括定义默认API版本和API支持的版本。
我们继续在AddApiVersioning下面添加API Explorer(Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer):
services.AddVersionedApiExplorer(options =>{ options.GroupNameFormat = "'v'VVV";});
该代码添加了一个API资源管理器,它的格式:'v'major[.minor][status] 。
现在在Configure方法中添加一个参数。将其命名为provider,类型为IApiVersionDescriptionProvider,如下所示:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IApiVersionDescriptionProvider provider)
这里涉及到的是有关API版本的信息,我们看下Configure中的UseSwaggerUI方法:
app.UseSwaggerUI(c =>{ foreach (var description in provider.ApiVersionDescriptions) { c.SwaggerEndpoint( $"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant()); }});
以上通过循环为每个发现的API版本构建一个Swagger访问地址。
现在,让我们运行程序并查看代码的结果。让我们看看Swagger UI,WeatherForecast的测试版本1 API和版本2 的API,看看如果我们发送请求,它们是否正常工作。您可以在下面的截图中看到效果,我们可以选择要检查的API版本:
我们可以看到v1和v2的WeatherForecast接口是不一样的,v1的版本被抛弃了,所以显示成灰色的。
而v2版本是正常的:
我们可以随便传入一个City参数,然后就可以看到返回记录了: