答案：.NET Web API 中接口版本控制可通过 URL 路径、查询字符串或请求头实现，常用方案包括路由中嵌入版本号（如 /api/v1/products）、使用 Microsoft.AspNetCore.Mvc.Versioning 包支持查询参数或请求头传递版本，并结合 Swagger 生成多版本文档，便于管理与兼容旧客户端。
在 .NET Web API 中进行接口版本控制，主要是为了在不影响旧客户端的前提下，安全地迭代和发布新功能。常见的做法是通过 URL、查询字符串、请求头等方式区分不同版本的 API。以下是几种主流且实用的版本控制方式及具体实现。
使用 URL 路径进行版本控制
这是最常见也最直观的方式，将版本号直接嵌入到 API 的路由中。
示例：
- /api/v1/products
- /api/v2/products
实现方法：
在控制器上使用 [Route] 特性指定版本路径：
[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 中配置：
{
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 路径版本最易理解，查询字符串灵活，请求头更隐蔽。合理使用版本控制能有效降低升级风险。
