mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-25 21:34:28 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
22 KiB
22 KiB
生命周期管理
**本文引用的文件** - [Architecture.cs](file://GFramework.Core/architecture/Architecture.cs) - [IArchitectureLifecycle.cs](file://GFramework.Core.Abstractions/architecture/IArchitectureLifecycle.cs) - [IArchitecturePhaseAware.cs](file://GFramework.Core.Abstractions/architecture/IArchitecturePhaseAware.cs) - [ArchitecturePhase.cs](file://GFramework.Core.Abstractions/enums/ArchitecturePhase.cs) - [ArchitectureConstants.cs](file://GFramework.Core/architecture/ArchitectureConstants.cs) - [ArchitectureConfiguration.cs](file://GFramework.Core/architecture/ArchitectureConfiguration.cs) - [ArchitectureContext.cs](file://GFramework.Core/architecture/ArchitectureContext.cs) - [IArchitecture.cs](file://GFramework.Core.Abstractions/architecture/IArchitecture.cs) - [IInitializable.cs](file://GFramework.Core.Abstractions/lifecycle/IInitializable.cs) - [ILifecycle.cs](file://GFramework.Core.Abstractions/lifecycle/ILifecycle.cs) - [ArchitectureConstantsTests.cs](file://GFramework.Core.Tests/architecture/ArchitectureConstantsTests.cs) - [ArchitectureConfigurationTests.cs](file://GFramework.Core.Tests/architecture/ArchitectureConfigurationTests.cs) - [TestArchitectureBase.cs](file://GFramework.Core.Tests/architecture/TestArchitectureBase.cs) - [README.md](file://GFramework.Core/architecture/README.md)目录
简介
本文件聚焦于GFramework的架构生命周期管理，围绕EnterPhase方法的实现机制展开，深入解析阶段转换验证、阶段变更通知、阶段感知对象处理，以及生命周期钩子注册与IArchitectureLifecycle接口的实现要求。同时，详细说明ValidatePhaseTransition的阶段转换规则与StrictPhaseValidation配置的作用，解释NotifyPhase与NotifyPhaseAwareObjects的通知流程，并介绍架构阶段枚举ArchitecturePhase与阶段常量定义。最后提供生命周期管理的完整流程图与实际使用示例，包含错误处理与调试技巧。
项目结构
生命周期管理主要位于核心库的architecture目录下，配合抽象层接口与测试用例共同构成完整的生命周期体系：
- 核心实现：Architecture.cs（生命周期入口、阶段转换、通知、注册）
- 接口定义：IArchitectureLifecycle.cs、IArchitecturePhaseAware.cs、IArchitecture.cs
- 枚举与常量：ArchitecturePhase.cs、ArchitectureConstants.cs
- 配置与上下文：ArchitectureConfiguration.cs、ArchitectureContext.cs
- 生命周期接口：IInitializable.cs、ILifecycle.cs
- 测试与示例：ArchitectureConstantsTests.cs、ArchitectureConfigurationTests.cs、TestArchitectureBase.cs、README.md
graph TB
subgraph "核心实现"
A["Architecture.cs"]
C["ArchitectureConstants.cs"]
K["ArchitectureConfiguration.cs"]
X["ArchitectureContext.cs"]
end
subgraph "抽象接口"
L["IArchitectureLifecycle.cs"]
P["IArchitecturePhaseAware.cs"]
I["IArchitecture.cs"]
E["ArchitecturePhase.cs"]
Z["IInitializable.cs"]
Y["ILifecycle.cs"]
end
subgraph "测试与示例"
T1["ArchitectureConstantsTests.cs"]
T2["ArchitectureConfigurationTests.cs"]
T3["TestArchitectureBase.cs"]
R["README.md"]
end
A --> C
A --> K
A --> X
A --> L
A --> P
A --> E
A --> Z
A --> Y
I --> A
T1 --> C
T2 --> K
T3 --> A
R --> A
图表来源
- Architecture.cs
- ArchitectureConstants.cs
- ArchitectureConfiguration.cs
- ArchitectureContext.cs
- IArchitectureLifecycle.cs
- IArchitecturePhaseAware.cs
- IArchitecture.cs
- ArchitecturePhase.cs
- IInitializable.cs
- ILifecycle.cs
- ArchitectureConstantsTests.cs
- ArchitectureConfigurationTests.cs
- TestArchitectureBase.cs
- README.md
章节来源
- Architecture.cs
- ArchitectureConstants.cs
- ArchitectureConfiguration.cs
- ArchitectureContext.cs
- IArchitectureLifecycle.cs
- IArchitecturePhaseAware.cs
- IArchitecture.cs
- ArchitecturePhase.cs
- IInitializable.cs
- ILifecycle.cs
- ArchitectureConstantsTests.cs
- ArchitectureConfigurationTests.cs
- TestArchitectureBase.cs
- README.md
核心组件
- EnterPhase：进入指定架构阶段的核心方法，负责阶段转换验证、阶段变更记录与通知。
- ValidatePhaseTransition：阶段转换规则校验，受StrictPhaseValidation影响。
- NotifyPhase：通知所有生命周期钩子当前阶段。
- NotifyPhaseAwareObjects：通知所有IArchitecturePhaseAware对象阶段变更。
- RegisterLifecycleHook：注册生命周期钩子，受AllowLateRegistration限制。
- ArchitecturePhase：阶段枚举，定义线性生命周期序列。
- ArchitectureConstants：阶段常量与转换规则定义。
- ArchitectureConfiguration：默认配置，含StrictPhaseValidation与AllowLateRegistration。
- ArchitectureContext：上下文服务访问与事件总线集成点。
章节来源
架构总览
生命周期管理采用“线性状态机”模式，阶段按固定顺序推进。EnterPhase作为入口，先进行转换验证，再更新CurrentPhase，随后通知生命周期钩子与阶段感知对象。初始化流程贯穿工具、模型、系统三类组件，最终进入Ready并冻结容器。
sequenceDiagram
participant Client as "调用方"
participant Arch as "Architecture"
participant Cfg as "Configuration"
participant Const as "ArchitectureConstants"
participant Hooks as "生命周期钩子"
participant Aware as "阶段感知对象"
Client->>Arch : "EnterPhase(next)"
Arch->>Arch : "ValidatePhaseTransition(next)"
alt "严格验证开启"
Arch->>Cfg : "读取StrictPhaseValidation"
Arch->>Const : "查询允许转换"
Const-->>Arch : "允许列表"
Arch->>Arch : "若不合法则抛出异常"
end
Arch->>Arch : "更新CurrentPhase"
Arch->>Hooks : "NotifyPhase(next)"
Hooks-->>Arch : "OnPhase回调"
Arch->>Aware : "NotifyPhaseAwareObjects(next)"
Aware-->>Arch : "OnArchitecturePhase回调"
Arch-->>Client : "完成阶段切换"
图表来源
详细组件分析
EnterPhase 方法实现机制
- 阶段转换验证：调用ValidatePhaseTransition，依据StrictPhaseValidation与ArchitectureConstants.PhaseTransitions判断合法性。
- 阶段变更记录：保存previousPhase，更新CurrentPhase，仅在阶段变化时记录日志。
- 阶段变更通知：先NotifyPhase通知生命周期钩子，再NotifyPhaseAwareObjects通知阶段感知对象。
flowchart TD
Start(["进入 EnterPhase"]) --> Validate["调用 ValidatePhaseTransition(next)"]
Validate --> Strict{"StrictPhaseValidation 开启？"}
Strict --> |否| Update["更新 CurrentPhase"]
Strict --> |是| CheckAllowed["查询 ArchitectureConstants.PhaseTransitions"]
CheckAllowed --> Allowed{"允许转换？"}
Allowed --> |否| Throw["抛出 InvalidOperationException"]
Allowed --> |是| Update
Update --> Notify1["NotifyPhase(next)"]
Notify1 --> Notify2["NotifyPhaseAwareObjects(next)"]
Notify2 --> End(["结束"])
Throw --> End
图表来源
章节来源
ValidatePhaseTransition 阶段转换规则与StrictPhaseValidation
- StrictPhaseValidation关闭：跳过验证，允许任意转换。
- StrictPhaseValidation开启：仅允许线性顺序转换，且FailedInitialization可从任意阶段转入。
- 转换规则来源于ArchitectureConstants.PhaseTransitions，保证阶段顺序一致性与失败路径存在性。
flowchart TD
S(["开始验证"]) --> CheckCfg["读取 StrictPhaseValidation"]
CheckCfg --> Enabled{"开启？"}
Enabled --> |否| OK["验证通过"]
Enabled --> |是| NextIsFail{"next 是否为 FailedInitialization？"}
NextIsFail --> |是| OK
NextIsFail --> |否| Lookup["查找 CurrentPhase 的允许列表"]
Lookup --> Found{"找到且包含 next？"}
Found --> |是| OK
Found --> |否| Err["抛出异常并记录致命日志"]
OK --> E(["结束"])
Err --> E
图表来源
章节来源
NotifyPhase 与 NotifyPhaseAwareObjects 通知机制
- NotifyPhase：遍历生命周期钩子列表，逐个调用OnPhase(phase, architecture)，并记录跟踪日志。
- NotifyPhaseAwareObjects：通过容器检索IArchitecturePhaseAware实例，逐个调用OnArchitecturePhase(phase)，并记录跟踪日志。
sequenceDiagram
participant Arch as "Architecture"
participant Hooks as "生命周期钩子集合"
participant Aware as "阶段感知对象集合"
Arch->>Hooks : "遍历 OnPhase(phase, architecture)"
Hooks-->>Arch : "回调完成"
Arch->>Aware : "遍历 OnArchitecturePhase(phase)"
Aware-->>Arch : "回调完成"
图表来源
章节来源
生命周期钩子注册机制与 IArchitectureLifecycle 实现要求
- RegisterLifecycleHook：在CurrentPhase达到Ready之后，若未开启AllowLateRegistration，则拒绝注册；否则加入_hooks列表。
- IArchitectureLifecycle：必须实现OnPhase(ArchitecturePhase, IArchitecture)，用于接收阶段变更通知。
- IArchitecture：对外暴露RegisterLifecycleHook方法，便于外部注册。
classDiagram
class IArchitecture {
+RegisterLifecycleHook(hook) IArchitectureLifecycle
}
class Architecture {
-_lifecycleHooks : IArchitectureLifecycle[]
+RegisterLifecycleHook(hook) IArchitectureLifecycle
+EnterPhase(next) void
}
class IArchitectureLifecycle {
+OnPhase(phase, architecture) void
}
IArchitecture <|.. Architecture
Architecture --> IArchitectureLifecycle : "注册/通知"
图表来源
章节来源
阶段感知对象处理（IArchitecturePhaseAware）
- 通过容器检索IArchitecturePhaseAware实例，逐一调用OnArchitecturePhase(phase)。
- 适用于需要在特定阶段执行逻辑的对象，如资源加载、UI状态同步等。
章节来源
架构阶段枚举与阶段常量定义
- ArchitecturePhase：定义None、BeforeUtilityInit、AfterUtilityInit、BeforeModelInit、AfterModelInit、BeforeSystemInit、AfterSystemInit、Ready、Destroying、Destroyed、FailedInitialization等阶段。
- ArchitectureConstants：定义PhaseOrder线性顺序与PhaseTransitions转换映射，确保严格线性推进与失败路径存在。
classDiagram
class ArchitecturePhase {
<<enum>>
+None
+BeforeUtilityInit
+AfterUtilityInit
+BeforeModelInit
+AfterModelInit
+BeforeSystemInit
+AfterSystemInit
+Ready
+Destroying
+Destroyed
+FailedInitialization
}
class ArchitectureConstants {
+PhaseOrder : ArchitecturePhase[]
+PhaseTransitions : ImmutableDictionary
}
ArchitectureConstants --> ArchitecturePhase : "使用"
图表来源
章节来源
生命周期管理完整流程图（初始化与销毁）
flowchart TD
InitStart(["Initialize/InitializeAsync 入口"]) --> Setup["基础环境与上下文初始化"]
Setup --> UserInit["调用子类 Init()"]
UserInit --> Group["按类型分组组件<br/>Utilities/Models/Systems"]
Group --> U1["进入 BeforeUtilityInit"]
U1 --> U2["初始化 Utilities 并进入 AfterUtilityInit"]
U2 --> M1["进入 BeforeModelInit"]
M1 --> M2["初始化 Models 并进入 AfterModelInit"]
M2 --> S1["进入 BeforeSystemInit"]
S1 --> S2["初始化 Systems 并进入 AfterSystemInit"]
S2 --> Freeze["冻结 IOC 容器"]
Freeze --> Ready["进入 Ready 并发送 Ready 事件"]
Ready --> Destroy["Destroy 触发 Destroying 阶段"]
Destroy --> Dispose["逆序销毁 IDisposable 组件"]
Dispose --> Destroyed["进入 Destroyed 并发送 Destroyed 事件"]
图表来源
章节来源
实际使用示例与最佳实践
- 生命周期钩子示例：参考README中的PerformanceMonitorHook示例，展示在各阶段打印日志。
- 钩子注册时机：必须在Ready阶段之前注册，否则会抛出异常。
- 阶段检查：通过CurrentPhase判断架构状态，避免在错误阶段执行操作。
章节来源
依赖分析
- Architecture依赖Configuration与ArchitectureConstants进行阶段验证与顺序约束。
- 通过容器检索IArchitecturePhaseAware与IArchitectureLifecycle，实现松耦合通知。
- ArchitectureContext提供服务缓存与事件总线集成，支持查询、命令、事件的统一访问。
graph LR
Arch["Architecture"] --> Cfg["ArchitectureConfiguration"]
Arch --> Const["ArchitectureConstants"]
Arch --> Ctx["ArchitectureContext"]
Arch --> Hook["IArchitectureLifecycle"]
Arch --> Aware["IArchitecturePhaseAware"]
Ctx --> Bus["IEventBus"]
图表来源
章节来源
性能考虑
- 去重集合：使用HashSet维护待初始化与可销毁组件，确保O(1)去重与O(1)插入/删除。
- 顺序与逆序：组件注册顺序保持初始化顺序，销毁时逆序执行，减少依赖破坏风险。
- 日志粒度：Info/Debug/Trace按重要性分级，避免过度日志影响性能。
- 异步初始化：支持IAsyncInitializable与IAsyncCommand，提升长耗时初始化效率。
[本节为通用指导，无需具体文件分析]
故障排查指南
- 阶段转换异常：检查StrictPhaseValidation与PhaseTransitions，确认转换是否符合线性顺序。
- Ready后注册钩子：若CurrentPhase已达Ready且未开启AllowLateRegistration，将抛出异常。
- 初始化失败：捕获Initialize/InitializeAsync异常后进入FailedInitialization并发送失败事件。
- 销毁异常：Destroy过程中单个组件异常会被捕获并记录，不影响其他组件销毁。
章节来源
结论
GFramework的生命周期管理以EnterPhase为核心，结合StrictPhaseValidation与ArchitectureConstants确保严格的线性状态机行为；通过NotifyPhase与NotifyPhaseAwareObjects实现钩子与感知对象的统一通知；借助ArchitectureConfiguration提供灵活的配置开关。整体设计清晰、可扩展，适合复杂游戏架构的生命周期编排。
[本节为总结，无需具体文件分析]
附录
阶段常量与转换规则验证（来自测试）
- PhaseOrder包含全部阶段且顺序正确。
- PhaseTransitions包含线性转换与失败路径，且每阶段最多一个转换。
- PhaseOrder与PhaseTransitions一致，保证转换方向正确。
章节来源
配置默认值与可定制性（来自测试）
- ArchitectureConfiguration默认StrictPhaseValidation为true，AllowLateRegistration为false。
- 支持独立修改LoggerProperties与ArchitectureProperties，不影响其他实例。
章节来源
- ArchitectureConfigurationTests.cs
- ArchitectureConfigurationTests.cs
- ArchitectureConfigurationTests.cs
测试架构基类（扩展EnterPhase以记录阶段历史）
- 通过重写EnterPhase记录PhaseHistory，便于断言阶段推进顺序。
章节来源