SuperAPI AI 工具集

api-versioning

编程与开发

查看项目

更新于 10-15 19:51

技能介绍

用途:为 ASP.NET Core 项目制定 API 版本管理策略,覆盖从初次设计到版本弃用的完整流程。资料强调从第一天就带版本号,URL 段版本(如 /api/v1/orders)为默认推荐方式,兼具可发现性与缓存友好性;破坏性变更应新增版本而非修改旧版本;按组而非单个端点划分版本。

主要能力:使用 Asp.Versioning 库配置版本读取器(UrlSegmentApiVersionReader、HeaderApiVersionReader("X-Api-Version"))、默认版本、未指定版本时的回退、版本报告与 ApiExplorer 分组格式("'v'VVV")。支持 URL 段、请求头、查询字符串三种策略;支持用 HasDeprecatedApiVersion 标记弃用版本,响应头返回 api-deprecated-versions。提供版本专属端点分组的映射示例(MapGroup 配合 NewApiVersionSet)。

使用方式:在 Program.cs 中注册 AddApiVersioning 与 AddApiExplorer;用 app.NewApiVersionSet().HasApiVersion(...).Build() 构建版本集,通过 app.MapGroup("/api/v{version:apiVersion}/...") 关联 WithApiVersionSet 映射各版本端点组。

决策参考:新公开 API 用 URL 段版本;服务间内部 API 可用请求头版本;破坏性响应结构变更开新版本;仅新增可选字段保持同版本;弃用版本需标记、设定下线时间并提供迁移路径。

限制:资料未提供具体包版本、性能数据、OpenAPI 集成的详细代码与迁移工具说明。