C#中如何实现API版本控制？实战接口版本管理教程

在C#的Web开发里，API版本控制是保证接口平滑演进的重要手段。通过合理的版本管理，新旧客户端可以同时访问各自适配的接口，避免升级带来的兼容性故障。

为什么需要API版本控制

当业务模型调整或数据结构变更时，如果直接修改线上接口，旧版App或第三方服务可能解析失败。使用版本控制可以隔离变化，给调用方迁移预留时间。

ASP.NET Core中的版本控制方式

常见做法有三种：

• URL路径版本：如 /api/v1/order
• 查询参数版本：如 /api/order?api-version=2.0
• 请求头版本：通过自定义Header传递版本号

实战：基于URL路径的版本控制

安装与配置

首先通过NuGet引入 Microsoft.AspNetCore.Mvc.Versioning 包，然后在 Program.cs 中配置服务。

// Program.cs 配置代码示例
using Microsoft.AspNetCore.Mvc.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
// 添加API版本控制，默认从URL读取版本
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

var app = builder.Build();
app.UseRouting();
app.MapControllers();
app.Run();

编写不同版本的控制器

使用 ApiVersion 特性标记控制器，并在路由中嵌入版本段。

using Microsoft.AspNetCore.Mvc;

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/order")]
public class OrderV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        // 返回旧版订单结构
        return Ok(new { id = 1, name = "测试订单" });
    }
}

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/order")]
public class OrderV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        // 返回新版订单结构，包含更多字段
        return Ok(new { id = 1, name = "测试订单", total = 99.9 });
    }
}

处理废弃版本

当某个版本不再维护，可使用 Deprecated 标记，并在响应头中告知调用方。

[ApiController]
[ApiVersion("1.0", Deprecated = true)]
[Route("api/v{version:apiVersion}/order")]
public class OrderV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new { id = 1, name = "旧版已废弃" });
    }
}

小结

在C#项目中引入API版本控制并不复杂。根据团队习惯选择URL、参数或Header方式，配合特性与路由规则，就能实现多版本接口共存与平滑下线。

C#API版本控制ASP.NET_Core接口教程版本管理修改时间：2026-07-24 22:24:23