mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-08 17:44:29 +08:00
docs(core): 添加核心架构与CQRS模式详细文档
- 新增Architecture架构详解文档，包含设计目标、生命周期管理和组件注册等内容 - 新增CQRS与Mediator模式文档，详细介绍命令查询职责分离的实现方式 - 新增核心框架概述文档，提供完整的架构图和快速入门指南 - 完善架构组件联动说明，涵盖初始化、命令执行和事件传播流程 - 补充最佳实践指导，明确分层职责和通信方式选择原则
This commit is contained in:
GeWuYou
parent
bb2b3a0c60
commit
f7e05d19cc
@ -14,8 +14,13 @@
|
||||
|
||||
## 概述
|
||||
|
||||
Architecture 是 GFramework 的核心类,负责管理整个应用的生命周期、组件注册和模块管理。从 v1.1.0 开始,Architecture
|
||||
采用模块化设计,将职责分离到专门的管理器中。
|
||||
Architecture 是 GFramework 的核心类,负责管理整个应用的生命周期、组件注册和模块管理。从 v1.1.0 开始,Architecture
|
||||
采用模块化设计,将职责分离到专门的协作者中。
|
||||
|
||||
> 命名约定:
|
||||
> - `ArchitectureServices` 是公开的基础服务入口,负责容器、事件总线、命令执行器、查询执行器和服务模块管理
|
||||
> - `ArchitectureComponentRegistry` 是内部组件注册器,专门负责 System / Model / Utility 的注册与生命周期接入
|
||||
> - 两者不是同一层职责,不要混用
|
||||
|
||||
### 设计目标
|
||||
|
||||
@ -28,10 +33,11 @@ Architecture 是 GFramework 的核心类,负责管理整个应用的生命周期
|
||||
### 核心组件
|
||||
|
||||
```
|
||||
Architecture (核心协调器)
|
||||
├── ArchitectureLifecycle (生命周期管理)
|
||||
├── ArchitectureComponentRegistry (组件注册)
|
||||
└── ArchitectureModules (模块管理)
|
||||
Architecture (核心协调器)
|
||||
├── ArchitectureBootstrapper (初始化基础设施编排)
|
||||
├── ArchitectureLifecycle (生命周期管理)
|
||||
├── ArchitectureComponentRegistry (组件注册)
|
||||
└── ArchitectureModules (模块管理)
|
||||
```
|
||||
|
||||
## 架构设计
|
||||
@ -40,18 +46,19 @@ Architecture (核心协调器)
|
||||
|
||||
Architecture 采用以下设计模式:
|
||||
|
||||
1. **组合模式 (Composition)**: Architecture 组合三个管理器
|
||||
2. **委托模式 (Delegation)**: 方法调用委托给专门的管理器
|
||||
3. **协调器模式 (Coordinator)**: Architecture 作为协调器统一对外接口
|
||||
1. **组合模式 (Composition)**: Architecture 组合多个内部协作者
|
||||
2. **委托模式 (Delegation)**: 方法调用委托给专门的管理器
|
||||
3. **协调器模式 (Coordinator)**: Architecture 作为协调器统一对外接口
|
||||
|
||||
### 类图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Architecture │
|
||||
│ - _lifecycle: ArchitectureLifecycle │
|
||||
│ - _componentRegistry: ArchitectureComponentRegistry│
|
||||
│ - _modules: ArchitectureModules │
|
||||
│ Architecture │
|
||||
│ - _bootstrapper: ArchitectureBootstrapper │
|
||||
│ - _lifecycle: ArchitectureLifecycle │
|
||||
│ - _componentRegistry: ArchitectureComponentRegistry│
|
||||
│ - _modules: ArchitectureModules │
|
||||
│ - _logger: ILogger │
|
||||
│ │
|
||||
│ + RegisterSystem<T>() │
|
||||
@ -62,17 +69,17 @@ Architecture 采用以下设计模式:
|
||||
│ + DestroyAsync() │
|
||||
│ + event PhaseChanged │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│ │ │
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||||
│ Lifecycle │ │ ComponentRegistry│ │ Modules │
|
||||
│ │ │ │ │ │
|
||||
│ - 阶段管理 │ │ - System 注册 │ │ - 模块安装 │
|
||||
│ - 钩子管理 │ │ - Model 注册 │ │ - 行为注册 │
|
||||
│ - 初始化 │ │ - Utility 注册 │ │ │
|
||||
│ - 销毁 │ │ - 生命周期注册 │ │ │
|
||||
└──────────────┘ └──────────────────┘ └──────────────┘
|
||||
│ │ │ │
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Bootstrapper │ │ Lifecycle │ │ComponentReg. │ │ Modules │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ - 环境初始化 │ │ - 阶段管理 │ │ - System 注册│ │ - 模块安装 │
|
||||
│ - 服务准备 │ │ - 钩子管理 │ │ - Model 注册 │ │ - 行为注册 │
|
||||
│ - 上下文绑定 │ │ - 组件初始化 │ │ - Utility 注册│ │ │
|
||||
│ - 容器冻结 │ │ - 就绪/销毁协调 │ │ - 生命周期接入│ │ │
|
||||
└──────────────┘ └──────────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
### 构造函数初始化
|
||||
@ -80,27 +87,28 @@ Architecture 采用以下设计模式:
|
||||
从 v1.1.0 开始,所有管理器在构造函数中初始化:
|
||||
|
||||
```csharp
|
||||
protected Architecture(
|
||||
IArchitectureConfiguration? configuration = null,
|
||||
IEnvironment? environment = null,
|
||||
IArchitectureServices? services = null,
|
||||
IArchitectureContext? context = null)
|
||||
{
|
||||
Configuration = configuration ?? new ArchitectureConfiguration();
|
||||
Environment = environment ?? new DefaultEnvironment();
|
||||
Services = services ?? new ArchitectureServices();
|
||||
_context = context;
|
||||
|
||||
// 初始化 Logger
|
||||
LoggerFactoryResolver.Provider = Configuration.LoggerProperties.LoggerFactoryProvider;
|
||||
_logger = LoggerFactoryResolver.Provider.CreateLogger(GetType().Name);
|
||||
|
||||
// 初始化管理器
|
||||
_lifecycle = new ArchitectureLifecycle(this, Configuration, Services, _logger);
|
||||
_componentRegistry = new ArchitectureComponentRegistry(this, Configuration, Services, _lifecycle, _logger);
|
||||
_modules = new ArchitectureModules(this, Services, _logger);
|
||||
}
|
||||
```
|
||||
protected Architecture(
|
||||
IArchitectureConfiguration? configuration = null,
|
||||
IEnvironment? environment = null,
|
||||
IArchitectureServices? services = null,
|
||||
IArchitectureContext? context = null)
|
||||
{
|
||||
var resolvedConfiguration = configuration ?? new ArchitectureConfiguration();
|
||||
var resolvedEnvironment = environment ?? new DefaultEnvironment();
|
||||
var resolvedServices = services ?? new ArchitectureServices();
|
||||
_context = context;
|
||||
|
||||
// 初始化 Logger
|
||||
LoggerFactoryResolver.Provider = resolvedConfiguration.LoggerProperties.LoggerFactoryProvider;
|
||||
_logger = LoggerFactoryResolver.Provider.CreateLogger(GetType().Name);
|
||||
|
||||
// 初始化协作者
|
||||
_bootstrapper = new ArchitectureBootstrapper(GetType(), resolvedEnvironment, resolvedServices, _logger);
|
||||
_lifecycle = new ArchitectureLifecycle(this, resolvedConfiguration, resolvedServices, _logger);
|
||||
_componentRegistry = new ArchitectureComponentRegistry(this, resolvedConfiguration, resolvedServices, _lifecycle, _logger);
|
||||
_modules = new ArchitectureModules(this, resolvedServices, _logger);
|
||||
}
|
||||
```
|
||||
|
||||
**优势**:
|
||||
|
||||
@ -189,15 +197,16 @@ architecture.RegisterLifecycleHook(new MyLifecycleHook());
|
||||
1. 创建 Architecture 实例
|
||||
└─> 构造函数初始化管理器
|
||||
|
||||
2. 调用 InitializeAsync() 或 Initialize()
|
||||
├─> 初始化环境 (Environment.Initialize())
|
||||
├─> 注册内置服务模块
|
||||
├─> 初始化架构上下文
|
||||
├─> 执行服务钩子
|
||||
├─> 初始化服务模块
|
||||
├─> 调用 OnInitialize() (用户注册组件)
|
||||
├─> 初始化所有组件
|
||||
│ ├─> BeforeUtilityInit → 初始化 Utility → AfterUtilityInit
|
||||
2. 调用 InitializeAsync() 或 Initialize()
|
||||
├─> ArchitectureBootstrapper 准备基础设施
|
||||
│ ├─> 初始化环境 (Environment.Initialize())
|
||||
│ ├─> 注册内置服务模块
|
||||
│ ├─> 初始化架构上下文并绑定 GameContext
|
||||
│ ├─> 执行服务钩子
|
||||
│ └─> 初始化服务模块
|
||||
├─> 调用 OnInitialize() (用户注册组件)
|
||||
├─> 初始化所有组件
|
||||
│ ├─> BeforeUtilityInit → 初始化 Utility → AfterUtilityInit
|
||||
│ ├─> BeforeModelInit → 初始化 Model → AfterModelInit
|
||||
│ └─> BeforeSystemInit → 初始化 System → AfterSystemInit
|
||||
├─> 冻结 IoC 容器
|
||||
|
||||
@ -216,15 +216,20 @@ public class GameArchitecture : Architecture
|
||||
{
|
||||
protected override void Init()
|
||||
{
|
||||
// 注册 Mediator 行为
|
||||
RegisterMediatorBehavior<LoggingBehavior>();
|
||||
RegisterMediatorBehavior<PerformanceBehavior>();
|
||||
// 注册通用开放泛型行为
|
||||
RegisterMediatorBehavior<LoggingBehavior<,>>();
|
||||
RegisterMediatorBehavior<PerformanceBehavior<,>>();
|
||||
|
||||
// 处理器会自动通过依赖注入注册
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`RegisterMediatorBehavior<TBehavior>()` 同时支持两种形式：
|
||||
|
||||
- 开放泛型行为，例如 `LoggingBehavior<,>`，用于匹配所有请求
|
||||
- 封闭行为类型，例如某个只服务于单一请求的 `SpecialBehavior`
|
||||
|
||||
## 高级用法
|
||||
|
||||
### Request（请求）
|
||||
|
||||
@ -319,7 +319,7 @@ public class PlayerController : IController
|
||||
|
||||
### Architecture 内部结构 (v1.1.0+)
|
||||
|
||||
从 v1.1.0 开始,Architecture 类采用模块化设计,将原本 708 行的单一类拆分为 4 个职责清晰的类:
|
||||
从 v1.1.0 开始,Architecture 类采用模块化设计,将原本 708 行的单一类拆分为多个职责清晰的协作者:
|
||||
|
||||
#### 1. Architecture (核心协调器)
|
||||
|
||||
@ -338,10 +338,21 @@ public class PlayerController : IController
|
||||
|
||||
- `PhaseChanged` - 阶段变更事件
|
||||
|
||||
#### 2. ArchitectureLifecycle (生命周期管理器)
|
||||
|
||||
**职责**: 管理架构的生命周期和阶段转换
|
||||
|
||||
#### 2. ArchitectureBootstrapper (初始化基础设施编排器)
|
||||
|
||||
**职责**: 在用户 `OnInitialize()` 执行前准备环境、服务和上下文
|
||||
|
||||
**核心功能**:
|
||||
|
||||
- 初始化环境对象
|
||||
- 注册内置服务模块
|
||||
- 绑定架构上下文到 `GameContext`
|
||||
- 执行服务钩子并冻结 IoC 容器
|
||||
|
||||
#### 3. ArchitectureLifecycle (生命周期管理器)
|
||||
|
||||
**职责**: 管理架构的生命周期和阶段转换
|
||||
|
||||
**核心功能**:
|
||||
|
||||
- 11 个架构阶段的管理和转换
|
||||
@ -355,11 +366,11 @@ public class PlayerController : IController
|
||||
- `EnterPhase()` - 进入指定阶段
|
||||
- `RegisterLifecycleHook()` - 注册生命周期钩子
|
||||
- `InitializeAllComponentsAsync()` - 初始化所有组件
|
||||
- `DestroyAsync()` - 异步销毁
|
||||
|
||||
#### 3. ArchitectureComponentRegistry (组件注册管理器)
|
||||
|
||||
**职责**: 管理 System、Model、Utility 的注册
|
||||
- `DestroyAsync()` - 异步销毁
|
||||
|
||||
#### 4. ArchitectureComponentRegistry (组件注册管理器)
|
||||
|
||||
**职责**: 管理 System、Model、Utility 的注册
|
||||
|
||||
**核心功能**:
|
||||
|
||||
@ -370,11 +381,14 @@ public class PlayerController : IController
|
||||
|
||||
**关键方法**:
|
||||
|
||||
- `RegisterSystem<T>()` - 注册系统
|
||||
- `RegisterModel<T>()` - 注册模型
|
||||
- `RegisterUtility<T>()` - 注册工具
|
||||
|
||||
#### 4. ArchitectureModules (模块管理器)
|
||||
- `RegisterSystem<T>()` - 注册系统
|
||||
- `RegisterModel<T>()` - 注册模型
|
||||
- `RegisterUtility<T>()` - 注册工具
|
||||
|
||||
> 命名提醒: 公开的 `ArchitectureServices` 负责容器和基础服务,并不承担组件注册职责。
|
||||
> `ArchitectureComponentRegistry` 才是内部的 System / Model / Utility 注册器。
|
||||
|
||||
#### 5. ArchitectureModules (模块管理器)
|
||||
|
||||
**职责**: 管理架构模块和中介行为
|
||||
|
||||
@ -429,16 +443,18 @@ public class PlayerController : IController
|
||||
### 1. 初始化流程
|
||||
|
||||
```
|
||||
创建 Architecture 实例
|
||||
└─> 构造函数
|
||||
├─> 初始化 Logger
|
||||
├─> 创建 ArchitectureLifecycle
|
||||
├─> 创建 ArchitectureComponentRegistry
|
||||
└─> 创建 ArchitectureModules
|
||||
└─> InitializeAsync()
|
||||
├─> OnInitialize() (用户注册组件)
|
||||
│ ├─> RegisterModel → Model.SetContext()
|
||||
│ ├─> RegisterSystem → System.SetContext()
|
||||
创建 Architecture 实例
|
||||
└─> 构造函数
|
||||
├─> 初始化 Logger
|
||||
├─> 创建 ArchitectureBootstrapper
|
||||
├─> 创建 ArchitectureLifecycle
|
||||
├─> 创建 ArchitectureComponentRegistry
|
||||
└─> 创建 ArchitectureModules
|
||||
└─> InitializeAsync()
|
||||
├─> Bootstrapper 准备环境/服务/上下文
|
||||
├─> OnInitialize() (用户注册组件)
|
||||
│ ├─> RegisterModel → Model.SetContext()
|
||||
│ ├─> RegisterSystem → System.SetContext()
|
||||
│ └─> RegisterUtility → 注册到容器
|
||||
└─> InitializeAllComponentsAsync()
|
||||
├─> BeforeUtilityInit → Utility.Initialize()
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user