mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-13 06:04:30 +08:00
110 lines
5.0 KiB
Markdown
110 lines
5.0 KiB
Markdown
# CQRS 重写迁移跟踪
|
||
|
||
## 目标
|
||
|
||
围绕 `GFramework` 当前的双轨 CQRS 现状，完成一轮以“去 Mediator 外部依赖”为目标的架构迁移：
|
||
|
||
- 将 `Mediator` 从 GFramework 公共 API 和运行时主路径中移除
|
||
- 基于 GFramework 自有抽象重建正式 CQRS runtime、行为管道和注册机制
|
||
- 保留 `EventBus` 作为框架级事件系统，不与 CQRS notification 混同
|
||
- 让 `CoreGrid-Migration` 直连本地 `GFramework`，作为真实迁移验证工程
|
||
- 为复杂迁移建立明确恢复点与进度追踪，避免上下文过长或中断后失去状态
|
||
|
||
## 当前恢复点
|
||
|
||
- 恢复点编号：`CQRS-REWRITE-RP-002`
|
||
- 当前阶段：`Phase 4`
|
||
- 当前焦点：
|
||
- 清理剩余 `Mediator` 包依赖与文档残留
|
||
- 评估是否继续把协程扩展和测试项目中的 `Mediator.Abstractions` 完全移除
|
||
- 规划第二阶段优化：代码生成注册、性能收敛、行为 API 命名统一
|
||
|
||
## 本轮计划
|
||
|
||
### Phase 0：工作流基础
|
||
|
||
- [x] 在 `local-plan/todos/` 建立本任务跟踪文档
|
||
- [x] 在 `local-plan/traces/` 建立本任务追踪文档
|
||
- [x] 将恢复点 / trace / subagent 协作规范写入 `AGENTS.md`
|
||
|
||
### Phase 1：本地验证链路
|
||
|
||
- [x] 确认 `CoreGrid-Migration` 当前引用形态
|
||
- [x] 将 `CoreGrid-Migration` 从 NuGet 包切到本地 `GFramework` 工程引用
|
||
- [x] 让 `CoreGrid-Migration` 使用本地 Source Generator 而不是外部已发布版本
|
||
- [x] 验证本地引用链路至少能完成 restore / build
|
||
|
||
### Phase 2：CQRS 基础重建
|
||
|
||
- [x] 在 `GFramework.Core.Abstractions` 定义自有 CQRS 契约
|
||
- [x] 在 `GFramework.Core` 落地 dispatcher / handler registry / behavior pipeline
|
||
- [x] 清理 `IArchitectureContext` 中对 `Mediator.*` 的公共签名依赖
|
||
- [x] 设计 CQRS 模块启用方式，替代 `Configurator => AddMediator(...)`
|
||
|
||
### Phase 3：接入迁移
|
||
|
||
- [x] 迁移 `GFramework.Core.Cqrs.*` 基类到新契约
|
||
- [x] 迁移 `ContextAwareMediator*Extensions` 与协程扩展
|
||
- [x] 迁移 `CoreGrid-Migration/scripts/cqrs/**` 到新契约
|
||
- [x] 删除 `GameArchitecture.Configurator` 中的 `AddMediator(...)`
|
||
|
||
### Phase 4：收尾
|
||
|
||
- [ ] 移除 `Mediator` 包依赖与相关测试/文档残留
|
||
- [x] 运行目标构建与测试
|
||
- [x] 记录剩余风险与下一恢复点
|
||
|
||
## 当前完成结果
|
||
|
||
- `CoreGrid-Migration` 已直连本地 `GFramework` 源码与本地 source generators。
|
||
- `GameArchitecture` 已不再依赖 `collection.AddMediator(...)` 即可使用 CQRS。
|
||
- `GFramework.Core.Abstractions` 新增自有 CQRS 契约：
|
||
- `IRequest<TResponse>` / `INotification` / `IStreamRequest<TResponse>`
|
||
- `IRequestHandler<,>` / `INotificationHandler<>` / `IStreamRequestHandler<,>`
|
||
- `Unit`
|
||
- `IPipelineBehavior<,>` / `MessageHandlerDelegate<,>`
|
||
- `ArchitectureBootstrapper` 会在初始化阶段自动扫描并注册当前架构程序集与 `GFramework.Core` 程序集中的 CQRS handlers。
|
||
- `CqrsDispatcher` 已支持：
|
||
- request dispatch
|
||
- notification publish
|
||
- stream dispatch
|
||
- context-aware handler 注入
|
||
- request pipeline behavior 链式执行
|
||
- `GFramework.Core.Tests` 中原依赖 `Mediator` 注册路径的测试已切换到框架内建 CQRS 注册路径。
|
||
- 当前验证状态：
|
||
- `dotnet build GFramework/GFramework.sln` 通过
|
||
- `dotnet test GFramework/GFramework.Core.Tests/GFramework.Core.Tests.csproj --no-build` 通过，`1621` 个测试全部通过
|
||
- `dotnet build CoreGrid-Migration/CoreGrid.sln` 通过
|
||
|
||
## 当前已知事实
|
||
|
||
- `GFramework` 当前仍同时维护：
|
||
- 基于 `CommandExecutor` / `QueryExecutor` / `EventBus` 的轻量旧 CQRS
|
||
- 基于 GFramework 自有抽象的新 CQRS runtime
|
||
- 仍存在 `Mediator` 残留的区域主要集中在：
|
||
- 文档中的历史说明
|
||
- `MediatorCoroutineExtensions` 及对应测试
|
||
- 测试项目对 `Mediator.Abstractions` 的少量残余依赖
|
||
- `CoreGrid-Migration` 已切到本地源码引用，并在当前恢复点完成构建验证
|
||
|
||
## 当前风险
|
||
|
||
- `GFramework` 仓库存在与本任务无关的既有改动，提交时必须避免覆盖
|
||
- `CoreGrid-Migration` 是 worktree，WSL 下原生 `git` 解析该 worktree 路径有兼容问题
|
||
- 当前 `RegisterMediatorBehavior` 命名仍保留历史前缀，但底层已切换为框架自有 CQRS pipeline；若后续要彻底脱媒介命名，需要一次 API 命名迁移
|
||
- 当前 handler 自动注册基于运行时反射扫描；若后续追求冷启动与 AOT 友好性，需要补 source-generator 注册路径
|
||
|
||
## 下次恢复建议
|
||
|
||
若本轮中断，优先从以下顺序恢复：
|
||
|
||
1. 查看 `local-plan/traces/cqrs-rewrite-migration-trace.md`
|
||
2. 确认当前恢复点 `CQRS-REWRITE-RP-002` 已对应到最新提交
|
||
3. 优先决定是否继续移除 `Mediator.Abstractions` 包与 `MediatorCoroutineExtensions` 历史兼容层
|
||
4. 若继续演进，再处理 CQRS 注册的生成器化与 API 命名统一
|
||
|
||
## 备注
|
||
|
||
- 本文档是当前任务的主恢复点，后续每个关键阶段完成后都要更新
|
||
- 发生方向调整时，不覆盖旧结论，直接追加阶段记录与新的恢复点编号
|