.NET Web API如何进行接口版本控制-C#.Net教程-PHP中文网

答案：.NET Web API 中接口版本控制可通过 URL 路径、查询字符串或请求头实现，常用方案包括路由中嵌入版本号（如 /api/v1/products）、使用 Microsoft.AspNetCore.Mvc.Versioning 包支持查询参数或请求头传递版本，并结合 Swagger 生成多版本文档，便于管理与兼容旧客户端。

.net web api如何进行接口版本控制

在 .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 中配置：

JSON Toolkit

JSON文件多功能工具。支持格式化、验证、压缩、键排序及点记法路径查询。零依赖。

下载

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 路径版本最易理解，查询字符串灵活，请求头更隐蔽。合理使用版本控制能有效降低升级风险。