在 ASP.NET Core WebAPI如何实现版本控制？

在 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 中实现版本控制的方式包括：

1. URL 路径版本控制：将版本号嵌入 URL 路径。
2. 查询字符串版本控制：将版本号作为查询参数传递。
3. 请求头版本控制：将版本号放在 HTTP 请求头中。
4. 媒体类型版本控制 ：将版本号嵌入到 Accept 请求头中。
5. 组合多种方式：同时支持多种版本控制方式。

通过版本控制，我们可以更好地管理 API 的演进，确保新旧版本的兼容性，同时为客户端提供清晰的版本选择。