跳转至

架构重构说明

文档版本: 1.7.0 最后更新: 2026-04-10 Git 提交: 2cba097 作者: Lincoln

概述

本文档记录了 JAiRouter 项目的重大架构重构历史,帮助开发者理解系统演进过程和设计决策。

V2.0 架构重构(2026-Q2 计划)

重构目标

  • 提升系统可扩展性
  • 降低模块耦合度
  • 改善代码可维护性
  • 支持更多后端服务

主要变更

1. 适配器层重构

重构前:

public class GPUStackAdapter {
    public Mono<Response> chat(Request request) { ... }
    public Mono<Response> embedding(EmbeddingRequest request) { ... }
}

重构后:

public interface AiServiceAdapter {
    String getServiceType();
    Mono<Response> chat(Request request);
    Mono<Response> embedding(EmbeddingRequest request);
}

public abstract class BaseAiServiceAdapter implements AiServiceAdapter {
    // 公共逻辑:重试、超时、错误处理
}

public class GPUStackAdapter extends BaseAiServiceAdapter {
    // 只关注 GPUStack 特定逻辑
}

优势: - 统一接口,易于扩展新服务 - 公共逻辑复用,减少代码重复 - 符合开闭原则

2. 负载均衡器重构

重构前: 硬编码负载均衡策略

重构后: 策略模式

public interface LoadBalancerStrategy {
    String select(List<String> instances, String serviceKey);
}

public class RoundRobinStrategy implements LoadBalancerStrategy { ... }
public class WeightedStrategy implements LoadBalancerStrategy { ... }
public class LeastConnectionsStrategy implements LoadBalancerStrategy { ... }

3. 限流器重构

重构前: 单一限流实现

重构后: 限流器工厂模式

public interface RateLimiter {
    Mono<Boolean> tryAcquire(String key);
}

public class TokenBucketRateLimiter implements RateLimiter { ... }
public class SlidingWindowRateLimiter implements RateLimiter { ... }
public class LeakyBucketRateLimiter implements RateLimiter { ... }

public class RateLimiterFactory {
    public RateLimiter create(RateLimiterType type, Config config) { ... }
}

4. 熔断器重构(V1.4.1 已完成)

使用状态模式重构熔断器,圈复杂度从 15 降低到 5。

详情: V1.4.1 更新日志


V1.7 安全架构增强(2026-04)

新增安全模块

  1. 安全黑名单管理
  2. IP 黑名单
  3. 用户黑名单
  4. 令牌黑名单

  5. 审计日志系统

  6. 安全操作审计
  7. 配置变更审计
  8. API Key 操作审计

  9. 数据脱敏

  10. 敏感字段自动脱敏
  11. 可配置脱敏规则

V1.6 配置管理优化(2026-04)

配置持久化重构

变更: - 移除配置合并功能,简化逻辑 - 优化版本管理,支持快速回滚 - 增加配置变更审计


V1.5 响应式编程改造(2026-03)

WebFlux 全面改造

改造内容: - 所有控制器改为响应式 - 数据库访问使用 R2DBC - HTTP 调用使用 WebClient

性能提升: - 并发能力提升 50% - 响应时间降低 30%


V1.4 模块化设计(2026-03)

模块划分

模块职责包路径
控制器层API 入口controller
适配器层服务协议转换adapter
负载均衡层实例选择loadbalancer
限流层请求限流ratelimiter
熔断层故障保护circuitbreaker
存储层配置持久化repository

架构原则

1. 单一职责

每个模块只负责一个明确的职责,避免功能臃肿。

2. 开闭原则

对扩展开放,对修改关闭。新增功能通过扩展实现,而非修改现有代码。

3. 依赖倒置

高层模块不依赖低层模块,都依赖抽象接口。

4. 接口隔离

使用多个专门的接口,而非单一的总接口。

5. 最少知识

模块之间减少耦合,只与直接相关的模块交互。


重构流程

1. 问题识别

  • 代码复杂度过高
  • 模块耦合严重
  • 扩展新功能困难
  • 测试覆盖率低

2. 方案设计

  • 设计新模式/架构
  • 评估影响范围
  • 制定迁移计划
  • 准备回滚方案

3. 渐进实施

  • 小步快跑,分步实施
  • 保持向后兼容
  • 充分测试验证
  • 及时文档更新

4. 验证发布

  • 性能基准测试
  • 功能回归测试
  • 用户验收测试
  • 正式发布

重构收益

指标重构前重构后提升
代码复杂度2512-52%
测试覆盖率60%85%+42%
新增适配器时间2 天0.5 天-75%
Bug 数量/月155-67%

未来规划

V2.0 路线图

  • [ ] 插件化架构
  • [ ] 热配置更新
  • [ ] 多租户支持
  • [ ] GraphQL API
  • [ ] gRPC 支持

相关文档


更新日期: 2026-04-10 文档维护: JAiRouter Team