ASP.NET Core中的API版本控制是什么？如何配置？

API版本控制通过多版本共存保障兼容性，需安装Microsoft.AspNetCore.Mvc.Versioning包，在Program.cs中配置服务、版本读取器及Swagger集成，并在控制器用[ApiVersion]标记版本，实现平滑迭代。

API版本控制在ASP.NET Core中，本质上是一种管理API变更的策略，它允许你在不破坏现有客户端的情况下，逐步迭代和发布新的API功能。简单来说，就是让你的API能够同时提供多个版本（比如v1和v2），老用户继续使用v1，新用户或升级后的用户则可以使用v2，从而避免了“大爆炸式”的更新，确保了服务的平稳过渡和客户端的兼容性。配置它，主要是通过集成官方提供的NuGet包，然后在启动类中注册服务，并用特性标记你的控制器和动作。

解决方案

在ASP.NET Core中配置API版本控制，通常涉及以下几个核心步骤。我个人觉得，最关键的是理解它背后的设计哲学，而不仅仅是复制代码。

首先，你需要安装官方提供的NuGet包

Microsoft.AspNetCore.Mvc.Versioning

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

接着，在你的

Program.cs

Startup.cs

builder.Services

// Program.cs
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning; // 引入版本控制命名空间
using Microsoft.AspNetCore.Mvc.ApiExplorer; // 引入API Explorer命名空间
using Microsoft.Extensions.Options;
using Swashbuckle.AspNetCore.SwaggerGen; // 引入Swagger命名空间
using Microsoft.OpenApi.Models; // 引入OpenAPI模型命名空间

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();

// 配置API版本控制
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true; // 在响应头中报告支持的API版本
    options.AssumeDefaultVersionWhenUnspecified = true; // 如果客户端未指定版本，则使用默认版本
    options.DefaultApiVersion = new ApiVersion(1, 0); // 设置默认API版本为1.0

    // 你可以选择不同的版本读取器，这里以Header为例
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
    // 或者 QueryStringApiVersionReader("api-version")
    // 或者 UrlSegmentApiVersionReader() - 需要配合路由模板
    // 或者 CombineApiVersionReader(new HeaderApiVersionReader("api-version"), new QueryStringApiVersionReader("api-version"))
});

// 配置API Explorer，用于与Swagger集成
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV"; // 设置分组格式，如 "v1"
    options.SubstituteApiVersionInUrl = true; // 在URL中替换API版本占位符
});

// 配置Swagger生成器
builder.Services.AddSwaggerGen(options =>
{
    // 这里需要为每个API版本生成一个Swagger文档
    var provider = builder.Services.BuildServiceProvider().GetRequiredService();
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, new OpenApiInfo()
        {
            Title = $"My API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
            Description = description.IsDeprecated ? "此API版本已废弃。" : string.Empty
        });
    }
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        var provider = app.Services.GetRequiredService();
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
        }
    });
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

接下来，你需要在控制器或具体的Action方法上使用

[ApiVersion]

// Controllers/V1/WeatherForecastController.cs
using Microsoft.AspNetCore.Mvc;

namespace MyApi.Controllers.V1
{
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]")] // 注意这里的路由模板
    [ApiVersion("1.0")] // 标记这个控制器属于1.0版本
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger _logger;

        public WeatherForecastController(ILogger logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

// Controllers/V2/WeatherForecastController.cs
using Microsoft.AspNetCore.Mvc;

namespace MyApi.Controllers.V2
{
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiVersion("2.0")] // 标记这个控制器属于2.0版本
    public class WeatherForecastV2Controller : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Cooler", "Warmer", "Unpredictable" // 假设2.0版本有不同的摘要
        };

        private readonly ILogger _logger;

        public WeatherForecastV2Controller(ILogger logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecastV2")]
        public IEnumerable Get()
        {
            return Enumerable.Range(1, 3).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-10, 40),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

现在，当客户端请求

GET /api/weatherforecast

api-version: 1.0

api-version: 2.0

为什么我的API需要版本控制？（以及不做的代价是什么？）

这是一个我经常会和团队成员讨论的问题。很多时候，项目初期为了快速上线，版本控制常常被搁置，觉得“以后再说”。但我的经验告诉我，这种“以后再说”往往会变成一个巨大的技术债务。API，尤其是公共API，一旦发布，它就形成了一种契约。如果你在没有版本控制的情况下随意修改这个契约，比如改变响应结构、移除某个字段、甚至修改参数类型，那么所有依赖你API的客户端都会瞬间崩溃。

想象一下，你有一个移动App，数百万用户正在使用。如果你的API突然进行了一次“破坏性”更新，而没有提供旧版本的支持，那么所有用户的App都将无法正常工作，除非他们立即更新App。但我们都知道，强制用户更新App是一个痛苦的过程，用户流失率会飙升，你的支持团队也会被海量的投诉淹没。

不引入版本控制的代价是巨大的：

• 客户端兼容性灾难： 每次API更新都可能导致现有客户端失效，这不仅是技术问题，更是业务和用户体验的严重倒退。
• 部署风险剧增： 任何API变更都必须小心翼翼，因为一次小小的改动都可能引发连锁反应。部署新版本就像走钢丝，生怕踩到地雷。
• 迭代速度受限： 为了避免破坏性变更，开发者不得不采用各种“打补丁”的方式来添加新功能，导致代码臃肿、难以维护。新功能的开发周期也会被拉长。
• 失去客户信任： 频繁的API中断和不兼容性会让你的API消费者对你的服务失去信心，转向更稳定、更可靠的替代方案。

所以，API版本控制不是一个可有可无的特性，而是一个现代API设计中不可或缺的基石。它让你有能力在不影响现有用户的前提下，持续地演进和优化你的API，这对于任何一个有生命力的产品来说，都是至关重要的。

在ASP.NET Core中，有哪些常见的API版本控制策略？各自的优缺点是什么？

在ASP.NET Core中，版本控制的“策略”其实更多是指我们如何将版本信息传递给API，也就是所谓的“版本读取器”。不同的读取方式各有其适用场景和优缺点。

A1.art

一个创新的AI艺术应用平台，旨在简化和普及艺术创作

下载

1. URL路径版本控制 (URL Path Versioning):

   • 示例:

     GET /api/v1/products

   • 实现方式: 在路由模板中包含版本信息，如

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

     。
   • 优点:
     • 直观清晰: 版本信息直接体现在URL中，非常容易理解和识别。
     • 易于缓存: 不同版本的URL是独立的，有利于CDN和客户端缓存。
     • 浏览器友好: 可以直接在浏览器中访问不同版本的API。
   • 缺点:
     • 不符合RESTful原则: RESTful设计推崇资源URI的稳定性，版本信息作为资源的一部分会使URI发生变化。
     • 路由配置稍复杂: 需要在每个控制器或Action的路由中明确指定版本占位符。
     • URL冗余: 每次请求都需要带上版本信息，使得URL看起来稍长。
   • 个人看法: 这是最常见也是最被接受的一种方式，尽管有REST原则上的争议，但其清晰性往往能压倒一切。

2. 查询字符串版本控制 (Query String Versioning):

   • 示例:

     GET /api/products?api-version=1.0

   • 实现方式: 使用

     QueryStringApiVersionReader

     ，客户端在查询字符串中传递版本参数。
   • 优点:
     • URI整洁: 核心资源URI保持不变，版本信息是附加参数。
     • 实现简单: 配置相对容易，客户端也容易添加参数。
   • 缺点:
     • 容易遗漏: 客户端可能会忘记传递版本参数，导致API使用默认版本。
     • 语义不明确: 版本信息是查询参数，而不是资源的一部分，有时会让人觉得“怪怪的”。
     • 缓存问题: 如果版本参数影响了响应内容，可能需要更复杂的缓存策略。
   • 个人看法: 适合内部API，或者对URL长度和简洁性有较高要求的场景。

3. HTTP Header 版本控制 (Header Versioning):

   • 示例:

     GET /api/products

     ，请求头中包含

     X-Api-Version: 1.0

   • 实现方式: 使用

     HeaderApiVersionReader

     ，客户端在自定义HTTP头中传递版本信息。
   • 优点:
     • 最符合RESTful原则: 资源URI保持纯净和稳定，版本信息通过元数据（Header）传递。
     • 对客户端透明: 浏览器默认不会显示，更适合机器对机器的通信。
     • 灵活性高: 可以定义多个自定义Header来传递不同的元数据。
   • 缺点:
     • 不直观: 版本信息不在URL中，调试时需要检查请求头。
     • 浏览器不友好: 无法直接通过浏览器地址栏测试不同版本的API。
     • 客户端实现稍复杂: 需要客户端代码显式添加Header。
   • 个人看法: 我个人很喜欢这种方式，它优雅地解决了RESTful原则和版本控制的冲突。对于非浏览器调用的API（比如移动App、其他后端服务），这是一个非常好的选择。

4. Media Type 版本控制 (Media Type Versioning):

   • 示例:

     GET /api/products

     ，请求头中包含

     Accept: application/vnd.myapi.v1+json

   • 实现方式: 使用

     MediaTypeApiVersionReader

     ，客户端在

     Accept

     头中指定带有版本信息的MIME类型。
   • 优点:
     • 高度RESTful: 充分利用HTTP标准协议的

       Accept

       头来协商内容类型和版本。
     • 语义丰富: 可以同时表达内容类型和版本信息。
   • 缺点:
     • 最复杂: 客户端实现起来最复杂，也最不常见。
     • 冗长:

       Accept

       头的值可能变得很长。
     • 理解成本高: 对于不熟悉HTTP规范的开发者来说，理解和使用门槛较高。
   • 个人看法: 这种方式虽然最符合REST原则，但在实际项目中很少见到大规模应用，因为它对客户端和开发者的要求都比较高。除非你的项目对HTTP协议的严格遵守有非常高的要求，否则不建议作为首选。

最终选择哪种策略，往往是团队的偏好、API的消费者类型以及项目需求综合权衡的结果。没有绝对的“最好”，只有“最适合”。

如何在Swagger/OpenAPI中正确展示不同版本的API文档？

当你的API开始支持版本控制后，一个很现实的问题就摆在眼前：如何让你的API文档（通常是Swagger/OpenAPI）也能清晰地展示这些版本？如果Swagger只显示一个版本，或者把所有版本的API混在一起，那简直是一场灾难。幸运的是，ASP.NET Core的API版本控制库与Swagger有很好的集成能力。

关键在于使用

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

在

Program.cs

1. 启用API Explorer并配置分组: 在你注册

   AddApiVersioning

   之后，紧接着需要注册

   AddVersionedApiExplorer

   。

   builder.Services.AddVersionedApiExplorer(options =>
   {
       // 这个格式字符串非常重要，它定义了Swagger文档分组的名称。
       // 'v'VVV 表示版本号将以 "v1", "v2" 这样的形式出现。
       // 如果你的版本是 "1.0"，它会生成 "v1.0"。
       options.GroupNameFormat = "'v'VVV";
   
       // 当使用URL路径版本控制时，这个选项会让API Explorer将URL中的
       // {version:apiVersion} 占位符替换为实际的版本号，
       // 从而生成正确的Swagger路径。
       options.SubstituteApiVersionInUrl = true;
   });

   IApiVersionDescriptionProvider

   服务就是由

   AddVersionedApiExplorer

   提供的，它能帮你获取所有已注册的API版本描述信息。

2. 配置SwaggerGen生成器： 在

   AddSwaggerGen

   中，你需要遍历

   IApiVersionDescriptionProvider

   提供的

   ApiVersionDescription

   列表，为每个API版本创建一个独立的Swagger文档（

   OpenApiInfo

   ）。

   builder.Services.AddSwaggerGen(options =>
   {
       // 获取API版本描述提供者
       var provider = builder.Services.BuildServiceProvider().GetRequiredService();
   
       // 为每个API版本创建独立的Swagger文档
       foreach (var description in provider.ApiVersionDescriptions)
       {
           options.SwaggerDoc(description.GroupName, new OpenApiInfo()
           {
               Title = $"我的API {description.ApiVersion}", // 文档标题，包含版本号
               Version = description.ApiVersion.ToString(), // 版本