用途:为 ASP.NET Core HTTP API 提供版本控制方案,基于 Asp.Versioning 包族,支持 URL 段、请求头、查询字符串三种策略,并可用于 Minimal APIs 与 MVC 控制器。
主要能力:URL 段(/api/v1/)为首选方案,简单、可发现、可缓存;请求头版本通过 X-Api-Version 读取;查询字符串版本使用 api-version 参数。可组合多个版本读取器(ApiVersionReader.Combine),第一个解析成功的读取器生效,便于迁移。支持 Sunset 策略(RFC 8594)与版本弃用标记,响应头可包含 api-supported-versions、api-deprecated-versions、Sunset、Link。
使用方式:Minimal APIs 安装 Asp.Versioning.Http;MVC 控制器安装 Asp.Versioning.Mvc.ApiExplorer。通过 AddApiVersioning 配置 DefaultApiVersion、AssumeDefaultVersionWhenUnspecified、ReportApiVersions、ApiVersionReader。Minimal APIs 使用 NewApiVersionSet、MapGroup、MapToApiVersion;MVC 使用 [ApiVersion] 特性与路由 api/v{version:apiVersion}。Sunset 在 options.Policies.Sunset(1.0) 处设置生效时间与迁移链接。
适用场景:公共 API(推荐 URL 段)、内部受控客户端 API(可用请求头)、快速原型或兼容旧客户端(可用查询字符串)。
限制:Minimal API 端点模式、按版本生成 OpenAPI、按版本认证授权不在本技能范围内。不要对新项目使用旧包 Microsoft.AspNetCore.Mvc.Versioning,应迁移到 Asp.Versioning.Mvc 或 Asp.Versioning.Http;建议使用 8.* 版本范围;需开启 ReportApiVersions;公开 API 不建议启用 AssumeDefaultVersionWhenUnspecified。需要 .NET 8.0+。具体收费、平台与效果资料暂未提供。