ASP.NET Core WebAPI 版本控制实现指南

在现代软件开发中，API版本控制是一项至关重要的功能，它允许开发者在不破坏现有系统的情况下推出新功能，同时确保向后兼容性。ASP.NET Core WebAPI 提供了多种实现版本控制的方法，本文将详细介绍如何使用 Microsoft.AspNetCore.Mvc.Versioning 包来实现这一功能。

一、前提条件

1. Visual Studio：确保安装了 Visual Studio 16.4 或更高版本。
2. .NET Core：确保已安装 .NET Core 3.1 或更高版本。
3. Postman：用于测试 Web API（如果尚未安装，可以从 Postman 官网下载）。

二、创建 ASP.NET Core Web API 项目

1. 打开 Visual Studio，单击“文件”->“新建”->“项目”。
2. 选择“ASP.NET Core Web 应用程序”模板，单击“下一步”。
3. 给项目命名，并单击“创建”按钮。
4. 选择“API”模板，单击“创建”按钮。

三、安装 Microsoft.AspNetCore.Mvc.Versioning 包

1. 右键单击解决方案，选择“管理 NuGet 包”。
2. 搜索“Microsoft.AspNetCore.Mvc.Versioning”并安装。

四、配置版本控制

1. 打开 Startup.cs 文件，在 ConfigureServices 方法中添加以下代码：

public void ConfigureServices(IServiceCollection services)
{
 services.AddControllers();
 services.AddApiVersioning(options =>
 {
 // 返回响应标头中支持的版本信息
 options.ReportApiVersions = true;
 
 // 默认情况下，假定未指定版本的请求为1.0版本
 options.AssumeDefaultVersionWhenUnspecified = true;
 
 // 设置默认API版本
 options.DefaultApiVersion = new ApiVersion(1, 0);
 
 // 支持MediaType、Header、QueryString设置版本号，默认使用QueryString
 options.ApiVersionReader = ApiVersionReader.Combine(
 new MediaTypeApiVersionReader("api-version"),
 new HeaderApiVersionReader("api-version"),
 new QueryStringApiVersionReader("api-version"),
 new UrlSegmentApiVersionReader()
 );
 });
}

1. 在 Configure 方法中启用版本控制：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
 if (env.IsDevelopment())
 {
 app.UseDeveloperExceptionPage();
 }

 app.UseHttpsRedirection();
 app.UseApiVersioning();
 app.UseRouting();
 app.UseAuthorization();
 app.UseEndpoints(endpoints =>
 {
 endpoints.MapControllers();
 });
}

五、实现版本控制

1. 基于查询字符串的版本控制

   使用 [ApiVersion] 属性标记控制器或方法，并通过查询字符串传递 api-version 参数。

   [ApiController]
   [Route("[controller]")]
   [ApiVersion("1.0", Deprecated = true)]
   [ApiVersion("2.0")]
   public class WeatherForecastController : ControllerBase
   {
    // 控制器方法
   }
   

   调用方式：https://localhost:5000/weatherforecast?api-version=1.0 或 https://localhost:5000/weatherforecast?api-version=2.0

2. 基于URL路径段的版本控制

   在控制器路由中添加版本段，例如 /api/v{version:apiVersion}/[controller]。

   [ApiController]
   [Route("/api/v{version:apiVersion}/[controller]")]
   [ApiVersion("1.0")]
   [ApiVersion("2.0")]
   public class WeatherForecastController : ControllerBase
   {
    // 控制器方法
   }
   

   调用方式：https://localhost:5000/api/v1/weatherforecast 或 https://localhost:5000/api/v2/weatherforecast

3. 基于HTTP头的版本控制

   在请求头中传递 api-version 参数。

   options.ApiVersionReader = ApiVersionReader.Combine(
    new MediaTypeApiVersionReader("api-version"),
    new HeaderApiVersionReader("api-version")
   );
   

   调用方式：在请求头中添加 api-version: 1.0 或 api-version: 2.0

六、测试版本控制

使用 Postman 或其他 API 测试工具，通过不同的方式（查询字符串、URL路径段、HTTP头）传递 api-version 参数，验证版本控制是否生效。

七、总结

ASP.NET Core WebAPI 提供了灵活且强大的版本控制功能，通过 Microsoft.AspNetCore.Mvc.Versioning 包，开发者可以轻松实现基于查询字符串、URL路径段和HTTP头的版本控制。这些功能不仅有助于及时推出新功能，还能确保现有系统的向后兼容性，为开发者提供了更多的灵活性和控制力。