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
（后者主要用于与Swagger/OpenAPI集成，让文档也支持版本）。
接着，在你的
Program.cs
（或者旧版ASP.NET Core中的
Startup.cs
）文件中，你需要注册API版本控制服务。这通常在
builder.Services
部分完成：
// Program.csusing 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/swashbucklebuilder.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.csusing 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.csusing 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
的请求头时，会调用V1的控制器；如果带上
api-version: 2.0
，则会调用V2的控制器。
为什么我的API需要版本控制？（以及不做的代价是什么？）
这是一个我经常会和团队成员讨论的问题。很多时候，项目初期为了快速上线，版本控制常常被搁置，觉得“以后再说”。但我的经验告诉我，这种“以后再说”往往会变成一个巨大的技术债务。API，尤其是公共API，一旦发布，它就形成了一种契约。如果你在没有版本控制的情况下随意修改这个契约，比如改变响应结构、移除某个字段、甚至修改参数类型，那么所有依赖你API的客户端都会瞬间崩溃。
想象一下，你有一个移动App，数百万用户正在使用。如果你的API突然进行了一次“破坏性”更新，而没有提供旧版本的支持，那么所有用户的App都将无法正常工作，除非他们立即更新App。但我们都知道，强制用户更新App是一个痛苦的过程，用户流失率会飙升，你的支持团队也会被海量的投诉淹没。
不引入版本控制的代价是巨大的：
客户端兼容性灾难： 每次API更新都可能导致现有客户端失效，这不仅是技术问题，更是业务和用户体验的严重倒退。部署风险剧增： 任何API变更都必须小心翼翼，因为一次小小的改动都可能引发连锁反应。部署新版本就像走钢丝，生怕踩到地雷。迭代速度受限： 为了避免破坏性变更，开发者不得不采用各种“打补丁”的方式来添加新功能，导致代码臃肿、难以维护。新功能的开发周期也会被拉长。失去客户信任： 频繁的API中断和不兼容性会让你的API消费者对你的服务失去信心，转向更稳定、更可靠的替代方案。
所以，API版本控制不是一个可有可无的特性，而是一个现代API设计中不可或缺的基石。它让你有能力在不影响现有用户的前提下，持续地演进和优化你的API，这对于任何一个有生命力的产品来说，都是至关重要的。
在ASP.NET Core中，有哪些常见的API版本控制策略？各自的优缺点是什么？
在ASP.NET Core中，版本控制的“策略”其实更多是指我们如何将版本信息传递给API，也就是所谓的“版本读取器”。不同的读取方式各有其适用场景和优缺点。
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原则上的争议，但其清晰性往往能压倒一切。
查询字符串版本控制 (Query String Versioning):
示例:
GET /api/products?api-version=1.0
实现方式: 使用
QueryStringApiVersionReader
，客户端在查询字符串中传递版本参数。优点:URI整洁: 核心资源URI保持不变，版本信息是附加参数。实现简单: 配置相对容易，客户端也容易添加参数。缺点:容易遗漏: 客户端可能会忘记传递版本参数，导致API使用默认版本。语义不明确: 版本信息是查询参数，而不是资源的一部分，有时会让人觉得“怪怪的”。缓存问题: 如果版本参数影响了响应内容，可能需要更复杂的缓存策略。个人看法: 适合内部API，或者对URL长度和简洁性有较高要求的场景。
HTTP Header 版本控制 (Header Versioning):
示例:
GET /api/products
，请求头中包含
X-Api-Version: 1.0
实现方式: 使用
HeaderApiVersionReader
，客户端在自定义HTTP头中传递版本信息。优点:最符合RESTful原则: 资源URI保持纯净和稳定，版本信息通过元数据（Header）传递。对客户端透明: 浏览器默认不会显示，更适合机器对机器的通信。灵活性高: 可以定义多个自定义Header来传递不同的元数据。缺点:不直观: 版本信息不在URL中，调试时需要检查请求头。浏览器不友好: 无法直接通过浏览器地址栏测试不同版本的API。客户端实现稍复杂: 需要客户端代码显式添加Header。个人看法: 我个人很喜欢这种方式，它优雅地解决了RESTful原则和版本控制的冲突。对于非浏览器调用的API（比如移动App、其他后端服务），这是一个非常好的选择。
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
这个包，它能帮助Swagger理解你的API版本结构。
在
Program.cs
中的配置，我们已经看到了一些端倪。这里我再展开讲一下具体的原理和配置细节：
启用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版本描述信息。
配置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(), // 版本
以上就是ASP.NET Core中的API版本控制是什么？如何配置？的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1439471.html
微信扫一扫 
支付宝扫一扫 
