Architecture 架构详解

深入了解 GFramework 的核心架构设计和实现

概述

Architecture 是 GFramework 的核心类,负责管理整个应用的生命周期、组件注册和模块管理。从 v1.1.0 开始,Architecture 采用模块化设计,将职责分离到专门的协作者中。

命名约定:
ArchitectureServices 是公开的基础服务入口,负责容器、事件总线、命令执行器、查询执行器和服务模块管理
ArchitectureComponentRegistry 是内部组件注册器,专门负责 System / Model / Utility 的注册与生命周期接入
两者不是同一层职责,不要混用

设计目标

单一职责: 每个管理器只负责一个明确的功能
类型安全: 基于泛型的组件获取和注册
生命周期管理: 自动的初始化和销毁机制
可扩展性: 支持模块和钩子扩展
向后兼容: 保持公共 API 稳定

核心组件

Architecture (核心协调器)
    ├── ArchitectureBootstrapper (初始化基础设施编排)
    ├── ArchitectureLifecycle (生命周期管理)
    ├── ArchitectureComponentRegistry (组件注册)
    └── ArchitectureModules (模块管理)

架构设计

设计模式

Architecture 采用以下设计模式:

组合模式 (Composition): Architecture 组合多个内部协作者
委托模式 (Delegation): 方法调用委托给专门的管理器
协调器模式 (Coordinator): Architecture 作为协调器统一对外接口

类图

┌─────────────────────────────────────────────────────┐
│                   Architecture                       │
│  - _bootstrapper: ArchitectureBootstrapper          │
│  - _lifecycle: ArchitectureLifecycle                │
│  - _componentRegistry: ArchitectureComponentRegistry│
│  - _modules: ArchitectureModules                    │
│  - _logger: ILogger                                 │
│                                                     │
│  + RegisterSystem<T>()                              │
│  + RegisterModel<T>()                               │
│  + RegisterUtility<T>()                             │
│  + InstallModule()                                  │
│  + InitializeAsync()                                │
│  + DestroyAsync()                                   │
│  + event PhaseChanged                               │
└─────────────────────────────────────────────────────┘
         │                    │                    │                    │
         │                    │                    │                    │
         ▼                    ▼                    ▼                    ▼
┌──────────────┐   ┌──────────────────┐   ┌──────────────┐   ┌──────────────┐
│ Bootstrapper │   │ Lifecycle        │   │ComponentReg. │   │   Modules    │
│              │   │                  │   │              │   │              │
│ - 环境初始化  │   │ - 阶段管理        │   │ - System 注册│   │ - 模块安装    │
│ - 服务准备    │   │ - 钩子管理        │   │ - Model 注册 │   │ - 行为注册    │
│ - 上下文绑定  │   │ - 组件初始化      │   │ - Utility 注册│   │              │
│ - 容器冻结    │   │ - 就绪/销毁协调   │   │ - 生命周期接入│   │              │
└──────────────┘   └──────────────────┘   └──────────────┘   └──────────────┘

构造函数初始化

从 v1.1.0 开始,所有管理器在构造函数中初始化:

csharp

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);
}

优势:

消除 null! 断言,提高代码安全性
对象在构造后立即可用
符合"构造即完整"原则
可以在 InitializeAsync 之前访问事件

生命周期管理

架构阶段

Architecture 定义了 11 个生命周期阶段:

阶段	说明	触发时机
`None`	初始状态	构造函数完成后
`BeforeUtilityInit`	Utility 初始化前	开始初始化 Utility
`AfterUtilityInit`	Utility 初始化后	所有 Utility 初始化完成
`BeforeModelInit`	Model 初始化前	开始初始化 Model
`AfterModelInit`	Model 初始化后	所有 Model 初始化完成
`BeforeSystemInit`	System 初始化前	开始初始化 System
`AfterSystemInit`	System 初始化后	所有 System 初始化完成
`Ready`	就绪状态	所有组件初始化完成
`Destroying`	销毁中	开始销毁
`Destroyed`	已销毁	销毁完成
`FailedInitialization`	初始化失败	初始化过程中发生异常

阶段转换

正常流程:
None → BeforeUtilityInit → AfterUtilityInit → BeforeModelInit → AfterModelInit
     → BeforeSystemInit → AfterSystemInit → Ready → Destroying → Destroyed

异常流程:
Any → FailedInitialization

阶段事件

可以通过 PhaseChanged 事件监听阶段变化:

csharp

public class MyArchitecture : Architecture
{
    protected override void OnInitialize()
    {
        // 监听阶段变化
        PhaseChanged += phase =>
        {
            Console.WriteLine($"Phase changed to: {phase}");
        };
    }
}

生命周期钩子

实现 IArchitectureLifecycleHook 接口可以在阶段变化时执行自定义逻辑:

csharp

public class MyLifecycleHook : IArchitectureLifecycleHook
{
    public void OnPhase(ArchitecturePhase phase, IArchitecture architecture)
    {
        switch (phase)
        {
            case ArchitecturePhase.Ready:
                Console.WriteLine("Architecture is ready!");
                break;
            case ArchitecturePhase.Destroying:
                Console.WriteLine("Architecture is being destroyed!");
                break;
        }
    }
}

// 注册钩子
architecture.RegisterLifecycleHook(new MyLifecycleHook());

初始化流程

1. 创建 Architecture 实例
   └─> 构造函数初始化管理器

2. 调用 InitializeAsync() 或 Initialize()
   ├─> ArchitectureBootstrapper 准备基础设施
   │   ├─> 初始化环境 (Environment.Initialize())
   │   ├─> 注册内置服务模块
   │   ├─> 初始化架构上下文并绑定 GameContext
   │   ├─> 执行服务钩子
   │   └─> 初始化服务模块
   ├─> 调用 OnInitialize() (用户注册组件)
   ├─> 初始化所有组件
   │   ├─> BeforeUtilityInit → 初始化 Utility → AfterUtilityInit
   │   ├─> BeforeModelInit → 初始化 Model → AfterModelInit
   │   └─> BeforeSystemInit → 初始化 System → AfterSystemInit
   ├─> CompleteInitialization() 冻结 IoC 容器
   └─> 进入 Ready 阶段

3. 等待就绪 (可选)
   └─> await architecture.WaitUntilReadyAsync()

销毁流程

1. 调用 DestroyAsync() 或 Destroy()
   ├─> 检查当前阶段 (如果是 None 或已销毁则直接返回)
   ├─> 进入 Destroying 阶段
   ├─> 逆序销毁所有组件
   │   ├─> 优先调用 IAsyncDestroyable.DestroyAsync()
   │   └─> 否则调用 IDestroyable.Destroy()
   ├─> 销毁服务模块
   ├─> 进入 Destroyed 阶段
   └─> 清空 IoC 容器

版本: 1.1.0 更新日期: 2026-03-17 相关文档:

核心框架概述

Architecture 架构详解 ​

目录 ​

概述 ​

设计目标 ​

核心组件 ​

架构设计 ​

设计模式 ​

类图 ​

构造函数初始化 ​

生命周期管理 ​

架构阶段 ​

阶段转换 ​

阶段事件 ​

生命周期钩子 ​

初始化流程 ​

销毁流程 ​

Architecture 架构详解

目录

概述

设计目标

核心组件

架构设计

设计模式

类图

构造函数初始化

生命周期管理

架构阶段

阶段转换

阶段事件

生命周期钩子

初始化流程

销毁流程