diff --git a/docs/zh-CN/core/architecture.md b/docs/zh-CN/core/architecture.md index 90b5c341..12007e4d 100644 --- a/docs/zh-CN/core/architecture.md +++ b/docs/zh-CN/core/architecture.md @@ -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() │ @@ -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 容器 diff --git a/docs/zh-CN/core/cqrs.md b/docs/zh-CN/core/cqrs.md index f1f3801a..d0cf0f9e 100644 --- a/docs/zh-CN/core/cqrs.md +++ b/docs/zh-CN/core/cqrs.md @@ -216,15 +216,20 @@ public class GameArchitecture : Architecture { protected override void Init() { - // 注册 Mediator 行为 - RegisterMediatorBehavior(); - RegisterMediatorBehavior(); + // 注册通用开放泛型行为 + RegisterMediatorBehavior>(); + RegisterMediatorBehavior>(); // 处理器会自动通过依赖注入注册 } } ``` +`RegisterMediatorBehavior()` 同时支持两种形式： + +- 开放泛型行为，例如 `LoggingBehavior<,>`，用于匹配所有请求 +- 封闭行为类型，例如某个只服务于单一请求的 `SpecialBehavior` + ## 高级用法 ### Request（请求） diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index a61cfb37..950c7100 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -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()` - 注册系统 -- `RegisterModel()` - 注册模型 -- `RegisterUtility()` - 注册工具 - -#### 4. ArchitectureModules (模块管理器) +- `RegisterSystem()` - 注册系统 +- `RegisterModel()` - 注册模型 +- `RegisterUtility()` - 注册工具 + +> 命名提醒: 公开的 `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()