武装你的WEBAPI-OData之API版本管理

本文属于OData系列

Intro

对外提供WEBAPI时,如果遇上了版本升级,那么控制WEBAPI的版本也是非常必要的。OData官方提供了版本控制以及管理的解决方案,我个人是实践体会是不好用,好在社区提供了对应的nuget包,与.NET主版本同步更新。

介绍

ASP.NET API Versioning是一个提供ASP.NET WEBAPI版本管理的包,支持ASP.NET、ASP.NET CORE、ASP.NET CORE ODATA,作者以前是微软的员工,现在不在微软工作了,因此原先的命名空间不能继续用了。现在这个项目已经加入.NET Foundation,作者也非常活跃。

版本管理

首先对现有的项目安装这个包:

Install-Package Asp.Versioning.OData

在Program.cs文件中修改一下:

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddControllers().AddOData();
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning().AddOData(
    options =>
    {
        options.AddRouteComponents();
    } );

var app = builder.Build();

app.MapControllers();
app.Run();

然后在需要控制版本的控制器上加上[ApiVersion]修饰就可以了。

[ApiVersion( 1.0 )]
public class PeopleController : ODataController
{
    [EnableQuery]
    public IActionResult Get() => Ok( new[] { new Person() } );
}

注意,默认的版本是1.0,不过最好显式声明一下。

EDM升级

EDM根据版本不同也会有一些区别,需要分别进行配置,原来的GetEdm()模式显得有点麻烦,而EDM配置在这个库中变得非常灵活,使用的是Configuration模式。

示例代码如下:

public class DeviceInfoModelConfiguration : IModelConfiguration
{
	public void Apply(ODataModelBuilder builder, ApiVersion apiVersion, string routePrefix)
	{
		switch (apiVersion.MajorVersion)
		{
			case 1:
				builder.EntitySet<DeviceInfo>("DeviceInfoes").EntityType.HasKey(p => p.DeviceId);
				break;
			case 2:
				builder.EntitySet<DeviceInfo>("DeviceInfos").EntityType.HasKey(p => p.DeviceId).Ignore(w => w.Layout);
				break;
			default:
				break;
		};
	}
}

只需要实现IModelConfiguration接口,并在Apply函数中根据版本对实体或者DTO对象进行配置,不同版本的EDM可以不一样。

一般实践是一个实体对象一个IModelConfiguration,方便后面管理。

配置Swagger

因为有重复配置的模型,直接使用默认的Swagger会报错,这个时候需要使用到Versioned API Explorer,对Swagger拓展版本信息。

Install-Package Asp.Versioning.OData.ApiExplorer

安装Asp.Versioning.OData.ApiExplorer,重新改造一下Program.cs文件:

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddControllers().AddOData();
builder.Services.AddProblemDetails();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddApiVersioning()
                .AddOData( options => options.AddRouteComponents() )
                .AddODataApiExplorer(
                     // format the version as "'v'major[.minor][-status]"
                     options => options.GroupNameFormat = "'v'VVV" );

services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(
    options =>
    {
        foreach ( var description in app.DescribeApiVersions() )
        {
            var url = $"/swagger/{description.GroupName}/swagger.json";
            var name = description.GroupName.ToUpperInvariant();
            options.SwaggerEndpoint( url, name );
        }
    } );
app.MapControllers();
app.Run();

还需要一个配置的类如下:

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
  readonly IApiVersionDescriptionProvider provider;

  public ConfigureSwaggerOptions( IApiVersionDescriptionProvider provider ) =>
    this.provider = provider;

  public void Configure( SwaggerGenOptions options )
  {
    foreach ( var description in provider.ApiVersionDescriptions )
    {
      options.SwaggerDoc(
        description.GroupName,
          new OpenApiInfo()
          {
            Title = $"Example API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
          } );
    }
  }
}

这样,swagger界面就可以下拉选择不同版本的API了。
武装你的WEBAPI-OData之API版本管理

旧系统升级

WEBAPI Versioning对这个内容有介绍,其中需要注意的是,基于路径的版本匹配并不支持默认版本的特性,对于以前系统直接使用api/开头的控制器,并不能直接默认转到到api/v1(参考介绍)。为了兼容旧系统,我们只能在ASP.NET CORE的管线上想想办法:插入一个中间件,对路径进行判断,如果是api开头的,就直接转到api/v1;如果是api/v开头的,那么就直接下一步。

    public class RedirectMiddlewareForV1
    {
        private readonly RequestDelegate _next;

        public RedirectMiddlewareForV1(RequestDelegate next)
        {
            _next = next;
        }

        public async Task InvokeAsync(HttpContext context)
        {
            if (context.Request.Path.StartsWithSegments("/api") && !context.Request.Path.Value.StartsWith("/api/v"))
            {
                //千万小心,一定需要保留原来的QueryString
                var newUrl = $"{context.Request.Path.Value.Replace("/api/", "/api/v1/")}{context.Request.QueryString}";
                //permanent指示永久迁移,preserveMethod指示保留原来的谓词与body
                context.Response.Redirect(newUrl, permanent: true, preserveMethod: true);
            }
            else
            {
                await _next(context);
            }
        }


    }

然后在configure函数中注册这个中间件就可以了。

app.UseMiddleware<RedirectMiddlewareForV1>();

请注意:

  • context.Request.Path.StartsWithSegments函数只能匹配完整的路径词汇,/api/v2去匹配/api/v会返回false。
  • 另外需要了解HTTP 301/302/307/308之间的区别,如果需要保留原来的请求body,需要使用307/308,308是永久移动。
  • Redirect并不保留原来的QueryString,需要手动拼接。

FAQ

  1. 无法正确显示不同版本的Swagger,提示InvalidOperationException: Can't use schemaId "\(B" for type "\)A.B". The same schemaId is already used for type "$A.B"
    这个问题是由多次对同一个类型Schema生成造成的。最常见的情况是你的控制器有方法不属于OData Routing的一部分(比如直接使用HttpGet指定),这样程序在扫描的过程中会重复对对象进行生成。解决办法有两种:
  1. 无法加载Swagger,提示System.MissingMethodException: Method not found: 'Microsoft.OData.ModelBuilder.Config.DefaultQuerySettings Microsoft.AspNetCore.OData.ODataOptions.get_QuerySettings()
    这个是版本问题,本人使用的OData版本在8.1.0,有一些破坏性更改,只要保持引用的OData版本<= 8.0.12就可以了。
    详细分析看这个MissingMethodException with OData v8.1.0 · Issue #980 · dotnet/aspnet-api-versioning (github.com)
  2. 找不到DescribeApiVersions()方法
    app找不到这个方法,大概率是在.NET 6的Minimal API之前的代码升级出现的,之前app是用IWebhostBuilder构建的,而现在的app是直接用过WebApplication构建得到的,含义不同,最简单的方法是改造一下,使用WebApplication重写一下Startup内容。

参考

原文链接:https://www.cnblogs.com/podolski/p/17375269.html

本站文章如无特殊说明,均为本站原创,如若转载,请注明出处:武装你的WEBAPI-OData之API版本管理 - Python技术站

(0)
上一篇 2023年5月9日
下一篇 2023年5月10日

相关文章

  • C#实现根据银行卡卡号判断银行名

    C#实现根据银行卡卡号判断银行名的方法可以分为以下几个步骤: 步骤一:了解银行卡卡号规则 在判断银行名之前,我们需要了解银行卡卡号的规则,常见银行卡卡号长度如下: 中国银行:19位 工商银行:16位或19位 农业银行:19位 建设银行:19位 交通银行:16位或19位 中信银行:16位或19位 招商银行:16位或19位 浦发银行:16位或19位 兴业银行:1…

    C# 2023年6月7日
    00
  • C# 连接本地数据库的实现示例

    下面是详细的攻略: C# 连接本地数据库的实现示例 在 C# 中,连接本地数据库需要使用 .Net Framework 中的 ADO.NET 技术。 常见的本地数据库包括 Access 和 SQL Server Express, 下面将以连接 SQL Server Express 为例,讲解如何连接本地数据库。 使用 SQL Server Managemen…

    C# 2023年6月1日
    00
  • asp.net页面master页面与ascx用户控件传值的问题

    ASP.NET页面中,Master页面和ASCX用户控件是常见的组件。Master页面通常用于定义网站的整体布局和风格,而ASCX用户控件则用于封装重复使用的控件或作为嵌入其他页面的组件。在一些复杂的应用场景中,我们需要在Master页面和ASCX用户控件之间传递数据或状态,下面是传值的两种方法。 方法一:通过属性(Property)传值 借助于Proper…

    C# 2023年6月3日
    00
  • .net从服务器下载文件中文名乱码解决方案

    针对“.net从服务器下载文件中文名乱码解决方案”,以下是完整攻略的步骤: 问题背景 当从服务器下载文件时,如果文件名中包含中文字符,很容易出现乱码错误。这是由于字符编码问题造成的。 解决方案 .NET提供了System.Net.WebClient类来下载文件。要解决中文文件名乱码问题,我们需要进行以下设置: 设置下载参数 下载文件前需要设置WebClien…

    C# 2023年5月15日
    00
  • C#多线程用法详解

    C#多线程用法详解 C#支持多线程编程,可以充分利用多核CPU的性能,提高程序的性能和响应速度。本文将详细讲解C#多线程的用法。 线程的创建 C#创建线程有两种方式,一种是使用Thread类,另一种是使用ThreadPool类。 使用Thread类创建线程 使用Thread类创建线程可以获得更多的控制权,可以更灵活地控制线程的行为。 Thread threa…

    C# 2023年5月15日
    00
  • C#实现自由组合本地缓存、分布式缓存和数据查询

    C#实现自由组合本地缓存、分布式缓存和数据查询 在应用程序中,缓存数据是提高性能和响应时间的有效方法。使用缓存可以减少对数据源的访问,从而提高应用程序的性能并减少响应时间。 在C#中,可以使用以下三种方式实现缓存: 本地缓存(Local Cache) 分布式缓存(Distributed Cache) 数据库缓存(Database Cache) 这三种方式都有…

    C# 2023年5月31日
    00
  • C#应用BindingSource实现数据同步的方法

    下面我将详细讲解“C#应用BindingSource实现数据同步的方法”的完整攻略,包含步骤和示例说明。 步骤一:创建数据源 首先,需要创建数据源。这里以一个简单的学生信息表作为数据源示例。可以在VS中通过“添加数据源”进行创建,然后选择“从数据库创建”并选择相应的数据表,并通过“测试连接”测试以确保数据库连接正常。 步骤二:添加BindingSource …

    C# 2023年6月2日
    00
  • ASP.NET操作各类时间段获取方法汇总

    ASP.NET操作各类时间段获取方法汇总 在ASP.NET中,我们常常需要获取各类时间段,例如获取当前时间、获取某个日期的年月日信息、获取指定时间段的日期列表。本文将系统介绍ASP.NET操作各类时间段获取方法及其使用场景,包括以下几个方面: 获取当前时间 获取当前日期的年月日信息 获取指定时间段的日期列表 1. 获取当前时间 要获取当前时间,我们可以使用 …

    C# 2023年6月1日
    00
合作推广
合作推广
分享本页
返回顶部