C#怎么进行API版本控制？基于URL与Header的API版本控制实现方法

在C#开发ASP.NET Core Web API的过程中，随着业务迭代，接口逻辑会不断调整，直接修改原有接口容易导致调用方出现兼容性问题，因此API版本控制是开发过程中必不可少的一环。常见的版本控制方式有基于URL路径和基于请求Header两种，下面分别介绍实现方法。

基础环境准备

首先需要创建ASP.NET Core Web API项目，然后安装API版本控制相关的NuGet包，执行以下命令安装：

Install-Package Microsoft.AspNetCore.Mvc.Versioning

安装完成后，需要在Program.cs中添加版本控制的服务配置，代码如下：

var builder = WebApplication.CreateBuilder(args);

// 添加API版本控制服务
builder.Services.AddApiVersioning(options =>
{
    // 当请求没有指定版本时，使用默认版本
    options.AssumeDefaultVersionWhenUnspecified = true;
    // 设置默认版本为1.0
    options.DefaultApiVersion = new ApiVersion(1, 0);
    // 在响应头中返回支持的版本信息
    options.ReportApiVersions = true;
});

builder.Services.AddControllers();
var app = builder.Build();

app.UseAuthorization();
app.MapControllers();
app.Run();

基于URL的API版本控制实现

基于URL的版本控制是将版本号直接放在请求的URL路径中，比如/api/v1/weather、/api/v2/weather，这种方式直观易懂，调用方可以明确知道请求的版本。

控制器定义

定义两个不同版本的Weather控制器，分别在URL中指定版本：

using Microsoft.AspNetCore.Mvc;

// 版本1的控制器，URL路径包含v1
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class WeatherController : ControllerBase
{
    [HttpGet]
    public IActionResult GetV1()
    {
        return Ok(new { Version = "1.0", Data = "这是版本1的天气数据" });
    }
}

// 版本2的控制器，URL路径包含v2
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class WeatherV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetV2()
    {
        return Ok(new { Version = "2.0", Data = "这是版本2的天气数据", Extra = "新增的额外字段" });
    }
}

请求示例

使用Postman或者浏览器请求以下地址，可以得到对应版本的结果：

• 请求https://localhost:port/api/v1/weather，返回版本1的数据
• 请求https://localhost:port/api/v2/weather，返回版本2的数据

基于Header的API版本控制实现

基于Header的版本控制是将版本号放在HTTP请求头中，URL路径不体现版本信息，这种方式可以让URL更简洁，适合对URL规范性要求高的场景。

配置调整

需要在Program.cs的版本控制配置中添加Header读取规则：

builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    // 从请求头中读取版本号，头名称为api-version
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});

控制器定义

控制器不需要在URL中指定版本，通过特性标记支持的版本即可：

using Microsoft.AspNetCore.Mvc;

// 版本1的控制器，支持1.0版本
[ApiController]
[Route("api/[controller]")]
[ApiVersion("1.0")]
public class UserController : ControllerBase
{
    [HttpGet]
    public IActionResult GetV1()
    {
        return Ok(new { Version = "1.0", User = "默认用户" });
    }
}

// 版本2的控制器，支持2.0版本
[ApiController]
[Route("api/[controller]")]
[ApiVersion("2.0")]
public class UserV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetV2()
    {
        return Ok(new { Version = "2.0", User = "新版本用户", Age = 20 });
    }
}

请求示例

请求时需要在请求头中添加api-version字段，值为对应的版本号：

• 请求头添加api-version: 1.0，请求https://localhost:port/api/user，返回版本1的数据
• 请求头添加api-version: 2.0，请求https://localhost:port/api/user，返回版本2的数据

两种方式对比

两种版本控制方式各有适用场景，具体对比如下：

注意事项

• 版本号定义建议遵循语义化版本规范，比如1.0、2.1等，方便管理迭代节奏
• 旧版本接口不要直接删除，建议标记废弃，给调用方足够的迁移时间
• 如果有多个版本共存，建议统一使用同一种版本控制方式，避免调用方混淆

C#API_versioningASP.NET_CoreURL版本控制Header版本控制修改时间：2026-06-25 19:51:36