.NET Web API如何进行接口版本控制

来源：这里教程网时间：2026-02-21 17:31:05 作者：

在 .NET Web API 中进行接口版本控制，主要是为了在不影响旧客户端的前提下，安全地迭代和发布新功能。常见的做法是通过 URL、查询字符串、请求头等方式区分不同版本的 API。以下是几种主流且实用的版本控制方式及具体实现。

使用 URL 路径进行版本控制

这是最常见也最直观的方式，将版本号直接嵌入到 API 的路由中。

示例：

/api/v1/products /api/v2/products

实现方法：

在控制器上使用

[Route]

特性指定版本路径：

[ApiController]
[Route("api/v1/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("v1 result");
}

[ApiController]
[Route("api/v2/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("v2 result with new fields");
}

注意：两个同名控制器需放在不同命名空间或使用不同类名避免冲突，推荐按版本分目录管理。

使用查询字符串进行版本控制

将版本信息作为查询参数传递，适合不想改变 URL 结构的场景。

示例：

/api/products?api-version=1.0 /api/products?api-version=2.0

实现方法：

安装 NuGet 包

Microsoft.AspNetCore.Mvc.Versioning

，然后在

Program.cs

中配置：

builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});

// 控制器上标注支持的版本
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet]
[MapToApiVersion("1.0")]
public IActionResult GetV1() => Ok("Version 1.0");

[HttpGet]
[MapToApiVersion("2.0")]
public IActionResult GetV2() => Ok("Version 2.0");
}

使用请求头进行版本控制

通过自定义 HTTP 请求头传递版本信息，保持 URL 洁净，适合内部系统或对 URL 敏感的场景。

示例：

请求头：api-version: 1.0

配置方式：

builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});

控制器写法与查询字符串方式一致，不再重复。

结合 Swagger 显示多版本文档

使用

Swashbuckle.AspNetCore

时，可配合

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

自动生成各版本的 Swagger 文档。

安装包：

Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

配置示例：

builder.Services.AddVersionedApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});

// Swagger 配置中为每个版本生成独立文档
var apiVersionDescriptionProvider = app.Services.GetRequiredService();
app.UseSwagger();
app.UseSwaggerUI(options =>
{
foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
{
options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
}
});

基本上就这些。选择哪种方式取决于团队规范和客户端兼容性要求。URL 路径版本最易理解，查询字符串灵活，请求头更隐蔽。合理使用版本控制能有效降低升级风险。