GFramework/GFramework.Core.Abstractions

GFramework.Core.Abstractions 抽象层

GFramework 框架的接口定义模块，提供所有核心组件的抽象契约

概述

GFramework.Core.Abstractions 是 GFramework 框架的抽象层定义模块，包含了框架中所有核心组件的接口（Interface）、枚举（Enum）和配置类（Class）。该模块采用 netstandard2.0 作为目标框架，确保了广泛的兼容性和可移植性。

本模块遵循以下设计原则：

• 接口隔离：每个接口职责单一，便于实现和测试
• 依赖倒置：上层模块依赖抽象接口，而非具体实现
• 组合优于继承：通过接口组合获得能力，而非通过继承获得
• 类型安全：充分利用泛型系统确保类型安全

本模块的包 ID 为 GeWuYou.GFramework.Core.Abstractions，遵循命名空间 GFramework.Core.Abstractions 下的所有定义。

目录结构

GFramework.Core.Abstractions/
├── architecture/         # 架构核心接口
│   ├── IArchitecture.cs
│   ├── IArchitectureConfiguration.cs
│   ├── IArchitectureContext.cs
│   ├── IArchitectureLifecycle.cs
│   ├── IArchitectureModule.cs
│   ├── IArchitecturePhaseAware.cs
│   ├── IArchitectureServices.cs
│   └── IAsyncInitializable.cs
├── command/              # 命令模式接口
│   ├── ICommand.cs
│   ├── ICommandBus.cs
│   └── ICommandInput.cs
├── controller/           # 控制器接口
│   └── IController.cs
├── enums/                # 枚举定义
│   └── ArchitecturePhase.cs
├── environment/          # 环境接口
│   └── IEnvironment.cs
├── events/               # 事件系统接口
│   ├── IEasyEvent.cs
│   ├── ITypeEventSystem.cs
│   ├── IUnRegister.cs
│   └── IUnRegisterList.cs
├── ioc/                  # 依赖注入容器接口
│   └── IIocContainer.cs
├── logging/              # 日志系统接口
│   ├── ILogger.cs
│   ├── ILoggerFactory.cs
│   ├── ILoggerFactoryProvider.cs
│   └── LogLevel.cs
├── model/                # 模型接口
│   └── IModel.cs
├── properties/           # 配置类
│   ├── ArchitectureProperties.cs
│   └── LoggerProperties.cs
├── property/             # 可绑定属性接口
│   ├── IBindableProperty.cs
│   └── IReadonlyBindableProperty.cs
├── query/                # 查询模式接口
│   ├── IQuery.cs
│   ├── IQueryBus.cs
│   └── IQueryInput.cs
├── rule/                 # 规则接口
│   ├── IContextAware.cs
│   └── ILogAware.cs
├── system/               # 系统接口
│   └── ISystem.cs
└── utility/              # 工具接口
    ├── IContextUtility.cs
    └── IUtility.cs

模块说明

1. architecture（架构核心）

架构模块是整个框架的核心，定义了应用架构的生命周期管理和组件注册机制。该模块包含以下接口：

IArchitecture

架构接口是整个应用的核心管理器，负责管理系统、模型和工具类的注册与获取。它继承自 IAsyncInitializable 接口，支持异步初始化。该接口提供了注册系统（ RegisterSystem<T>）、注册模型（ RegisterModel<T>）、注册工具（ RegisterUtility<T>）的方法，以及安装模块（ InstallModule）和注册生命周期钩子（ RegisterLifecycleHook）的功能。

IArchitectureContext

架构上下文接口提供了对已注册组件的访问能力，是组件之间通信的桥梁。通过该接口，可以获取系统（ GetSystem<TSystem>）、模型（ GetModel<TModel>）和工具（ GetUtility<TUtility>）实例。同时，该接口还支持发送命令（ SendCommand）、发送查询（ SendQuery）和发送事件（ SendEvent）等横切操作。

IArchitectureConfiguration

架构配置接口定义了框架的配置选项，包括日志配置（LoggerProperties ）和架构配置（ArchitectureProperties ）。通过该接口，可以在运行时调整框架的行为，如设置日志级别、启用延迟注册等。

IArchitectureLifecycle

架构生命周期接口定义了架构在不同阶段的回调方法。当架构进入特定阶段时，会通知所有注册的生命周期监听器。该接口主要用于模块化架构的阶段感知。

IArchitectureModule

架构模块接口继承自 IArchitectureLifecycle 和 IArchitecturePhaseAware 接口，定义了模块安装到架构的标准方法（ Install）。通过模块化机制，可以将复杂功能封装为可插拔的模块。

IArchitecturePhaseAware

架构阶段感知接口允许组件在架构的不同阶段执行相应的逻辑。该接口提供了 OnArchitecturePhase 方法，当架构进入指定阶段时会被调用。

IArchitectureServices

架构服务接口定义了框架核心服务组件，继承自 IContextAware 接口。该接口提供了依赖注入容器（ Container）、类型事件系统（ TypeEventSystem）、命令总线（ CommandBus）和查询总线（ QueryBus）的访问能力。

IAsyncInitializable

异步初始化接口定义了组件的异步初始化方法（InitializeAsync ）。该接口用于需要执行异步初始化操作的组件，如加载资源、建立网络连接等。

2. command（命令模式）

命令模块实现了命令查询职责分离模式（CQRS）中的命令部分，用于封装写操作。该模块包含以下接口：

ICommand

命令接口定义了无返回值命令的基本契约，继承自 IContextAware 接口。该接口提供了命令执行方法（ Execute），用于执行具体的业务逻辑。带返回值的命令由泛型接口 ICommand<TResult> 定义，同样继承自 IContextAware 接口。

ICommandBus

命令总线接口负责命令的发送和执行调度。该接口提供了发送无返回值命令（Send ）和发送带返回值命令（Send<TResult>）的方法。

ICommandInput

命令输入接口是命令模式中输入数据的标记接口，不包含任何成员定义。该接口用于规范化命令的输入参数类型。

3. controller（控制器）

控制器模块定义了表现层与业务逻辑层之间的桥梁接口。

IController

控制器接口是 MVC 架构中控制层的抽象定义。该接口作为标记接口使用，不包含任何方法定义，但实现该接口的类通常会获得访问架构上下文的能力，从而可以发送命令、查询数据、注册事件等。

4. enums（枚举定义）

枚举模块定义了框架中使用的枚举类型。

ArchitecturePhase

架构阶段枚举定义了系统架构初始化和运行过程中的各个关键阶段。按照初始化流程，依次包括：None（无效阶段）、BeforeUtilityInit （工具类初始化之前）、AfterUtilityInit（工具类初始化之后）、BeforeModelInit（模型初始化之前）、AfterModelInit（模型初始化之后）、 BeforeSystemInit（系统初始化之前）、AfterSystemInit（系统初始化之后）、Ready（就绪阶段），以及销毁相关阶段：Destroying （正在销毁中）、Destroyed（已销毁）、FailedInitialization（初始化失败）。

5. environment（环境接口）

环境模块定义了应用程序运行环境的抽象接口。

IEnvironment

环境接口提供了获取应用程序运行环境相关信息的能力。该接口支持根据键值获取配置值（ Get<T>）、尝试获取环境值（TryGet ）、获取必需的环境值（GetRequired<T>），以及注册键值对（ Register）和初始化环境（Initialize）。

6. events（事件系统）

事件模块实现了框架的事件驱动通信机制，支持类型安全和松耦合的组件通信。

ITypeEventSystem

类型事件系统接口是基于类型的事件发布-订阅机制的抽象定义。该接口支持发送无参事件（ Send<T>）、发送带参事件（Send<T>）、注册事件监听器（ Register<T>）和注销事件监听器（UnRegister<T>）。

IEasyEvent

简单事件接口定义了基础的事件注册功能（Register）。该接口用于简单的无参事件场景。

IUnRegister

注销接口提供了事件监听器的注销功能（UnRegister）。所有事件注册方法的返回值都实现了该接口，用于在适当时机取消事件监听。

IUnRegisterList

统一注销接口提供了管理多个注销句柄的能力。该接口维护了一个注销对象列表（UnregisterList ），可以在批量注销时统一处理。

7. ioc（依赖注入）

IoC 模块实现了控制反转和依赖注入机制，用于管理组件的生命周期和依赖关系。

IIocContainer

依赖注入容器接口是框架的核心服务接口之一，继承自 IContextAware 接口。该接口提供了丰富的服务注册和解析方法，包括注册单例（RegisterSingleton<T> ）、注册多个实例（RegisterPlurality）、注册系统（RegisterSystem ）、注册类型（Register）等。在解析方面，支持获取单个实例（Get<T> ）、获取必需实例（GetRequired<T>）、获取所有实例（GetAll<T> ）和获取排序后的实例（GetAllSorted<T>）。此外，还提供了检查（ Contains）、清空（Clear）和冻结（ Freeze）等实用方法。

8. logging（日志系统）

日志模块提供了完整的日志记录抽象，支持多级别日志输出。

LogLevel

日志级别枚举定义了日志消息的严重程度等级，包括：Trace（跟踪级别，用于详细的程序执行流程信息）、Debug（调试级别，用于调试过程中的详细信息）、 Info（信息级别，用于一般性的程序运行信息）、Warning（警告级别，用于表示可能的问题或异常情况）、Error （错误级别，用于表示错误但程序仍可继续运行的情况）、Fatal（致命级别，用于表示严重的错误导致程序无法继续运行）。

ILogger

日志记录器接口是框架日志系统的核心接口，提供了完整的日志记录能力。该接口支持以下功能：

• 级别启用检查：提供了各个日志级别的是否启用检查方法，如 IsTraceEnabled、 IsDebugEnabled、IsInfoEnabled、 IsWarnEnabled、IsErrorEnabled、 IsFatalEnabled，以及通用的 IsEnabledForLevel 方法。
• 日志记录方法：每个日志级别都有多种重载形式，支持简单消息、格式化消息和异常记录。格式化为 Trace、Debug、Info、 Warn、Error、Fatal 六个级别，每个级别都提供了 msg、format+arg、format+arg1+arg2、format+params、msg+exception 等多种调用方式。
• 获取日志记录器名称：通过 Name 方法获取日志记录器的名称。

ILoggerFactory

日志工厂接口用于创建日志记录器实例（GetLogger）。该接口支持指定日志记录器名称和最小日志级别。

ILoggerFactoryProvider

日志工厂提供者接口扩展了日志工厂的功能，支持动态设置最小日志级别（MinLevel ）和创建日志记录器（CreateLogger）。

9. model（模型接口）

模型模块定义了数据层的抽象接口。

IModel

模型接口继承自 IContextAware 和 IArchitecturePhaseAware 接口，定义了模型组件的基本行为。该接口提供了模型初始化方法（Init），用于执行模型相关的初始化逻辑。

10. properties（配置类）

配置模块定义了框架使用的配置选项类。

LoggerProperties

日志配置选项类用于配置日志系统的相关参数，包含日志工厂提供程序属性（ LoggerFactoryProvider）。

ArchitectureProperties

架构选项配置类用于定义架构行为的相关配置选项，包含两个属性：AllowLateRegistration（允许延迟注册开关，控制是否允许在初始化完成后进行组件注册）和 StrictPhaseValidation（严格阶段验证开关，控制是否启用严格的阶段验证机制）。

11. property（可绑定属性）

可绑定属性模块实现了响应式数据绑定机制，支持数据变化的自动通知。

IReadonlyBindableProperty<T>

只读可绑定属性接口继承自 IEasyEvent 接口，提供了属性值的读取和变更监听功能。该接口支持获取当前值（Value ）、注册带初始值的回调（RegisterWithInitValue）、取消注册回调（ UnRegister）和注册回调（ Register）。

IBindableProperty<T>

可绑定属性接口继承自只读可绑定属性接口，提供了可读写的属性绑定功能。该接口在只读接口的基础上增加了属性值的设置能力（ Value 的 setter）以及不触发事件的设置方法（ SetValueWithoutEvent）。

12. query（查询模式）

查询模块实现了命令查询职责分离模式（CQRS）中的查询部分，用于封装读操作。

IQuery<TResult>

查询接口继承自 IContextAware 接口，定义了执行查询操作的契约。该接口提供了查询执行方法（ Do），返回指定类型的结果。

IQueryBus

查询总线接口负责查询的发送和执行调度。该接口提供了发送查询并返回结果的方法（Send<TResult>）。

IQueryInput

查询输入接口是查询模式中输入数据的标记接口，不包含任何成员定义。

13. rule（规则接口）

规则模块定义了框架组件需要遵循的约束和规则接口。

IContextAware

上下文感知接口允许实现类设置和获取架构上下文。该接口提供了设置上下文（SetContext ）和获取上下文（GetContext）的方法。框架中大多数核心组件（如命令、查询、系统、模型、工具、IoC 容器等）都实现了该接口，以获得访问架构服务的能力。

ILogAware

日志感知接口允许实现类设置和使用日志记录器。该接口提供了设置日志记录器的方法（SetLogger）。

14. system（系统接口）

系统模块定义了业务逻辑层的抽象接口。

ISystem

系统接口继承自 IContextAware 和 IArchitecturePhaseAware 接口，定义了系统组件的基本行为。该接口提供了系统初始化方法（Init）和系统销毁方法（ Destroy），用于管理系统的生命周期。

15. utility（工具接口）

工具模块定义了无状态工具类的抽象接口。

IUtility

工具接口是所有工具类实现的基础接口，作为标记接口使用，不包含任何成员定义。该接口定义了通用工具类的基本契约。

IContextUtility

上下文工具接口继承自 IUtility 和 IContextAware 接口，提供了具有上下文感知能力的工具功能。该接口在工具接口的基础上增加了初始化方法（ Init）。

接口继承关系图

IArchitecture
    └── IAsyncInitializable

IArchitectureModule
    ├── IArchitectureLifecycle
    └── IArchitecturePhaseAware

IArchitectureServices
    └── IContextAware

ICommand
    └── IContextAware

ICommand<TResult>
    └── IContextAware

IIocContainer
    └── IContextAware

IQuery<TResult>
    └── IContextAware

IModel
    ├── IContextAware
    └── IArchitecturePhaseAware

ISystem
    ├── IContextAware
    └── IArchitecturePhaseAware

IContextUtility
    ├── IUtility
    └── IContextAware

IReadonlyBindableProperty<T>
    └── IEasyEvent

IBindableProperty<T>
    └── IReadonlyBindableProperty<T>

核心能力接口

框架中的组件通过实现特定的接口来获得相应的能力。这些能力接口主要分为以下几类：

上下文感知能力

通过实现 IContextAware 接口，组件可以获得设置和获取架构上下文的能力，从而访问框架提供的各种服务。命令、查询、系统、模型、工具、IoC 容器等核心组件都实现了该接口。

日志能力

通过实现 ILogAware 接口，组件可以获得使用日志记录器的能力。该接口提供了设置日志记录器的方法，使组件可以输出日志信息。

阶段感知能力

通过实现 IArchitecturePhaseAware 接口，组件可以在架构的不同阶段执行相应的逻辑。该接口提供了 OnArchitecturePhase 方法，当架构进入指定阶段时会被调用。

使用指南

实现框架组件

当需要实现框架的组件时，通常需要实现相应的接口并遵循框架的生命周期约定：

// 实现系统组件
public class CombatSystem : ISystem
{
    public void Init()
    {
        // 系统初始化逻辑
    }
    
    public void Destroy()
    {
        // 系统销毁逻辑
    }
}

// 实现模型组件
public class PlayerModel : IModel
{
    public void Init()
    {
        // 模型初始化逻辑
    }
}

// 实现工具组件
public class StorageUtility : IUtility
{
    // 工具类方法
}

// 实现命令
public class AttackCommand : ICommand
{
    public void Execute()
    {
        // 命令执行逻辑
    }
}

// 实现查询
public class GetPlayerInfoQuery : IQuery<PlayerInfo>
{
    public PlayerInfo Do()
    {
        // 查询执行逻辑
    }
}

访问框架服务

通过实现 IContextAware 接口，组件可以获得访问框架服务的能力：

public class MySystem : ISystem
{
    private IArchitectureContext _context;
    
    public void SetContext(IArchitectureContext context)
    {
        _context = context;
    }
    
    public IArchitectureContext GetContext()
    {
        return _context;
    }
    
    private void SomeMethod()
    {
        // 获取其他组件
        var playerModel = _context.GetModel<PlayerModel>();
        
        // 发送命令
        _context.SendCommand(new AttackCommand());
        
        // 发送查询
        var health = _context.SendQuery(new GetHealthQuery());
        
        // 发送事件
        _context.SendEvent(new GameEvent());
        
        // 注册事件监听
        _context.RegisterEvent<EnemySpawnedEvent>(OnEnemySpawned);
    }
}

相关文档

• GFramework.Core - 核心框架实现模块
• GFramework.Godot - Godot 平台集成模块
• 架构模块文档 - 架构接口详细说明
• 控制器模块文档 - 控制器使用说明

---

版本: 1.0.0

许可证: Apache 2.0