API 版本管理与 OpenAPI 契约

// 看似无害的「优化」，对老客户端却是破坏性变更
// 变更前
public record OrderDto(int Id, decimal Total, string Status);

// 变更后：Total 从 decimal 变 double，且删掉了 Status
public record OrderDto(int Id, double Total);

// Program.cs：注册版本服务，统一用查询串作为默认读取方式
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;          // 响应头回带支持的版本
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),      // /api/v1/...
        new QueryStringApiVersionReader("api-version"),
        new HeaderApiVersionReader("X-Api-Version"));
})
.AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";        // 分组名形如 v1、v2
    options.SubstituteApiVersionInUrl = true;  // 文档里把 {version} 替换成真实值
});

// 控制器：声明自己属于哪个版本
[ApiController]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class OrdersController : ControllerBase
{
    [HttpGet("{id:int}")]
    [MapToApiVersion("1.0")]
    public ActionResult<OrderV1> GetV1(int id) => Ok(OrderV1.From(_repo.Find(id)));

    [HttpGet("{id:int}")]
    [MapToApiVersion("2.0")]
    public ActionResult<OrderV2> GetV2(int id) => Ok(OrderV2.From(_repo.Find(id)));
}

// 用 ApiVersionDescriptionProvider 枚举所有版本，供文档与门禁脚本消费
public class ApiVersionInfo(IApiVersionDescriptionProvider provider)
{
    public IEnumerable<string> AllVersions =>
        provider.ApiVersionDescriptions.Select(d => d.GroupName);

    public bool IsDeprecated(string group) =>
        provider.ApiVersionDescriptions
                .First(d => d.GroupName == group).IsDeprecated;
}

// 每个版本生成一份 OpenAPI 文档，路径为 /openapi/v1.json、/openapi/v2.json
builder.Services.AddOpenApi("v1", options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info = new OpenApiInfo
        {
            Title = "订单服务",
            Version = "v1",
            Description = "订单域公开接口，v1 已进入维护期",
        };
        return Task.CompletedTask;
    });
});
builder.Services.AddOpenApi("v2");

app.MapOpenApi("/openapi/{documentName}.json");

// 自定义 Schema 转换器：把 decimal 输出为 string，避免前端浮点精度问题
public class DecimalAsStringTransformer : IOpenApiSchemaTransformer
{
    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext ctx,
                               CancellationToken ct)
    {
        if (ctx.JsonTypeInfo.Type == typeof(decimal))
        {
            schema.Type = JsonSchemaType.String;
            schema.Format = "decimal";
        }
        return Task.CompletedTask;
    }
}

// Refit：接口即契约，方法签名与 OpenAPI 一一对应
public interface IOrdersApi
{
    [Get("/api/v1/orders/{id}")]
    Task<OrderV1> GetOrderAsync(int id, CancellationToken ct = default);

    [Post("/api/v1/orders")]
    Task<OrderV1> CreateOrderAsync([Body] CreateOrderRequest req, CancellationToken ct = default);
}

builder.Services.AddRefitClient<IOrdersApi>()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"))
    .AddStandardResilienceHandler();   // 复用重试、熔断、超时策略

# Kiota：从线上文档生成强类型客户端，锁定版本号保证可复现
dotnet tool install --global Microsoft.OpenApi.Kiota
kiota generate \
  --language CSharp \
  --openapi /openapi/v2.json \
  --class-name OrdersClient \
  --namespace-name Contoso.Orders.Client \
  --output ./src/Contoso.Orders.Client

# 用 openapi-diff 对比主干与当前分支的文档，破坏性变更直接失败
npm install -g openapi-diff
openapi-diff baseline/openapi-v2.json current/openapi-v2.json \
  --fail-on-incompatible

// 在测试里断言「老客户端仍能反序列化新响应」
[Fact]
public async Task V2响应仍兼容V1客户端()
{
    var v2Json = await _client.GetStringAsync("/api/v2/orders/42");

    // 用 v1 的模型反序列化 v2 的响应，未知字段应被忽略
    var v1 = JsonSerializer.Deserialize<OrderV1>(v2Json,
        new JsonSerializerOptions { PropertyNameCaseInsensitive = true });

    Assert.NotNull(v1);
    Assert.True(v1!.Id > 0);
}

// 契约快照：把当前文档写入基线文件，PR 中人工评审差异
[Fact]
public async Task OpenApi文档与基线一致()
{
    var current = await _client.GetStringAsync("/openapi/v2.json");
    var baselinePath = Path.Combine("specs", "openapi-v2.baseline.json");

    if (Environment.GetEnvironmentVariable("UPDATE_SNAPSHOT") == "1")
    {
        await File.WriteAllTextAsync(baselinePath, current);
        return;
    }
    Assert.Equal(await File.ReadAllTextAsync(baselinePath), current);
}

// 中间件：对所有命中已弃用版本的响应补充标准头
public class DeprecationMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext ctx, ApiVersionInfo versions)
    {
        ctx.Response.OnStarting(() =>
        {
            var group = ctx.GetRequestedApiVersion()?.ToString("'v'VVV");
            if (group is not null && versions.IsDeprecated(group))
            {
                ctx.Response.Headers["Deprecation"] = "true";
                ctx.Response.Headers["Sunset"] = "Sat, 31 Jan 2026 23:59:59 GMT";
                ctx.Response.Headers["Link"] =
                    "</api/v3/orders>; rel=\"successor-version\"";
            }
            return Task.CompletedTask;
        });
        await next(ctx);
    }
}

// 遥测：按版本 + 调用方维度计数，判断何时可以安全下线
public class VersionMetricsMiddleware(RequestDelegate next, Meter meter)
{
    private readonly Counter<long> _counter =
        meter.CreateCounter<long>("api.requests.by_version");

    public async Task InvokeAsync(HttpContext ctx)
    {
        _counter.Add(1, new KeyValuePair<string, object?>(
            "version", ctx.GetRequestedApiVersion()?.ToString() ?? "none"),
            new KeyValuePair<string, object?>(
            "client", ctx.Request.Headers.UserAgent.ToString()));
        await next(ctx);
    }
}

# CI 中的契约门禁
name: contract
on: [pull_request]
jobs:
  openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x'
      - run: dotnet build -c Release
      - name: 导出当前文档
        run: dotnet run --project tools/ExportOpenApi -- --output ./specs
      - name: 破坏性变更检查
        run: npx openapi-diff ./specs/baseline.json ./specs/current.json --fail-on-incompatible
      - name: 规范 lint
        run: npx spectral lint ./specs/current.json --ruleset .spectral.yaml