在 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 的演进,确保新旧版本的兼容性,同时为客户端提供清晰的版本选择。

相关推荐
黑贝是条狗3 天前
对.net 的改变
.net core
小吴同学·7 天前
NET6 WebApi第5讲:中间件(源码理解,俄罗斯套娃怎么来的?);Web 服务器 (Nginx / IIS / Kestrel)、WSL、SSL/TSL
中间件·c#·.net·.netcore·.net core
坐望云起9 天前
ASP.NET Web的 Razor Pages应用,配置热重载,解决.NET Core MVC 页面在更改后不刷新
前端·后端·asp.net·mvc·.net core·razor pages
代码拾光21 天前
.NET Core 中如何实现缓存的预热?
.net core
EdisonZhou1 个月前
基于Microsoft.Extensions.AI核心库实现RAG应用
llm·aigc·.net core
时光追逐者1 个月前
一个开源且免费的 .NET CMS 和应用程序框架
开源·c#·.net·cms·.net core
EdisonZhou1 个月前
基于Microsoft.Extensions.VectorData实现语义搜索
llm·aigc·.net core
时光追逐者1 个月前
推荐几款开源免费的 .NET MAUI 组件库
microsoft·开源·c#·.net·.net core·maui
EdisonZhou1 个月前
.NET程序员AI开发基座:Microsoft.Extensions.AI
aigc·.net core