当前位置：首页 > news >正文

在.NET 8 中使用中介模式优雅处理多版本 API 请求

news 2025/8/22 6:30:59

在.NET 8 中使用中介模式优雅处理多版本 API 请求

在现代 Web API 开发中，API 版本管理是一个不可避免的挑战。随着业务需求的不断变化和功能的迭代升级，我们经常需要维护多个 API 版本以确保向后兼容性。本文将介绍如何在.NET 8 框架的ASP.NET Core 应用中，利用中介模式（Mediator Pattern）来优雅地处理多版本 API 请求，实现清晰、可扩展的版本管理方案。

为什么需要 API 版本管理？

随着 API 的演进，我们会面临以下场景：

新增功能需要修改现有 API 的请求 / 响应格式

优化数据结构导致旧版本客户端无法兼容

部分客户端因各种原因无法及时升级到最新版本

需要逐步淘汰旧功能但不能影响现有用户

直接修改现有 API 往往会导致 "破坏性更新"，影响正在使用旧版本的客户端。因此，一套完善的 API 版本管理策略至关重要。

中介模式：多版本 API 的理想选择

中介模式通过引入一个中介者角色，协调多个对象之间的交互，避免对象之间的直接耦合。在多版本 API 场景中，这一模式带来了诸多优势：

集中化路由：所有版本路由逻辑集中在中介者，便于维护

解耦版本实现：各版本处理器相互独立，仅通过中介者通信

简化扩展：新增版本只需实现新处理器并注册到中介者

版本间协作：通过中介者实现不同版本间的数据转换和依赖调用

.NET 8 中的实现方案

下面我们将详细介绍基于.NET 8 的实现方案，包含核心组件设计和具体实现代码。

核心组件设计

我们的方案包含以下核心组件：

IApiMediator：中介者接口，定义请求处理和版本管理契约

ApiMediator：中介者具体实现，负责路由请求和管理版本处理器

IRequestHandler：版本处理器接口，定义各版本 API 的处理契约

具体处理器：如 V1RequestHandler、V2RequestHandler 等，实现特定版本的业务逻辑

API 控制器：接收客户端请求并委托给中介者处理

实现代码

1. 定义接口契约

首先我们定义中介者和处理器的核心接口：

// IApiMediator.csusing Microsoft.AspNetCore.Mvc;using System.Threading.Tasks;namespace DotNet8ApiVersionExample;public interface IApiMediator{void RegisterHandler(IRequestHandler handler);Task<IActionResult> ProcessRequestAsync(string version, string action, object? data);Task<object?> ForwardRequestAsync(string targetVersion, string action, object? data);}// IRequestHandler.csnamespace DotNet8ApiVersionExample;public interface IRequestHandler{string SupportedVersion { get; }void SetMediator(IApiMediator mediator);Task<IActionResult> HandleRequestAsync(string action, object? data);}

2. 实现中介者

接下来实现中介者，负责管理处理器和路由请求：

// ApiMediator.csusing Microsoft.AspNetCore.Mvc;using System;using System.Collections.Generic;using System.Threading.Tasks;namespace DotNet8ApiVersionExample;public class ApiMediator : IApiMediator{private readonly Dictionary<string, IRequestHandler> _handlers = new();public void RegisterHandler(IRequestHandler handler){if (handler == null)throw new ArgumentNullException(nameof(handler));var version = handler.SupportedVersion;if (!_handlers.ContainsKey(version)){_handlers.Add(version, handler);handler.SetMediator(this);}}public async Task<IActionResult> ProcessRequestAsync(string version, string action, object? data){if (_handlers.TryGetValue(version, out var handler)){return await handler.HandleRequestAsync(action, data);}return new NotFoundObjectResult($"不支持的API版本: {version}");}public async Task<object?> ForwardRequestAsync(string targetVersion, string action, object? data){if (_handlers.TryGetValue(targetVersion, out var handler)){// 这里简化处理，实际可能需要转换数据格式var result = await handler.HandleRequestAsync(action, data);if (result is ObjectResult objectResult){return objectResult.Value;}}return null;}}

3. 实现版本处理器

下面实现两个版本的处理器，展示不同版本的业务逻辑：

// V1RequestHandler.csusing Microsoft.AspNetCore.Mvc;using System.Threading.Tasks;namespace DotNet8ApiVersionExample;public class V1RequestHandler : IRequestHandler{public string SupportedVersion => "v1";public IApiMediator? Mediator { get; private set; }public void SetMediator(IApiMediator mediator){Mediator = mediator;}public async Task<IActionResult> HandleRequestAsync(string action, object? data){switch (action){case "getUser":return await GetUser((int?)data);case "getOrders":return await GetOrders((int?)data);default:return new NotFoundObjectResult($"V1 API不支持的操作: {action}");}}private Task<IActionResult> GetUser(int? id){if (!id.HasValue)return Task.FromResult<IActionResult>(new BadRequestObjectResult("用户ID不能为空"));// 模拟数据库查询var user = new V1User { Id = id.Value, Name = "张三", Age = 30 };return Task.FromResult<IActionResult>(new OkObjectResult(user));}private Task<IActionResult> GetOrders(int? userId){// 实现V1版本的订单查询逻辑return Task.FromResult<IActionResult>(new OkObjectResult(new[] {new V1Order { Id = 1, Product = "商品A", Amount = 99.9m }}));}}// V2RequestHandler.csusing Microsoft.AspNetCore.Mvc;using System.Threading.Tasks;namespace DotNet8ApiVersionExample;public class V2RequestHandler : IRequestHandler{public string SupportedVersion => "v2";public IApiMediator? Mediator { get; private set; }public void SetMediator(IApiMediator mediator){Mediator = mediator;}public async Task<IActionResult> HandleRequestAsync(string action, object? data){switch (action){case "getUser":return await GetUser((int?)data);case "getOrders":return await GetOrders((int?)data);case "getUserWithAddress":return await GetUserWithAddress((int?)data);case "getLegacyReport":// 调用V1版本处理遗留报表if (Mediator != null){var legacyData = await Mediator.ForwardRequestAsync("v1", "getOrders", data);return new OkObjectResult(new V2Report {Data = legacyData,GeneratedAt = DateTime.Now,FormatVersion = "2.0"});}return new BadRequestObjectResult("无法生成报表");default:return new NotFoundObjectResult($"V2 API不支持的操作: {action}");}}private Task<IActionResult> GetUser(int? id){// 实现V2版本的用户查询逻辑，返回更丰富的信息var user = new V2User {Id = id.Value,FullName = "张三",Age = 30,MemberSince = new DateTime(2020, 1, 1)};return Task.FromResult<IActionResult>(new OkObjectResult(user));}// 其他方法实现...}

4. 实现 API 控制器

最后实现 API 控制器，接收客户端请求并委托给中介者：

// ApiController.csusing Microsoft.AspNetCore.Mvc;namespace DotNet8ApiVersionExample.Controllers;[ApiController][Route("api/{version}/[controller]")]public class ApiController : ControllerBase{private readonly IApiMediator _mediator;public ApiController(IApiMediator mediator){_mediator = mediator;}[HttpGet("user")]public async Task<IActionResult> GetUser(string version, [FromQuery] int? id){return await _mediator.ProcessRequestAsync(version, "getUser", id);}[HttpGet("orders")]public async Task<IActionResult> GetOrders(string version, [FromQuery] int? userId){return await _mediator.ProcessRequestAsync(version, "getOrders", userId);}[HttpGet("user-with-address")]public async Task<IActionResult> GetUserWithAddress(string version, [FromQuery] int? id){return await _mediator.ProcessRequestAsync(version, "getUserWithAddress", id);}[HttpGet("legacy-report")]public async Task<IActionResult> GetLegacyReport(string version, [FromQuery] int? userId){return await _mediator.ProcessRequestAsync(version, "getLegacyReport", userId);}}

5. 配置服务

在 Program.cs 中配置依赖注入和服务：

var builder = WebApplication.CreateBuilder(args);// 添加控制器builder.Services.AddControllers();// 注册中介者和处理器builder.Services.AddSingleton<IApiMediator, ApiMediator>();builder.Services.AddTransient<IRequestHandler, V1RequestHandler>();builder.Services.AddTransient<IRequestHandler, V2RequestHandler>();var app = builder.Build();// 配置中间件app.UseHttpsRedirection();app.UseRouting();app.UseAuthorization();app.MapControllers();app.Run();