如何实现Web API版本控制？多客户端兼容架构问询

针对你提到的单应用内实现API版本控制、避免代码冗余和控制器内大量版本判断的需求，以下是几种实用的架构方案：

1. 按版本拆分控制器与路由 #

• 直接在项目内按版本划分目录，比如Controllers/V1、Controllers/V2，分别存放对应版本的控制器类。
• 在路由配置中为不同版本的控制器添加前缀，例如/api/v1/users对应V1/UsersController，/api/v2/users对应V2/UsersController。
• 公共逻辑（如数据访问、工具函数）抽离到项目的共享层（比如Core或Services/Common），各版本控制器按需调用，避免代码重复。
• 优势：版本逻辑完全隔离，维护时无需跨版本修改同一文件，可读性和扩展性更强。

2. 基于请求标识的动态路由/服务分发 #

如果不想在URL中暴露版本号，可以通过请求头（如X-API-Version）或查询参数（如?api-version=2）传递版本信息，再通过中间件或过滤器做分发：

• 中间件解析版本标识后，将请求转发到对应版本的控制器方法，或者将对应版本的服务实例注入到请求上下文。
• 伪代码示例（以ASP.NET Core为例）：

  // 自定义中间件
  public async Task InvokeAsync(HttpContext context)
  {
      var version = context.Request.Headers["X-API-Version"].FirstOrDefault() ?? "1";
      // 根据版本映射到不同的服务实例
      var service = version switch
      {
          "1" => context.RequestServices.GetRequiredService<IUserServiceV1>(),
          "2" => context.RequestServices.GetRequiredService<IUserServiceV2>(),
          _ => context.RequestServices.GetRequiredService<IUserServiceV1>()
      };
      context.Items["CurrentUserService"] = service;
      await _next(context);
  }
  

• 控制器从HttpContext.Items中直接获取对应版本的服务，无需在控制器内编写版本判断逻辑。

3. 接口+多实现的服务层版本隔离 #

• 定义统一的业务接口，比如IUserService，然后为每个版本实现对应的类：UserServiceV1、UserServiceV2。
• 通过工厂模式或依赖注入的动态解析，根据请求版本获取对应的服务实现：

  public class UserServiceFactory
  {
      private readonly IServiceProvider _provider;
      public UserServiceFactory(IServiceProvider provider) => _provider = provider;
  
      public IUserService GetService(string version)
      {
          return version switch
          {
              "2" => _provider.GetRequiredService<UserServiceV2>(),
              _ => _provider.GetRequiredService<UserServiceV1>()
          };
      }
  }
  

• 控制器注入工厂类，根据请求版本调用对应服务，完全符合开闭原则，新增版本只需添加新的实现类即可。

4. 版本维护的辅助建议 #

• 尽量将版本差异限制在服务层，控制器仅负责请求接收与响应返回，避免控制器业务逻辑膨胀。
• 对于差异极小的版本，采用策略模式封装差异逻辑，减少重复代码。
• 制定版本淘汰计划，定期下线不再维护的旧版本，降低项目复杂度。

内容的提问来源于stack exchange，提问作者Artur Homoastricus