在 ASP.NET Core WebAPI 中实现版本控制（Versioning）是一种常见的做法，用于管理 API 的演进和兼容性。通过版本控制，我们可以在不破坏现有客户端的情况下引入新功能或修改现有功能。以下是实现版本控制的几种常见方法：
1. 使用 URL 路径版本控制
将版本号嵌入到 URL 路径中，例如 /api/v1/controller 和 /api/v2/controller。
实现步骤
安装 Microsoft.AspNetCore.Mvc.Versioning 包：
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
在 Program.cs 中配置版本控制：
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});
var app = builder.Build();
app.MapControllers();
app.Run();
在控制器中指定版本：
[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersController : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Version 1.0");
}
}
[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersV2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Version 2.0");
}
}
测试：
/api/v1/users返回Version 1.0/api/v2/users返回Version 2.0
2. 使用查询字符串版本控制
将版本号作为查询参数传递，例如 /api/users?api-version=1.0。
实现步骤
在 Program.cs 中配置版本控制：
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});
在控制器中指定版本（与 URL 路径版本控制相同）。
测试：
/api/users?api-version=1.0返回Version 1.0/api/users?api-version=2.0返回Version 2.0
3. 使用请求头版本控制
将版本号放在 HTTP 请求头中，例如 api-version: 1.0。
实现步骤
在 Program.cs 中配置版本控制：
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});
在控制器中指定版本（与 URL 路径版本控制相同）。
测试：
- 请求头中添加
api-version: 1.0，返回Version 1.0 - 请求头中添加
api-version: 2.0，返回Version 2.0
4. 使用媒体类型版本控制
将版本号嵌入到 Accept 请求头中，例如 application/json;v=1.0。
实现步骤
在 Program.cs 中配置版本控制：
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new MediaTypeApiVersionReader("v");
});
在控制器中指定版本（与 URL 路径版本控制相同）。
测试：
- 请求头中添加
Accept: application/json;v=1.0，返回Version 1.0 - 请求头中添加
Accept: application/json;v=2.0，返回Version 2.0
5. 组合多种版本控制方式
你可以同时支持多种版本控制方式，例如 URL 路径和查询字符串。
实现步骤
在 Program.cs 中配置版本控制：
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = ApiVersionReader.Combine(
new QueryStringApiVersionReader("api-version"),
new HeaderApiVersionReader("api-version")
);
});
在控制器中指定版本（与 URL 路径版本控制相同）。
测试：
/api/v1/users返回Version 1.0/api/users?api-version=2.0返回Version 2.0- 请求头中添加
api-version: 3.0，返回Version 3.0
总结
在 ASP.NET Core WebAPI 中实现版本控制的方式包括：
- URL 路径版本控制：将版本号嵌入 URL 路径。
- 查询字符串版本控制：将版本号作为查询参数传递。
- 请求头版本控制：将版本号放在 HTTP 请求头中。
- 媒体类型版本控制 ：将版本号嵌入到
Accept请求头中。 - 组合多种方式：同时支持多种版本控制方式。
通过版本控制，我们可以更好地管理 API 的演进，确保新旧版本的兼容性，同时为客户端提供清晰的版本选择。
