ASP.NET Core怎么实现API版本控制 ASP.NET Core API Versioning教程

月夜之吻 2025-12-25 00:00:00 次阅读

推荐使用 Microsoft.AspNetCore.Mvc.Versioning 包实现 ASP.NET Core API 版本控制，支持 URL、查询参数、请求头等多种版本标识方式，需在 Program.cs 中注册服务并配置默认版本、弃用提示等，控制器通过 [ApiVersion] 特性声明版本支持。

ASP.NET Core 实现 API 版本控制，推荐使用官方支持的 Microsoft.AspNetCore.Mvc.Versioning 包，它轻量、灵活，与 MVC 深度集成，支持 URL、查询参数、请求头等多种版本标识方式。

安装并启用版本控制服务

在 Program.cs 中注册服务并配置基础行为：

通过 AddApiVersioning 启用版本控制，设置默认版本（如 1.0）和是否报告支持的版本
可选启用 AssumeDefaultVersionWhenUnspecified = true，让无版本请求默认走 v1
若需返回 api-supported-versions 或 api-deprecated-versions 响应头，开启 ReportApiVersions = true

示例：

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

在控制器中声明版本支持

使用 [ApiVersion] 特性标注控制器或具体 Action，支持多个版本同时存在：

单个控制器支持多版本：加多个 [ApiVersion("1.0")] 和 [ApiVersion("2.0")]
不同控制器处理不同版本：如 ProductsControllerV1 和 ProductsControllerV2，都路由到 /api/products
配合 [MapToApiVersion("2.0")] 可将某个 Action 限定只响应 v2 请求

注意：必须为每个版本提供至少一个匹配的 endpoint，否则会返回 400 或 404。

选择版本识别方式（URL / Query / Header）

默认通过请求头 api-version 识别，但更常见的是 URL 路径（如 /api/v1/products）或查询参数（如 /api/products?api-version=1.0）：

URL 路径：配置 options.ApiVersionReader = new UrlSegmentApiVersionReader();，再用 [Route("api/v{version:apiVersion}/[controller]")]
查询参数：用 new QueryStringApiVersionReader("api-version")
请求头：默认即支持，客户端传 api-version: 2.0
也可组合使用，如优先读 URL，降级读 Header