SuperAPI AI 工具集

dotnet-api-versioning

编程与开发

查看项目

更新于 10-16 01:27

技能介绍

用途:为 ASP.NET Core 的 HTTP API 提供版本管理方案,基于 Asp.Versioning 库族。资料将 URL 路径段版本(/api/v1/)列为首选,因其简单、可发现、可缓存,且在所有 HTTP 客户端和日志中清晰可见。

主要能力:覆盖三种版本读取策略。URL 路径段使用 UrlSegmentApiVersionReader;请求头使用 HeaderApiVersionReader("X-Api-Version");查询字符串使用 QueryStringApiVersionReader("api-version")。可用 ApiVersionReader.Combine 组合多个读取器,首个解析出版本的读取器生效,适合从一种策略迁移到另一种。支持设置 DefaultApiVersion、AssumeDefaultVersionWhenUnspecified、ReportApiVersions(输出 api-supported-versions 响应头)。同时适用于 Minimal API(版本集与 MapGroup、MapToApiVersion)和 MVC 控制器([ApiVersion] 特性、AddApiExplorer 的 GroupNameFormat 与 SubstituteApiVersionInUrl)。

日落与弃用:通过 options.Policies.Sunset(版本).Effective(时间).Link(url).Title(...).Type(...) 设置日落策略,响应会返回 api-supported-versions、api-deprecated-versions、Sunset(遵循 RFC 8594)和 Link 头;弃用可用 HasDeprecatedApiVersion 或 [ApiVersion(..., Deprecated = true)] 标记。

安装与迁移:Minimal API 安装 Asp.Versioning.Http(8.),MVC 控制器安装 Asp.Versioning.Mvc.ApiExplorer(8.);旧包 Microsoft.AspNetCore.Mvc.Versioning 系列应迁移到 Asp.Versioning.Mvc,命名空间由 Microsoft.AspNetCore.Mvc.Versioning 改为 Asp.Versioning,ApiExplorer 改为 Asp.Versioning.ApiExplorer,并更新服务注册与自定义 IApiVersionReader。

限制与注意:资料明确要求新项目不要使用旧版包,不要硬编码包版本号而应使用版本范围,不要遗漏 ReportApiVersions,每个路由组只对应一个 API 版本,弃用版本时须提供日落日期与迁移链接,公开 API 不建议开启 AssumeDefaultVersionWhenUnspecified。资料未提供具体收费、价格或平台支持信息。