gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-26 06:16:43 +08:00
Code Issues Packages Projects Releases Wiki Activity
GFramework/.qoder/repowiki/zh/content/核心架构模块/架构管理系统/初始化流程.md
GeWuYou a79f02c987 docs(api): 添加 Core API 参考文档与事件系统接口文档 
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件
- 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明
- 提供完整的 API 使用示例路径、最佳实践与性能建议
- 包含架构图、依赖关系图与故障排查指南
- 添加测试用例参考与扩展方法说明
- [skip ci]
2026-01-21 23:45:10 +08:00

25 KiB
Raw Blame History

初始化流程

**本文引用的文件** - [GFramework.Core/architecture/Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [GFramework.Core/architecture/ArchitectureContext.cs](file://GFramework.Core/architecture/ArchitectureContext.cs) - [GFramework.Core/architecture/ArchitectureConfiguration.cs](file://GFramework.Core/architecture/ArchitectureConfiguration.cs) - [GFramework.Core/architecture/ArchitectureConstants.cs](file://GFramework.Core/architecture/ArchitectureConstants.cs) - [GFramework.Core.Abstractions/architecture/IArchitecture.cs](file://GFramework.Core.Abstractions/architecture/IArchitecture.cs) - [GFramework.Core.Abstractions/architecture/IAsyncInitializable.cs](file://GFramework.Core.Abstractions/architecture/IAsyncInitializable.cs) - [GFramework.Core.Abstractions/enums/ArchitecturePhase.cs](file://GFramework.Core.Abstractions/enums/ArchitecturePhase.cs) - [GFramework.Core/events/ArchitectureEvents.cs](file://GFramework.Core/events/ArchitectureEvents.cs) - [GFramework.Core.Tests/architecture/TestArchitectureBase.cs](file://GFramework.Core.Tests/architecture/TestArchitectureBase.cs) - [GFramework.Core.Tests/architecture/AsyncTestArchitecture.cs](file://GFramework.Core.Tests/architecture/AsyncTestArchitecture.cs) - [GFramework.Core.Tests/architecture/SyncTestArchitecture.cs](file://GFramework.Core.Tests/architecture/SyncTestArchitecture.cs) - [GFramework.Core.Tests/model/AsyncTestModel.cs](file://GFramework.Core.Tests/model/AsyncTestModel.cs) - [GFramework.Core.Tests/system/AsyncTestSystem.cs](file://GFramework.Core.Tests/system/AsyncTestSystem.cs)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件聚焦于 GFramework 的架构初始化流程，系统性解析以下主题：

  • Initialize 与 InitializeAsync 的区别及适用场景
  • InitializeInternalAsync 的完整初始化步骤与阶段划分
  • 基础环境设置、架构上下文初始化、用户自定义初始化、组件初始化分组、容器冻结与就绪通知
  • 异步初始化模式（asyncMode）的选择与 IAsyncInitializable 接口支持
  • 初始化失败处理机制与 ArchitecturePhase.FailedInitialization 的触发条件
  • 初始化流程时序图与同步/异步最佳实践示例

项目结构

围绕初始化流程的关键代码分布在以下模块：

  • 核心架构与上下文：Architecture、ArchitectureContext
  • 架构阶段与常量：ArchitecturePhase、ArchitectureConstants
  • 配置与事件：ArchitectureConfiguration、ArchitectureEvents
  • 接口契约：IArchitecture、IAsyncInitializable
  • 测试样例：TestArchitectureBase、AsyncTestArchitecture、SyncTestArchitecture、AsyncTestModel、AsyncTestSystem
graph TB
subgraph "核心"
A["Architecture<br/>初始化入口与流程控制"]
Ctx["ArchitectureContext<br/>服务与组件访问"]
Conf["ArchitectureConfiguration<br/>日志与架构属性"]
Const["ArchitectureConstants<br/>阶段顺序与转换"]
Phase["ArchitecturePhase<br/>阶段枚举"]
Events["ArchitectureEvents<br/>生命周期事件"]
end
subgraph "接口"
IA["IArchitecture<br/>架构接口"]
IAI["IAsyncInitializable<br/>异步初始化接口"]
end
subgraph "测试"
TBase["TestArchitectureBase<br/>测试基类"]
TA["AsyncTestArchitecture<br/>异步架构"]
TS["SyncTestArchitecture<br/>同步架构"]
TM["AsyncTestModel<br/>异步模型"]
TSys["AsyncTestSystem<br/>异步系统"]
end
IA --> A
IAI --> A
A --> Ctx
A --> Conf
A --> Const
A --> Phase
A --> Events
TBase --> A
TA --> TBase
TS --> TBase
TM --> IAI
TSys --> IAI

图表来源

章节来源

核心组件

  • Architecture：提供 Initialize/InitializeAsync 入口，驱动 InitializeInternalAsync 完成初始化；负责阶段推进、事件通知、组件注册与销毁。
  • ArchitectureContext：基于 IOC 容器的服务缓存与组件检索，封装命令/查询/事件的派发。
  • ArchitectureConfiguration：默认日志工厂与架构属性（如是否允许后期注册、是否严格阶段校验）。
  • ArchitectureConstants：阶段顺序与允许的阶段转换映射，定义 FailedInitialization 的“任意可达”特性。
  • IArchitecture：继承 IAsyncInitializable，暴露 Initialize/Destroy、组件注册与模块安装等能力。
  • IAsyncInitializable：定义 InitializeAsync 异步初始化契约。
  • ArchitecturePhase：线性阶段序列，贯穿初始化与销毁全过程。
  • ArchitectureEvents：初始化就绪、销毁中/完成、初始化失败等事件。

章节来源

架构总览

初始化流程由两条主线构成：

  • 同步初始化：Initialize 内部通过阻塞等待 InitializeInternalAsync 完成，随后抛出失败阶段或继续。
  • 异步初始化：InitializeAsync 直接 await InitializeInternalAsync，便于在 UI 线程或协程中挂起等待。

初始化主流程分为四个阶段：

  1. 基础环境与上下文设置
  2. 用户 Init 自定义初始化
  3. 组件初始化分组（工具/模型/系统）
  4. 容器冻结与就绪通知
sequenceDiagram
participant Caller as "调用方"
participant Arch as "Architecture"
participant Ctx as "ArchitectureContext"
participant Cfg as "ArchitectureConfiguration"
participant Const as "ArchitectureConstants"
participant Bus as "事件总线"
Caller->>Arch : "Initialize()/InitializeAsync()"
Arch->>Arch : "InitializeInternalAsync(asyncMode)"
Arch->>Cfg : "读取日志与架构属性"
Arch->>Arch : "Environment.Initialize()"
Arch->>Ctx : "创建/绑定上下文"
Arch->>Arch : "Services.SetContext(ctx)"
Arch->>Arch : "Init()用户自定义"
Arch->>Arch : "InitializeAllComponentsAsync(asyncMode)"
Arch->>Arch : "EnterPhase(Ready)"
Arch->>Bus : "发送就绪事件"
Arch-->>Caller : "完成/抛出异常"

图表来源

详细组件分析

Initialize 与 InitializeAsync 的区别与使用场景

  • Initialize
    • 语义：阻塞式同步初始化，适合控制台应用或可安全阻塞的场景。
    • 实现：内部通过 GetAwaiter().GetResult() 等待 InitializeInternalAsync 完成，若异常则进入 FailedInitialization 并抛出。
  • InitializeAsync
    • 语义：非阻塞式异步初始化，适合 Unity 主线程协程、UI 线程或需要并发控制的场景。
    • 实现：直接 await InitializeInternalAsync，异常同上处理。

章节来源

InitializeInternalAsync 的完整步骤

  • 基础环境与上下文设置
    • 设置日志工厂提供程序与最小日志级别
    • 初始化 Environment
    • 创建/绑定 ArchitectureContext，设置 Services.Context
  • 用户 Init
    • 调用受保护的 Init()，由子类实现注册组件与自定义逻辑
  • 组件初始化分组
    • 工具（IContextUtility）、模型（IModel）、系统（ISystem）三类分组初始化
    • 每组在 Before*/After* 阶段间执行，支持异步/同步初始化
  • 初始化完成
    • 冻结 IOC 容器，标记已初始化
    • 进入 Ready 阶段，发布 ArchitectureLifecycleReadyEvent

章节来源

组件初始化分组与阶段推进

  • 分组策略
    • 工具：IContextUtility，先 AfterUtilityInit 再 BeforeModelInit
    • 模型：IModel，先 AfterModelInit 再 BeforeSystemInit
    • 系统：ISystem，最后 AfterSystemInit
  • 阶段推进
    • 每个分组前后均进入对应 Before*/After* 阶段
    • 严格线性顺序，受 ArchitectureConstants 控制
  • 异步支持
    • asyncMode=true 且组件实现 IAsyncInitializable 时调用 InitializeAsync
    • 否则调用 Init()
flowchart TD
Start(["开始 InitializeInternalAsync"]) --> Env["设置日志与环境<br/>创建/绑定上下文"]
Env --> UserInit["调用用户 Init()"]
UserInit --> Group["分组初始化：工具/模型/系统"]
Group --> Freeze["冻结 IOC 容器"]
Freeze --> Ready["进入 Ready 阶段并发布就绪事件"]
Ready --> End(["结束"])
subgraph "分组初始化"
U["工具：BeforeUtilityInit → AfterUtilityInit"]
M["模型：BeforeModelInit → AfterModelInit"]
S["系统：BeforeSystemInit → AfterSystemInit"]
end
Group --> U --> M --> S

图表来源

章节来源

异步初始化模式（asyncMode）与 IAsyncInitializable 支持

  • asyncMode 选择
    • true：优先尝试 IAsyncInitializable.InitializeAsync
    • false：回退到 IInitializable.Init
  • IAsyncInitializable
    • 作为 IArchitecture 的父接口，保证架构自身具备异步初始化能力
    • 组件若实现该接口，将在 InitializeAllComponentsAsync 中被识别并异步初始化

章节来源

初始化失败处理与 FailedInitialization 触发

  • 触发条件
    • Initialize/InitializeAsync 在执行 InitializeInternalAsync 期间抛出异常
  • 处理流程
    • 记录错误日志
    • 进入 ArchitecturePhase.FailedInitialization
    • 发布 ArchitectureFailedInitializationEvent
    • 重新抛出异常
  • 阶段特性
    • FailedInitialization 可从任意阶段转换而来，便于兜底恢复

章节来源

阶段推进与事件通知

  • EnterPhase
    • 校验阶段转换合法性（受 ArchitectureProperties.StrictPhaseValidation 控制）
    • 通知生命周期钩子与架构阶段感知对象
  • ArchitectureConstants
    • 定义线性阶段顺序与允许转换
    • FailedInitialization 作为“任意可达”的失败路径

章节来源

使用示例与最佳实践

章节来源

依赖分析

  • Architecture 对各子系统（环境、上下文、服务、事件总线、IOC 容器）存在强耦合，负责统一调度
  • 组件注册遵循生命周期：先注册到 IOC，再登记到待初始化队列，最后在 Ready 前完成初始化
  • 阶段推进依赖 ArchitectureConstants 的线性约束，FailedInitialization 作为兜底路径
graph LR
Arch["Architecture"] --> Ctx["ArchitectureContext"]
Arch --> Env["Environment"]
Arch --> Svc["Services"]
Arch --> Bus["EventBus"]
Arch --> Cfg["ArchitectureConfiguration"]
Arch --> Const["ArchitectureConstants"]
Arch --> Phase["ArchitecturePhase"]
Arch --> IA["IArchitecture"]
Arch --> IAI["IAsyncInitializable"]

图表来源

章节来源

性能考虑

  • 组件分组初始化按类型顺序执行，避免跨类型依赖导致的死锁
  • InitializeAllComponentsAsync 在每组内串行初始化，保证依赖顺序；如需并行，可在组件内部自行拆分子任务
  • IOC 容器在 Ready 前冻结，有助于减少后续解析开销
  • 日志级别与工厂提供程序可通过 ArchitectureConfiguration 调整，避免过度日志影响性能

故障排查指南

章节来源

结论

GFramework 的初始化流程以 Architecture 为核心，通过 Initialize/InitializeAsync 提供同步与异步两种模式，借助 ArchitectureContext、ArchitectureConfiguration、ArchitectureConstants 与 ArchitecturePhase 形成清晰的生命周期与阶段控制。InitializeInternalAsync 将初始化拆解为基础环境设置、用户 Init、组件分组初始化与容器冻结四个阶段，既保证了初始化顺序与一致性，又通过 IAsyncInitializable 支持异步组件。失败路径通过 FailedInitialization 与事件机制提供兜底，便于上层进行恢复与诊断。

附录

  • 关键接口与职责
    • IArchitecture：架构入口与生命周期管理
    • IAsyncInitializable：异步初始化契约
    • ArchitecturePhase：阶段枚举与线性顺序
    • ArchitectureEvents：生命周期事件
  • 测试参考
    • 同步/异步架构与组件示例，便于对照验证初始化行为

章节来源