本文屬于OData系列

Intro

對外提供WEBAPI時，如果遇上了版本升級，那么控制WEBAPI的版本也是非常必要的。OData官方提供了版本控制以及管理的解決方案，我個人是實踐體會是不好用，好在社區(qū)提供了對應的nuget包，與.NET主版本同步更新。

介紹

ASP.NET API Versioning是一個提供ASP.NET WEBAPI版本管理的包，支持ASP.NET、ASP.NET CORE、ASP.NET CORE ODATA，作者以前是微軟的員工，現在不在微軟工作了，因此原先的命名空間不能繼續(xù)用了?，F在這個項目已經加入.NET Foundation，作者也非?；钴S。

版本管理

首先對現有的項目安裝這個包：

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根據版本不同也會有一些區(qū)別，需要分別進行配置，原來的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了。

舊系統(tǒng)升級

WEBAPI Versioning對這個內容有介紹，其中需要注意的是，基于路徑的版本匹配并不支持默認版本的特性，對于以前系統(tǒng)直接使用api/開頭的控制器，并不能直接默認轉到到api/v1（參考介紹）。為了兼容舊系統(tǒng)，我們只能在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>();

請注意:文章來源地址http://www.zghlxwxcb.cn/news/detail-436310.html

• context.Request.Path.StartsWithSegments函數只能匹配完整的路徑詞匯，/api/v2去匹配/api/v會返回false。
• 另外需要了解HTTP 301/302/307/308之間的區(qū)別，如果需要保留原來的請求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指定），這樣程序在掃描的過程中會重復對對象進行生成。解決辦法有兩種：

• 在EDM正確配置控制器中的Action或者Function，不要有不在OData路由的路徑。（UseODataRouteDebug()可以啟用$odata的路徑，這樣可以查看哪些路徑不被OData解析）
• 為每一個對象使用唯一名稱：在配置中增加options.CustomSchemaIds(type => type.AssemblyQualifiedName)這個項目，所有的swagger對外名稱會變成隨機生成的值，也可以規(guī)避這個問題。
  詳細分析看這個：Ignoring property on EDM causes InvalidOperationException: Can't use schemaId "\(B" for type "\)A.B". The same schemaId is already used for type "$A.B" · Issue #772 · dotnet/aspnet-api-versioning (github.com)

2. 無法加載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)
3. 找不到DescribeApiVersions()方法
   app找不到這個方法，大概率是在.NET 6的Minimal API之前的代碼升級出現的，之前app是用IWebhostBuilder構建的，而現在的app是直接用過WebApplication構建得到的，含義不同，最簡單的方法是改造一下，使用WebApplication重寫一下Startup內容。

參考

• API Documentation · dotnet/aspnet-api-versioning Wiki (github.com)

• API versioning extension with ASP.NET Core OData 8 - OData (microsoft.com)

到了這里，關于武裝你的WEBAPI-OData之API版本管理的文章就介紹完了。如果您還想了解更多內容，請在右上角搜索TOY模板網以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持TOY模板網！