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

推荐使用 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

处理弃用与兼容性提示

对已废弃的版本，可通过特性明确标记，并由框架自动注入响应头：

给控制器加 [ApiVersion("1.0", Deprecated = true)]
启用 ReportApiVersions = true 后，v1 接口响应头会包含 api-deprecated-versions: 1.0
客户端可根据该头决定是否提醒用户升级，服务端无需手动拦截或返回特殊状态码

基本上就这些。不复杂但容易忽略细节，比如忘了注册服务、没配路由模板、或多个版本控制器冲突——调试时留意日志里 ApiVersionMatcherPolicy 的匹配结果即可。

# 路由 # microsoft # 状态码 # .net # mvc # 接口 # 多个 # 推荐使用 # 的是 # 客户端 # 也可 # 可选 # 再用 # 可将 # 可通过 # 并由

返回目录在线咨询

上一篇：云服务器与传统物理服务器，哪种更适合建站？
下一篇：靖江品牌网站设计制作公司,靖江银监会官网投诉入口？

您的项目需求