v2.7.x Package 结构重组¶

版本系列：v2.7.0 - v2.7.8 完成日期：2026 年 4 月 28 日状态：已完成

一、概述¶

1.1 背景¶

v3.0.0 计划进行微服务架构转型。v2.7.x 版本完成了 Package 结构重组，将现有平铺式 package 结构重组为按服务模块分层结构，为微服务化做好准备。

1.2 目标¶

将代码按服务模块分组，每个模块对应未来一个微服务
建立清晰的服务边界定义
保持向后兼容，不破坏现有功能
所有测试保持通过

二、Package 结构变更¶

2.1 原结构（平铺式）¶

org.unreal.modelrouter/
├── adapter/          (~30 文件) 适配器
├── audit/            (~5 文件)  审计
├── checker/          (~5 文件)  检查器
├── circuitbreaker/   (~15 文件) 熔断器
├── cli/              (~3 文件)  命令行
├── config/           (~15 文件) 配置服务
├── constants/        (~5 文件)  常量
├── controller/       (~20 文件) 控制器
├── dto/              (~15 文件) DTO
├── entity/           (~5 文件)  实体
├── exception/        (~10 文件) 异常定义
├── exceptionhandler/ (~5 文件)  异常处理
├── factory/          (~5 文件)  工厂
├── fallback/         (~5 文件)  降级策略
├── filter/           (~10 文件) 过滤器
├── jpa/              (~15 文件) JPA 实体/仓库
├── loadbalancer/     (~15 文件) 负载均衡
├── model/            (~10 文件) 模型定义
├── monitoring/       (~25 文件) 监控指标
├── ratelimit/        (~10 文件) 限流器
├── repository/       (~5 文件)  仓库
├── sanitization/     (~5 文件)  脱敏服务
├── security/         (~40 文件) 安全认证
├── service/          (~15 文件) 业务服务
├── store/            (~20 文件) 状态存储
├── tracing/          (~20 文件) 链路追踪
├── util/             (~10 文件) 工具类
├── version/          (~10 文件) 版本管理
├── vo/               (~10 文件) VO

2.2 新结构（模块化）¶

org.unreal.modelrouter/
├── auth/             [认证服务]
│   ├── security/     JWT/ApiKey/Account/黑名单
│   ├── audit/        审计日志
│   └── controller/   认证相关控制器
│
├── config/           [配置服务]
│   ├── core/         ConfigurationService
│   ├── version/      版本管理
│   ├── sync/         配置同步
│   └── controller/   配置相关控制器
│
├── router/           [路由服务]
│   ├── adapter/      适配器实现
│   ├── loadbalancer/ 负载均衡
│   ├── circuitbreaker/ 熔断器
│   ├── ratelimit/    限流器
│   ├── fallback/     降级策略
│   ├── checker/      健康检查
│   ├── model/        路由模型
│   └── controller/   路由相关控制器
│
├── monitor/          [监控服务]
│   ├── tracing/      链路追踪
│   ├── monitoring/   监控指标
│   ├── error/        异常管理
│   └── controller/   监控相关控制器
│
├── persistence/      [持久化服务]
│   ├── store/        状态存储
│   ├── jpa/          JPA 实体/仓库
│   └── controller/   持久化控制器
│
├── common/           [公共基础设施]
│   ├── dto/          DTO
│   ├── vo/           VO
│   ├── model/        基础模型
│   ├── exception/    异常定义
│   ├── exceptionhandler/ 异常处理器
│   ├── util/         工具类
│   ├── filter/       过滤器
│   ├── constants/    常量定义
│   ├── sanitization/ 脱敏
│   ├── cli/          命令行
│   └── factory/      工厂
│
└── Application.java  主启动类

三、服务边界定义¶

服务	职责	核心组件	API 入口
auth	JWT认证、ApiKey管理、账户管理、审计日志	JwtService, ApiKeyService, AccountManager	/api/auth/, /api/jwt/, /api/api-keys/, /api/accounts/
config	配置管理、版本控制、配置持久化	ConfigurationService, VersionControl	/api/services/, /api/instances/, /api/versions/*
router	适配器管理、负载均衡、熔断器、限流器	BaseAdapter, LoadBalancer, CircuitBreaker	/api/chat/, /api/embeddings/, /api/rerank/*
monitor	链路追踪、监控指标、异常管理	TracingService, MetricsService	/api/tracing/, /api/monitoring/, /api/token-usage/*
persistence	状态存储、JPA实体、状态恢复	StatePersistence, JPA Entities	/internal/persistence/*
common	常量、DTO、VO、异常、工具、过滤器	Constants, DTOs, Utils	无（被其他服务引用）

四、版本执行记录¶

版本	日期	内容	文件迁移数
v2.7.0	2026-04-28	服务边界定义 + 目录创建	0
v2.7.1	2026-04-28	auth 模块迁移	106
v2.7.2	2026-04-28	config 模块迁移	33
v2.7.3	2026-04-28	router 模块迁移（adapter/loadbalancer）	34
v2.7.4	2026-04-28	router 模块迁移（circuitbreaker/ratelimit/fallback/checker）	28
v2.7.5	2026-04-28	monitor 模块迁移	100
v2.7.6	2026-04-28	persistence 模块迁移	50
v2.7.7	2026-04-28	common 模块迁移	100
v2.7.8	2026-04-28	controller 分组 + 验收	30

总迁移文件数: 487 个 Java 文件

五、迁移工具¶

5.1 迁移脚本¶

使用 scripts/migrate_package.py 脚本完成批量迁移：

# 示例：迁移 security 到 auth/security
python3 scripts/migrate_package.py \
  --source org.unreal.modelrouter.security \
  --target org.unreal.modelrouter.auth.security \
  --execute

5.2 脚本功能¶

批量移动 Java 文件
自动更新 package 声明
自动更新 import 语句
生成迁移报告

六、启动问题修复¶

迁移后发现并修复以下问题：

6.1 logback-spring.xml 类路径更新¶

<!-- 旧路径 -->
<appender class="org.unreal.modelrouter.tracing.logger.TracingLogbackAppender"/>

<!-- 新路径 -->
<appender class="org.unreal.modelrouter.monitor.tracing.logger.TracingLogbackAppender"/>

6.2 JPA Repository 扫描路径更新¶

// 旧路径
@EnableJpaRepositories(basePackages = "org.unreal.modelrouter.audit")

// 新路径
@EnableJpaRepositories(basePackages = "org.unreal.modelrouter.auth.audit")

6.3 Bean 冲突解决¶

多个 StatePersistenceService 实现冲突，使用 @Primary + @Qualifier 模式解决：

@Primary
@Service
public class CompositeStatePersistenceServiceImpl implements StatePersistenceService { ... }

// 消费者使用
@Qualifier("compositeStatePersistenceServiceImpl")
@Autowired
private StatePersistenceService statePersistenceService;

七、验收结果¶

7.1 编译验证¶

mvn clean package -DskipTests -Dcheckstyle.skip=true -Dspotbugs.skip=true
# 结果: BUILD SUCCESS

7.2 测试验证¶

mvn test
# 结果: 721 tests passed

7.3 启动验证¶

java -jar target/model-router-1.7.0.jar --server.port=8080
# 结果: Started ModelRouterApplication in 15.2 seconds
# Health: UP

八、后续计划¶

版本系列	时间	主题
v2.8.x	2026-05	配置文件整合
v2.9.x	2026-05	问题修复与梳理
v3.0.0	2026-06	微服务拆分

九、参考文档¶

服务边界定义：详见项目内部文档 innerdoc/03-重构记录/RFS-v2.7-服务边界定义.md
微服务化准备计划：详见项目内部文档 innerdoc/01-项目概述/v2.7-v2.9-微服务化准备开发计划.md