diff --git a/GFramework.Core.Tests/Architectures/TestArchitectureBase.cs b/GFramework.Core.Tests/Architectures/TestArchitectureBase.cs index c3d5e76..90f3d43 100644 --- a/GFramework.Core.Tests/Architectures/TestArchitectureBase.cs +++ b/GFramework.Core.Tests/Architectures/TestArchitectureBase.cs @@ -41,16 +41,8 @@ public abstract class TestArchitectureBase : Architecture { InitCalled = true; _postRegistrationHook?.Invoke(this); - } - /// - /// 进入指定架构阶段时的处理方法，记录阶段历史 - /// - /// 要进入的下一个架构阶段 - protected override void EnterPhase(ArchitecturePhase next) - { - base.EnterPhase(next); - // 记录进入的架构阶段到历史列表中 - PhaseHistory.Add(next); + // 订阅阶段变更事件以记录历史 + PhaseChanged += phase => PhaseHistory.Add(phase); } } \ No newline at end of file diff --git a/GFramework.Core/Architectures/Architecture.cs b/GFramework.Core/Architectures/Architecture.cs index 3bf2a98..c3e4743 100644 --- a/GFramework.Core/Architectures/Architecture.cs +++ b/GFramework.Core/Architectures/Architecture.cs @@ -1,14 +1,11 @@ using GFramework.Core.Abstractions.Architectures; using GFramework.Core.Abstractions.Enums; using GFramework.Core.Abstractions.Environment; -using GFramework.Core.Abstractions.Ioc; -using GFramework.Core.Abstractions.Lifecycle; using GFramework.Core.Abstractions.Logging; using GFramework.Core.Abstractions.Model; using GFramework.Core.Abstractions.Systems; using GFramework.Core.Abstractions.Utility; using GFramework.Core.Environment; -using GFramework.Core.Extensions; using GFramework.Core.Logging; using Microsoft.Extensions.DependencyInjection; @@ -17,41 +14,56 @@ namespace GFramework.Core.Architectures; /// /// 架构基类，提供系统、模型、工具等组件的注册与管理功能。 /// 专注于生命周期管理、初始化流程控制和架构阶段转换。 +/// +/// 重构说明：此类已重构为协调器模式，将职责委托给专门的管理器： +/// - ArchitectureLifecycle: 生命周期管理 +/// - ArchitectureComponentRegistry: 组件注册管理 +/// - ArchitectureModules: 模块管理 /// -public abstract class Architecture( - IArchitectureConfiguration? configuration = null, - IEnvironment? environment = null, - IArchitectureServices? services = null, - IArchitectureContext? context = null -) - : IArchitecture +public abstract class Architecture : IArchitecture { - #region Module Management + #region Constructor /// - /// 注册中介行为管道 - /// 用于配置Mediator框架的行为拦截和处理逻辑 + /// 构造函数，初始化架构和管理器 /// - /// 行为类型，必须是引用类型 - public void RegisterMediatorBehavior() where TBehavior : class + /// 架构配置 + /// 环境配置 + /// 服务管理器 + /// 架构上下文 + protected Architecture( + IArchitectureConfiguration? configuration = null, + IEnvironment? environment = null, + IArchitectureServices? services = null, + IArchitectureContext? context = null) { - _logger.Debug($"Registering mediator behavior: {typeof(TBehavior).Name}"); - Container.RegisterMediatorBehavior(); + 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); } + #endregion + + #region Lifecycle Hook Management + /// - /// 安装架构模块 + /// 注册生命周期钩子 /// - /// 要安装的模块 - /// 安装的模块实例 - public IArchitectureModule InstallModule(IArchitectureModule module) + /// 生命周期钩子实例 + /// 注册的钩子实例 + public IArchitectureLifecycleHook RegisterLifecycleHook(IArchitectureLifecycleHook hook) { - var name = module.GetType().Name; - var logger = LoggerFactoryResolver.Provider.CreateLogger(name); - logger.Debug($"Installing module: {name}"); - module.Install(this); - logger.Info($"Module installed: {name}"); - return module; + return _lifecycle.RegisterLifecycleHook(hook); } #endregion @@ -61,361 +73,99 @@ public abstract class Architecture( /// /// 获取架构配置对象 /// - private IArchitectureConfiguration Configuration { get; } = configuration ?? new ArchitectureConfiguration(); + private IArchitectureConfiguration Configuration { get; } /// /// 获取环境配置对象 /// - private IEnvironment Environment { get; } = environment ?? new DefaultEnvironment(); - - private IArchitectureServices Services { get; } = services ?? new ArchitectureServices(); + private IEnvironment Environment { get; } /// - /// 获取依赖注入容器 + /// 获取服务管理器 /// - private IIocContainer Container => Services.Container; + private IArchitectureServices Services { get; } /// /// 当前架构的阶段 /// - public ArchitecturePhase CurrentPhase { get; private set; } + public ArchitecturePhase CurrentPhase => _lifecycle.CurrentPhase; /// /// 架构上下文 /// public IArchitectureContext Context => _context!; + /// + /// 获取一个布尔值，指示当前架构是否处于就绪状态 + /// + public bool IsReady => _lifecycle.IsReady; + + /// + /// 获取用于配置服务集合的委托 + /// 默认实现返回null，子类可以重写此属性以提供自定义配置逻辑 + /// + public virtual Action? Configurator => null; + + /// + /// 阶段变更事件（用于测试和扩展） + /// + public event Action? PhaseChanged + { + add => _lifecycle.PhaseChanged += value; + remove => _lifecycle.PhaseChanged -= value; + } + #endregion #region Fields - private readonly TaskCompletionSource _readyTcs = new(TaskCreationOptions.RunContinuationsAsynchronously); - - /// - /// 获取一个布尔值，指示当前架构是否处于就绪状态。 - /// 当前架构的阶段等于 ArchitecturePhase.Ready 时返回 true，否则返回 false。 - /// - public bool IsReady => CurrentPhase == ArchitecturePhase.Ready; - - /// - /// 待初始化组件的去重集合。 - /// 用于存储需要初始化的组件实例，确保每个组件仅被初始化一次。 - /// - private readonly HashSet _pendingInitializableSet = []; - - /// - /// 存储所有待初始化的组件（统一管理，保持注册顺序） - /// - private readonly List _pendingInitializableList = []; - - /// - /// 可销毁组件的去重集合（支持 IDestroyable 和 IAsyncDestroyable） - /// - private readonly HashSet _disposableSet = []; - - /// - /// 存储所有需要销毁的组件（统一管理，保持注册逆序销毁） - /// - private readonly List _disposables = []; - - /// - /// 生命周期感知对象列表 - /// - private readonly List _lifecycleHooks = []; - - /// - /// 标记架构是否已初始化完成 - /// - private bool _mInitialized; - /// /// 日志记录器实例 /// - private ILogger _logger = null!; + private readonly ILogger _logger; /// /// 架构上下文实例 /// - private IArchitectureContext? _context = context; + private IArchitectureContext? _context; + + /// + /// 生命周期管理器 + /// + private readonly ArchitectureLifecycle _lifecycle; + + /// + /// 组件注册管理器 + /// + private readonly ArchitectureComponentRegistry _componentRegistry; + + /// + /// 模块管理器 + /// + private readonly ArchitectureModules _modules; #endregion - #region Lifecycle Management + #region Module Management /// - /// 进入指定的架构阶段，并执行相应的生命周期管理操作 + /// 注册中介行为管道 + /// 用于配置Mediator框架的行为拦截和处理逻辑 /// - /// 要进入的下一个架构阶段 - /// 当阶段转换不被允许时抛出异常 - protected virtual void EnterPhase(ArchitecturePhase next) + /// 行为类型，必须是引用类型 + public void RegisterMediatorBehavior() where TBehavior : class { - // 验证阶段转换 - ValidatePhaseTransition(next); - - // 执行阶段转换 - var previousPhase = CurrentPhase; - CurrentPhase = next; - - if (previousPhase != next) - _logger.Info($"Architecture phase changed: {previousPhase} -> {next}"); - - // 通知阶段变更 - NotifyPhase(next); - NotifyPhaseAwareObjects(next); + _modules.RegisterMediatorBehavior(); } /// - /// 验证阶段转换是否合法 + /// 安装架构模块 /// - /// 目标阶段 - /// 当阶段转换不合法时抛出 - private void ValidatePhaseTransition(ArchitecturePhase next) + /// 要安装的模块 + /// 安装的模块实例 + public IArchitectureModule InstallModule(IArchitectureModule module) { - // 不需要严格验证，直接返回 - if (!Configuration.ArchitectureProperties.StrictPhaseValidation) - return; - - // FailedInitialization 可以从任何阶段转换，直接返回 - if (next == ArchitecturePhase.FailedInitialization) - return; - - // 检查转换是否在允许列表中 - if (ArchitectureConstants.PhaseTransitions.TryGetValue(CurrentPhase, out var allowed) && - allowed.Contains(next)) - return; - - // 转换不合法，抛出异常 - var errorMsg = $"Invalid phase transition: {CurrentPhase} -> {next}"; - _logger.Fatal(errorMsg); - throw new InvalidOperationException(errorMsg); - } - - /// - /// 通知所有架构阶段感知对象阶段变更 - /// - /// 新阶段 - private void NotifyPhaseAwareObjects(ArchitecturePhase phase) - { - foreach (var obj in Container.GetAll()) - { - _logger.Trace($"Notifying phase-aware object {obj.GetType().Name} of phase change to {phase}"); - obj.OnArchitecturePhase(phase); - } - } - - /// - /// 通知所有生命周期钩子当前阶段变更 - /// - /// 当前架构阶段 - private void NotifyPhase(ArchitecturePhase phase) - { - foreach (var hook in _lifecycleHooks) - { - hook.OnPhase(phase, this); - _logger.Trace($"Notifying lifecycle hook {hook.GetType().Name} of phase {phase}"); - } - } - - /// - /// 注册生命周期钩子 - /// - /// 生命周期钩子实例 - /// 注册的钩子实例 - public IArchitectureLifecycleHook RegisterLifecycleHook(IArchitectureLifecycleHook hook) - { - if (CurrentPhase >= ArchitecturePhase.Ready && !Configuration.ArchitectureProperties.AllowLateRegistration) - throw new InvalidOperationException( - "Cannot register lifecycle hook after architecture is Ready"); - _lifecycleHooks.Add(hook); - return hook; - } - - /// - /// 统一的组件生命周期注册逻辑 - /// - /// 要注册的组件 - private void RegisterLifecycleComponent(T component) - { - // 处理初始化 - if (component is IInitializable initializable) - { - if (!_mInitialized) - { - // 原子去重：HashSet.Add 返回 true 表示添加成功（之前不存在） - if (_pendingInitializableSet.Add(initializable)) - { - _pendingInitializableList.Add(initializable); - _logger.Trace($"Added {component.GetType().Name} to pending initialization queue"); - } - } - else - { - throw new InvalidOperationException( - "Cannot initialize component after Architecture is Ready"); - } - } - - // 处理销毁（支持 IDestroyable 或 IAsyncDestroyable） - if (component is not (IDestroyable or IAsyncDestroyable)) return; - // 原子去重：HashSet.Add 返回 true 表示添加成功（之前不存在） - if (!_disposableSet.Add(component)) return; - _disposables.Add(component); - _logger.Trace($"Registered {component.GetType().Name} for destruction"); - } - - /// - /// 初始化所有待初始化的组件 - /// - /// 是否使用异步模式 - private async Task InitializeAllComponentsAsync(bool asyncMode) - { - _logger.Info($"Initializing {_pendingInitializableList.Count} components"); - - // 按类型分组初始化（保持原有的阶段划分） - var utilities = _pendingInitializableList.OfType().ToList(); - var models = _pendingInitializableList.OfType().ToList(); - var systems = _pendingInitializableList.OfType().ToList(); - - // 1. 工具初始化阶段（始终进入阶段，仅在有组件时执行初始化） - EnterPhase(ArchitecturePhase.BeforeUtilityInit); - - if (utilities.Count != 0) - { - _logger.Info($"Initializing {utilities.Count} context utilities"); - - foreach (var utility in utilities) - { - _logger.Debug($"Initializing utility: {utility.GetType().Name}"); - await InitializeComponentAsync(utility, asyncMode); - } - - _logger.Info("All context utilities initialized"); - } - - EnterPhase(ArchitecturePhase.AfterUtilityInit); - - // 2. 模型初始化阶段（始终进入阶段，仅在有组件时执行初始化） - EnterPhase(ArchitecturePhase.BeforeModelInit); - - if (models.Count != 0) - { - _logger.Info($"Initializing {models.Count} models"); - - foreach (var model in models) - { - _logger.Debug($"Initializing model: {model.GetType().Name}"); - await InitializeComponentAsync(model, asyncMode); - } - - _logger.Info("All models initialized"); - } - - EnterPhase(ArchitecturePhase.AfterModelInit); - - // 3. 系统初始化阶段（始终进入阶段，仅在有组件时执行初始化） - EnterPhase(ArchitecturePhase.BeforeSystemInit); - - if (systems.Count != 0) - { - _logger.Info($"Initializing {systems.Count} systems"); - - foreach (var system in systems) - { - _logger.Debug($"Initializing system: {system.GetType().Name}"); - await InitializeComponentAsync(system, asyncMode); - } - - _logger.Info("All systems initialized"); - } - - EnterPhase(ArchitecturePhase.AfterSystemInit); - - _pendingInitializableList.Clear(); - _pendingInitializableSet.Clear(); - _logger.Info("All components initialized"); - } - - /// - /// 异步初始化单个组件 - /// - /// 要初始化的组件 - /// 是否使用异步模式 - private static async Task InitializeComponentAsync(IInitializable component, bool asyncMode) - { - if (asyncMode && component is IAsyncInitializable asyncInit) - await asyncInit.InitializeAsync(); - else - component.Initialize(); - } - - /// - /// 抽象初始化方法，由子类重写以进行自定义初始化操作 - /// - protected abstract void OnInitialize(); - - /// - /// 异步销毁架构及所有组件 - /// - public virtual async ValueTask DestroyAsync() - { - // 检查当前阶段，如果已经处于销毁或已销毁状态则直接返回 - if (CurrentPhase >= ArchitecturePhase.Destroying) - { - _logger.Warn("Architecture destroy called but already in destroying/destroyed state"); - return; - } - - // 进入销毁阶段 - _logger.Info("Starting architecture destruction"); - EnterPhase(ArchitecturePhase.Destroying); - - // 销毁所有实现了 IAsyncDestroyable 或 IDestroyable 的组件（按注册逆序销毁） - _logger.Info($"Destroying {_disposables.Count} disposable components"); - - for (var i = _disposables.Count - 1; i >= 0; i--) - { - var component = _disposables[i]; - try - { - _logger.Debug($"Destroying component: {component.GetType().Name}"); - - // 优先使用异步销毁 - if (component is IAsyncDestroyable asyncDestroyable) - { - await asyncDestroyable.DestroyAsync(); - } - else if (component is IDestroyable destroyable) - { - destroyable.Destroy(); - } - } - catch (Exception ex) - { - _logger.Error($"Error destroying {component.GetType().Name}", ex); - // 继续销毁其他组件，不会因为一个组件失败而中断 - } - } - - _disposables.Clear(); - _disposableSet.Clear(); - - // 销毁服务模块 - await Services.ModuleManager.DestroyAllAsync(); - - Container.Clear(); - - // 进入已销毁阶段 - EnterPhase(ArchitecturePhase.Destroyed); - _logger.Info("Architecture destruction completed"); - } - - /// - /// 销毁架构并清理所有组件资源（同步方法，保留用于向后兼容） - /// - [Obsolete("建议使用 DestroyAsync() 以支持异步清理")] - public virtual void Destroy() - { - DestroyAsync().AsTask().GetAwaiter().GetResult(); + return _modules.InstallModule(module); } #endregion @@ -423,177 +173,77 @@ public abstract class Architecture( #region Component Registration /// - /// 验证是否允许注册组件 + /// 注册一个系统到架构中 /// - /// 组件类型描述 - /// 当不允许注册时抛出 - private void ValidateRegistration(string componentType) - { - if (CurrentPhase < ArchitecturePhase.Ready || - Configuration.ArchitectureProperties.AllowLateRegistration) return; - var errorMsg = $"Cannot register {componentType} after Architecture is Ready"; - _logger.Error(errorMsg); - throw new InvalidOperationException(errorMsg); - } - - /// - /// 注册一个系统到架构中。 - /// 若当前未初始化，则暂存至待初始化列表；否则立即初始化该系统。 - /// - /// 要注册的系统类型，必须实现ISystem接口 + /// 要注册的系统类型 /// 要注册的系统实例 /// 注册成功的系统实例 public TSystem RegisterSystem(TSystem system) where TSystem : ISystem { - ValidateRegistration("system"); - - _logger.Debug($"Registering system: {typeof(TSystem).Name}"); - - system.SetContext(Context); - Container.RegisterPlurality(system); - - // 处理生命周期 - RegisterLifecycleComponent(system); - - _logger.Info($"System registered: {typeof(TSystem).Name}"); - return system; + return _componentRegistry.RegisterSystem(system); } /// - /// 注册系统类型，由 DI 容器自动创建实例 + /// 注册系统类型，由 DI 容器自动创建实例 /// /// 系统类型 - /// 可选的实例创建后回调，用于自定义配置 + /// 可选的实例创建后回调 public void RegisterSystem(Action? onCreated = null) where T : class, ISystem { - ValidateRegistration("system"); - _logger.Debug($"Registering system type: {typeof(T).Name}"); - - Container.RegisterFactory(sp => - { - // 1. DI 创建实例 - var system = ActivatorUtilities.CreateInstance(sp); - - // 2. 框架默认处理 - system.SetContext(Context); - RegisterLifecycleComponent(system); - - // 3. 用户自定义处理（钩子） - onCreated?.Invoke(system); - - _logger.Debug($"System created: {typeof(T).Name}"); - return system; - }); - - _logger.Info($"System type registered: {typeof(T).Name}"); + _componentRegistry.RegisterSystem(onCreated); } /// - /// 注册一个模型到架构中。 - /// 若当前未初始化，则暂存至待初始化列表；否则立即初始化该模型。 + /// 注册一个模型到架构中 /// - /// 要注册的模型类型，必须实现IModel接口 + /// 要注册的模型类型 /// 要注册的模型实例 /// 注册成功的模型实例 public TModel RegisterModel(TModel model) where TModel : IModel { - ValidateRegistration("model"); - - _logger.Debug($"Registering model: {typeof(TModel).Name}"); - - model.SetContext(Context); - Container.RegisterPlurality(model); - - // 处理生命周期 - RegisterLifecycleComponent(model); - - _logger.Info($"Model registered: {typeof(TModel).Name}"); - return model; + return _componentRegistry.RegisterModel(model); } /// - /// 注册模型类型，由 DI 容器自动创建实例 + /// 注册模型类型，由 DI 容器自动创建实例 /// /// 模型类型 - /// 可选的实例创建后回调，用于自定义配置 + /// 可选的实例创建后回调 public void RegisterModel(Action? onCreated = null) where T : class, IModel { - ValidateRegistration("model"); - _logger.Debug($"Registering model type: {typeof(T).Name}"); - - Container.RegisterFactory(sp => - { - var model = ActivatorUtilities.CreateInstance(sp); - model.SetContext(Context); - RegisterLifecycleComponent(model); - - // 用户自定义钩子 - onCreated?.Invoke(model); - - _logger.Debug($"Model created: {typeof(T).Name}"); - return model; - }); - - _logger.Info($"Model type registered: {typeof(T).Name}"); + _componentRegistry.RegisterModel(onCreated); } /// /// 注册一个工具到架构中 /// - /// 要注册的工具类型，必须实现IUtility接口 + /// 要注册的工具类型 /// 要注册的工具实例 /// 注册成功的工具实例 public TUtility RegisterUtility(TUtility utility) where TUtility : IUtility { - _logger.Debug($"Registering utility: {typeof(TUtility).Name}"); - - // 处理上下文工具类型的设置和生命周期管理 - utility.IfType(contextUtility => - { - contextUtility.SetContext(Context); - // 处理生命周期 - RegisterLifecycleComponent(contextUtility); - }); - - Container.RegisterPlurality(utility); - _logger.Info($"Utility registered: {typeof(TUtility).Name}"); - return utility; + return _componentRegistry.RegisterUtility(utility); } /// - /// 注册工具类型，由 DI 容器自动创建实例 + /// 注册工具类型，由 DI 容器自动创建实例 /// /// 工具类型 - /// 可选的实例创建后回调，用于自定义配置 + /// 可选的实例创建后回调 public void RegisterUtility(Action? onCreated = null) where T : class, IUtility { - _logger.Debug($"Registering utility type: {typeof(T).Name}"); - - Container.RegisterFactory(sp => - { - var utility = ActivatorUtilities.CreateInstance(sp); - - // 如果是 IContextUtility，设置上下文 - if (utility is IContextUtility contextUtility) - { - contextUtility.SetContext(Context); - RegisterLifecycleComponent(contextUtility); - } - - // 用户自定义钩子 - onCreated?.Invoke(utility); - - _logger.Debug($"Utility created: {typeof(T).Name}"); - return utility; - }); - - _logger.Info($"Utility type registered: {typeof(T).Name}"); + _componentRegistry.RegisterUtility(onCreated); } #endregion #region Initialization + /// + /// 抽象初始化方法，由子类重写以进行自定义初始化操作 + /// + protected abstract void OnInitialize(); + /// /// 同步初始化方法，阻塞当前线程直到初始化完成 /// @@ -606,7 +256,7 @@ public abstract class Architecture( catch (Exception e) { _logger.Error("Architecture initialization failed:", e); - EnterPhase(ArchitecturePhase.FailedInitialization); + _lifecycle.MarkAsFailed(e); throw; } } @@ -614,7 +264,6 @@ public abstract class Architecture( /// /// 异步初始化方法，返回Task以便调用者可以等待初始化完成 /// - /// 表示异步初始化操作的Task public async Task InitializeAsync() { try @@ -624,32 +273,29 @@ public abstract class Architecture( catch (Exception e) { _logger.Error("Architecture initialization failed:", e); - EnterPhase(ArchitecturePhase.FailedInitialization); + _lifecycle.MarkAsFailed(e); throw; } } /// - /// 异步初始化架构内部组件，包括上下文、模型和系统的初始化 + /// 异步初始化架构内部组件 /// - /// 是否启用异步模式进行组件初始化 - /// 异步任务，表示初始化操作的完成 + /// 是否启用异步模式 private async Task InitializeInternalAsync(bool asyncMode) { - // === 基础上下文 & Logger === - LoggerFactoryResolver.Provider = Configuration.LoggerProperties.LoggerFactoryProvider; - _logger = LoggerFactoryResolver.Provider.CreateLogger(GetType().Name); + // === 基础环境初始化 === Environment.Initialize(); // 注册内置服务模块 - Services.ModuleManager.RegisterBuiltInModules(Container); + Services.ModuleManager.RegisterBuiltInModules(Services.Container); - // 将 Environment 注册到容器（如果尚未注册） - if (!Container.Contains()) - Container.RegisterPlurality(Environment); + // 将 Environment 注册到容器 + if (!Services.Container.Contains()) + Services.Container.RegisterPlurality(Environment); - // 初始化架构上下文（如果尚未初始化） - _context ??= new ArchitectureContext(Container); + // 初始化架构上下文 + _context ??= new ArchitectureContext(Services.Container); GameContext.Bind(GetType(), _context); // 为服务设置上下文 @@ -660,7 +306,7 @@ public abstract class Architecture( } // 执行服务钩子 - Container.ExecuteServicesHook(Configurator); + Services.Container.ExecuteServicesHook(Configurator); // 初始化服务模块 await Services.ModuleManager.InitializeAllAsync(asyncMode); @@ -671,39 +317,44 @@ public abstract class Architecture( _logger.Debug("User OnInitialize() completed"); // === 组件初始化阶段 === - await InitializeAllComponentsAsync(asyncMode); + await _lifecycle.InitializeAllComponentsAsync(asyncMode); // === 初始化完成阶段 === - Container.Freeze(); + Services.Container.Freeze(); _logger.Info("IOC container frozen"); - _mInitialized = true; - EnterPhase(ArchitecturePhase.Ready); - // 🔥 释放 Ready await - _readyTcs.TrySetResult(); - + _lifecycle.MarkAsReady(); _logger.Info($"Architecture {GetType().Name} is ready - all components initialized"); } /// /// 等待架构初始化完成（Ready 阶段） - /// 如果架构已经处于就绪状态，则立即返回已完成的任务； - /// 否则返回一个任务，该任务将在架构进入就绪状态时完成。 /// - /// 表示等待操作的Task对象 public Task WaitUntilReadyAsync() { - return IsReady ? Task.CompletedTask : _readyTcs.Task; + return _lifecycle.WaitUntilReadyAsync(); + } + + #endregion + + #region Destruction + + /// + /// 异步销毁架构及所有组件 + /// + public virtual async ValueTask DestroyAsync() + { + await _lifecycle.DestroyAsync(); } /// - /// 获取用于配置服务集合的委托 - /// 默认实现返回null，子类可以重写此属性以提供自定义配置逻辑 + /// 销毁架构并清理所有组件资源（同步方法，保留用于向后兼容） /// - /// - /// 一个可为空的Action委托，用于配置IServiceCollection实例 - /// - public virtual Action? Configurator => null; + [Obsolete("建议使用 DestroyAsync() 以支持异步清理")] + public virtual void Destroy() + { + _lifecycle.Destroy(); + } #endregion } \ No newline at end of file diff --git a/GFramework.Core/Architectures/ArchitectureComponentRegistry.cs b/GFramework.Core/Architectures/ArchitectureComponentRegistry.cs new file mode 100644 index 0000000..d39d597 --- /dev/null +++ b/GFramework.Core/Architectures/ArchitectureComponentRegistry.cs @@ -0,0 +1,204 @@ +using GFramework.Core.Abstractions.Architectures; +using GFramework.Core.Abstractions.Enums; +using GFramework.Core.Abstractions.Logging; +using GFramework.Core.Abstractions.Model; +using GFramework.Core.Abstractions.Systems; +using GFramework.Core.Abstractions.Utility; +using GFramework.Core.Extensions; +using Microsoft.Extensions.DependencyInjection; + +namespace GFramework.Core.Architectures; + +/// +/// 架构组件注册管理器 +/// 负责管理 System、Model、Utility 的注册 +/// +internal sealed class ArchitectureComponentRegistry( + IArchitecture architecture, + IArchitectureConfiguration configuration, + IArchitectureServices services, + ArchitectureLifecycle lifecycle, + ILogger logger) +{ + #region Validation + + /// + /// 验证是否允许注册组件 + /// + /// 组件类型描述 + /// 当不允许注册时抛出 + private void ValidateRegistration(string componentType) + { + if (lifecycle.CurrentPhase < ArchitecturePhase.Ready || + configuration.ArchitectureProperties.AllowLateRegistration) return; + var errorMsg = $"Cannot register {componentType} after Architecture is Ready"; + logger.Error(errorMsg); + throw new InvalidOperationException(errorMsg); + } + + #endregion + + #region System Registration + + /// + /// 注册一个系统到架构中 + /// + /// 要注册的系统类型 + /// 要注册的系统实例 + /// 注册成功的系统实例 + public TSystem RegisterSystem(TSystem system) where TSystem : ISystem + { + ValidateRegistration("system"); + + logger.Debug($"Registering system: {typeof(TSystem).Name}"); + + system.SetContext(architecture.Context); + services.Container.RegisterPlurality(system); + + // 处理生命周期 + lifecycle.RegisterLifecycleComponent(system); + + logger.Info($"System registered: {typeof(TSystem).Name}"); + return system; + } + + /// + /// 注册系统类型，由 DI 容器自动创建实例 + /// + /// 系统类型 + /// 可选的实例创建后回调 + public void RegisterSystem(Action? onCreated = null) where T : class, ISystem + { + ValidateRegistration("system"); + logger.Debug($"Registering system type: {typeof(T).Name}"); + + services.Container.RegisterFactory(sp => + { + // 1. DI 创建实例 + var system = ActivatorUtilities.CreateInstance(sp); + + // 2. 框架默认处理 + system.SetContext(architecture.Context); + lifecycle.RegisterLifecycleComponent(system); + + // 3. 用户自定义处理（钩子） + onCreated?.Invoke(system); + + logger.Debug($"System created: {typeof(T).Name}"); + return system; + }); + + logger.Info($"System type registered: {typeof(T).Name}"); + } + + #endregion + + #region Model Registration + + /// + /// 注册一个模型到架构中 + /// + /// 要注册的模型类型 + /// 要注册的模型实例 + /// 注册成功的模型实例 + public TModel RegisterModel(TModel model) where TModel : IModel + { + ValidateRegistration("model"); + + logger.Debug($"Registering model: {typeof(TModel).Name}"); + + model.SetContext(architecture.Context); + services.Container.RegisterPlurality(model); + + // 处理生命周期 + lifecycle.RegisterLifecycleComponent(model); + + logger.Info($"Model registered: {typeof(TModel).Name}"); + return model; + } + + /// + /// 注册模型类型，由 DI 容器自动创建实例 + /// + /// 模型类型 + /// 可选的实例创建后回调 + public void RegisterModel(Action? onCreated = null) where T : class, IModel + { + ValidateRegistration("model"); + logger.Debug($"Registering model type: {typeof(T).Name}"); + + services.Container.RegisterFactory(sp => + { + var model = ActivatorUtilities.CreateInstance(sp); + model.SetContext(architecture.Context); + lifecycle.RegisterLifecycleComponent(model); + + // 用户自定义钩子 + onCreated?.Invoke(model); + + logger.Debug($"Model created: {typeof(T).Name}"); + return model; + }); + + logger.Info($"Model type registered: {typeof(T).Name}"); + } + + #endregion + + #region Utility Registration + + /// + /// 注册一个工具到架构中 + /// + /// 要注册的工具类型 + /// 要注册的工具实例 + /// 注册成功的工具实例 + public TUtility RegisterUtility(TUtility utility) where TUtility : IUtility + { + logger.Debug($"Registering utility: {typeof(TUtility).Name}"); + + // 处理上下文工具类型的设置和生命周期管理 + utility.IfType(contextUtility => + { + contextUtility.SetContext(architecture.Context); + // 处理生命周期 + lifecycle.RegisterLifecycleComponent(contextUtility); + }); + + services.Container.RegisterPlurality(utility); + logger.Info($"Utility registered: {typeof(TUtility).Name}"); + return utility; + } + + /// + /// 注册工具类型，由 DI 容器自动创建实例 + /// + /// 工具类型 + /// 可选的实例创建后回调 + public void RegisterUtility(Action? onCreated = null) where T : class, IUtility + { + logger.Debug($"Registering utility type: {typeof(T).Name}"); + + services.Container.RegisterFactory(sp => + { + var utility = ActivatorUtilities.CreateInstance(sp); + + // 如果是 IContextUtility，设置上下文 + if (utility is IContextUtility contextUtility) + { + contextUtility.SetContext(architecture.Context); + lifecycle.RegisterLifecycleComponent(contextUtility); + } + + // 用户自定义钩子 + onCreated?.Invoke(utility); + + logger.Debug($"Utility created: {typeof(T).Name}"); + return utility; + }); + + logger.Info($"Utility type registered: {typeof(T).Name}"); + } + + #endregion +} \ No newline at end of file diff --git a/GFramework.Core/Architectures/ArchitectureLifecycle.cs b/GFramework.Core/Architectures/ArchitectureLifecycle.cs new file mode 100644 index 0000000..dbe2629 --- /dev/null +++ b/GFramework.Core/Architectures/ArchitectureLifecycle.cs @@ -0,0 +1,420 @@ +using GFramework.Core.Abstractions.Architectures; +using GFramework.Core.Abstractions.Enums; +using GFramework.Core.Abstractions.Lifecycle; +using GFramework.Core.Abstractions.Logging; +using GFramework.Core.Abstractions.Model; +using GFramework.Core.Abstractions.Systems; +using GFramework.Core.Abstractions.Utility; + +namespace GFramework.Core.Architectures; + +/// +/// 架构生命周期管理器 +/// 负责管理架构的阶段转换、组件初始化和销毁 +/// +internal sealed class ArchitectureLifecycle( + IArchitecture architecture, + IArchitectureConfiguration configuration, + IArchitectureServices services, + ILogger logger) +{ + #region Lifecycle Hook Management + + /// + /// 注册生命周期钩子 + /// + /// 生命周期钩子实例 + /// 注册的钩子实例 + public IArchitectureLifecycleHook RegisterLifecycleHook(IArchitectureLifecycleHook hook) + { + if (CurrentPhase >= ArchitecturePhase.Ready && !configuration.ArchitectureProperties.AllowLateRegistration) + throw new InvalidOperationException( + "Cannot register lifecycle hook after architecture is Ready"); + _lifecycleHooks.Add(hook); + return hook; + } + + #endregion + + #region Component Lifecycle Management + + /// + /// 统一的组件生命周期注册逻辑 + /// + /// 要注册的组件 + public void RegisterLifecycleComponent(object component) + { + // 处理初始化 + if (component is IInitializable initializable) + { + if (!_initialized) + { + // 原子去重：HashSet.Add 返回 true 表示添加成功（之前不存在） + if (_pendingInitializableSet.Add(initializable)) + { + _pendingInitializableList.Add(initializable); + logger.Trace($"Added {component.GetType().Name} to pending initialization queue"); + } + } + else + { + throw new InvalidOperationException( + "Cannot initialize component after Architecture is Ready"); + } + } + + // 处理销毁（支持 IDestroyable 或 IAsyncDestroyable） + if (component is not (IDestroyable or IAsyncDestroyable)) return; + // 原子去重：HashSet.Add 返回 true 表示添加成功（之前不存在） + if (!_disposableSet.Add(component)) return; + _disposables.Add(component); + logger.Trace($"Registered {component.GetType().Name} for destruction"); + } + + #endregion + + #region Fields + + private readonly TaskCompletionSource _readyTcs = new(TaskCreationOptions.RunContinuationsAsynchronously); + + /// + /// 待初始化组件的去重集合 + /// + private readonly HashSet _pendingInitializableSet = []; + + /// + /// 存储所有待初始化的组件（统一管理，保持注册顺序） + /// + private readonly List _pendingInitializableList = []; + + /// + /// 可销毁组件的去重集合（支持 IDestroyable 和 IAsyncDestroyable） + /// + private readonly HashSet _disposableSet = []; + + /// + /// 存储所有需要销毁的组件（统一管理，保持注册逆序销毁） + /// + private readonly List _disposables = []; + + /// + /// 生命周期感知对象列表 + /// + private readonly List _lifecycleHooks = []; + + /// + /// 标记架构是否已初始化完成 + /// + private bool _initialized; + + #endregion + + #region Properties + + /// + /// 当前架构的阶段 + /// + public ArchitecturePhase CurrentPhase { get; private set; } + + /// + /// 获取一个布尔值，指示当前架构是否处于就绪状态 + /// + public bool IsReady => CurrentPhase == ArchitecturePhase.Ready; + + /// + /// 获取一个布尔值，指示架构是否已初始化 + /// + public bool IsInitialized => _initialized; + + /// + /// 阶段变更事件（用于测试和扩展） + /// + public event Action? PhaseChanged; + + #endregion + + #region Phase Management + + /// + /// 进入指定的架构阶段，并执行相应的生命周期管理操作 + /// + /// 要进入的下一个架构阶段 + /// 当阶段转换不被允许时抛出异常 + public void EnterPhase(ArchitecturePhase next) + { + // 验证阶段转换 + ValidatePhaseTransition(next); + + // 执行阶段转换 + var previousPhase = CurrentPhase; + CurrentPhase = next; + + if (previousPhase != next) + logger.Info($"Architecture phase changed: {previousPhase} -> {next}"); + + // 通知阶段变更 + NotifyPhase(next); + NotifyPhaseAwareObjects(next); + + // 触发阶段变更事件（用于测试和扩展） + PhaseChanged?.Invoke(next); + } + + /// + /// 验证阶段转换是否合法 + /// + /// 目标阶段 + /// 当阶段转换不合法时抛出 + private void ValidatePhaseTransition(ArchitecturePhase next) + { + // 不需要严格验证，直接返回 + if (!configuration.ArchitectureProperties.StrictPhaseValidation) + return; + + // FailedInitialization 可以从任何阶段转换，直接返回 + if (next == ArchitecturePhase.FailedInitialization) + return; + + // 检查转换是否在允许列表中 + if (ArchitectureConstants.PhaseTransitions.TryGetValue(CurrentPhase, out var allowed) && + allowed.Contains(next)) + return; + + // 转换不合法，抛出异常 + var errorMsg = $"Invalid phase transition: {CurrentPhase} -> {next}"; + logger.Fatal(errorMsg); + throw new InvalidOperationException(errorMsg); + } + + /// + /// 通知所有架构阶段感知对象阶段变更 + /// + /// 新阶段 + private void NotifyPhaseAwareObjects(ArchitecturePhase phase) + { + foreach (var obj in services.Container.GetAll()) + { + logger.Trace($"Notifying phase-aware object {obj.GetType().Name} of phase change to {phase}"); + obj.OnArchitecturePhase(phase); + } + } + + /// + /// 通知所有生命周期钩子当前阶段变更 + /// + /// 当前架构阶段 + private void NotifyPhase(ArchitecturePhase phase) + { + foreach (var hook in _lifecycleHooks) + { + hook.OnPhase(phase, architecture); + logger.Trace($"Notifying lifecycle hook {hook.GetType().Name} of phase {phase}"); + } + } + + #endregion + + #region Initialization + + /// + /// 初始化所有待初始化的组件 + /// + /// 是否使用异步模式 + public async Task InitializeAllComponentsAsync(bool asyncMode) + { + logger.Info($"Initializing {_pendingInitializableList.Count} components"); + + // 按类型分组初始化（保持原有的阶段划分） + var utilities = _pendingInitializableList.OfType().ToList(); + var models = _pendingInitializableList.OfType().ToList(); + var systems = _pendingInitializableList.OfType().ToList(); + + // 1. 工具初始化阶段 + EnterPhase(ArchitecturePhase.BeforeUtilityInit); + + if (utilities.Count != 0) + { + logger.Info($"Initializing {utilities.Count} context utilities"); + + foreach (var utility in utilities) + { + logger.Debug($"Initializing utility: {utility.GetType().Name}"); + await InitializeComponentAsync(utility, asyncMode); + } + + logger.Info("All context utilities initialized"); + } + + EnterPhase(ArchitecturePhase.AfterUtilityInit); + + // 2. 模型初始化阶段 + EnterPhase(ArchitecturePhase.BeforeModelInit); + + if (models.Count != 0) + { + logger.Info($"Initializing {models.Count} models"); + + foreach (var model in models) + { + logger.Debug($"Initializing model: {model.GetType().Name}"); + await InitializeComponentAsync(model, asyncMode); + } + + logger.Info("All models initialized"); + } + + EnterPhase(ArchitecturePhase.AfterModelInit); + + // 3. 系统初始化阶段 + EnterPhase(ArchitecturePhase.BeforeSystemInit); + + if (systems.Count != 0) + { + logger.Info($"Initializing {systems.Count} systems"); + + foreach (var system in systems) + { + logger.Debug($"Initializing system: {system.GetType().Name}"); + await InitializeComponentAsync(system, asyncMode); + } + + logger.Info("All systems initialized"); + } + + EnterPhase(ArchitecturePhase.AfterSystemInit); + + _pendingInitializableList.Clear(); + _pendingInitializableSet.Clear(); + _initialized = true; + logger.Info("All components initialized"); + } + + /// + /// 异步初始化单个组件 + /// + /// 要初始化的组件 + /// 是否使用异步模式 + private static async Task InitializeComponentAsync(IInitializable component, bool asyncMode) + { + if (asyncMode && component is IAsyncInitializable asyncInit) + await asyncInit.InitializeAsync(); + else + component.Initialize(); + } + + #endregion + + #region Destruction + + /// + /// 异步销毁架构及所有组件 + /// + public async ValueTask DestroyAsync() + { + // 检查当前阶段，如果已经处于销毁或已销毁状态则直接返回 + if (CurrentPhase >= ArchitecturePhase.Destroying) + { + logger.Warn("Architecture destroy called but already in destroying/destroyed state"); + return; + } + + // 如果从未初始化（None 阶段），只清理已注册的组件，不进行阶段转换 + if (CurrentPhase == ArchitecturePhase.None) + { + logger.Debug("Architecture destroy called but never initialized, cleaning up registered components"); + await CleanupComponentsAsync(); + return; + } + + // 进入销毁阶段 + logger.Info("Starting architecture destruction"); + EnterPhase(ArchitecturePhase.Destroying); + + // 清理所有组件 + await CleanupComponentsAsync(); + + // 销毁服务模块 + await services.ModuleManager.DestroyAllAsync(); + + services.Container.Clear(); + + // 进入已销毁阶段 + EnterPhase(ArchitecturePhase.Destroyed); + logger.Info("Architecture destruction completed"); + } + + /// + /// 清理所有已注册的可销毁组件 + /// + private async ValueTask CleanupComponentsAsync() + { + // 销毁所有实现了 IAsyncDestroyable 或 IDestroyable 的组件（按注册逆序销毁） + logger.Info($"Destroying {_disposables.Count} disposable components"); + + for (var i = _disposables.Count - 1; i >= 0; i--) + { + var component = _disposables[i]; + try + { + logger.Debug($"Destroying component: {component.GetType().Name}"); + + // 优先使用异步销毁 + if (component is IAsyncDestroyable asyncDestroyable) + { + await asyncDestroyable.DestroyAsync(); + } + else if (component is IDestroyable destroyable) + { + destroyable.Destroy(); + } + } + catch (Exception ex) + { + logger.Error($"Error destroying {component.GetType().Name}", ex); + // 继续销毁其他组件，不会因为一个组件失败而中断 + } + } + + _disposables.Clear(); + _disposableSet.Clear(); + } + + /// + /// 销毁架构并清理所有组件资源（同步方法，保留用于向后兼容） + /// + [Obsolete("建议使用 DestroyAsync() 以支持异步清理")] + public void Destroy() + { + DestroyAsync().AsTask().GetAwaiter().GetResult(); + } + + #endregion + + #region Ready State + + /// + /// 标记架构为就绪状态 + /// + public void MarkAsReady() + { + EnterPhase(ArchitecturePhase.Ready); + _readyTcs.TrySetResult(); + } + + /// + /// 标记架构初始化失败 + /// + /// 失败异常 + public void MarkAsFailed(Exception exception) + { + EnterPhase(ArchitecturePhase.FailedInitialization); + _readyTcs.TrySetException(exception); + } + + /// + /// 等待架构就绪 + /// + public Task WaitUntilReadyAsync() => _readyTcs.Task; + + #endregion +} \ No newline at end of file diff --git a/GFramework.Core/Architectures/ArchitectureModules.cs b/GFramework.Core/Architectures/ArchitectureModules.cs new file mode 100644 index 0000000..3b60cc2 --- /dev/null +++ b/GFramework.Core/Architectures/ArchitectureModules.cs @@ -0,0 +1,39 @@ +using GFramework.Core.Abstractions.Architectures; +using GFramework.Core.Abstractions.Logging; + +namespace GFramework.Core.Architectures; + +/// +/// 架构模块管理器 +/// 负责管理架构模块的安装和中介行为注册 +/// +internal sealed class ArchitectureModules( + IArchitecture architecture, + IArchitectureServices services, + ILogger logger) +{ + /// + /// 注册中介行为管道 + /// 用于配置Mediator框架的行为拦截和处理逻辑 + /// + /// 行为类型，必须是引用类型 + public void RegisterMediatorBehavior() where TBehavior : class + { + logger.Debug($"Registering mediator behavior: {typeof(TBehavior).Name}"); + services.Container.RegisterMediatorBehavior(); + } + + /// + /// 安装架构模块 + /// + /// 要安装的模块 + /// 安装的模块实例 + public IArchitectureModule InstallModule(IArchitectureModule module) + { + var name = module.GetType().Name; + logger.Debug($"Installing module: {name}"); + module.Install(architecture); + logger.Info($"Module installed: {name}"); + return module; + } +} \ No newline at end of file diff --git a/GFramework.csproj b/GFramework.csproj index ae91b88..aa36eaf 100644 --- a/GFramework.csproj +++ b/GFramework.csproj @@ -122,4 +122,7 @@ + + + diff --git a/docs/zh-CN/abstractions/core-abstractions.md b/docs/zh-CN/abstractions/core-abstractions.md index 176826c..4a139d7 100644 --- a/docs/zh-CN/abstractions/core-abstractions.md +++ b/docs/zh-CN/abstractions/core-abstractions.md @@ -129,7 +129,7 @@ public interface IQuery ### IIocContainer -IOC 容器接口： +IoC 容器接口： ```csharp public interface IIocContainer diff --git a/docs/zh-CN/core/architecture.md b/docs/zh-CN/core/architecture.md index 2cfdaab..6ae229b 100644 --- a/docs/zh-CN/core/architecture.md +++ b/docs/zh-CN/core/architecture.md @@ -1,608 +1,231 @@ -# Architecture 包使用说明 +# Architecture 架构详解 + +> 深入了解 GFramework 的核心架构设计和实现 + +## 目录 + +- [概述](#概述) +- [架构设计](#架构设计) +- [生命周期管理](#生命周期管理) +- [组件注册](#组件注册) +- [模块系统](#模块系统) +- [最佳实践](#最佳实践) +- [API 参考](#api-参考) ## 概述 -Architecture 包是整个框架的核心，提供了基于分层架构模式的应用程序架构基础。它实现了依赖注入(IoC) -容器、组件生命周期管理，以及命令、查询、事件的统一调度机制。 +Architecture 是 GFramework 的核心类,负责管理整个应用的生命周期、组件注册和模块管理。从 v1.1.0 开始,Architecture +采用模块化设计,将职责分离到专门的管理器中。 -**注意**：本框架的 Core 模块与 Godot 解耦，Godot 相关集成在 GFramework.Godot 包中实现。 +### 设计目标 -## 核心接口 +- **单一职责**: 每个管理器只负责一个明确的功能 +- **类型安全**: 基于泛型的组件获取和注册 +- **生命周期管理**: 自动的初始化和销毁机制 +- **可扩展性**: 支持模块和钩子扩展 +- **向后兼容**: 保持公共 API 稳定 -### IArchitecture +### 核心组件 -架构接口，定义了框架的核心功能契约。 - -**主要职责：** - -- **组件注册**：注册 System、Model、Utility -- **组件获取**：从容器中获取已注册的组件 -- **命令处理**：发送并执行命令 -- **查询处理**：发送并执行查询 -- **事件管理**：发送、注册、注销事件 -- **模块管理**：安装和管理架构模块 -- **生命周期管理**：管理架构的初始化、运行和销毁阶段 - -**核心方法:** -```csharp -// 组件注册 -void RegisterSystem(TSystem system) where TSystem : ISystem; -void RegisterModel(TModel model) where TModel : IModel; -void RegisterUtility(TUtility utility) where TUtility : IUtility; - -// 组件获取(通过容器) -T GetModel() where T : class, IModel; -T GetSystem() where T : class, ISystem; -T GetUtility() where T : class, IUtility; - -// 命令处理 -void SendCommand(ICommand command); -TResult SendCommand(ICommand command); - -// 查询处理 -TResult SendQuery(IQuery query); - -// 事件管理 -void SendEvent() where T : new(); -void SendEvent(T e); -IUnRegister RegisterEvent(Action onEvent); -void UnRegisterEvent(Action onEvent); +``` +Architecture (核心协调器) + ├── ArchitectureLifecycle (生命周期管理) + ├── ArchitectureComponentRegistry (组件注册) + └── ArchitectureModules (模块管理) ``` -### IArchitecturePhaseAware +## 架构设计 -架构阶段感知接口，允许组件监听架构阶段变化。 +### 设计模式 -**核心方法：** -```csharp -void OnArchitecturePhase(ArchitecturePhase phase); +Architecture 采用以下设计模式: + +1. **组合模式 (Composition)**: Architecture 组合三个管理器 +2. **委托模式 (Delegation)**: 方法调用委托给专门的管理器 +3. **协调器模式 (Coordinator)**: Architecture 作为协调器统一对外接口 + +### 类图 + +``` +┌─────────────────────────────────────────────────────┐ +│ Architecture │ +│ - _lifecycle: ArchitectureLifecycle │ +│ - _componentRegistry: ArchitectureComponentRegistry│ +│ - _modules: ArchitectureModules │ +│ - _logger: ILogger │ +│ │ +│ + RegisterSystem() │ +│ + RegisterModel() │ +│ + RegisterUtility() │ +│ + InstallModule() │ +│ + InitializeAsync() │ +│ + DestroyAsync() │ +│ + event PhaseChanged │ +└─────────────────────────────────────────────────────┘ + │ │ │ + │ │ │ + ▼ ▼ ▼ +┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ +│ Lifecycle │ │ ComponentRegistry│ │ Modules │ +│ │ │ │ │ │ +│ - 阶段管理 │ │ - System 注册 │ │ - 模块安装 │ +│ - 钩子管理 │ │ - Model 注册 │ │ - 行为注册 │ +│ - 初始化 │ │ - Utility 注册 │ │ │ +│ - 销毁 │ │ - 生命周期注册 │ │ │ +└──────────────┘ └──────────────────┘ └──────────────┘ ``` -### IArchitectureModule +### 构造函数初始化 -架构模块接口，支持模块化架构扩展。 +从 v1.1.0 开始,所有管理器在构造函数中初始化: -**核心方法：** ```csharp -void Install(IArchitecture architecture); -``` - -### IAsyncInitializable - -异步初始化接口，支持组件异步初始化。 - -**核心方法：** -```csharp -Task InitializeAsync(); -``` - -## 核心类 - -### Architecture 架构基类 - -架构基类，实现了 `IArchitecture` 接口，提供完整的架构功能实现。 - -**构造函数参数：** -```csharp -public abstract class Architecture( +protected Architecture( IArchitectureConfiguration? configuration = null, IEnvironment? environment = null, IArchitectureServices? services = null, - IArchitectureContext? context = null -) -``` - -**特性：** - -- **阶段式生命周期管理** - ：支持多个架构阶段（BeforeUtilityInit、AfterUtilityInit、BeforeModelInit、AfterModelInit、BeforeSystemInit、AfterSystemInit、Ready、FailedInitialization、Destroying、Destroyed） -- **模块安装系统**：支持通过 `InstallModule` 扩展架构功能 -- **异步初始化**：支持同步和异步两种初始化方式 -- **IoC 容器集成**：内置依赖注入容器 -- **事件系统集成**：集成类型化事件系统 -- **与平台无关**：Core 模块不依赖 Godot，可以在任何 .NET 环境中使用 -- **严格的阶段验证**：可配置的阶段转换验证机制 -- **组件生命周期管理**：自动管理组件的初始化和销毁 - -**架构阶段：** -```csharp -public enum ArchitecturePhase + IArchitectureContext? context = null) { - None = 0, // 初始阶段 - BeforeUtilityInit = 1, // 工具初始化前 - AfterUtilityInit = 2, // 工具初始化后 - BeforeModelInit = 3, // 模型初始化前 - AfterModelInit = 4, // 模型初始化后 - BeforeSystemInit = 5, // 系统初始化前 - AfterSystemInit = 6, // 系统初始化后 - Ready = 7, // 就绪状态 - FailedInitialization = 8, // 初始化失败 - Destroying = 9, // 正在销毁 - Destroyed = 10 // 已销毁 + 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); } ``` -**初始化流程：** +**优势**: -1. 创建架构实例（传入配置或使用默认配置） -2. 初始化基础上下文和日志系统 -3. 调用用户自定义的 `Init()` 方法 -4. 按顺序初始化组件： - - 工具初始化（BeforeUtilityInit → AfterUtilityInit） - - 模型初始化（BeforeModelInit → AfterModelInit） - - 系统初始化（BeforeSystemInit → AfterSystemInit） -5. 冻结 IOC 容器 -6. 进入 Ready 阶段 +- 消除 `null!` 断言,提高代码安全性 +- 对象在构造后立即可用 +- 符合"构造即完整"原则 +- 可以在 InitializeAsync 之前访问事件 -**销毁流程：** +## 生命周期管理 -1. 进入 Destroying 阶段 -2. 按注册逆序销毁所有实现了 `IDisposable` 的组件 -3. 进入 Destroyed 阶段 -4. 清理所有资源 +### 架构阶段 -**使用示例:** +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 -// 1. 定义你的架构（继承 Architecture 基类） -public class GameArchitecture : Architecture +public class MyArchitecture : Architecture { - protected override void Init() + protected override void OnInitialize() { - // 注册 Model - RegisterModel(new PlayerModel()); - RegisterModel(new InventoryModel()); - - // 注册 System - RegisterSystem(new GameplaySystem()); - RegisterSystem(new SaveSystem()); - - // 注册 Utility - RegisterUtility(new StorageUtility()); - RegisterUtility(new TimeUtility()); - } -} - -// 2. 创建并初始化架构 -var architecture = new GameArchitecture(); -architecture.Initialize(); - -// 或者异步初始化 -// var architecture = new GameArchitecture(); -// await architecture.InitializeAsync(); - -// 3. 等待架构就绪 -await architecture.WaitUntilReadyAsync(); - -// 4. 通过依赖注入使用架构 -// 在 Controller 或其他组件中获取架构实例 -using GFramework.Core.Abstractions.Controller; -using GFramework.SourceGenerators.Abstractions.Rule; - -[ContextAware] -public partial class GameController : IController -{ - public void Start() - { - // 获取 Model（使用扩展方法访问架构（[ContextAware] 实现 IContextAware 接口）） - var playerModel = this.GetModel(); - - // 发送命令 - this.SendCommand(new StartGameCommand()); - - // 发送查询 - var score = this.SendQuery(new GetScoreQuery()); - - // 注册事件 - this.RegisterEvent(OnPlayerDied); - } - - private void OnPlayerDied(PlayerDiedEvent e) - { - // 处理玩家死亡事件 + // 监听阶段变化 + PhaseChanged += phase => + { + Console.WriteLine($"Phase changed to: {phase}"); + }; } } ``` -**核心方法与属性:** +### 生命周期钩子 -#### 初始化方法 - -**Initialize()** - -同步初始化方法，阻塞当前线程直到初始化完成。 -```csharp -public void Initialize() -``` - -**特点：** - -- 阻塞式初始化 -- 适用于简单场景或控制台应用 -- 初始化失败时抛出异常并进入 `FailedInitialization` 阶段 - -使用示例： -```csharp -var architecture = new GameArchitecture(); -architecture.Initialize(); // 阻塞等待初始化完成 -``` - -异常处理：如果初始化过程中发生异常，架构会进入 `FailedInitialization` 阶段。 - -**InitializeAsync()** - -异步初始化方法，返回 Task 以便调用者可以等待初始化完成。 -```csharp -public async Task InitializeAsync() -``` - -**特点：** - -- 非阻塞式初始化 -- 支持异步组件初始化 -- 适用于需要异步加载资源的场景 -- 初始化失败时抛出异常并进入 `FailedInitialization` 阶段 - -使用示例： -```csharp -var architecture = new GameArchitecture(); -await architecture.InitializeAsync(); // 异步等待初始化完成 -``` - -优势： -- 支持异步初始化 Model 和 System -- 可以利用异步 I/O 操作（如异步加载数据） -- 提高初始化性能 -- 不会阻塞主线程 - -#### 模块管理 - -**InstallModule(IArchitectureModule module)** - -安装架构模块，用于扩展架构功能。 -```csharp -public IArchitectureModule InstallModule(IArchitectureModule module) -``` - -**返回值：** 返回安装的模块实例 - -**特点：** - -- 模块安装时会自动注册生命周期钩子 -- 模块可以注册额外的组件到架构中 -- 只能在架构进入 Ready 阶段之前安装模块 - -参数： - -- `module`：要安装的模块实例 - -使用示例： +实现 `IArchitectureLifecycleHook` 接口可以在阶段变化时执行自定义逻辑: ```csharp -// 定义模块 -public class NetworkModule : IArchitectureModule -{ - public void Install(IArchitecture architecture) - { - // 注册网络相关的 System 和 Utility - architecture.RegisterSystem(new NetworkSystem()); - architecture.RegisterUtility(new HttpClientUtility()); - } -} - -// 安装模块 -var architecture = new GameArchitecture(); -var installedModule = architecture.InstallModule(new NetworkModule()); -``` - -#### 生命周期钩子 - -**RegisterLifecycleHook(IArchitectureLifecycle hook)** - -注册生命周期钩子，用于在架构阶段变化时执行自定义逻辑。 -```csharp -public IArchitectureLifecycle RegisterLifecycleHook(IArchitectureLifecycle hook) -``` - -**返回值：** 返回注册的生命周期钩子实例 - -**特点：** - -- 生命周期钩子可以监听所有架构阶段变化 -- 只能在架构进入 Ready 阶段之前注册 -- 架构会按注册顺序通知所有钩子 - -参数： - -- `hook`：生命周期钩子实例 - -使用示例： - -```csharp -// 定义生命周期钩子 -public class PerformanceMonitorHook : IArchitectureLifecycle +public class MyLifecycleHook : IArchitectureLifecycleHook { public void OnPhase(ArchitecturePhase phase, IArchitecture architecture) { switch (phase) { - case ArchitecturePhase.BeforeModelInit: - Console.WriteLine("开始监控 Model 初始化性能"); - break; - case ArchitecturePhase.AfterModelInit: - Console.WriteLine("Model 初始化完成,停止监控"); - break; case ArchitecturePhase.Ready: - Console.WriteLine("架构就绪,开始性能统计"); - break; - } - } -} - -// 注册生命周期钩子 -var architecture = new GameArchitecture(); -var registeredHook = architecture.RegisterLifecycleHook(new PerformanceMonitorHook()); -architecture.Initialize(); -``` - -**注意：** 生命周期钩子只能在架构进入 Ready 阶段之前注册。 - -#### 属性 - -**CurrentPhase** - -获取当前架构的阶段。 -```csharp -public ArchitecturePhase CurrentPhase { get; private set; } -``` - -**特点：** - -- 只读属性，外部无法直接修改 -- 实时反映架构的当前状态 -- 可用于条件判断和状态检查 - -使用示例： - -```csharp -var architecture = new GameArchitecture(); - -// 检查架构是否已就绪 -if (architecture.CurrentPhase == ArchitecturePhase.Ready) -{ - Console.WriteLine("架构已就绪,可以开始游戏"); -} - -// 在异步操作中检查阶段变化 -await Task.Run(async () => -{ - while (architecture.CurrentPhase != ArchitecturePhase.Ready) - { - Console.WriteLine($"当前阶段: {architecture.CurrentPhase}"); - await Task.Delay(100); - } -}); -``` - -**Context** - -获取架构上下文，提供对架构服务的访问。 -```csharp -public IArchitectureContext Context { get; } -``` - -**特点：** - -- 提供对架构核心服务的访问 -- 包含事件总线、命令总线、查询总线等 -- 是架构内部服务的统一入口 - -使用示例： - -```csharp -// 通过 Context 访问服务 -var context = architecture.Context; -var eventBus = context.EventBus; -var commandBus = context.CommandBus; -var queryBus = context.QueryBus; -var environment = context.Environment; -``` - -#### 高级特性 - -```csharp -// 1. 使用自定义配置 -var config = new ArchitectureConfiguration -{ - ArchitectureProperties = new ArchitectureProperties - { - StrictPhaseValidation = true, // 启用严格阶段验证 - AllowLateRegistration = false // 禁止就绪后注册组件 - } -}; -var architecture = new GameArchitecture(configuration: config); - -// 2. 模块安装 -var module = new GameModule(); -architecture.InstallModule(module); - -// 3. 监听架构阶段变化 -public class GamePhaseListener : IArchitecturePhaseAware -{ - public void OnArchitecturePhase(ArchitecturePhase phase) - { - switch (phase) - { - case ArchitecturePhase.Ready: - Console.WriteLine("架构已就绪,可以开始游戏了"); + Console.WriteLine("Architecture is ready!"); break; case ArchitecturePhase.Destroying: - Console.WriteLine("架构正在销毁"); + Console.WriteLine("Architecture is being destroyed!"); break; } } } -// 4. 生命周期钩子 -public class LifecycleHook : IArchitectureLifecycle -{ - public void OnPhase(ArchitecturePhase phase, IArchitecture architecture) - { - Console.WriteLine($"架构阶段变化: {phase}"); - } -} - -// 5. 等待架构就绪 -public async Task WaitForArchitectureReady() -{ - var architecture = new GameArchitecture(); - var initTask = architecture.InitializeAsync(); - - // 可以在其他地方等待架构就绪 - await architecture.WaitUntilReadyAsync(); - Console.WriteLine("架构已就绪"); -} +// 注册钩子 +architecture.RegisterLifecycleHook(new MyLifecycleHook()); ``` -### ArchitectureConfiguration 架构配置类 +### 初始化流程 -架构配置类，用于配置架构的行为。 +``` +1. 创建 Architecture 实例 + └─> 构造函数初始化管理器 -**主要配置项：** +2. 调用 InitializeAsync() 或 Initialize() + ├─> 初始化环境 (Environment.Initialize()) + ├─> 注册内置服务模块 + ├─> 初始化架构上下文 + ├─> 执行服务钩子 + ├─> 初始化服务模块 + ├─> 调用 OnInitialize() (用户注册组件) + ├─> 初始化所有组件 + │ ├─> BeforeUtilityInit → 初始化 Utility → AfterUtilityInit + │ ├─> BeforeModelInit → 初始化 Model → AfterModelInit + │ └─> BeforeSystemInit → 初始化 System → AfterSystemInit + ├─> 冻结 IoC 容器 + └─> 进入 Ready 阶段 -```csharp -public class ArchitectureConfiguration : IArchitectureConfiguration -{ - public IArchitectureProperties ArchitectureProperties { get; set; } = new ArchitectureProperties(); - public IEnvironmentProperties EnvironmentProperties { get; set; } = new EnvironmentProperties(); - public ILoggerProperties LoggerProperties { get; set; } = new LoggerProperties(); -} - -public class ArchitectureProperties -{ - public bool StrictPhaseValidation { get; set; } = false; // 严格阶段验证 - public bool AllowLateRegistration { get; set; } = true; // 允许延迟注册 -} +3. 等待就绪 (可选) + └─> await architecture.WaitUntilReadyAsync() ``` -**使用示例：** +### 销毁流程 -```csharp -var config = new ArchitectureConfiguration -{ - ArchitectureProperties = new ArchitectureProperties - { - StrictPhaseValidation = true, // 启用严格阶段验证 - AllowLateRegistration = false // 禁止就绪后注册组件 - }, - LoggerProperties = new LoggerProperties - { - LoggerFactoryProvider = new ConsoleLoggerFactoryProvider() // 自定义日志工厂 - } -}; - -var architecture = new GameArchitecture(configuration: config); ``` - -### ArchitectureServices 架构服务类 - -架构服务类，管理命令总线、查询总线、IOC容器和类型事件系统。 - -**核心服务：** - -- `IIocContainer Container`：依赖注入容器 -- `IEventBus EventBus`：事件总线 -- `ICommandBus CommandBus`：命令总线 -- `IQueryBus QueryBus`：查询总线 - -### ArchitectureContext 架构上下文类 - -架构上下文类，提供对架构服务的访问。 - -**功能：** - -- 统一访问架构核心服务 -- 管理服务实例的生命周期 -- 提供服务解析功能 - -### GameContext 游戏上下文类 - -游戏上下文类，管理架构上下文与类型的绑定关系。 - -**功能：** - -- 维护架构类型与上下文实例的映射 -- 提供全局上下文访问 -- 支持多架构实例管理 - -## 设计模式 - -### 1. 依赖注入 - -通过构造函数注入或容器解析获取架构实例。 - -### 2. 控制反转 (IoC) - -使用内置 IoC 容器管理组件生命周期和依赖关系。 - -### 3. 命令模式 - -通过 `ICommand` 封装所有用户操作。 - -### 4. 查询模式 (CQRS) - -通过 `IQuery` 分离查询和命令操作。 - -### 5. 观察者模式 - -通过事件系统实现组件间的松耦合通信。 - -### 6. 阶段式生命周期管理 - -通过 `ArchitecturePhase` 枚举和生命周期钩子管理架构状态。 - -### 7. 组合优于继承 - -通过接口组合获得不同能力，而不是深层继承链。 - -### 8. 模块化设计 - -通过 `IArchitectureModule` 实现架构的可扩展性。 - -### 9. 工厂模式 - -通过配置对象和工厂方法创建架构实例。 - -## 最佳实践 - -1. **保持架构类简洁**：只在 `Init()` 中注册组件，不要包含业务逻辑 -2. **合理划分职责**： - - Model：数据和状态 - - System：业务逻辑和规则 - - Utility：无状态的工具方法 -3. **使用依赖注入**：通过构造函数注入架构实例，便于测试 -4. **事件命名规范**：使用过去式命名事件类，如 `PlayerDiedEvent` -5. **避免循环依赖**：System 不应直接引用 System，应通过事件通信 -6. **使用模块扩展**：通过 `IArchitectureModule` 实现架构的可扩展性 -7. **Core 模块与平台解耦**：GFramework.Core 不包含 Godot 相关代码，Godot 集成在单独模块中 -8. **合理配置阶段验证**：根据项目需求配置 `StrictPhaseValidation` 和 `AllowLateRegistration` -9. **及时处理初始化异常**：捕获并处理架构初始化过程中的异常 -10. **使用异步初始化**：对于需要加载大量资源的场景，优先使用 `InitializeAsync()` - -## 相关包 - -- **command** - 命令模式实现 -- **query** - 查询模式实现 -- **events** - 事件系统 -- **ioc** - IoC 容器 -- **model** - 数据模型 -- **system** - 业务系统 -- **utility** - 工具类 -- **GFramework.Godot** - Godot 特定集成（GodotNode 扩展、GodotLogger 等） -- **extensions** - 扩展方法 -- **logging** - 日志系统 -- **environment** - 环境管理 +1. 调用 DestroyAsync() 或 Destroy() + ├─> 检查当前阶段 (如果是 None 或已销毁则直接返回) + ├─> 进入 Destroying 阶段 + ├─> 逆序销毁所有组件 + │ ├─> 优先调用 IAsyncDestroyable.DestroyAsync() + │ └─> 否则调用 IDestroyable.Destroy() + ├─> 销毁服务模块 + ├─> 清空 IoC 容器 + └─> 进入 Destroyed 阶段 +``` --- -**许可证**：Apache 2.0 \ No newline at end of file +**版本**: 1.1.0 +**更新日期**: 2026-03-17 +**相关文档**: + +- [核心框架概述](./index.md) +- [ADR-001: 拆分 Architecture 核心类](/docs/adr/001-split-architecture-class.md) diff --git a/docs/zh-CN/core/index.md b/docs/zh-CN/core/index.md index 1d1cfda..189f0a6 100644 --- a/docs/zh-CN/core/index.md +++ b/docs/zh-CN/core/index.md @@ -65,15 +65,48 @@ Event ──┘ ### 架构阶段 +框架提供了精细化的生命周期管理,包含 11 个阶段: + ``` -初始化：Init → BeforeUtilityInit → AfterUtilityInit → BeforeModelInit → AfterModelInit → BeforeSystemInit → AfterSystemInit → Ready -销毁：Destroy → Destroying → Destroyed +初始化流程: +None → BeforeUtilityInit → AfterUtilityInit → BeforeModelInit → AfterModelInit → BeforeSystemInit → AfterSystemInit → Ready + +销毁流程: +Ready → Destroying → Destroyed + +异常流程: +Any → FailedInitialization ``` +每个阶段都会触发 `PhaseChanged` 事件,允许组件监听架构状态变化。 + ## 架构图 ### 整体架构 +从 v1.1.0 开始,Architecture 类采用模块化设计,将职责分离到专门的管理器中: + +``` + ┌──────────────────┐ + │ Architecture │ ← 核心协调器 + └────────┬─────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ + ┌────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐ + │ Lifecycle │ │ Component │ │ Modules │ + │ Manager │ │ Registry │ │ Manager │ + └─────────────┘ └─────────────┘ └─────────────────┘ + │ │ │ + │ │ │ + 生命周期管理 组件注册管理 模块管理 + - 阶段转换 - System 注册 - 模块安装 + - 钩子管理 - Model 注册 - 行为注册 + - 初始化/销毁 - Utility 注册 +``` + +这种设计遵循单一职责原则,使代码更易维护和测试。详见 [ADR-001](/docs/adr/001-split-architecture-class.md)。 + ``` ┌──────────────────┐ │ Architecture │ ← 管理所有组件 @@ -284,6 +317,93 @@ public class PlayerController : IController ## 包说明 +### Architecture 内部结构 (v1.1.0+) + +从 v1.1.0 开始,Architecture 类采用模块化设计,将原本 708 行的单一类拆分为 4 个职责清晰的类: + +#### 1. Architecture (核心协调器) + +**职责**: 提供统一的公共 API,协调各个管理器 + +**主要方法**: + +- `RegisterSystem()` - 注册系统 +- `RegisterModel()` - 注册模型 +- `RegisterUtility()` - 注册工具 +- `InstallModule()` - 安装模块 +- `InitializeAsync()` / `Initialize()` - 初始化架构 +- `DestroyAsync()` / `Destroy()` - 销毁架构 + +**事件**: + +- `PhaseChanged` - 阶段变更事件 + +#### 2. ArchitectureLifecycle (生命周期管理器) + +**职责**: 管理架构的生命周期和阶段转换 + +**核心功能**: + +- 11 个架构阶段的管理和转换 +- 生命周期钩子 (IArchitectureLifecycleHook) 管理 +- 组件初始化 (按 Utility → Model → System 顺序) +- 组件销毁 (逆序销毁) +- 就绪状态管理 + +**关键方法**: + +- `EnterPhase()` - 进入指定阶段 +- `RegisterLifecycleHook()` - 注册生命周期钩子 +- `InitializeAllComponentsAsync()` - 初始化所有组件 +- `DestroyAsync()` - 异步销毁 + +#### 3. ArchitectureComponentRegistry (组件注册管理器) + +**职责**: 管理 System、Model、Utility 的注册 + +**核心功能**: + +- 组件注册和验证 +- 自动设置组件上下文 (IContextAware) +- 自动注册组件生命周期 (IInitializable、IDestroyable) +- 支持实例注册和类型注册 + +**关键方法**: + +- `RegisterSystem()` - 注册系统 +- `RegisterModel()` - 注册模型 +- `RegisterUtility()` - 注册工具 + +#### 4. ArchitectureModules (模块管理器) + +**职责**: 管理架构模块和中介行为 + +**核心功能**: + +- 模块安装 (IArchitectureModule) +- 中介行为注册 (Mediator Behaviors) + +**关键方法**: + +- `InstallModule()` - 安装模块 +- `RegisterMediatorBehavior()` - 注册中介行为 + +#### 设计优势 + +这种模块化设计带来以下优势: + +1. **单一职责**: 每个类只负责一个明确的功能 +2. **易于测试**: 可以独立测试每个管理器 +3. **易于维护**: 修改某个功能不影响其他功能 +4. **易于扩展**: 添加新功能更容易 +5. **代码安全**: 消除了 `null!` 断言,所有字段在构造后立即可用 + +详细的设计决策请参考 [ADR-001: 拆分 Architecture 核心类](/docs/adr/001-split-architecture-class.md)。 + +--- + +## 包说明 + | 包名 | 职责 | 文档 | |------------------|-----------------|----------------------| | **architecture** | 架构核心，管理所有组件生命周期 | [查看](./architecture) | @@ -308,12 +428,25 @@ public class PlayerController : IController ``` 创建 Architecture 实例 - └─> Init() - ├─> RegisterModel → Model.SetContext() → Model.Init() - ├─> RegisterSystem → System.SetContext() → System.Init() - └─> RegisterUtility → Utility 注册到容器 + └─> 构造函数 + ├─> 初始化 Logger + ├─> 创建 ArchitectureLifecycle + ├─> 创建 ArchitectureComponentRegistry + └─> 创建 ArchitectureModules + └─> InitializeAsync() + ├─> OnInitialize() (用户注册组件) + │ ├─> RegisterModel → Model.SetContext() + │ ├─> RegisterSystem → System.SetContext() + │ └─> RegisterUtility → 注册到容器 + └─> InitializeAllComponentsAsync() + ├─> BeforeUtilityInit → Utility.Initialize() + ├─> BeforeModelInit → Model.Initialize() + ├─> BeforeSystemInit → System.Initialize() + └─> Ready ``` +**重要变更 (v1.1.0)**: 管理器现在在构造函数中初始化,而不是在 InitializeAsync 中。这消除了 `null!` 断言,提高了代码安全性。 + ### 2. Command 执行流程 ``` @@ -503,5 +636,21 @@ public interface IController : --- -**版本**: 1.0.0 -**许可证**: Apache 2.0 \ No newline at end of file +**版本**: 1.1.0 +**更新日期**: 2026-03-17 +**许可证**: Apache 2.0 + +## 更新日志 + +### v1.1.0 (2026-03-17) + +**重大重构**: + +- 拆分 Architecture 类为 4 个职责清晰的类 +- 消除 3 处 `null!` 强制断言,提高代码安全性 +- 在构造函数中初始化管理器,符合"构造即完整"原则 +- 添加 `PhaseChanged` 事件,支持阶段监听 + +**向后兼容**: 所有公共 API 保持不变,现有代码无需修改。 + +详见 [ADR-001: 拆分 Architecture 核心类](/docs/adr/001-split-architecture-class.md) \ No newline at end of file diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 7f8aa38..699856f 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -189,7 +189,7 @@ public class GameArchitecture : Architecture } } -// ✅ 使用 IOC 容器注册 +// ✅ 使用 IoC 容器注册 protected override void ConfigureServices(IServiceCollection services) { services.AddSingleton<IPlayerService, PlayerService>();