MoneyTree.ApiVersioning API 版本控制

📋 概述

MoneyTree.ApiVersioning 提供灵活的 API 版本控制能力，支持多种版本策略（URL 路径、请求头、查询字符串），具备版本弃用提醒机制和 Swagger 自动分组功能。

🏗️ 项目文件结构

MoneyTree.ApiVersioning/
├── MoneyTree.ApiVersioning.csproj
├── GlobalUsings.cs
├── ApiVersion.cs                     # 版本号模型
├── Abstractions/
│   ├── IApiVersionProvider.cs        # 版本提供者接口
│   └── IApiVersionStrategy.cs        # 版本策略接口
├── Core/
│   ├── ApiVersionContext.cs          # 版本上下文
│   └── ApiVersionOptions.cs          # 版本配置选项
├── Deprecation/
│   └── ApiVersionDeprecationPolicy.cs # 版本弃用策略
├── Extensions/
│   ├── ApiVersioningBuilder.cs       # 流畅配置构造器
│   ├── ApiVersioningExtensions.cs    # DI 注册扩展
│   └── EndpointConventionBuilderExtensions.cs  # 终结点版本约束扩展
├── Filters/
│   └── ApiVersionEndpointFilter.cs   # 版本终结点过滤器
├── Middleware/
│   └── ApiVersionMiddleware.cs       # 版本解析中间件
└── Strategies/
    ├── HeaderVersionStrategy.cs      # 请求头策略
    ├── QueryStringVersionStrategy.cs # 查询字符串策略
    └── UrlPathVersionStrategy.cs     # URL 路径策略

🚀 基础配置

// Program.cs
using MoneyTree.ApiVersioning.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMoneyTreeApiVersioning(v =>
{
    v.UseUrlPath()
     .UseHeader("X-API-Version")
     .AddVersion(new ApiVersion(1, 0))
     .AddVersion(new ApiVersion(2, 0))
     .SetDefaultVersion(new ApiVersion(1, 0));
});

var app = builder.Build();
app.UseMoneyTreeApiVersioning();

🎯 版本策略

多策略组合

框架支持同时启用多种版本策略，按优先级依次尝试解析。

🔒 终结点版本约束

通过扩展方法为特定终结点设置版本要求：

// 此终结点最低支持 v1.0
app.MapGet("/api/orders", () => Results.Ok())
   .RequireApiVersion(new ApiVersion(1, 0));

// 此终结点从 v1.0 到 v2.0 之间可用（在 v2.0 后移除）
app.MapGet("/api/orders/legacy", () => Results.Ok())
   .RequireApiVersion(new ApiVersion(1, 0), new ApiVersion(1, 0))
   .Deprecated(sunsetDate: DateTime.UtcNow.AddMonths(6));

⚠️ 版本弃用

弃用机制允许标记不再推荐使用的 API 版本，并通知客户端最终下线的日期。

启用弃用标记

var deprecationPolicy = app.Services.GetRequiredService<ApiVersionDeprecationPolicy>();
deprecationPolicy.Deprecate(new ApiVersion(1, 0), DateTime.UtcNow.AddMonths(3));

弃用响应头

弃用的 API 会自动在响应中添加以下 HTTP 头信息：

📊 Swagger 集成

模块自动将不同版本的 API 分组到独立的 Swagger 文档中，便于开发者查阅和调试。