GFramework/docs/zh-CN/core/architecture.md

Architecture 架构详解

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

目录

• 概述
• 架构设计
• 生命周期管理
• 组件注册
• 模块系统
• 最佳实践
• API 参考

概述

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

设计目标

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

核心组件

Architecture (核心协调器)
    ├── ArchitectureLifecycle (生命周期管理)
    ├── ArchitectureComponentRegistry (组件注册)
    └── ArchitectureModules (模块管理)

架构设计

设计模式

Architecture 采用以下设计模式:

1. 组合模式 (Composition): Architecture 组合三个管理器
2. 委托模式 (Delegation): 方法调用委托给专门的管理器
3. 协调器模式 (Coordinator): Architecture 作为协调器统一对外接口

类图

┌─────────────────────────────────────────────────────┐
│                   Architecture                       │
│  - _lifecycle: ArchitectureLifecycle                │
│  - _componentRegistry: ArchitectureComponentRegistry│
│  - _modules: ArchitectureModules                    │
│  - _logger: ILogger                                 │
│                                                     │
│  + RegisterSystem<T>()                              │
│  + RegisterModel<T>()                               │
│  + RegisterUtility<T>()                             │
│  + InstallModule()                                  │
│  + InitializeAsync()                                │
│  + DestroyAsync()                                   │
│  + event PhaseChanged                               │
└─────────────────────────────────────────────────────┘
         │                    │                    │
         │                    │                    │
         ▼                    ▼                    ▼
┌──────────────┐   ┌──────────────────┐   ┌──────────────┐
│ Lifecycle    │   │ ComponentRegistry│   │   Modules    │
│              │   │                  │   │              │
│ - 阶段管理    │   │ - System 注册    │   │ - 模块安装    │
│ - 钩子管理    │   │ - Model 注册     │   │ - 行为注册    │
│ - 初始化      │   │ - Utility 注册   │   │              │
│ - 销毁        │   │ - 生命周期注册   │   │              │
└──────────────┘   └──────────────────┘   └──────────────┘

构造函数初始化

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

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

优势:

• 消除 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 事件监听阶段变化:

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

生命周期钩子

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

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()
   ├─> 初始化环境 (Environment.Initialize())
   ├─> 注册内置服务模块
   ├─> 初始化架构上下文
   ├─> 执行服务钩子
   ├─> 初始化服务模块
   ├─> 调用 OnInitialize() (用户注册组件)
   ├─> 初始化所有组件
   │   ├─> BeforeUtilityInit → 初始化 Utility → AfterUtilityInit
   │   ├─> BeforeModelInit → 初始化 Model → AfterModelInit
   │   └─> BeforeSystemInit → 初始化 System → AfterSystemInit
   ├─> 冻结 IoC 容器
   └─> 进入 Ready 阶段

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

销毁流程

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

---

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

• 核心框架概述
• ADR-001: 拆分 Architecture 核心类