.NET 8 中 API 版本控制的优秀实践-编程学习网

API 版本控制的重要性

API 版本控制是一种结构化和可预测地管理 API 变更的实践。它有助于保持与现有客户端的兼容性，同时允许开发人员在不影响现有用户的情况下改进 API 或添加新功能。其主要优势包括：

向后兼容：确保现有的客户端在引入新更改时仍然可以继续使用 API 而不会出错。
持续改进：允许开发人员在不影响现有用户的情况下改进 API 或添加新功能。
平滑过渡：为客户端提供从一个 API 版本迁移到另一个版本的清晰路径。
错误管理：当因变更引发问题时，有助于更有效地识别问题。

API 版本控制策略

在.NET 8 中，常见的 API 版本控制策略包括：

URI 路径版本控制：版本号包含在 URI 路径中，如 https://api.example.com/v1/users 和 https://api.example.com/v2/users。
查询参数版本控制：版本号包含在 URL 的查询参数中，如 https://api.example.com/users?version=1 和 https://api.example.com/users?version=2。
Header 版本控制：版本号包含在 HTTP 头信息中，如 X-API-Version: 2。
内容协商（媒体类型版本控制）：使用 Accept 头信息来指定 API 的版本，如 Accept: application/json;version=1。

实现 API 版本控制的步骤

以下是在.NET 8 中实现 API 版本控制的具体步骤和示例代码。

第一步：安装必要的包

首先，需要安装支持 API 版本控制的 NuGet 包。在.NET 8 中，可以使用 Microsoft.AspNetCore.Mvc.Versioning 包。

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

第二步：在 Startup.cs 中配置 API 版本控制

修改 Startup.cs 文件，添加 API 版本控制的配置。

using Microsoft.AspNetCore.Mvc.Versioning;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);

// 添加服务
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    // 为不同版本定义Swagger文档
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "MyAPIv1",
        Description = "API 文档: 版本 1"
    });
    options.SwaggerDoc("v2", new OpenApiInfo
    {
        Version = "v2",
        Title = "MyAPIv2",
        Description = "API 文档: 版本 2"
    });

    // 使用解决冲突的策略
    options.ResolveConflictingActions(apiDescriptions =>
    {
        return apiDescriptions.First();
    });
});

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0); // 默认版本: 1.0
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    // 结合多种版本控制方式
    options.ApiVersionReader = ApiVersionReader.Combine(
        new QueryStringApiVersionReader("version"),
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("X-API-Version"),
        new MediaTypeApiVersionReader("version")
    );
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        // 为每个版本定义端点
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "MyAPIv1");
        options.SwaggerEndpoint("/swagger/v2/swagger.json", "MyAPIv2");
    });
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

第三步：创建 Users 控制器

实现一个支持多种版本控制方式的 UsersController。

using Microsoft.AspNetCore.Mvc;

namespace RestAPIVersioning.Controllers
{
    [ApiController]
    [ApiVersion("1.0")]
    [ApiVersion("2.0")]
    [Route("api/v{version:apiVersion}/users")] // URI版本控制
    // 注意：查询字符串、Header和媒体类型版本控制通常不需要额外的路由属性
    public class UsersController : ControllerBase
    {
        [HttpGet]
        [MapToApiVersion("1.0")]
        public IActionResult GetUsers()
        {
            var users = new[] { new { Id = 1, Name = "John Doe" } };
            return Ok(users);
        }

        [HttpGet]
        [MapToApiVersion("2.0")]
        public IActionResult GetUsersV2()
        {
            var users = new[] { new { Id = 1, Name = "John Doe", Email = "john.doe@example.com" } };
            return Ok(users);
        }
    }
}

第四步：测试你的版本化 API

运行你的应用，并使用不同的版本控制方式访问 API：

URI 版本控制：http://localhost:/api/v1/users 和 http://localhost:/api/v2/users
查询参数版本控制：http://localhost:/api/users?version=1 和 http://localhost:/api/users?version=2
Header 版本控制：在 HTTP 请求的 Header 中添加 X-API-Version: 2
内容协商（媒体类型版本控制）：在 HTTP 请求的 Accept 头信息中添加 application/json;version=1

通过以上步骤，你可以在.NET 8 中有效地实现 API 版本控制，确保 API 的兼容性和可扩展性。