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

相关推荐
宝桥南山13 天前
Model Context Protocol (MCP) - 尝试创建和测试一下MCP Server
microsoft·ai·微软·c#·.net·.net core
代码拾光16 天前
面试官:如果某个业务量突然提升100倍QPS你会怎么做?
.net core·架构设计
WikeSoft17 天前
1.net core 工作流WorkFlow流程(介绍)
.net·.net core·workflow·流程引擎
hez201018 天前
用 .NET NativeAOT 构建完全 distroless 的静态链接应用
c#·.net·aot·.net core·native
EdisonZhou23 天前
使用MCP C# SDK开发MCP Server + Client
llm·aigc·asp.net core·.net core
黑贝是条狗1 个月前
对.net 的改变
.net core
小吴同学·1 个月前
NET6 WebApi第5讲:中间件(源码理解,俄罗斯套娃怎么来的?);Web 服务器 (Nginx / IIS / Kestrel)、WSL、SSL/TSL
中间件·c#·.net·.netcore·.net core
坐望云起1 个月前
ASP.NET Web的 Razor Pages应用,配置热重载,解决.NET Core MVC 页面在更改后不刷新
前端·后端·asp.net·mvc·.net core·razor pages
代码拾光1 个月前
.NET Core 中如何实现缓存的预热?
.net core
EdisonZhou2 个月前
基于Microsoft.Extensions.AI核心库实现RAG应用
llm·aigc·.net core