gewuyou/GFramework
1
0
Fork 0
mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-22 10:34:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor(core): 重构架构和命令相关代码结构

Browse Source 
- 调整了 Architecture 类中字段和方法的布局，提升可读性
- 优化了命令执行逻辑，明确区分有无返回值的命令处理
- 规范了接口和抽象类的注释格式，增强文档清晰度
- 统一了代码风格，对齐缩进与换行符使用
- 补充了事件系统中泛型事件类的功能实现
- 完善了 README 文档中的条目结构和内容表述
This commit is contained in:
GwWuYou 2025-12-12 21:10:21 +08:00
parent 6da64eaf01
commit 82713e34f0
64 changed files with 1195 additions and 808 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
GFramework.Core.Godot/GFramework.Core.Godot.csproj
View File

@ -9,15 +9,16 @@
</PropertyGroup>
<ItemGroup>
<PackageReference Include="GodotSharpEditor" Version="4.5.1" />
<PackageReference Include="Godot.SourceGenerators" Version="4.5.1"/>
<PackageReference Include="GodotSharpEditor" Version="4.5.1"/>
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\GFramework.Core\GFramework.Core.csproj" />
<ProjectReference Include="..\GFramework.Core\GFramework.Core.csproj"/>
</ItemGroup>
<ItemGroup>
<Compile Remove="extensions\ControlExtensions.cs" />
<Compile Remove="extensions\ControlExtensions.cs"/>
</ItemGroup>
</Project>

181
GFramework.Core.Godot/component/DragDropComponent.cs Normal file
View File

@ -0,0 +1,181 @@
using GFramework.Core.architecture;
using GFramework.Core.controller;
using GFramework.Core.events;
using GFramework.Core.extensions;
using GFramework.Core.Godot.extensions;
using Godot;
namespace GFramework.Core.Godot.component;
/// <summary>
/// 拖拽组件类，用于处理节点的拖放逻辑。
/// 实现了 IController 接口以支持架构通信，并通过信号通知拖拽事件的发生。
/// </summary>
public abstract partial class DragDropComponent : Node, IController
{
/// <summary>
/// 当拖拽被取消时触发的信号。
/// </summary>
/// <param name="startingPosition">拖拽起始位置。</param>
[Signal]
public delegate void DragCanceledEventHandler(Vector2 startingPosition);
/// <summary>
/// 当拖拽开始时触发的信号。
/// </summary>
[Signal]
public delegate void DragStartedEventHandler();
/// <summary>
/// 当拖拽结束并放置时触发的信号。
/// </summary>
/// <param name="startingPosition">拖拽起始位置。</param>
[Signal]
public delegate void DroppedEventHandler(Vector2 startingPosition);
/// <summary>
/// 取消注册列表，用于管理需要在节点销毁时取消注册的对象
/// </summary>
private readonly IUnRegisterList _unRegisterList = new UnRegisterList();
private bool _isDragging;
private Vector2 _offset = Vector2.Zero;
private Vector2 _startingPosition;
/// <summary>
/// 目标区域，通常是可交互的游戏对象（如单位或物品）所在的碰撞区域。
/// </summary>
public required Area2D Target { get; set; }
/// <summary>
/// 是否启用拖拽功能。若为 false，则忽略所有输入事件。
/// </summary>
public bool Enable { get; set; }
public string GroupName { get; set; } = "dragging";
public int ZIndexMax { get; set; } = 99;
public int ZIndexMin { get; set; } = 0;
/// <summary>
/// 获取游戏架构实例
/// </summary>
/// <returns>返回游戏架构接口实例</returns>
public abstract IArchitecture GetArchitecture();
/// <summary>
/// 节点准备就绪时的回调方法。
/// 在节点添加到场景树后调用，绑定目标区域的输入事件处理器。
/// </summary>
public override void _Ready()
{
Target = GetParent() as Area2D ?? throw new InvalidOperationException("Target must be an Area2D node.");
Target.InputEvent += OnTargetInputEvent;
}
/// <summary>
/// 处理输入事件的方法
/// </summary>
/// <param name="event">输入事件对象</param>
public override void _Input(InputEvent @event)
{
// 处理取消拖拽操作：当正在拖拽且按下取消拖拽按键时，执行取消拖拽逻辑
if (!_isDragging || Target.IsInvalidNode() || !@event.IsActionPressed("cancel_drag")) return;
CancelDragging();
// 设置输入为处理，防止输入穿透
this.SetInputAsHandled();
}
/// <summary>
/// 处理目标区域接收到的输入事件。
/// 根据当前是否处于拖拽状态以及用户操作决定执行开始、取消或完成拖拽的动作。
/// </summary>
/// <param name="viewport">接收输入事件的视图端口节点。</param>
/// <param name="event">发生的输入事件。</param>
/// <param name="_">事件索引（未使用）。</param>
private void OnTargetInputEvent(Node viewport, InputEvent @event, long _)
{
if (!Enable) return;
// 获取当前正在拖拽的对象
var draggingObj = GetTree().GetFirstNodeInGroup(GroupName);
switch (_isDragging)
{
// 如果当前没有拖拽操作且已有其他对象正在拖拽，则直接返回
case false when draggingObj is not null:
return;
// 处理开始拖拽操作：当未在拖拽状态且按下选择按键时，开始拖拽
case false when @event.IsActionPressed("select"):
StartDragging();
break;
// 处理放置操作：当正在拖拽且释放选择按键时，执行放置逻辑
case true when @event.IsActionReleased("select"):
Drop();
break;
}
}
/// <summary>
/// 每帧更新逻辑，在拖拽过程中持续更新目标的位置。
/// </summary>
/// <param name="delta">与上一帧的时间间隔（秒）。</param>
public override void _Process(double delta)
{
if (_isDragging && Target.IsValidNode()) Target.GlobalPosition = Target.GetGlobalMousePosition() + _offset;
}
/// <summary>
/// 结束拖拽流程的基础方法。
/// 清除拖拽标志位并将目标从拖拽组中移除，恢复其层级顺序。
/// </summary>
private void EndDragging()
{
_isDragging = false;
Target.RemoveFromGroup(GroupName);
Target.ZIndex = ZIndexMin;
}
/// <summary>
/// 执行取消拖拽的操作。
/// 调用 EndDragging 并发出 DragCanceled 信号。
/// </summary>
private void CancelDragging()
{
EndDragging();
EmitSignalDragCanceled(_startingPosition);
}
/// <summary>
/// 开始拖拽操作。
/// 设置初始位置和偏移量，将目标加入拖拽组并提升显示层级，最后发出 DragStarted 信号。
/// </summary>
private void StartDragging()
{
_isDragging = true;
_startingPosition = Target.GlobalPosition;
Target.AddToGroup(GroupName);
Target.ZIndex = ZIndexMax;
_offset = Target.GlobalPosition - Target.GetGlobalMousePosition();
EmitSignalDragStarted();
}
/// <summary>
/// 完成一次拖拽操作。
/// 调用 EndDragging 方法并发出 Dropped 信号。
/// </summary>
private void Drop()
{
EndDragging();
EmitSignalDropped(_startingPosition);
}
/// <summary>
/// 节点退出场景树时的回调方法。
/// 在节点从场景树移除前调用，用于清理资源。
/// </summary>
public override void _ExitTree()
{
_unRegisterList.UnRegisterAll();
}
}

99
GFramework.Core.Godot/extensions/NodeExtensions.cs
View File

@ -1,87 +1,64 @@
using System;
using System.Threading.Tasks;
using Godot;
using Godot;
namespace GFramework.Core.Godot.extensions;
/// <summary>
/// 节点扩展方法类，提供对Godot节点的扩展功能
/// 节点扩展方法类，提供对Godot节点的扩展功能
/// </summary>
public static class NodeExtensions
{
/// <summary>
/// 安全地将节点加入删除队列，在下一帧开始时释放节点资源
/// 安全地将节点加入删除队列，在下一帧开始时释放节点资源
/// </summary>
/// <param name="node">要释放的节点实例</param>
public static void QueueFreeX(this Node? node)
{
// 检查节点是否为空
if (node is null)
{
return;
}
if (node is null) return;
// 检查节点实例是否有效
if (!GodotObject.IsInstanceValid(node))
{
return;
}
if (!GodotObject.IsInstanceValid(node)) return;
// 检查节点是否已经加入删除队列
if (node.IsQueuedForDeletion())
{
return;
}
if (node.IsQueuedForDeletion()) return;
// 延迟调用QueueFree方法，避免在当前帧中直接删除节点
node.CallDeferred(Node.MethodName.QueueFree);
}
/// <summary>
/// 立即释放节点资源，不等待下一帧
/// 立即释放节点资源，不等待下一帧
/// </summary>
/// <param name="node">要立即释放的节点实例</param>
public static void FreeX(this Node? node)
{
// 检查节点是否为空
if (node is null)
{
return;
}
if (node is null) return;
// 检查节点实例是否有效
if (!GodotObject.IsInstanceValid(node))
{
return;
}
if (!GodotObject.IsInstanceValid(node)) return;
// 检查节点是否已经加入删除队列
if (node.IsQueuedForDeletion())
{
return;
}
if (node.IsQueuedForDeletion()) return;
// 立即释放节点资源
node.Free();
}
/// <summary>
/// 如果节点尚未进入场景树，则等待 ready 信号。
/// 如果已经在场景树中，则立刻返回。
/// 如果节点尚未进入场景树，则等待 ready 信号。
/// 如果已经在场景树中，则立刻返回。
/// </summary>
public static async Task WaitUntilReady(this Node node)
{
if (!node.IsInsideTree())
{
await node.ToSignal(node, Node.SignalName.Ready);
}
if (!node.IsInsideTree()) await node.ToSignal(node, Node.SignalName.Ready);
}
/// <summary>
/// 检查节点是否有效：
/// 1. 非 null
/// 2. Godot 实例仍然存在（未被释放）
/// 3. 已经加入 SceneTree
/// 检查节点是否有效：
/// 1. 非 null
/// 2. Godot 实例仍然存在（未被释放）
/// 3. 已经加入 SceneTree
/// </summary>
public static bool IsValidNode(this Node? node)
{
@ -91,12 +68,11 @@ public static class NodeExtensions
}
/// <summary>
/// 检查节点是否无效：
/// 1. 为 null，或者
/// 2. Godot 实例已被释放，或者
/// 3. 尚未加入 SceneTree
///
/// 返回 true 表示该节点不可用。
/// 检查节点是否无效：
/// 1. 为 null，或者
/// 2. Godot 实例已被释放，或者
/// 3. 尚未加入 SceneTree
/// 返回 true 表示该节点不可用。
/// </summary>
public static bool IsInvalidNode(this Node? node)
{
@ -106,7 +82,7 @@ public static class NodeExtensions
}
/// <summary>
/// 将当前节点的输入事件标记为已处理，防止事件继续向父节点传播。
/// 将当前节点的输入事件标记为已处理，防止事件继续向父节点传播。
/// </summary>
/// <param name="node">要处理输入事件的节点实例</param>
public static void SetInputAsHandled(this Node node)
@ -116,7 +92,7 @@ public static class NodeExtensions
}
/// <summary>
/// 设置节点所在场景树的暂停状态
/// 设置节点所在场景树的暂停状态
/// </summary>
/// <param name="node">要操作的节点对象</param>
/// <param name="paused">暂停状态标识，默认为true表示暂停，false表示恢复运行</param>
@ -127,7 +103,7 @@ public static class NodeExtensions
}
/// <summary>
/// 查找指定名称的子节点并将其转换为指定类型
/// 查找指定名称的子节点并将其转换为指定类型
/// </summary>
/// <typeparam name="T">要转换到的目标节点类型</typeparam>
/// <param name="node">要在其子节点中进行查找的父节点</param>
@ -137,12 +113,12 @@ public static class NodeExtensions
public static T? FindChildX<T>(this Node node, string name, bool recursive = true)
where T : Node
{
var child = node.FindChild(name, recursive, owned: false);
var child = node.FindChild(name, recursive, false);
return child as T;
}
/// <summary>
/// 获取指定路径的节点，如果不存在则创建一个新的节点
/// 获取指定路径的节点，如果不存在则创建一个新的节点
/// </summary>
/// <typeparam name="T">节点类型，必须继承自Node且具有无参构造函数</typeparam>
/// <param name="node">父节点</param>
@ -163,7 +139,7 @@ public static class NodeExtensions
}
/// <summary>
/// 异步添加子节点并等待其准备就绪
/// 异步添加子节点并等待其准备就绪
/// </summary>
/// <param name="parent">父节点</param>
/// <param name="child">要添加的子节点</param>
@ -175,7 +151,7 @@ public static class NodeExtensions
}
/// <summary>
/// 获取父节点并将其转换为指定类型
/// 获取父节点并将其转换为指定类型
/// </summary>
/// <typeparam name="T">要转换到的目标节点类型</typeparam>
/// <param name="node">当前节点</param>
@ -184,8 +160,9 @@ public static class NodeExtensions
{
return node.GetParent() as T;
}
/// <summary>
/// 获取场景树的根节点的第一个子节点
/// 获取场景树的根节点的第一个子节点
/// </summary>
/// <param name="node">扩展方法的目标节点</param>
/// <returns>根节点的第一个子节点</returns>
@ -195,7 +172,7 @@ public static class NodeExtensions
}
/// <summary>
/// 遍历节点的所有子节点，并对指定类型的子节点执行特定操作
/// 遍历节点的所有子节点，并对指定类型的子节点执行特定操作
/// </summary>
/// <typeparam name="T">要筛选的节点类型</typeparam>
/// <param name="node">扩展方法的目标节点</param>
@ -208,7 +185,7 @@ public static class NodeExtensions
}
/// <summary>
/// 禁用节点所在场景树的输入处理功能
/// 禁用节点所在场景树的输入处理功能
/// </summary>
/// <param name="node">扩展方法的目标节点</param>
public static void DisableInput(this Node node)
@ -219,7 +196,7 @@ public static class NodeExtensions
}
/// <summary>
/// 启用节点所在场景树的输入处理功能
/// 启用节点所在场景树的输入处理功能
/// </summary>
/// <param name="node">扩展方法的目标节点</param>
public static void EnableInput(this Node node)
@ -230,7 +207,7 @@ public static class NodeExtensions
}
/// <summary>
/// 打印节点的路径信息到控制台
/// 打印节点的路径信息到控制台
/// </summary>
/// <param name="node">扩展方法的目标节点</param>
public static void LogNodePath(this Node node)
@ -239,7 +216,7 @@ public static class NodeExtensions
}
/// <summary>
/// 以树形结构递归打印节点及其所有子节点的名称
/// 以树形结构递归打印节点及其所有子节点的名称
/// </summary>
/// <param name="node">扩展方法的目标节点</param>
/// <param name="indent">缩进字符串，用于显示层级关系</param>
@ -253,7 +230,7 @@ public static class NodeExtensions
}
/// <summary>
/// 安全地延迟调用指定方法，确保节点有效后再执行
/// 安全地延迟调用指定方法，确保节点有效后再执行
/// </summary>
/// <param name="node">扩展方法的目标节点</param>
/// <param name="method">要延迟调用的方法名</param>
@ -263,6 +240,4 @@ public static class NodeExtensions
if (node != null && GodotObject.IsInstanceValid(node))
node.CallDeferred(method);
}
}

4
GFramework.Core.Godot/extensions/UnRegisterExtension.cs
View File

@ -4,12 +4,12 @@ using Godot;
namespace GFramework.Core.Godot.extensions;
/// <summary>
/// 提供取消注册扩展方法的静态类
/// 提供取消注册扩展方法的静态类
/// </summary>
public static class UnRegisterExtension
{
/// <summary>
/// 当节点退出场景树时自动取消注册监听器
/// 当节点退出场景树时自动取消注册监听器
/// </summary>
/// <param name="unRegister">需要在节点退出时被取消注册的监听器接口实例</param>
/// <param name="node">Godot节点对象，当该节点退出场景树时触发取消注册操作</param>

92
GFramework.Core/README.md
View File

@ -102,6 +102,7 @@ Event ──┘
### 为什么需要这个框架？
在传统的 Godot 开发中，我们经常遇到这些问题：
- 💔 **代码耦合严重**：UI 直接访问游戏逻辑，逻辑直接操作 UI
- 🔄 **难以维护**：修改一个功能需要改动多个文件
- 🐛 **难以测试**：业务逻辑和 UI 混在一起无法独立测试
@ -133,6 +134,7 @@ public class GameArchitecture : Architecture<GameArchitecture>
```
**优势**：
- ✅ **单例模式**：通过 `GameArchitecture.Interface` 全局访问
- ✅ **自动初始化**：注册时自动调用组件的 Init 方法
- ✅ **依赖注入**：组件自动获得架构引用，无需手动传递
@ -173,12 +175,14 @@ public class PlayerModel : AbstractModel
```
**优势**：
- ✅ **数据响应式**：BindableProperty 让数据变化自动通知 UI
- ✅ **职责单一**：只存储数据，不包含复杂业务逻辑
- ✅ **易于测试**：可以独立测试数据逻辑
- ✅ **数据持久化**：可以轻松序列化整个 Model 进行存档
**为什么不在 Model 中写业务逻辑？**
- 保持 Model 简单纯粹，业务逻辑应该在 System 中处理
- Model 应该是"被动"的，等待其他组件修改它
@ -209,12 +213,14 @@ public class CombatSystem : AbstractSystem
```
**优势**：
- ✅ **事件驱动**：通过事件解耦，不同 System 之间松耦合
- ✅ **可组合**：多个 System 协同工作，每个专注自己的领域
- ✅ **易于扩展**：新增功能只需添加新的 System 和事件监听
- ✅ **独立测试**：可以模拟事件来测试 System 的逻辑
**System 与 Model 的关系**：
- System 读取和修改 Model 的数据
- System 不应该存储重要的游戏状态（状态应在 Model 中）
- System 可以存储临时的计算结果或缓存
@ -251,18 +257,21 @@ public partial class PlayerController : Node, IController
```
**优势**：
- ✅ **自动更新 UI**：通过 BindableProperty，数据变化自动反映到界面
- ✅ **生命周期管理**：自动注销监听，避免内存泄漏
- ✅ **分离关注点**：UI 逻辑和业务逻辑完全分离
- ✅ **易于修改 UI**：改变 UI 不影响业务逻辑
**为什么使用 RegisterWithInitValue？**
- 注册监听时立即获得当前值，避免 UI 显示空白
- 后续数据变化会自动触发更新
### 完成！现在你有了一个完整的架构
这 4 步完成后，你就拥有了：
- 📦 **清晰的数据层**（Model）
- 🧠 **独立的业务逻辑**（System）
- 🎮 **灵活的控制层**（Controller）
@ -277,20 +286,20 @@ public partial class PlayerController : Node, IController
## 包说明
| 包名 | 职责 | 文档 |
|-----|------|------|
| 包名 | 职责 | 文档 |
|------------------|-----------------|---------------------------------|
| **architecture** | 架构核心，管理所有组件生命周期 | [📖 查看](architecture/README.md) |
| **model** | 数据模型层，存储游戏状态 | [📖 查看](model/README.md) |
| **system** | 业务逻辑层，处理游戏系统 | [📖 查看](system/README.md) |
| **controller** | 控制器层，连接视图和逻辑 | [📖 查看](controller/README.md) |
| **utility** | 工具类层，提供无状态工具 | [📖 查看](utility/README.md) |
| **command** | 命令模式，封装写操作 | [📖 查看](command/README.md) |
| **query** | 查询模式，封装读操作 | [📖 查看](query/README.md) |
| **events** | 事件系统，组件间通信 | [📖 查看](events/README.md) |
| **property** | 可绑定属性，响应式编程 | [📖 查看](property/README.md) |
| **ioc** | IoC 容器，依赖注入 | [📖 查看](ioc/README.md) |
| **rule** | 规则接口，定义组件约束 | [📖 查看](rule/README.md) |
| **extensions** | 扩展方法，简化 API 调用 | [📖 查看](extensions/README.md) |
| **model** | 数据模型层，存储游戏状态 | [📖 查看](model/README.md) |
| **system** | 业务逻辑层，处理游戏系统 | [📖 查看](system/README.md) |
| **controller** | 控制器层，连接视图和逻辑 | [📖 查看](controller/README.md) |
| **utility** | 工具类层，提供无状态工具 | [📖 查看](utility/README.md) |
| **command** | 命令模式，封装写操作 | [📖 查看](command/README.md) |
| **query** | 查询模式，封装读操作 | [📖 查看](query/README.md) |
| **events** | 事件系统，组件间通信 | [📖 查看](events/README.md) |
| **property** | 可绑定属性，响应式编程 | [📖 查看](property/README.md) |
| **ioc** | IoC 容器，依赖注入 | [📖 查看](ioc/README.md) |
| **rule** | 规则接口，定义组件约束 | [📖 查看](rule/README.md) |
| **extensions** | 扩展方法，简化 API 调用 | [📖 查看](extensions/README.md) |
## 组件联动
@ -346,6 +355,7 @@ Controller: Health.RegisterWithInitValue(hp => UpdateUI(hp))
#### ✅ 好的实践 vs ❌ 坏的实践
**Model 层**：
```csharp
// ✅ 好：只存储数据
public class PlayerModel : AbstractModel
@ -367,6 +377,7 @@ public class PlayerModel : AbstractModel
```
**System 层**：
```csharp
// ✅ 好：处理业务逻辑
public class CombatSystem : AbstractSystem
@ -398,6 +409,7 @@ public class CombatSystem : AbstractSystem
```
**Controller 层**：
```csharp
// ✅ 好：只处理 UI 和用户输入
public partial class AttackButton : Button, IController
@ -430,12 +442,12 @@ public partial class AttackButton : Button, IController
不同的通信方式适用于不同场景，选对方式能让代码更优雅。
| 通信方式 | 使用场景 | 示例 | 优势 |
|---------|---------|------|------|
| **Command** | 用户操作、修改状态 | 购买物品、攻击敌人 | 可撤销、可记录 |
| **Query** | 查询数据、检查条件 | 查询金币数量、检查是否可购买 | 明确只读意图 |
| **Event** | 通知其他组件 | 玩家死亡、物品拾取 | 松耦合、可扩展 |
| **BindableProperty** | 数据→UI 自动同步 | 生命值变化更新血条 | 自动化、不会遗漏 |
| 通信方式 | 使用场景 | 示例 | 优势 |
|----------------------|------------|----------------|----------|
| **Command** | 用户操作、修改状态 | 购买物品、攻击敌人 | 可撤销、可记录 |
| **Query** | 查询数据、检查条件 | 查询金币数量、检查是否可购买 | 明确只读意图 |
| **Event** | 通知其他组件 | 玩家死亡、物品拾取 | 松耦合、可扩展 |
| **BindableProperty** | 数据→UI 自动同步 | 生命值变化更新血条 | 自动化、不会遗漏 |
**实战示例：购物系统**
@ -527,6 +539,7 @@ public partial class GoldDisplay : Label, IController
**为什么需要注销？**
忘记注销监听器会导致：
- 💥 **内存泄漏**：对象无法被 GC 回收
- 🐛 **逻辑错误**：已销毁的对象仍在响应事件
- 📉 **性能下降**：无用的监听器消耗资源
@ -726,6 +739,7 @@ public class CombatSystemTests
```
**优势**：
- 不需要启动游戏就能测试逻辑
- 可以快速验证各种边界情况
- 易于进行回归测试
@ -840,6 +854,7 @@ protected override void Init()
```
**优势总结**：
- 数据驱动，易于存档
- 事件解耦，易于扩展
- UI 自动化，不会遗漏更新
@ -854,12 +869,14 @@ protected override void Init()
**理念**：每个类只负责一件事，只有一个改变的理由。
**在框架中的体现**：
- **Model**：只负责存储数据
- **System**：只负责处理业务逻辑
- **Controller**：只负责 UI 交互
- **Utility**：只负责提供工具方法
**好处**：
- 代码更容易理解和维护
- 修改一个功能不会影响其他功能
- 单元测试更简单
@ -869,11 +886,13 @@ protected override void Init()
**理念**：对扩展开放，对修改封闭。
**在框架中的实现**：
- 通过**事件系统**添加新功能，无需修改现有代码
- 新的 System 可以监听现有事件，插入自己的逻辑
- 符合"插件式"的架构设计
**示例**：
```csharp
// 现有：战斗系统
public class CombatSystem : AbstractSystem
@ -908,11 +927,13 @@ public class CriticalSystem : AbstractSystem
**理念**：依赖抽象（接口）而非具体实现。
**在框架中的应用**：
- 所有组件通过接口交互
- 通过 IoC 容器注入依赖
- 易于替换实现和编写测试
**好处**：
- 降低耦合度
- 易于进行单元测试（可以 mock）
- 可以灵活替换实现
@ -922,6 +943,7 @@ public class CriticalSystem : AbstractSystem
**理念**：使用多个专门的接口，而不是一个庞大的接口。
**在框架中的体现**：
```csharp
// 小而专注的接口
public interface ICanGetModel : IBelongToArchitecture { }
@ -936,6 +958,7 @@ public interface IController :
```
**优势**：
- 类只需要实现它真正需要的方法
- 接口更容易理解和使用
- 减少不必要的依赖
@ -945,11 +968,13 @@ public interface IController :
**理念**：通过接口组合获得能力，而不是通过继承。
**传统继承的问题**：
- 继承层次深，难以理解
- 子类与父类紧密耦合
- 难以灵活组合能力
**框架的解决方案**：
```csharp
// ✅ 通过接口组合能力
public interface IController :
@ -966,39 +991,44 @@ public class BattleController : GameController { }
### 框架核心设计模式 🎨
| 设计模式 | 应用位置 | 解决的问题 | 带来的好处 |
|---------|---------|-----------|-----------|
| **单例模式** | Architecture | 全局唯一的架构实例 | 统一的组件管理 |
| **工厂模式** | IoC 容器 | 组件的创建和管理 | 解耦创建逻辑 |
| **观察者模式** | Event 系统 | 组件间的通信 | 松耦合通信 |
| **命令模式** | Command | 封装操作请求 | 支持撤销重做 |
| **策略模式** | System | 不同的业务逻辑 | 易于切换策略 |
| **依赖注入** | 整体架构 | 组件间的依赖 | 自动管理依赖 |
| **模板方法** | Abstract 类 | 定义算法骨架 | 统一流程规范 |
| 设计模式 | 应用位置 | 解决的问题 | 带来的好处 |
|-----------|--------------|-----------|---------|
| **单例模式** | Architecture | 全局唯一的架构实例 | 统一的组件管理 |
| **工厂模式** | IoC 容器 | 组件的创建和管理 | 解耦创建逻辑 |
| **观察者模式** | Event 系统 | 组件间的通信 | 松耦合通信 |
| **命令模式** | Command | 封装操作请求 | 支持撤销重做 |
| **策略模式** | System | 不同的业务逻辑 | 易于切换策略 |
| **依赖注入** | 整体架构 | 组件间的依赖 | 自动管理依赖 |
| **模板方法** | Abstract 类 | 定义算法骨架 | 统一流程规范 |
### 为什么这样设计？🤔
#### 1. 降低学习成本
- 遵循业界标准模式和原则
- 有经验的开发者能快速上手
- 清晰的分层易于理解
#### 2. 提高代码质量
- 强制分层，避免意大利面代码
- 职责明确，减少 bug
- 易于 Code Review
#### 3. 便于团队协作
- 清晰的职责划分，减少冲突
- 统一的代码风格
- 新人容易融入项目
#### 4. 易于维护扩展
- 符合 SOLID 原则
- 通过事件添加功能无需修改现有代码
- 模块化设计，易于替换
#### 5. 支持单元测试
- 依赖注入让 mock 变得简单
- 接口设计便于测试
- 业务逻辑与 UI 分离，可独立测试
@ -1006,16 +1036,19 @@ public class BattleController : GameController { }
### 架构演进建议 🚀
#### 小型项目（< 5000 行代码）
- 使用基础的 MVC 分层
- 适度使用 Command 和 Query
- 事件系统用于关键通知
#### 中型项目（5000-20000 行）
- 完整使用框架所有特性
- 细分 System 的职责
- 引入更多 Utility 复用代码
#### 大型项目（> 20000 行）
- 考虑按功能模块拆分多个 Architecture
- 使用事件总线连接不同模块
- 引入领域驱动设计（DDD）概念
@ -1023,6 +1056,7 @@ public class BattleController : GameController { }
### 常见反模式 ⚠️
#### 反模式 1：上帝类（God Class）
```csharp
// ❌ 一个类做所有事情
public class GameManager
@ -1042,6 +1076,7 @@ public class SaveSystem { /* 只负责存档 */ }
```
#### 反模式 2：循环依赖
```csharp
// ❌ A 依赖 B，B 又依赖 A
public class SystemA
@ -1071,6 +1106,7 @@ public class SystemB
```
#### 反模式 3：过度设计
```csharp
// ❌ 简单功能过度抽象
public interface IClickable { }

262
GFramework.Core/architecture/Architecture.cs
View File

@ -9,43 +9,23 @@ using GFramework.Core.utility;
namespace GFramework.Core.architecture;
/// <summary>
/// 架构基类，提供系统、模型、工具等组件的注册与管理功能。
/// 使用单例模式确保全局唯一实例，并支持命令、查询和事件机制。
/// 架构基类，提供系统、模型、工具等组件的注册与管理功能。
/// 使用单例模式确保全局唯一实例，并支持命令、查询和事件机制。
/// </summary>
/// <typeparam name="T">派生类类型，用于实现单例</typeparam>
public abstract class Architecture<T> : IArchitecture where T : Architecture<T>, new()
{
/// <summary>
/// 标记架构是否已初始化完成
/// </summary>
private bool _mInited;
/// <summary>
/// 存储尚未初始化的系统集合，在初始化阶段统一调用Init方法
/// </summary>
private readonly HashSet<ISystem> _mSystems = [];
/// <summary>
/// 存储尚未初始化的模型集合，在初始化阶段统一调用Init方法
/// </summary>
private readonly HashSet<IModel> _mModels = [];
/// <summary>
/// 注册补丁委托，允许在架构创建后执行额外逻辑
/// </summary>
public static Action<T> OnRegisterPatch { get; set; } = _ => { };
/// <summary>
/// 静态只读字段，用于延迟初始化架构实例
/// 使用Lazy确保线程安全的单例模式实现
/// 静态只读字段，用于延迟初始化架构实例
/// 使用Lazy确保线程安全的单例模式实现
/// </summary>
/// <remarks>
/// 初始化过程包括：
/// 1. 创建T类型的实例
/// 2. 调用用户自定义的Init方法
/// 3. 执行注册的补丁逻辑
/// 4. 初始化所有已注册的模型和系统
/// 5. 清理临时集合并标记初始化完成
/// 初始化过程包括：
/// 1. 创建T类型的实例
/// 2. 调用用户自定义的Init方法
/// 3. 执行注册的补丁逻辑
/// 4. 初始化所有已注册的模型和系统
/// 5. 清理临时集合并标记初始化完成
/// </remarks>
/// <returns>T类型的架构实例</returns>
private static readonly Lazy<T> MArchitectureLazy = new(() =>
@ -58,18 +38,12 @@ public abstract class Architecture<T> : IArchitecture where T : Architecture<T>,
OnRegisterPatch?.Invoke(arch);
// 初始化所有已注册但尚未初始化的模型
foreach (var model in arch._mModels)
{
model.Init();
}
foreach (var model in arch._mModels) model.Init();
arch._mModels.Clear();
// 初始化所有已注册但尚未初始化的系统
foreach (var system in arch._mSystems)
{
system.Init();
}
foreach (var system in arch._mSystems) system.Init();
arch._mSystems.Clear();
@ -78,33 +52,52 @@ public abstract class Architecture<T> : IArchitecture where T : Architecture<T>,
}, LazyThreadSafetyMode.ExecutionAndPublication);
/// <summary>
/// 获取架构实例的受保护静态属性
/// 通过Lazy初始化确保只创建一个实例
/// 控制反转容器，用于存储和获取各种服务（如系统、模型、工具）
/// </summary>
private readonly IocContainer _mContainer = new();
/// <summary>
/// 存储尚未初始化的模型集合，在初始化阶段统一调用Init方法
/// </summary>
private readonly HashSet<IModel> _mModels = [];
/// <summary>
/// 存储尚未初始化的系统集合，在初始化阶段统一调用Init方法
/// </summary>
private readonly HashSet<ISystem> _mSystems = [];
/// <summary>
/// 类型化事件系统，负责事件的发布与订阅管理
/// </summary>
private readonly TypeEventSystem _mTypeEventSystem = new();
/// <summary>
/// 标记架构是否已初始化完成
/// </summary>
private bool _mInited;
/// <summary>
/// 注册补丁委托，允许在架构创建后执行额外逻辑
/// </summary>
public static Action<T> OnRegisterPatch { get; set; } = _ => { };
/// <summary>
/// 获取架构实例的受保护静态属性
/// 通过Lazy初始化确保只创建一个实例
/// </summary>
/// <returns>T类型的架构实例</returns>
protected static T MArchitecture => MArchitectureLazy.Value;
/// <summary>
/// 获取架构实例的公共静态属性，以接口形式暴露
/// 提供对外访问架构功能的标准接口
/// 获取架构实例的公共静态属性，以接口形式暴露
/// 提供对外访问架构功能的标准接口
/// </summary>
/// <returns>IArchitecture接口类型的架构实例</returns>
public static IArchitecture Interface => MArchitectureLazy.Value;
/// <summary>
/// 抽象初始化方法，由子类重写以进行自定义初始化操作
/// </summary>
protected abstract void Init();
/// <summary>
/// 控制反转容器，用于存储和获取各种服务（如系统、模型、工具）
/// </summary>
private readonly IocContainer _mContainer = new();
/// <summary>
/// 注册一个系统到架构中。
/// 若当前未初始化，则暂存至待初始化列表；否则立即初始化该系统。
/// 注册一个系统到架构中。
/// 若当前未初始化，则暂存至待初始化列表；否则立即初始化该系统。
/// </summary>
/// <typeparam name="TSystem">要注册的系统类型</typeparam>
/// <param name="system">要注册的系统实例</param>
@ -114,18 +107,14 @@ public abstract class Architecture<T> : IArchitecture where T : Architecture<T>,
_mContainer.Register(system);
if (!_mInited)
{
_mSystems.Add(system);
}
else
{
system.Init();
}
}
/// <summary>
/// 注册一个模型到架构中。
/// 若当前未初始化，则暂存至待初始化列表；否则立即初始化该模型。
/// 注册一个模型到架构中。
/// 若当前未初始化，则暂存至待初始化列表；否则立即初始化该模型。
/// </summary>
/// <typeparam name="TModel">要注册的模型类型</typeparam>
/// <param name="model">要注册的模型实例</param>
@ -135,62 +124,132 @@ public abstract class Architecture<T> : IArchitecture where T : Architecture<T>,
_mContainer.Register(model);
if (!_mInited)
{
_mModels.Add(model);
}
else
{
model.Init();
}
}
/// <summary>
/// 注册一个工具到架构中。
/// 工具不会被延迟初始化，直接放入IOC容器供后续使用。
/// 注册一个工具到架构中。
/// 工具不会被延迟初始化，直接放入IOC容器供后续使用。
/// </summary>
/// <typeparam name="TUtility">要注册的工具类型</typeparam>
/// <param name="utility">要注册的工具实例</param>
public void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility =>
public void RegisterUtility<TUtility>(TUtility utility) where TUtility : IUtility
{
_mContainer.Register(utility);
}
/// <summary>
/// 从IOC容器中获取指定类型的系统实例
/// 从IOC容器中获取指定类型的系统实例
/// </summary>
/// <typeparam name="TSystem">目标系统类型</typeparam>
/// <returns>对应的系统实例</returns>
public TSystem GetSystem<TSystem>() where TSystem : class, ISystem => _mContainer.Get<TSystem>();
public TSystem GetSystem<TSystem>() where TSystem : class, ISystem
{
return _mContainer.Get<TSystem>();
}
/// <summary>
/// 从IOC容器中获取指定类型的模型实例
/// 从IOC容器中获取指定类型的模型实例
/// </summary>
/// <typeparam name="TModel">目标模型类型</typeparam>
/// <returns>对应的模型实例</returns>
public TModel GetModel<TModel>() where TModel : class, IModel => _mContainer.Get<TModel>();
public TModel GetModel<TModel>() where TModel : class, IModel
{
return _mContainer.Get<TModel>();
}
/// <summary>
/// 从IOC容器中获取指定类型的工具实例
/// 从IOC容器中获取指定类型的工具实例
/// </summary>
/// <typeparam name="TUtility">目标工具类型</typeparam>
/// <returns>对应的工具实例</returns>
public TUtility GetUtility<TUtility>() where TUtility : class, IUtility => _mContainer.Get<TUtility>();
public TUtility GetUtility<TUtility>() where TUtility : class, IUtility
{
return _mContainer.Get<TUtility>();
}
/// <summary>
/// 发送一个带返回结果的命令请求
/// 发送一个带返回结果的命令请求
/// </summary>
/// <typeparam name="TResult">命令执行后的返回值类型</typeparam>
/// <param name="command">要发送的命令对象</param>
/// <returns>命令执行的结果</returns>
public TResult SendCommand<TResult>(ICommand<TResult> command) => ExecuteCommand(command);
public TResult SendCommand<TResult>(ICommand<TResult> command)
{
return ExecuteCommand(command);
}
/// <summary>
/// 发送一个无返回结果的命令请求
/// 发送一个无返回结果的命令请求
/// </summary>
/// <typeparam name="TCommand">命令的具体类型</typeparam>
/// <param name="command">要发送的命令对象</param>
public void SendCommand<TCommand>(TCommand command) where TCommand : ICommand => ExecuteCommand(command);
public void SendCommand<TCommand>(TCommand command) where TCommand : ICommand
{
ExecuteCommand(command);
}
/// <summary>
/// 执行一个带返回结果的命令
/// 发起一次查询请求并获得其结果
/// </summary>
/// <typeparam name="TResult">查询结果的数据类型</typeparam>
/// <param name="query">要发起的查询对象</param>
/// <returns>查询得到的结果数据</returns>
public TResult SendQuery<TResult>(IQuery<TResult> query)
{
return DoQuery(query);
}
/// <summary>
/// 发布一个默认构造的新事件对象
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
public void SendEvent<TEvent>() where TEvent : new()
{
_mTypeEventSystem.Send<TEvent>();
}
/// <summary>
/// 发布一个具体的事件对象
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
/// <param name="e">要发布的事件实例</param>
public void SendEvent<TEvent>(TEvent e)
{
_mTypeEventSystem.Send(e);
}
/// <summary>
/// 订阅某个特定类型的事件
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
/// <param name="onEvent">当事件发生时触发的动作</param>
/// <returns>可用于取消订阅的对象</returns>
public IUnRegister RegisterEvent<TEvent>(Action<TEvent> onEvent)
{
return _mTypeEventSystem.Register(onEvent);
}
/// <summary>
/// 取消对某类型事件的监听
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
/// <param name="onEvent">之前绑定的事件处理器</param>
public void UnRegisterEvent<TEvent>(Action<TEvent> onEvent)
{
_mTypeEventSystem.UnRegister(onEvent);
}
/// <summary>
/// 抽象初始化方法，由子类重写以进行自定义初始化操作
/// </summary>
protected abstract void Init();
/// <summary>
/// 执行一个带返回结果的命令
/// </summary>
/// <typeparam name="TResult">命令执行后的返回值类型</typeparam>
/// <param name="command">要执行的命令对象</param>
@ -202,7 +261,7 @@ public abstract class Architecture<T> : IArchitecture where T : Architecture<T>,
}
/// <summary>
/// 执行一个无返回结果的命令
/// 执行一个无返回结果的命令
/// </summary>
/// <param name="command">要执行的命令对象</param>
protected virtual void ExecuteCommand(ICommand command)
@ -212,15 +271,7 @@ public abstract class Architecture<T> : IArchitecture where T : Architecture<T>,
}
/// <summary>
/// 发起一次查询请求并获得其结果
/// </summary>
/// <typeparam name="TResult">查询结果的数据类型</typeparam>
/// <param name="query">要发起的查询对象</param>
/// <returns>查询得到的结果数据</returns>
public TResult SendQuery<TResult>(IQuery<TResult> query) => DoQuery(query);
/// <summary>
/// 实际执行查询逻辑的方法
/// 实际执行查询逻辑的方法
/// </summary>
/// <typeparam name="TResult">查询结果的数据类型</typeparam>
/// <param name="query">要处理的查询对象</param>
@ -230,37 +281,4 @@ public abstract class Architecture<T> : IArchitecture where T : Architecture<T>,
query.SetArchitecture(this);
return query.Do();
}
/// <summary>
/// 类型化事件系统，负责事件的发布与订阅管理
/// </summary>
private readonly TypeEventSystem _mTypeEventSystem = new();
/// <summary>
/// 发布一个默认构造的新事件对象
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
public void SendEvent<TEvent>() where TEvent : new() => _mTypeEventSystem.Send<TEvent>();
/// <summary>
/// 发布一个具体的事件对象
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
/// <param name="e">要发布的事件实例</param>
public void SendEvent<TEvent>(TEvent e) => _mTypeEventSystem.Send(e);
/// <summary>
/// 订阅某个特定类型的事件
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
/// <param name="onEvent">当事件发生时触发的动作</param>
/// <returns>可用于取消订阅的对象</returns>
public IUnRegister RegisterEvent<TEvent>(Action<TEvent> onEvent) => _mTypeEventSystem.Register(onEvent);
/// <summary>
/// 取消对某类型事件的监听
/// </summary>
/// <typeparam name="TEvent">事件类型</typeparam>
/// <param name="onEvent">之前绑定的事件处理器</param>
public void UnRegisterEvent<TEvent>(Action<TEvent> onEvent) => _mTypeEventSystem.UnRegister(onEvent);
}

32
GFramework.Core/architecture/IArchitecture.cs
View File

@ -8,62 +8,62 @@ using GFramework.Core.utility;
namespace GFramework.Core.architecture;
/// <summary>
/// 架构接口，定义了应用程序架构的核心功能，包括系统、模型、工具的注册和获取，
/// 以及命令、查询、事件的发送和处理机制
/// 架构接口，定义了应用程序架构的核心功能，包括系统、模型、工具的注册和获取，
/// 以及命令、查询、事件的发送和处理机制
/// </summary>
public interface IArchitecture
{
/// <summary>
/// 注册系统实例到架构中
/// 注册系统实例到架构中
/// </summary>
/// <typeparam name="T">系统类型，必须实现ISystem接口</typeparam>
/// <param name="system">要注册的系统实例</param>
void RegisterSystem<T>(T system) where T : ISystem;
/// <summary>
/// 注册模型实例到架构中
/// 注册模型实例到架构中
/// </summary>
/// <typeparam name="T">模型类型，必须实现IModel接口</typeparam>
/// <param name="model">要注册的模型实例</param>
void RegisterModel<T>(T model) where T : IModel;
/// <summary>
/// 注册工具实例到架构中
/// 注册工具实例到架构中
/// </summary>
/// <typeparam name="T">工具类型，必须实现IUtility接口</typeparam>
/// <param name="utility">要注册的工具实例</param>
void RegisterUtility<T>(T utility) where T : IUtility;
/// <summary>
/// 从架构中获取指定类型的系统实例
/// 从架构中获取指定类型的系统实例
/// </summary>
/// <typeparam name="T">系统类型，必须是class且实现ISystem接口</typeparam>
/// <returns>指定类型的系统实例</returns>
T GetSystem<T>() where T : class, ISystem;
/// <summary>
/// 从架构中获取指定类型的模型实例
/// 从架构中获取指定类型的模型实例
/// </summary>
/// <typeparam name="T">模型类型，必须是class且实现IModel接口</typeparam>
/// <returns>指定类型的模型实例</returns>
T GetModel<T>() where T : class, IModel;
/// <summary>
/// 从架构中获取指定类型的工具实例
/// 从架构中获取指定类型的工具实例
/// </summary>
/// <typeparam name="T">工具类型，必须是class且实现IUtility接口</typeparam>
/// <returns>指定类型的工具实例</returns>
T GetUtility<T>() where T : class, IUtility;
/// <summary>
/// 发送并执行指定的命令
/// 发送并执行指定的命令
/// </summary>
/// <typeparam name="T">命令类型，必须实现ICommand接口</typeparam>
/// <param name="command">要执行的命令实例</param>
void SendCommand<T>(T command) where T : ICommand;
/// <summary>
/// 发送并执行带有返回值的命令
/// 发送并执行带有返回值的命令
/// </summary>
/// <typeparam name="TResult">命令执行结果的类型</typeparam>
/// <param name="command">要执行的命令实例</param>
@ -71,7 +71,7 @@ public interface IArchitecture
TResult SendCommand<TResult>(ICommand<TResult> command);
/// <summary>
/// 发送并执行查询操作
/// 发送并执行查询操作
/// </summary>
/// <typeparam name="TResult">查询结果的类型</typeparam>
/// <param name="query">要执行的查询实例</param>
@ -79,20 +79,20 @@ public interface IArchitecture
TResult SendQuery<TResult>(IQuery<TResult> query);
/// <summary>
/// 发送无参事件
/// 发送无参事件
/// </summary>
/// <typeparam name="T">事件类型，必须具有无参构造函数</typeparam>
void SendEvent<T>() where T : new();
/// <summary>
/// 发送指定的事件实例
/// 发送指定的事件实例
/// </summary>
/// <typeparam name="T">事件类型</typeparam>
/// <param name="e">要发送的事件实例</param>
void SendEvent<T>(T e);
/// <summary>
/// 注册事件监听器
/// 注册事件监听器
/// </summary>
/// <typeparam name="T">事件类型</typeparam>
/// <param name="onEvent">事件触发时的回调方法</param>
@ -100,9 +100,9 @@ public interface IArchitecture
IUnRegister RegisterEvent<T>(Action<T> onEvent);
/// <summary>
/// 取消注册事件监听器
/// 取消注册事件监听器
/// </summary>
/// <typeparam name="T">事件类型</typeparam>
/// <param name="onEvent">要取消注册的事件回调方法</param>
void UnRegisterEvent<T>(Action<T> onEvent);
}
}

14
GFramework.Core/architecture/README.md
View File

@ -11,6 +11,7 @@ Architecture 包是整个框架的核心，提供了基于 MVC 架构模式的
架构接口，定义了框架的核心功能契约。
**主要职责：**
- 组件注册：注册 System、Model、Utility
- 组件获取：从容器中获取已注册的组件
- 命令处理：发送并执行命令
@ -49,6 +50,7 @@ void UnRegisterEvent<T>(Action<T> onEvent);
架构基类，实现了 [`IArchitecture`](IArchitecture.cs) 接口，提供完整的架构功能实现。
**特性：**
- **单例模式**：使用泛型和 `Lazy<T>` 确保全局唯一实例
- **线程安全**：采用 `LazyThreadSafetyMode.ExecutionAndPublication` 保证多线程安全
- **生命周期管理**：自动管理 System 和 Model 的初始化顺序
@ -56,6 +58,7 @@ void UnRegisterEvent<T>(Action<T> onEvent);
- **事件系统**：集成类型化事件系统，支持类型安全的事件通信
**初始化流程：**
1. 创建架构实例
2. 调用用户自定义的 `Init()` 方法
3. 执行注册的补丁逻辑（`OnRegisterPatch`）
@ -133,27 +136,32 @@ GameArchitecture.Interface.RegisterSystem(newSystem);
## 设计模式
### 单例模式
通过泛型约束和 `Lazy<T>` 实现类型安全的单例。
### 依赖注入（IoC）
使用内置 IoC 容器管理组件生命周期和依赖关系。
### 命令模式
通过 [`ICommand`](../command/ICommand.cs) 封装所有用户操作。
### 查询模式（CQRS）
通过 [`IQuery<T>`](../query/IQuery.cs) 分离查询和命令操作。
### 观察者模式
通过事件系统实现组件间的松耦合通信。
## 最佳实践
1. **保持架构类简洁**：只在 `Init()` 中注册组件，不要包含业务逻辑
2. **合理划分职责**：
- Model：数据和状态
- System：业务逻辑和规则
- Utility：无状态的工具方法
- Model：数据和状态
- System：业务逻辑和规则
- Utility：无状态的工具方法
3. **使用接口访问**：通过 `Interface` 属性访问架构，便于测试
4. **事件命名规范**：使用过去式命名事件类，如 `PlayerDiedEvent`
5. **避免循环依赖**：System 不应直接引用 System，应通过事件通信

52
GFramework.Core/command/AbstractCommand.cs
View File

@ -4,37 +4,46 @@ using GFramework.Core.rule;
namespace GFramework.Core.command;
/// <summary>
/// 抽象命令类，实现 ICommand 接口，为具体命令提供基础架构支持
/// 抽象命令类，实现 ICommand 接口，为具体命令提供基础架构支持
/// </summary>
public abstract class AbstractCommand : ICommand
{
private IArchitecture _mArchitecture;
/// <summary>
/// 获取命令所属的架构实例
/// 获取命令所属的架构实例
/// </summary>
/// <returns>IArchitecture 架构接口实例</returns>
IArchitecture IBelongToArchitecture.GetArchitecture() => _mArchitecture;
IArchitecture IBelongToArchitecture.GetArchitecture()
{
return _mArchitecture;
}
/// <summary>
/// 设置命令所属的架构实例
/// 设置命令所属的架构实例
/// </summary>
/// <param name="architecture">要设置的架构实例</param>
void ICanSetArchitecture.SetArchitecture(IArchitecture architecture) => _mArchitecture = architecture;
void ICanSetArchitecture.SetArchitecture(IArchitecture architecture)
{
_mArchitecture = architecture;
}
/// <summary>
/// 执行命令，调用抽象方法 OnExecute 来实现具体逻辑
/// 执行命令，调用抽象方法 OnExecute 来实现具体逻辑
/// </summary>
void ICommand.Execute() => OnExecute();
void ICommand.Execute()
{
OnExecute();
}
/// <summary>
/// 抽象方法，由子类实现具体的命令执行逻辑
/// 抽象方法，由子类实现具体的命令执行逻辑
/// </summary>
protected abstract void OnExecute();
}
/// <summary>
/// 带返回值的抽象命令类，实现 ICommand{TResult} 接口，为需要返回结果的命令提供基础架构支持
/// 带返回值的抽象命令类，实现 ICommand{TResult} 接口，为需要返回结果的命令提供基础架构支持
/// </summary>
/// <typeparam name="TResult">命令执行后返回的结果类型</typeparam>
public abstract class AbstractCommand<TResult> : ICommand<TResult>
@ -42,26 +51,35 @@ public abstract class AbstractCommand<TResult> : ICommand<TResult>
private IArchitecture _mArchitecture;
/// <summary>
/// 获取命令所属的架构实例
/// 获取命令所属的架构实例
/// </summary>
/// <returns>IArchitecture 架构接口实例</returns>
IArchitecture IBelongToArchitecture.GetArchitecture() => _mArchitecture;
IArchitecture IBelongToArchitecture.GetArchitecture()
{
return _mArchitecture;
}
/// <summary>
/// 设置命令所属的架构实例
/// 设置命令所属的架构实例
/// </summary>
/// <param name="architecture">要设置的架构实例</param>
void ICanSetArchitecture.SetArchitecture(IArchitecture architecture) => _mArchitecture = architecture;
void ICanSetArchitecture.SetArchitecture(IArchitecture architecture)
{
_mArchitecture = architecture;
}
/// <summary>
/// 执行命令，调用抽象方法 OnExecute 来实现具体逻辑并返回结果
/// 执行命令，调用抽象方法 OnExecute 来实现具体逻辑并返回结果
/// </summary>
/// <returns>TResult 类型的执行结果</returns>
TResult ICommand<TResult>.Execute() => OnExecute();
TResult ICommand<TResult>.Execute()
{
return OnExecute();
}
/// <summary>
/// 抽象方法，由子类实现具体的命令执行逻辑
/// 抽象方法，由子类实现具体的命令执行逻辑
/// </summary>
/// <returns>TResult 类型的执行结果</returns>
protected abstract TResult OnExecute();
}
}

6
GFramework.Core/command/ICanSendCommand.cs
View File

@ -3,7 +3,7 @@ using GFramework.Core.rule;
namespace GFramework.Core.command;
/// <summary>
/// 定义一个可以发送命令的接口，继承自IBelongToArchitecture接口。
/// 该接口用于标识那些具备发送命令能力的架构组件。
/// 定义一个可以发送命令的接口，继承自IBelongToArchitecture接口。
/// 该接口用于标识那些具备发送命令能力的架构组件。
/// </summary>
public interface ICanSendCommand : IBelongToArchitecture;
public interface ICanSendCommand : IBelongToArchitecture;

18
GFramework.Core/command/ICommand.cs
View File

@ -8,22 +8,22 @@ using GFramework.Core.utility;
namespace GFramework.Core.command;
/// <summary>
/// 命令接口，定义了无返回值命令的基本契约
/// 该接口继承了多个框架能力接口，使命令可以访问架构、系统、模型、工具，并能够发送事件、命令和查询
/// 命令接口，定义了无返回值命令的基本契约
/// 该接口继承了多个框架能力接口，使命令可以访问架构、系统、模型、工具，并能够发送事件、命令和查询
/// </summary>
public interface ICommand : ICanSetArchitecture, ICanGetSystem, ICanGetModel, ICanGetUtility,
ICanSendEvent, ICanSendCommand, ICanSendQuery
{
/// <summary>
/// 执行命令的核心方法
/// 该方法不接受参数且无返回值，具体实现由派生类完成
/// 执行命令的核心方法
/// 该方法不接受参数且无返回值，具体实现由派生类完成
/// </summary>
void Execute();
}
/// <summary>
/// 带返回值的命令接口，定义了有返回值命令的基本契约
/// 该接口继承了多个框架能力接口，使命令可以访问架构、系统、模型、工具，并能够发送事件、命令和查询
/// 带返回值的命令接口，定义了有返回值命令的基本契约
/// 该接口继承了多个框架能力接口，使命令可以访问架构、系统、模型、工具，并能够发送事件、命令和查询
/// </summary>
/// <typeparam name="TResult">命令执行后返回的结果类型</typeparam>
public interface ICommand<out TResult> : ICanSetArchitecture, ICanGetSystem, ICanGetModel,
@ -31,9 +31,9 @@ public interface ICommand<out TResult> : ICanSetArchitecture, ICanGetSystem, ICa
ICanSendEvent, ICanSendCommand, ICanSendQuery
{
/// <summary>
/// 执行命令的核心方法
/// 该方法不接受参数，但会返回指定类型的结果
/// 执行命令的核心方法
/// 该方法不接受参数，但会返回指定类型的结果
/// </summary>
/// <returns>命令执行后的结果，类型为 TResult</returns>
TResult Execute();
}
}

5
GFramework.Core/command/README.md
View File

@ -11,6 +11,7 @@ Command 包实现了命令模式（Command Pattern），用于封装用户操作
无返回值命令接口，定义了命令的基本契约。
**继承的能力接口：**
- [`ICanSetArchitecture`](../rule/ICanSetArchitecture.cs) - 可设置架构
- [`ICanGetSystem`](../system/ICanGetSystem.cs) - 可获取系统
- [`ICanGetModel`](../model/ICanGetModel.cs) - 可获取模型
@ -20,6 +21,7 @@ Command 包实现了命令模式（Command Pattern），用于封装用户操作
- [`ICanSendQuery`](../query/ICanSendQuery.cs) - 可发送查询
**核心方法：**
```csharp
void Execute(); // 执行命令
```
@ -29,6 +31,7 @@ void Execute(); // 执行命令
带返回值的命令接口，用于需要返回执行结果的命令。
**核心方法：**
```csharp
TResult Execute(); // 执行命令并返回结果
```
@ -232,12 +235,14 @@ public class LoginCommand : AbstractCommand<bool>
## 命令 vs 系统方法
**何时使用命令：**
- 需要参数化操作
- 需要记录操作历史（用于撤销/重做）
- 操作需要跨多个系统协调
- 用户触发的离散操作
**何时使用系统方法：**
- 持续运行的逻辑（如每帧更新）
- 系统内部的私有逻辑
- 不需要外部调用的功能

8
GFramework.Core/controller/IController.cs
View File

@ -8,9 +8,9 @@ using GFramework.Core.utility;
namespace GFramework.Core.controller;
/// <summary>
/// 控制器接口，定义了控制器需要实现的所有功能契约
/// 该接口继承了多个框架核心接口，用于支持控制器的各种能力
/// 包括架构归属、命令发送、系统获取、模型获取、事件注册、查询发送和工具获取等功能
/// 控制器接口，定义了控制器需要实现的所有功能契约
/// 该接口继承了多个框架核心接口，用于支持控制器的各种能力
/// 包括架构归属、命令发送、系统获取、模型获取、事件注册、查询发送和工具获取等功能
/// </summary>
public interface IController : ICanSendCommand, ICanGetSystem, ICanGetModel,
ICanRegisterEvent, ICanSendQuery, ICanGetUtility;
ICanRegisterEvent, ICanSendQuery, ICanGetUtility;

65
GFramework.Core/controller/README.md
View File

@ -2,7 +2,8 @@
## 概述
Controller 包定义了控制器（Controller）的接口规范。控制器是 MVC 架构中的 C 层，负责处理用户交互、协调视图和模型，是连接表现层和业务层的桥梁。在本框架中，Controller 通常对应 Godot 的节点脚本。
Controller 包定义了控制器（Controller）的接口规范。控制器是 MVC 架构中的 C
层，负责处理用户交互、协调视图和模型，是连接表现层和业务层的桥梁。在本框架中，Controller 通常对应 Godot 的节点脚本。
## 核心接口
@ -11,6 +12,7 @@ Controller 包定义了控制器（Controller）的接口规范。控制器是 M
控制器接口，定义了控制器需要实现的所有功能契约。
**继承的能力接口：**
- [`ICanSendCommand`](../command/ICanSendCommand.cs) - 可发送命令
- [`ICanGetSystem`](../system/ICanGetSystem.cs) - 可获取系统
- [`ICanGetModel`](../model/ICanGetModel.cs) - 可获取模型
@ -21,6 +23,7 @@ Controller 包定义了控制器（Controller）的接口规范。控制器是 M
**能力说明：**
控制器拥有框架中最全面的能力集合，可以：
1. 发送命令执行业务逻辑
2. 获取系统调用服务
3. 获取模型读写数据
@ -224,40 +227,40 @@ public partial class CombatController : Node, IController
### ✅ 应该做的事
1. **处理用户输入**
- 键盘、鼠标、触摸输入
- UI 按钮点击
- 手势识别
- 键盘、鼠标、触摸输入
- UI 按钮点击
- 手势识别
2. **协调视图和模型**
- 监听模型变化更新视图
- 将用户操作转换为命令
- 监听模型变化更新视图
- 将用户操作转换为命令
3. **管理界面逻辑**
- UI 元素的显示/隐藏
- 动画播放控制
- 视觉反馈
- UI 元素的显示/隐藏
- 动画播放控制
- 视觉反馈
4. **事件监听**
- 注册关心的事件
- 响应事件更新界面
- 注册关心的事件
- 响应事件更新界面
### ❌ 不应该做的事
1. **不包含业务逻辑**
- 业务逻辑应该在 System 中
- 控制器只负责调用和协调
- 业务逻辑应该在 System 中
- 控制器只负责调用和协调
2. **不直接修改模型**
- 应该通过 Command 修改模型
- 避免直接访问 Model 的 setter
- 应该通过 Command 修改模型
- 避免直接访问 Model 的 setter
3. **不处理复杂计算**
- 复杂计算应该在 Query 或 System 中
- 控制器保持简洁
- 复杂计算应该在 Query 或 System 中
- 控制器保持简洁
4. **不保存核心状态**
- 核心状态应该在 Model 中
- 控制器可以保存临时 UI 状态
- 核心状态应该在 Model 中
- 控制器可以保存临时 UI 状态
## 生命周期管理
@ -326,28 +329,28 @@ public partial class GameController : Node, IController
## 最佳实践
1. **一个控制器对应一个视图**
- 每个 Godot 场景/节点有对应的控制器
- 避免一个控制器管理多个不相关的视图
- 每个 Godot 场景/节点有对应的控制器
- 避免一个控制器管理多个不相关的视图
2. **使用依赖注入获取依赖**
- 通过 `GetModel()`、`GetSystem()` 获取依赖
- 不要在构造函数中获取，应在 `_Ready()` 中
- 通过 `GetModel()`、`GetSystem()` 获取依赖
- 不要在构造函数中获取，应在 `_Ready()` 中
3. **保持控制器轻量**
- 复杂逻辑放在 Command、Query、System 中
- 控制器只做协调和转发
- 复杂逻辑放在 Command、Query、System 中
- 控制器只做协调和转发
4. **合理使用缓存**
- 频繁使用的 Model、System 可以缓存引用
- 平衡性能和内存占用
- 频繁使用的 Model、System 可以缓存引用
- 平衡性能和内存占用
5. **统一管理事件注销**
- 使用 `IUnRegisterList` 统一管理
- 在 `_ExitTree()` 中统一注销
- 使用 `IUnRegisterList` 统一管理
- 在 `_ExitTree()` 中统一注销
6. **命名规范**
- 控制器类名：`XxxController`
- 继承 Godot 节点：`Node`、`Control`、`Node2D` 等
- 控制器类名：`XxxController`
- 继承 Godot 节点：`Node`、`Control`、`Node2D` 等
## 常见模式

9
GFramework.Core/events/DefaultUnRegister.cs
View File

@ -1,16 +1,15 @@
namespace GFramework.Core.events;
/// <summary>
/// 默认注销器类，用于执行注销操作
/// 默认注销器类，用于执行注销操作
/// </summary>
/// <param name="onUnRegister">注销时要执行的回调函数</param>
public class DefaultUnRegister(Action onUnRegister): IUnRegister
public class DefaultUnRegister(Action onUnRegister) : IUnRegister
{
private Action _mOnUnRegister = onUnRegister;
/// <summary>
/// 执行注销操作，调用注册的回调函数并清理引用
/// 执行注销操作，调用注册的回调函数并清理引用
/// </summary>
public void UnRegister()
{
@ -18,4 +17,4 @@ public class DefaultUnRegister(Action onUnRegister): IUnRegister
_mOnUnRegister.Invoke();
_mOnUnRegister = null;
}
}
}

20
GFramework.Core/events/EasyEvent.cs
View File

@ -1,14 +1,14 @@
namespace GFramework.Core.events;
/// <summary>
/// 简单事件类，用于注册、注销和触发无参事件回调
/// 简单事件类，用于注册、注销和触发无参事件回调
/// </summary>
public class EasyEvent
{
private Action _mOnEvent = () => { };
/// <summary>
/// 注册事件回调函数
/// 注册事件回调函数
/// </summary>
/// <param name="onEvent">要注册的事件回调函数</param>
/// <returns>用于注销事件的 unregister 对象</returns>
@ -19,13 +19,19 @@ public class EasyEvent
}
/// <summary>
/// 注销已注册的事件回调函数
/// 注销已注册的事件回调函数
/// </summary>
/// <param name="onEvent">要注销的事件回调函数</param>
public void UnRegister(Action onEvent) => _mOnEvent -= onEvent;
public void UnRegister(Action onEvent)
{
_mOnEvent -= onEvent;
}
/// <summary>
/// 触发所有已注册的事件回调函数
/// 触发所有已注册的事件回调函数
/// </summary>
public void Trigger() => _mOnEvent?.Invoke();
}
public void Trigger()
{
_mOnEvent?.Invoke();
}
}

146
GFramework.Core/events/EasyEventGeneric.cs
View File

@ -1,20 +1,36 @@
namespace GFramework.Core.events;
/// <summary>
/// 泛型事件类，支持一个泛型参数 T 的事件注册、注销与触发。
/// 实现了 IEasyEvent 接口以提供统一的事件操作接口。
/// 泛型事件类，支持一个泛型参数 T 的事件注册、注销与触发。
/// 实现了 IEasyEvent 接口以提供统一的事件操作接口。
/// </summary>
/// <typeparam name="T">事件回调函数的第一个参数类型。</typeparam>
public class EasyEvent<T> : IEasyEvent
{
/// <summary>
/// 存储已注册的事件处理委托。
/// 默认为空操作（no-op）委托，避免 null 检查。
/// 存储已注册的事件处理委托。
/// 默认为空操作（no-op）委托，避免 null 检查。
/// </summary>
private Action<T> _mOnEvent = e => { };
/// <summary>
/// 注册一个事件监听器，并返回可用于取消注册的对象。
/// 显式实现 IEasyEvent 接口中的 Register 方法。
/// 允许使用无参 Action 来订阅当前带参事件。
/// </summary>
/// <param name="onEvent">无参事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
IUnRegister IEasyEvent.Register(Action onEvent)
{
return Register(Action);
void Action(T _)
{
onEvent();
}
}
/// <summary>
/// 注册一个事件监听器，并返回可用于取消注册的对象。
/// </summary>
/// <param name="onEvent">要注册的事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
@ -25,46 +41,56 @@ public class EasyEvent<T> : IEasyEvent
}
/// <summary>
/// 取消指定的事件监听器。
/// 取消指定的事件监听器。
/// </summary>
/// <param name="onEvent">需要被注销的事件处理方法。</param>
public void UnRegister(Action<T> onEvent) => _mOnEvent -= onEvent;
public void UnRegister(Action<T> onEvent)
{
_mOnEvent -= onEvent;
}
/// <summary>
/// 触发所有已注册的事件处理程序，并传递参数 t。
/// 触发所有已注册的事件处理程序，并传递参数 t。
/// </summary>
/// <param name="t">传递给事件处理程序的参数。</param>
public void Trigger(T t) => _mOnEvent?.Invoke(t);
/// <summary>
/// 显式实现 IEasyEvent 接口中的 Register 方法。
/// 允许使用无参 Action 来订阅当前带参事件。
/// </summary>
/// <param name="onEvent">无参事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
IUnRegister IEasyEvent.Register(Action onEvent)
public void Trigger(T t)
{
return Register(Action);
void Action(T _) => onEvent();
_mOnEvent?.Invoke(t);
}
}
/// <summary>
/// 支持两个泛型参数 T 和 TK 的事件类。
/// 提供事件注册、注销和触发功能。
/// 支持两个泛型参数 T 和 TK 的事件类。
/// 提供事件注册、注销和触发功能。
/// </summary>
/// <typeparam name="T">第一个参数类型。</typeparam>
/// <typeparam name="TK">第二个参数类型。</typeparam>
public class EasyEvent<T, TK> : IEasyEvent
{
/// <summary>
/// 存储已注册的双参数事件处理委托。
/// 默认为空操作（no-op）委托。
/// 存储已注册的双参数事件处理委托。
/// 默认为空操作（no-op）委托。
/// </summary>
private Action<T, TK> _mOnEvent = (_, _) => { };
/// <summary>
/// 注册一个接受两个参数的事件监听器，并返回可用于取消注册的对象。
/// 显式实现 IEasyEvent 接口中的 Register 方法。
/// 允许使用无参 Action 来订阅当前带参事件。
/// </summary>
/// <param name="onEvent">无参事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
IUnRegister IEasyEvent.Register(Action onEvent)
{
return Register(Action);
void Action(T _, TK __)
{
onEvent();
}
}
/// <summary>
/// 注册一个接受两个参数的事件监听器，并返回可用于取消注册的对象。
/// </summary>
/// <param name="onEvent">要注册的事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
@ -75,34 +101,28 @@ public class EasyEvent<T, TK> : IEasyEvent
}
/// <summary>
/// 取消指定的双参数事件监听器。
/// 取消指定的双参数事件监听器。
/// </summary>
/// <param name="onEvent">需要被注销的事件处理方法。</param>
public void UnRegister(Action<T, TK> onEvent) => _mOnEvent -= onEvent;
public void UnRegister(Action<T, TK> onEvent)
{
_mOnEvent -= onEvent;
}
/// <summary>
/// 触发所有已注册的事件处理程序，并传递参数 t 和 k。
/// 触发所有已注册的事件处理程序，并传递参数 t 和 k。
/// </summary>
/// <param name="t">第一个参数。</param>
/// <param name="k">第二个参数。</param>
public void Trigger(T t, TK k) => _mOnEvent?.Invoke(t, k);
/// <summary>
/// 显式实现 IEasyEvent 接口中的 Register 方法。
/// 允许使用无参 Action 来订阅当前带参事件。
/// </summary>
/// <param name="onEvent">无参事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
IUnRegister IEasyEvent.Register(Action onEvent)
public void Trigger(T t, TK k)
{
return Register(Action);
void Action(T _, TK __) => onEvent();
_mOnEvent?.Invoke(t, k);
}
}
/// <summary>
/// 支持三个泛型参数 T、TK 和 TS 的事件类。
/// 提供事件注册、注销和触发功能。
/// 支持三个泛型参数 T、TK 和 TS 的事件类。
/// 提供事件注册、注销和触发功能。
/// </summary>
/// <typeparam name="T">第一个参数类型。</typeparam>
/// <typeparam name="TK">第二个参数类型。</typeparam>
@ -110,13 +130,29 @@ public class EasyEvent<T, TK> : IEasyEvent
public class EasyEvent<T, TK, TS> : IEasyEvent
{
/// <summary>
/// 存储已注册的三参数事件处理委托。
/// 默认为空操作（no-op）委托。
/// 存储已注册的三参数事件处理委托。
/// 默认为空操作（no-op）委托。
/// </summary>
private Action<T, TK, TS> _mOnEvent = (_, _, _) => { };
/// <summary>
/// 注册一个接受三个参数的事件监听器，并返回可用于取消注册的对象。
/// 显式实现 IEasyEvent 接口中的 Register 方法。
/// 允许使用无参 Action 来订阅当前带参事件。
/// </summary>
/// <param name="onEvent">无参事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
IUnRegister IEasyEvent.Register(Action onEvent)
{
return Register(Action);
void Action(T _, TK __, TS ___)
{
onEvent();
}
}
/// <summary>
/// 注册一个接受三个参数的事件监听器，并返回可用于取消注册的对象。
/// </summary>
/// <param name="onEvent">要注册的事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
@ -127,28 +163,22 @@ public class EasyEvent<T, TK, TS> : IEasyEvent
}
/// <summary>
/// 取消指定的三参数事件监听器。
/// 取消指定的三参数事件监听器。
/// </summary>
/// <param name="onEvent">需要被注销的事件处理方法。</param>
public void UnRegister(Action<T, TK, TS> onEvent) => _mOnEvent -= onEvent;
public void UnRegister(Action<T, TK, TS> onEvent)
{
_mOnEvent -= onEvent;
}
/// <summary>
/// 触发所有已注册的事件处理程序，并传递参数 t、k 和 s。
/// 触发所有已注册的事件处理程序，并传递参数 t、k 和 s。
/// </summary>
/// <param name="t">第一个参数。</param>
/// <param name="k">第二个参数。</param>
/// <param name="s">第三个参数。</param>
public void Trigger(T t, TK k, TS s) => _mOnEvent?.Invoke(t, k, s);
/// <summary>
/// 显式实现 IEasyEvent 接口中的 Register 方法。
/// 允许使用无参 Action 来订阅当前带参事件。
/// </summary>
/// <param name="onEvent">无参事件处理方法。</param>
/// <returns>IUnRegister 对象，用于稍后注销该事件监听器。</returns>
IUnRegister IEasyEvent.Register(Action onEvent)
public void Trigger(T t, TK k, TS s)
{
return Register(Action);
void Action(T _, TK __, TS ___) => onEvent();
_mOnEvent?.Invoke(t, k, s);
}
}
}

60
GFramework.Core/events/EasyEvents.cs
View File

@ -1,42 +1,51 @@
namespace GFramework.Core.events;
/// <summary>
/// EasyEvents事件管理器类，用于全局事件的注册、获取和管理
/// 提供了类型安全的事件系统，支持泛型事件的自动创建和检索
/// EasyEvents事件管理器类，用于全局事件的注册、获取和管理
/// 提供了类型安全的事件系统，支持泛型事件的自动创建和检索
/// </summary>
public class EasyEvents
{
/// <summary>
/// 全局单例事件管理器实例
/// 全局单例事件管理器实例
/// </summary>
private static readonly EasyEvents MGlobalEvents = new();
/// <summary>
/// 获取指定类型的全局事件实例
/// </summary>
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口</typeparam>
/// <returns>指定类型的事件实例，如果未注册则返回默认值</returns>
public static T Get<T>() where T : IEasyEvent => MGlobalEvents.GetEvent<T>();
/// <summary>
/// 注册指定类型的全局事件
/// </summary>
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口且具有无参构造函数</typeparam>
public static void Register<T>() where T : IEasyEvent, new() => MGlobalEvents.AddEvent<T>();
/// <summary>
/// 存储事件类型与事件实例映射关系的字典
/// 存储事件类型与事件实例映射关系的字典
/// </summary>
private readonly Dictionary<Type, IEasyEvent> _mTypeEvents = new();
/// <summary>
/// 添加指定类型的事件到事件字典中
/// 获取指定类型的全局事件实例
/// </summary>
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口且具有无参构造函数</typeparam>
public void AddEvent<T>() where T : IEasyEvent, new() => _mTypeEvents.Add(typeof(T), new T());
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口</typeparam>
/// <returns>指定类型的事件实例，如果未注册则返回默认值</returns>
public static T Get<T>() where T : IEasyEvent
{
return MGlobalEvents.GetEvent<T>();
}
/// <summary>
/// 获取指定类型的事件实例
/// 注册指定类型的全局事件
/// </summary>
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口且具有无参构造函数</typeparam>
public static void Register<T>() where T : IEasyEvent, new()
{
MGlobalEvents.AddEvent<T>();
}
/// <summary>
/// 添加指定类型的事件到事件字典中
/// </summary>
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口且具有无参构造函数</typeparam>
public void AddEvent<T>() where T : IEasyEvent, new()
{
_mTypeEvents.Add(typeof(T), new T());
}
/// <summary>
/// 获取指定类型的事件实例
/// </summary>
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口</typeparam>
/// <returns>指定类型的事件实例，如果不存在则返回默认值</returns>
@ -46,7 +55,7 @@ public class EasyEvents
}
/// <summary>
/// 获取指定类型的事件实例，如果不存在则创建并添加到事件字典中
/// 获取指定类型的事件实例，如果不存在则创建并添加到事件字典中
/// </summary>
/// <typeparam name="T">事件类型，必须实现IEasyEvent接口且具有无参构造函数</typeparam>
/// <returns>指定类型的事件实例</returns>
@ -54,14 +63,11 @@ public class EasyEvents
{
var eType = typeof(T);
// 尝试从字典中获取事件实例
if (_mTypeEvents.TryGetValue(eType, out var e))
{
return (T)e;
}
if (_mTypeEvents.TryGetValue(eType, out var e)) return (T)e;
// 如果不存在则创建新实例并添加到字典中
var t = new T();
_mTypeEvents.Add(eType, t);
return t;
}
}
}

8
GFramework.Core/events/ICanRegisterEvent.cs
View File

@ -3,8 +3,8 @@ using GFramework.Core.rule;
namespace GFramework.Core.events;
/// <summary>
/// 定义一个可以注册事件的接口，继承自IBelongToArchitecture接口。
/// 该接口用于标识那些能够注册事件的对象，通常在框架的事件系统中使用。
/// 实现此接口的类型表明它属于某个架构组件，并具备事件注册的能力。
/// 定义一个可以注册事件的接口，继承自IBelongToArchitecture接口。
/// 该接口用于标识那些能够注册事件的对象，通常在框架的事件系统中使用。
/// 实现此接口的类型表明它属于某个架构组件，并具备事件注册的能力。
/// </summary>
public interface ICanRegisterEvent:IBelongToArchitecture;
public interface ICanRegisterEvent : IBelongToArchitecture;

6
GFramework.Core/events/ICanSendEvent.cs
View File

@ -3,7 +3,7 @@ using GFramework.Core.rule;
namespace GFramework.Core.events;
/// <summary>
/// 定义一个可以发送事件的接口，继承自IBelongToArchitecture接口。
/// 该接口用于标识那些具备发送事件能力的类型，通常作为架构中事件发送功能的基础接口。
/// 定义一个可以发送事件的接口，继承自IBelongToArchitecture接口。
/// 该接口用于标识那些具备发送事件能力的类型，通常作为架构中事件发送功能的基础接口。
/// </summary>
public interface ICanSendEvent : IBelongToArchitecture;
public interface ICanSendEvent : IBelongToArchitecture;

4
GFramework.Core/events/IEasyEvent.cs
View File

@ -1,12 +1,12 @@
namespace GFramework.Core.events;
/// <summary>
/// 事件接口，定义了事件注册的基本功能
/// 事件接口，定义了事件注册的基本功能
/// </summary>
public interface IEasyEvent
{
/// <summary>
/// 注册事件处理函数
/// 注册事件处理函数
/// </summary>
/// <param name="onEvent">事件触发时要执行的回调函数</param>
/// <returns>用于取消注册的句柄对象</returns>

6
GFramework.Core/events/IUnRegister.cs
View File

@ -1,12 +1,12 @@
namespace GFramework.Core.events;
/// <summary>
/// 提供注销功能的接口
/// 提供注销功能的接口
/// </summary>
public interface IUnRegister
{
/// <summary>
/// 执行注销操作
/// 执行注销操作
/// </summary>
void UnRegister();
}
}

6
GFramework.Core/events/IUnRegisterList.cs
View File

@ -1,12 +1,12 @@
namespace GFramework.Core.events;
/// <summary>
/// 提供统一注销功能的接口，用于管理需要注销的对象列表
/// 提供统一注销功能的接口，用于管理需要注销的对象列表
/// </summary>
public interface IUnRegisterList
{
/// <summary>
/// 获取需要注销的对象列表
/// 获取需要注销的对象列表
/// </summary>
List<IUnRegister> UnregisterList { get; }
}
}

31
GFramework.Core/events/OrEvent.cs
View File

@ -3,12 +3,19 @@ using GFramework.Core.extensions;
namespace GFramework.Core.events;
/// <summary>
/// OrEvent类用于实现事件的或逻辑组合，当任意一个注册的事件触发时，都会触发OrEvent本身
/// OrEvent类用于实现事件的或逻辑组合，当任意一个注册的事件触发时，都会触发OrEvent本身
/// </summary>
public class OrEvent : IUnRegisterList
{
private Action _mOnEvent = () => { };
/// <summary>
/// 将指定的事件与当前OrEvent进行或逻辑组合
/// 获取取消注册列表
/// </summary>
public List<IUnRegister> UnregisterList { get; } = new();
/// <summary>
/// 将指定的事件与当前OrEvent进行或逻辑组合
/// </summary>
/// <param name="easyEvent">要组合的事件对象</param>
/// <returns>返回当前OrEvent实例，支持链式调用</returns>
@ -18,10 +25,8 @@ public class OrEvent : IUnRegisterList
return this;
}
private Action _mOnEvent = () => { };
/// <summary>
/// 注册事件处理函数
/// 注册事件处理函数
/// </summary>
/// <param name="onEvent">要注册的事件处理函数</param>
/// <returns>返回一个可取消注册的对象</returns>
@ -32,7 +37,7 @@ public class OrEvent : IUnRegisterList
}
/// <summary>
/// 取消注册指定的事件处理函数
/// 取消注册指定的事件处理函数
/// </summary>
/// <param name="onEvent">要取消注册的事件处理函数</param>
public void UnRegister(Action onEvent)
@ -42,12 +47,10 @@ public class OrEvent : IUnRegisterList
}
/// <summary>
/// 触发所有已注册的事件处理函数
/// 触发所有已注册的事件处理函数
/// </summary>
private void Trigger() => _mOnEvent?.Invoke();
/// <summary>
/// 获取取消注册列表
/// </summary>
public List<IUnRegister> UnregisterList { get; } = new List<IUnRegister>();
}
private void Trigger()
{
_mOnEvent?.Invoke();
}
}

49
GFramework.Core/events/README.md
View File

@ -11,6 +11,7 @@ Events 包提供了一套完整的事件系统，实现了观察者模式（Obse
基础事件接口，定义了事件注册的基本功能。
**核心方法：**
```csharp
IUnRegister Register(Action onEvent); // 注册事件处理函数
```
@ -20,6 +21,7 @@ IUnRegister Register(Action onEvent); // 注册事件处理函数
注销接口，用于取消事件注册。
**核心方法：**
```csharp
void UnRegister(); // 执行注销操作
```
@ -29,6 +31,7 @@ void UnRegister(); // 执行注销操作
注销列表接口，用于批量管理注销对象。
**属性：**
```csharp
List<IUnRegister> UnregisterList { get; } // 获取注销列表
```
@ -456,42 +459,42 @@ public override void _Ready()
## 最佳实践
1. **事件命名规范**
- 使用过去式：`PlayerDiedEvent`、`LevelCompletedEvent`
- 使用 `Event` 后缀：便于识别
- 使用结构体：减少内存分配
- 使用过去式：`PlayerDiedEvent`、`LevelCompletedEvent`
- 使用 `Event` 后缀：便于识别
- 使用结构体：减少内存分配
2. **事件数据设计**
- 只包含必要信息
- 使用值类型（struct）提高性能
- 避免传递可变引用
- 只包含必要信息
- 使用值类型（struct）提高性能
- 避免传递可变引用
3. **避免事件循环**
- 事件处理器中谨慎发送新事件
- 使用命令打破循环依赖
- 事件处理器中谨慎发送新事件
- 使用命令打破循环依赖
4. **合理使用事件**
- 用于通知状态变化
- 用于跨模块通信
- 不用于返回数据（使用 Query）
- 用于通知状态变化
- 用于跨模块通信
- 不用于返回数据（使用 Query）
5. **注销管理**
- 始终注销事件监听
- 使用 `IUnRegisterList` 批量管理
- 利用 Godot 节点生命周期
- 始终注销事件监听
- 使用 `IUnRegisterList` 批量管理
- 利用 Godot 节点生命周期
6. **性能考虑**
- 避免频繁触发的事件（如每帧）
- 事件处理器保持轻量
- 使用结构体事件减少 GC
- 避免频繁触发的事件（如每帧）
- 事件处理器保持轻量
- 使用结构体事件减少 GC
## 事件 vs 其他通信方式
| 方式 | 适用场景 | 优点 | 缺点 |
|------|---------|------|------|
| **Event** | 状态变化通知、跨模块通信 | 松耦合、一对多 | 难以追踪调用链 |
| **Command** | 执行操作、修改状态 | 封装逻辑、可撤销 | 单向通信 |
| **Query** | 查询数据 | 职责清晰、有返回值 | 同步调用 |
| **BindableProperty** | UI 数据绑定 | 自动更新、响应式 | 仅限单一属性 |
| 方式 | 适用场景 | 优点 | 缺点 |
|----------------------|--------------|-----------|---------|
| **Event** | 状态变化通知、跨模块通信 | 松耦合、一对多 | 难以追踪调用链 |
| **Command** | 执行操作、修改状态 | 封装逻辑、可撤销 | 单向通信 |
| **Query** | 查询数据 | 职责清晰、有返回值 | 同步调用 |
| **BindableProperty** | UI 数据绑定 | 自动更新、响应式 | 仅限单一属性 |
## 相关包

20
GFramework.Core/events/TypeEventSystem.cs
View File

@ -1,19 +1,27 @@
namespace GFramework.Core.events;
/// <summary>
/// TypeEventSystem
/// TypeEventSystem
/// </summary>
public class TypeEventSystem
{
public static readonly TypeEventSystem Global = new();
private readonly EasyEvents _mEvents = new();
public static readonly TypeEventSystem Global = new();
public void Send<T>() where T : new()
{
_mEvents.GetEvent<EasyEvent<T>>()?.Trigger(new T());
}
public void Send<T>() where T : new() => _mEvents.GetEvent<EasyEvent<T>>()?.Trigger(new T());
public void Send<T>(T e)
{
_mEvents.GetEvent<EasyEvent<T>>()?.Trigger(e);
}
public void Send<T>(T e) => _mEvents.GetEvent<EasyEvent<T>>()?.Trigger(e);
public IUnRegister Register<T>(Action<T> onEvent) => _mEvents.GetOrAddEvent<EasyEvent<T>>().Register(onEvent);
public IUnRegister Register<T>(Action<T> onEvent)
{
return _mEvents.GetOrAddEvent<EasyEvent<T>>().Register(onEvent);
}
public void UnRegister<T>(Action<T> onEvent)
{

24
GFramework.Core/events/UnRegisterList.cs
View File

@ -1,15 +1,19 @@
namespace GFramework.Core.events;
/// <summary>
/// 取消注册列表类，用于管理多个需要取消注册的对象
/// 取消注册列表类，用于管理多个需要取消注册的对象
/// </summary>
public class UnRegisterList : IUnRegisterList
{
private readonly List<IUnRegister> _unRegisterList = [];
/// <summary>
/// 向取消注册列表中添加一个新的可取消注册对象
/// 获取取消注册列表的只读属性
/// </summary>
public List<IUnRegister> UnregisterList { get; }
/// <summary>
/// 向取消注册列表中添加一个新的可取消注册对象
/// </summary>
/// <param name="unRegister">需要添加到列表中的可取消注册对象</param>
public void Add(IUnRegister unRegister)
@ -18,22 +22,14 @@ public class UnRegisterList : IUnRegisterList
}
/// <summary>
/// 对列表中的所有对象执行取消注册操作，并清空列表
/// 对列表中的所有对象执行取消注册操作，并清空列表
/// </summary>
public void UnRegisterAll()
{
// 遍历所有注册项并执行取消注册
foreach (var t in _unRegisterList)
{
t.UnRegister();
}
foreach (var t in _unRegisterList) t.UnRegister();
// 清空列表
_unRegisterList.Clear();
}
/// <summary>
/// 获取取消注册列表的只读属性
/// </summary>
public List<IUnRegister> UnregisterList { get; }
}
}

30
GFramework.Core/extensions/CanGetExtensions.cs
View File

@ -5,46 +5,52 @@ using GFramework.Core.utility;
namespace GFramework.Core.extensions;
/// <summary>
/// 提供获取模型对象扩展方法的静态类
/// 提供获取模型对象扩展方法的静态类
/// </summary>
public static class CanGetModelExtension
{
/// <summary>
/// 从架构中获取指定类型的模型实例
/// 从架构中获取指定类型的模型实例
/// </summary>
/// <typeparam name="T">要获取的模型类型，必须实现IModel接口</typeparam>
/// <param name="self">实现ICanGetModel接口的对象实例</param>
/// <returns>指定类型的模型实例</returns>
public static T GetModel<T>(this ICanGetModel self) where T : class, IModel =>
self.GetArchitecture().GetModel<T>();
public static T GetModel<T>(this ICanGetModel self) where T : class, IModel
{
return self.GetArchitecture().GetModel<T>();
}
}
/// <summary>
/// 提供获取系统对象扩展方法的静态类
/// 提供获取系统对象扩展方法的静态类
/// </summary>
public static class CanGetSystemExtension
{
/// <summary>
/// 从架构中获取指定类型的系统实例
/// 从架构中获取指定类型的系统实例
/// </summary>
/// <typeparam name="T">要获取的系统类型，必须实现ISystem接口</typeparam>
/// <param name="self">实现ICanGetSystem接口的对象实例</param>
/// <returns>指定类型的系统实例</returns>
public static T GetSystem<T>(this ICanGetSystem self) where T : class, ISystem =>
self.GetArchitecture().GetSystem<T>();
public static T GetSystem<T>(this ICanGetSystem self) where T : class, ISystem
{
return self.GetArchitecture().GetSystem<T>();
}
}
/// <summary>
/// 提供获取工具对象扩展方法的静态类
/// 提供获取工具对象扩展方法的静态类
/// </summary>
public static class CanGetUtilityExtension
{
/// <summary>
/// 从架构中获取指定类型的工具实例
/// 从架构中获取指定类型的工具实例
/// </summary>
/// <typeparam name="T">要获取的工具类型，必须实现IUtility接口</typeparam>
/// <param name="self">实现ICanGetUtility接口的对象实例</param>
/// <returns>指定类型的工具实例</returns>
public static T GetUtility<T>(this ICanGetUtility self) where T : class, IUtility =>
self.GetArchitecture().GetUtility<T>();
public static T GetUtility<T>(this ICanGetUtility self) where T : class, IUtility
{
return self.GetArchitecture().GetUtility<T>();
}
}

18
GFramework.Core/extensions/CanRegisterEventExtensions.cs
View File

@ -3,26 +3,30 @@
namespace GFramework.Core.extensions;
/// <summary>
/// 事件注册扩展类，提供ICanRegisterEvent接口的扩展方法用于注册和注销事件
/// 事件注册扩展类，提供ICanRegisterEvent接口的扩展方法用于注册和注销事件
/// </summary>
public static class CanRegisterEventExtensions
{
/// <summary>
/// 注册指定类型的事件处理函数
/// 注册指定类型的事件处理函数
/// </summary>
/// <typeparam name="T">事件数据类型</typeparam>
/// <param name="self">实现ICanRegisterEvent接口的对象实例</param>
/// <param name="onEvent">事件处理回调函数</param>
/// <returns>返回事件注销器接口，可用于后续注销事件</returns>
public static IUnRegister RegisterEvent<T>(this ICanRegisterEvent self, Action<T> onEvent) =>
self.GetArchitecture().RegisterEvent(onEvent);
public static IUnRegister RegisterEvent<T>(this ICanRegisterEvent self, Action<T> onEvent)
{
return self.GetArchitecture().RegisterEvent(onEvent);
}
/// <summary>
/// 注销指定类型的事件处理函数
/// 注销指定类型的事件处理函数
/// </summary>
/// <typeparam name="T">事件数据类型</typeparam>
/// <param name="self">实现ICanRegisterEvent接口的对象实例</param>
/// <param name="onEvent">要注销的事件处理回调函数</param>
public static void UnRegisterEvent<T>(this ICanRegisterEvent self, Action<T> onEvent) =>
public static void UnRegisterEvent<T>(this ICanRegisterEvent self, Action<T> onEvent)
{
self.GetArchitecture().UnRegisterEvent(onEvent);
}
}
}

49
GFramework.Core/extensions/CanSendExtensions.cs
View File

@ -5,72 +5,85 @@ using GFramework.Core.query;
namespace GFramework.Core.extensions;
/// <summary>
/// 提供发送命令功能的扩展类
/// 提供发送命令功能的扩展类
/// </summary>
public static class CanSendCommandExtension
{
/// <summary>
/// 发送指定类型的命令，该命令类型必须实现ICommand接口且具有无参构造函数
/// 发送指定类型的命令，该命令类型必须实现ICommand接口且具有无参构造函数
/// </summary>
/// <typeparam name="T">命令类型，必须实现ICommand接口且具有无参构造函数</typeparam>
/// <param name="self">实现ICanSendCommand接口的对象实例</param>
public static void SendCommand<T>(this ICanSendCommand self) where T : ICommand, new() =>
public static void SendCommand<T>(this ICanSendCommand self) where T : ICommand, new()
{
self.GetArchitecture().SendCommand(new T());
}
/// <summary>
/// 发送指定的命令实例
/// 发送指定的命令实例
/// </summary>
/// <typeparam name="T">命令类型，必须实现ICommand接口</typeparam>
/// <param name="self">实现ICanSendCommand接口的对象实例</param>
/// <param name="command">要发送的命令实例</param>
public static void SendCommand<T>(this ICanSendCommand self, T command) where T : ICommand =>
public static void SendCommand<T>(this ICanSendCommand self, T command) where T : ICommand
{
self.GetArchitecture().SendCommand(command);
}
/// <summary>
/// 发送带有返回值的命令并获取执行结果
/// 发送带有返回值的命令并获取执行结果
/// </summary>
/// <typeparam name="TResult">命令执行结果的类型</typeparam>
/// <param name="self">实现ICanSendCommand接口的对象实例</param>
/// <param name="command">要发送的命令实例，必须实现ICommand&lt;TResult&gt;接口</param>
/// <returns>命令执行后的返回结果</returns>
public static TResult SendCommand<TResult>(this ICanSendCommand self, ICommand<TResult> command) =>
self.GetArchitecture().SendCommand(command);
public static TResult SendCommand<TResult>(this ICanSendCommand self, ICommand<TResult> command)
{
return self.GetArchitecture().SendCommand(command);
}
}
/// <summary>
/// 提供发送事件功能的扩展类
/// 提供发送事件功能的扩展类
/// </summary>
public static class CanSendEventExtension
{
/// <summary>
/// 发送指定类型的事件，该事件类型必须具有无参构造函数
/// 发送指定类型的事件，该事件类型必须具有无参构造函数
/// </summary>
/// <typeparam name="T">事件类型，必须具有无参构造函数</typeparam>
/// <param name="self">实现ICanSendEvent接口的对象实例</param>
public static void SendEvent<T>(this ICanSendEvent self) where T : new() =>
public static void SendEvent<T>(this ICanSendEvent self) where T : new()
{
self.GetArchitecture().SendEvent<T>();
}
/// <summary>
/// 发送指定的事件实例
/// 发送指定的事件实例
/// </summary>
/// <typeparam name="T">事件类型</typeparam>
/// <param name="self">实现ICanSendEvent接口的对象实例</param>
/// <param name="e">要发送的事件实例</param>
public static void SendEvent<T>(this ICanSendEvent self, T e) => self.GetArchitecture().SendEvent(e);
public static void SendEvent<T>(this ICanSendEvent self, T e)
{
self.GetArchitecture().SendEvent(e);
}
}
/// <summary>
/// 提供发送查询功能的扩展类
/// 提供发送查询功能的扩展类
/// </summary>
public static class CanSendQueryExtension
{
/// <summary>
/// 发送查询请求并获取查询结果
/// 发送查询请求并获取查询结果
/// </summary>
/// <typeparam name="TResult">查询结果的类型</typeparam>
/// <param name="self">实现ICanSendQuery接口的对象实例</param>
/// <param name="query">要发送的查询实例，必须实现IQuery&lt;TResult&gt;接口</param>
/// <returns>查询操作的返回结果</returns>
public static TResult SendQuery<TResult>(this ICanSendQuery self, IQuery<TResult> query) =>
self.GetArchitecture().SendQuery(query);
}
public static TResult SendQuery<TResult>(this ICanSendQuery self, IQuery<TResult> query)
{
return self.GetArchitecture().SendQuery(query);
}
}

9
GFramework.Core/extensions/OrEventExtensions.cs
View File

@ -3,15 +3,18 @@
namespace GFramework.Core.extensions;
/// <summary>
/// 提供Or事件扩展方法的静态类
/// 提供Or事件扩展方法的静态类
/// </summary>
public static class OrEventExtensions
{
/// <summary>
/// 创建一个OrEvent实例，将当前事件与指定事件进行逻辑或运算组合
/// 创建一个OrEvent实例，将当前事件与指定事件进行逻辑或运算组合
/// </summary>
/// <param name="self">当前的IEasyEvent事件实例</param>
/// <param name="e">要与当前事件进行或运算的另一个IEasyEvent事件实例</param>
/// <returns>返回一个新的OrEvent实例，表示两个事件的或运算结果</returns>
public static OrEvent Or(this IEasyEvent self, IEasyEvent e) => new OrEvent().Or(self).Or(e);
public static OrEvent Or(this IEasyEvent self, IEasyEvent e)
{
return new OrEvent().Or(self).Or(e);
}
}

17
GFramework.Core/extensions/README.md
View File

@ -8,7 +8,8 @@ Extensions 包提供了一系列扩展方法，简化了框架各个接口的使
### 1. 获取组件扩展 ([`CanGetExtensions.cs`](CanGetExtensions.cs))
为 [`ICanGetModel`](../model/ICanGetModel.cs)、[`ICanGetSystem`](../system/ICanGetSystem.cs)、[`ICanGetUtility`](../utility/ICanGetUtility.cs) 提供扩展方法。
为 [`ICanGetModel`](../model/ICanGetModel.cs)、[`ICanGetSystem`](../system/ICanGetSystem.cs)、[
`ICanGetUtility`](../utility/ICanGetUtility.cs) 提供扩展方法。
#### CanGetModelExtension
@ -480,17 +481,17 @@ public class AchievementSystem : AbstractSystem
```
2. **理解扩展方法本质**：
- 扩展方法是静态方法的语法糖
- 不会改变原始类型的结构
- 仅在编译时解析
- 扩展方法是静态方法的语法糖
- 不会改变原始类型的结构
- 仅在编译时解析
3. **Godot 特定功能**：
- `UnRegisterWhenNodeExitTree` 仅在 Godot 环境下可用
- 使用 `#if GODOT` 编译指令控制
- `UnRegisterWhenNodeExitTree` 仅在 Godot 环境下可用
- 使用 `#if GODOT` 编译指令控制
4. **性能考虑**：
- 扩展方法本身无性能开销
- 实际调用的是底层方法
- 扩展方法本身无性能开销
- 实际调用的是底层方法
## 相关包

18
GFramework.Core/extensions/UnRegisterListExtension.cs
View File

@ -2,33 +2,31 @@
namespace GFramework.Core.extensions;
/// <summary>
/// 扩展方法类，为IUnRegister和IUnRegisterList接口提供便捷的注册和注销功能
/// 扩展方法类，为IUnRegister和IUnRegisterList接口提供便捷的注册和注销功能
/// </summary>
public static class UnRegisterListExtension
{
/// <summary>
/// 将指定的可注销对象添加到注销列表中
/// 将指定的可注销对象添加到注销列表中
/// </summary>
/// <param name="self">要添加的可注销对象</param>
/// <param name="unRegisterList">目标注销列表</param>
public static void AddToUnregisterList(this IUnRegister self, IUnRegisterList unRegisterList) =>
public static void AddToUnregisterList(this IUnRegister self, IUnRegisterList unRegisterList)
{
unRegisterList.UnregisterList.Add(self);
}
/// <summary>
/// 注销列表中的所有对象并清空列表
/// 注销列表中的所有对象并清空列表
/// </summary>
/// <param name="self">包含注销列表的对象</param>
public static void UnRegisterAll(this IUnRegisterList self)
{
// 遍历注销列表中的所有对象并执行注销操作
foreach (var unRegister in self.UnregisterList)
{
unRegister.UnRegister();
}
foreach (var unRegister in self.UnregisterList) unRegister.UnRegister();
// 清空注销列表
self.UnregisterList.Clear();
}
}
}

13
GFramework.Core/ioc/IocContainer.cs
View File

@ -1,14 +1,14 @@
namespace GFramework.Core.ioc;
/// <summary>
/// IOC容器类，用于管理对象的注册和获取
/// IOC容器类，用于管理对象的注册和获取
/// </summary>
public class IocContainer
{
private readonly Dictionary<Type, object> _mInstances = new();
/// <summary>
/// 注册一个实例到IOC容器中
/// 注册一个实例到IOC容器中
/// </summary>
/// <typeparam name="T">实例的类型</typeparam>
/// <param name="instance">要注册的实例对象</param>
@ -20,7 +20,7 @@ public class IocContainer
}
/// <summary>
/// 从IOC容器中获取指定类型的实例
/// 从IOC容器中获取指定类型的实例
/// </summary>
/// <typeparam name="T">要获取的实例类型</typeparam>
/// <returns>返回指定类型的实例，如果未找到则返回null</returns>
@ -29,11 +29,8 @@ public class IocContainer
var key = typeof(T);
// 尝试从字典中获取实例
if (_mInstances.TryGetValue(key, out var retInstance))
{
return retInstance as T;
}
if (_mInstances.TryGetValue(key, out var retInstance)) return retInstance as T;
return null;
}
}
}

24
GFramework.Core/ioc/README.md
View File

@ -2,7 +2,8 @@
## 概述
IoC（Inversion of Control，控制反转）包提供了一个轻量级的依赖注入容器，用于管理框架中各种组件的注册和获取。通过 IoC 容器，可以实现组件间的解耦，便于测试和维护。
IoC（Inversion of Control，控制反转）包提供了一个轻量级的依赖注入容器，用于管理框架中各种组件的注册和获取。通过 IoC
容器，可以实现组件间的解耦，便于测试和维护。
## 核心类
@ -11,6 +12,7 @@ IoC（Inversion of Control，控制反转）包提供了一个轻量级的依赖
IoC 容器类，负责管理对象的注册和获取。
**主要功能：**
- 注册实例到容器
- 从容器中获取实例
- 类型安全的依赖管理
@ -26,6 +28,7 @@ public void Register<T>(T instance)
```
**参数：**
- `instance`: 要注册的实例对象
**使用示例：**
@ -48,6 +51,7 @@ public T Get<T>() where T : class
```
**返回值：**
- 返回指定类型的实例，如果未找到则返回 `null`
**使用示例：**
@ -294,6 +298,7 @@ var service = container.Get<MyService>();
```
**特点：**
- ✅ 简单易用
- ✅ 性能高
- ❌ 不支持构造函数注入
@ -314,6 +319,7 @@ var controller = container.Resolve<MyController>();
```
**特点：**
- ✅ 自动依赖注入
- ✅ 生命周期管理
- ✅ 复杂场景支持
@ -391,20 +397,20 @@ else
## 注意事项
1. **类型唯一性**
- 每个类型只能注册一个实例
- 重复注册会覆盖之前的实例
- 每个类型只能注册一个实例
- 重复注册会覆盖之前的实例
2. **手动管理依赖顺序**
- 组件的依赖关系需要手动保证
- 先注册被依赖的组件
- 组件的依赖关系需要手动保证
- 先注册被依赖的组件
3. **无生命周期管理**
- 实例一旦注册就一直存在
- 需要手动管理实例的生命周期
- 实例一旦注册就一直存在
- 需要手动管理实例的生命周期
4. **线程安全**
- 当前实现非线程安全
- 避免多线程同时访问
- 当前实现非线程安全
- 避免多线程同时访问
## 扩展可能性

29
GFramework.Core/model/AbstractModel.cs
View File

@ -3,34 +3,43 @@
namespace GFramework.Core.model;
/// <summary>
/// 抽象模型基类，实现IModel接口，提供模型的基本架构支持
/// 抽象模型基类，实现IModel接口，提供模型的基本架构支持
/// </summary>
public abstract class AbstractModel : IModel
{
/// <summary>
/// 模型所属的架构实例
/// 模型所属的架构实例
/// </summary>
protected IArchitecture Architecture;
/// <summary>
/// 获取模型所属的架构实例
/// 获取模型所属的架构实例
/// </summary>
/// <returns>返回当前模型关联的架构对象</returns>
public IArchitecture GetArchitecture() => Architecture;
public IArchitecture GetArchitecture()
{
return Architecture;
}
/// <summary>
/// 设置模型所属的架构实例
/// 设置模型所属的架构实例
/// </summary>
/// <param name="architecture">要关联到此模型的架构实例</param>
public void SetArchitecture(IArchitecture architecture) => Architecture = architecture;
public void SetArchitecture(IArchitecture architecture)
{
Architecture = architecture;
}
/// <summary>
/// 初始化模型，调用抽象方法OnInit执行具体初始化逻辑
/// 初始化模型，调用抽象方法OnInit执行具体初始化逻辑
/// </summary>
void IModel.Init() => OnInit();
void IModel.Init()
{
OnInit();
}
/// <summary>
/// 抽象初始化方法，由子类实现具体的初始化逻辑
/// 抽象初始化方法，由子类实现具体的初始化逻辑
/// </summary>
protected abstract void OnInit();
}
}

6
GFramework.Core/model/ICanGetModel.cs
View File

@ -3,7 +3,7 @@
namespace GFramework.Core.model;
/// <summary>
/// 定义一个接口，表示可以获取模型的架构组件。
/// 该接口继承自IBelongToArchitecture，表明实现此接口的类型属于特定架构。
/// 定义一个接口，表示可以获取模型的架构组件。
/// 该接口继承自IBelongToArchitecture，表明实现此接口的类型属于特定架构。
/// </summary>
public interface ICanGetModel : IBelongToArchitecture;
public interface ICanGetModel : IBelongToArchitecture;

6
GFramework.Core/model/IModel.cs
View File

@ -5,12 +5,12 @@ using GFramework.Core.utility;
namespace GFramework.Core.model;
/// <summary>
/// 模型接口，定义了模型的基本行为和功能
/// 模型接口，定义了模型的基本行为和功能
/// </summary>
public interface IModel : ICanSetArchitecture, ICanGetUtility, ICanSendEvent
{
/// <summary>
/// 初始化模型
/// 初始化模型
/// </summary>
void Init();
}
}

5
GFramework.Core/model/README.md
View File

@ -2,7 +2,8 @@
## 概述
Model 包定义了数据模型层的接口和基类。Model 是 MVC 架构中的 M 层，负责管理应用程序的数据和状态。Model 层应该只包含数据和简单的数据逻辑，不包含复杂的业务逻辑。
Model 包定义了数据模型层的接口和基类。Model 是 MVC 架构中的 M 层，负责管理应用程序的数据和状态。Model
层应该只包含数据和简单的数据逻辑，不包含复杂的业务逻辑。
## 核心接口
@ -11,11 +12,13 @@ Model 包定义了数据模型层的接口和基类。Model 是 MVC 架构中的
模型接口，定义了模型的基本行为和功能。
**继承的能力接口：**
- [`ICanSetArchitecture`](../rule/ICanSetArchitecture.cs) - 可设置架构引用
- [`ICanGetUtility`](../utility/ICanGetUtility.cs) - 可获取工具类
- [`ICanSendEvent`](../events/ICanSendEvent.cs) - 可发送事件
**核心方法：**
```csharp
void Init(); // 初始化模型
```

96
GFramework.Core/property/BindableProperty.cs
View File

@ -2,34 +2,23 @@ using GFramework.Core.events;
namespace GFramework.Core.property;
/// <summary>
/// 可绑定属性类，用于实现数据绑定功能
/// 可绑定属性类，用于实现数据绑定功能
/// </summary>
/// <typeparam name="T">属性值的类型</typeparam>
/// <param name="defaultValue">属性的默认值</param>
public class BindableProperty<T>(T defaultValue = default!) : IBindableProperty<T>
{
private Action<T>? _mOnValueChanged;
protected T MValue = defaultValue;
/// <summary>
/// 获取或设置属性值比较器，默认使用Equals方法进行比较
/// 获取或设置属性值比较器，默认使用Equals方法进行比较
/// </summary>
public static Func<T, T, bool> Comparer { get; set; } = (a, b) => a!.Equals(b)!;
/// <summary>
/// 设置自定义比较器
/// </summary>
/// <param name="comparer">用于比较两个值是否相等的函数</param>
/// <returns>当前可绑定属性实例</returns>
public BindableProperty<T> WithComparer(Func<T, T, bool> comparer)
{
Comparer = comparer;
return this;
}
/// <summary>
/// 获取或设置属性值，当值发生变化时会触发注册的回调事件
/// 获取或设置属性值，当值发生变化时会触发注册的回调事件
/// </summary>
public T Value
{
@ -37,12 +26,12 @@ public class BindableProperty<T>(T defaultValue = default!) : IBindableProperty<
set
{
// 使用 default(T) 替代 null 比较，避免 SonarQube 警告
if (EqualityComparer<T>.Default.Equals(value, default!) &&
EqualityComparer<T>.Default.Equals(MValue, default!))
if (EqualityComparer<T>.Default.Equals(value, default!) &&
EqualityComparer<T>.Default.Equals(MValue, default!))
return;
// 若新值与旧值相等则不执行后续操作
if (!EqualityComparer<T>.Default.Equals(value, default!) && Comparer(value, MValue))
if (!EqualityComparer<T>.Default.Equals(value, default!) && Comparer(value, MValue))
return;
SetValue(value);
@ -51,27 +40,16 @@ public class BindableProperty<T>(T defaultValue = default!) : IBindableProperty<
}
/// <summary>
/// 设置属性值的虚方法，可在子类中重写
/// 直接设置属性值而不触发事件
/// </summary>
/// <param name="newValue">新的属性值</param>
protected virtual void SetValue(T newValue) => MValue = newValue;
public void SetValueWithoutEvent(T newValue)
{
MValue = newValue;
}
/// <summary>
/// 获取属性值的虚方法，可在子类中重写
/// </summary>
/// <returns>当前属性值</returns>
protected virtual T GetValue() => MValue;
/// <summary>
/// 直接设置属性值而不触发事件
/// </summary>
/// <param name="newValue">新的属性值</param>
public void SetValueWithoutEvent(T newValue) => MValue = newValue;
private Action<T>? _mOnValueChanged = null;
/// <summary>
/// 注册属性值变化事件回调
/// 注册属性值变化事件回调
/// </summary>
/// <param name="onValueChanged">属性值变化时的回调函数</param>
/// <returns>可用于取消注册的接口</returns>
@ -82,7 +60,7 @@ public class BindableProperty<T>(T defaultValue = default!) : IBindableProperty<
}
/// <summary>
/// 注册属性值变化事件回调，并立即调用回调函数传递当前值
/// 注册属性值变化事件回调，并立即调用回调函数传递当前值
/// </summary>
/// <param name="action">属性值变化时的回调函数</param>
/// <returns>可用于取消注册的接口</returns>
@ -93,19 +71,23 @@ public class BindableProperty<T>(T defaultValue = default!) : IBindableProperty<
}
/// <summary>
/// 取消注册属性值变化事件回调
/// 取消注册属性值变化事件回调
/// </summary>
/// <param name="onValueChanged">要取消注册的回调函数</param>
public void UnRegister(Action<T> onValueChanged) => _mOnValueChanged -= onValueChanged;
public void UnRegister(Action<T> onValueChanged)
{
_mOnValueChanged -= onValueChanged;
}
/// <summary>
/// 实现IEasyEvent接口的注册方法，将无参事件转换为有参事件处理
/// 实现IEasyEvent接口的注册方法，将无参事件转换为有参事件处理
/// </summary>
/// <param name="onEvent">无参事件回调</param>
/// <returns>可用于取消注册的接口</returns>
IUnRegister IEasyEvent.Register(Action onEvent)
{
return Register(Action);
void Action(T _)
{
onEvent();
@ -113,8 +95,40 @@ public class BindableProperty<T>(T defaultValue = default!) : IBindableProperty<
}
/// <summary>
/// 返回属性值的字符串表示形式
/// 设置自定义比较器
/// </summary>
/// <param name="comparer">用于比较两个值是否相等的函数</param>
/// <returns>当前可绑定属性实例</returns>
public BindableProperty<T> WithComparer(Func<T, T, bool> comparer)
{
Comparer = comparer;
return this;
}
/// <summary>
/// 设置属性值的虚方法，可在子类中重写
/// </summary>
/// <param name="newValue">新的属性值</param>
protected virtual void SetValue(T newValue)
{
MValue = newValue;
}
/// <summary>
/// 获取属性值的虚方法，可在子类中重写
/// </summary>
/// <returns>当前属性值</returns>
protected virtual T GetValue()
{
return MValue;
}
/// <summary>
/// 返回属性值的字符串表示形式
/// </summary>
/// <returns>属性值的字符串表示</returns>
public override string ToString() => Value?.ToString() ?? string.Empty;
public override string ToString()
{
return Value?.ToString() ?? string.Empty;
}
}

11
GFramework.Core/property/BindablePropertyUnRegister.cs
View File

@ -2,9 +2,8 @@ using GFramework.Core.events;
namespace GFramework.Core.property;
/// <summary>
/// 可绑定属性注销器类，用于取消注册可绑定属性的值变化监听
/// 可绑定属性注销器类，用于取消注册可绑定属性的值变化监听
/// </summary>
/// <typeparam name="T">可绑定属性的值类型</typeparam>
/// <param name="bindableProperty">需要注销的可绑定属性实例</param>
@ -13,17 +12,17 @@ public class BindablePropertyUnRegister<T>(BindableProperty<T> bindableProperty,
: IUnRegister
{
/// <summary>
/// 获取或设置可绑定属性实例
/// 获取或设置可绑定属性实例
/// </summary>
public BindableProperty<T> BindableProperty { get; set; } = bindableProperty;
/// <summary>
/// 获取或设置值变化时的回调函数
/// 获取或设置值变化时的回调函数
/// </summary>
public Action<T> OnValueChanged { get; set; } = onValueChanged;
/// <summary>
/// 执行注销操作，取消注册值变化监听并清理引用
/// 执行注销操作，取消注册值变化监听并清理引用
/// </summary>
public void UnRegister()
{
@ -34,4 +33,4 @@ public class BindablePropertyUnRegister<T>(BindableProperty<T> bindableProperty,
// 清理回调函数引用
OnValueChanged = null;
}
}
}

10
GFramework.Core/property/IBindableProperty.cs
View File

@ -1,19 +1,19 @@
namespace GFramework.Core.property;
/// <summary>
/// 可绑定属性接口，继承自只读可绑定属性接口，提供可读写的属性绑定功能
/// 可绑定属性接口，继承自只读可绑定属性接口，提供可读写的属性绑定功能
/// </summary>
/// <typeparam name="T">属性值的类型</typeparam>
public interface IBindableProperty<T> : IReadonlyBindableProperty<T>
{
/// <summary>
/// 获取或设置属性的值
/// 获取或设置属性的值
/// </summary>
new T Value { get; set; }
/// <summary>
/// 设置属性值但不触发事件通知
/// 设置属性值但不触发事件通知
/// </summary>
/// <param name="newValue">要设置的新值</param>
void SetValueWithoutEvent(T newValue);
}
}

17
GFramework.Core/property/IReadonlyBindableProperty.cs
View File

@ -2,35 +2,34 @@ using GFramework.Core.events;
namespace GFramework.Core.property;
/// <summary>
/// 只读可绑定属性接口，提供属性值的读取和变更监听功能
/// 只读可绑定属性接口，提供属性值的读取和变更监听功能
/// </summary>
/// <typeparam name="T">属性值的类型</typeparam>
public interface IReadonlyBindableProperty<out T> : IEasyEvent
{
/// <summary>
/// 获取属性的当前值
/// 获取属性的当前值
/// </summary>
T Value { get; }
/// <summary>
/// 注册属性值变更回调，并立即执行一次初始值的回调
/// 注册属性值变更回调，并立即执行一次初始值的回调
/// </summary>
/// <param name="action">属性值变更时执行的回调函数，参数为新的属性值</param>
/// <returns>用于取消注册的句柄对象</returns>
IUnRegister RegisterWithInitValue(Action<T> action);
/// <summary>
/// 取消注册属性值变更回调
/// 取消注册属性值变更回调
/// </summary>
/// <param name="onValueChanged">要取消注册的回调函数</param>
void UnRegister(Action<T> onValueChanged);
/// <summary>
/// 注册属性值变更回调
/// 注册属性值变更回调
/// </summary>
/// <param name="onValueChanged">属性值变更时执行的回调函数，参数为新的属性值</param>
/// <returns>用于取消注册的句柄对象</returns>
IUnRegister Register(Action<T> onValueChanged);
}
}

2
GFramework.Core/property/README.md
View File

@ -11,6 +11,7 @@ Property 包提供了可绑定属性（BindableProperty）的实现，支持属
只读可绑定属性接口，提供属性值的读取和变更监听功能。
**核心成员：**
```csharp
T Value { get; } // 获取属性值
IUnRegister Register(Action<T> onValueChanged); // 注册监听
@ -23,6 +24,7 @@ void UnRegister(Action<T> onValueChanged); // 取消监听
可绑定属性接口，继承自只读接口，增加了修改能力。
**核心成员：**
```csharp
new T Value { get; set; } // 可读写的属性值
void SetValueWithoutEvent(T newValue); // 设置值但不触发事件

47
GFramework.Core/query/AbstractQuery.cs
View File

@ -3,34 +3,43 @@ using GFramework.Core.architecture;
namespace GFramework.Core.query;
/// <summary>
/// 抽象查询类，提供查询操作的基础实现
/// 抽象查询类，提供查询操作的基础实现
/// </summary>
/// <typeparam name="T">查询结果的类型</typeparam>
public abstract class AbstractQuery<T> : IQuery<T>
{
/// <summary>
/// 执行查询操作
/// </summary>
/// <returns>查询结果</returns>
public T Do() => OnDo();
/// <summary>
/// 抽象方法，由子类实现具体的查询逻辑
/// </summary>
/// <returns>查询结果</returns>
protected abstract T OnDo();
private IArchitecture _mArchitecture;
/// <summary>
/// 获取架构实例
/// 执行查询操作
/// </summary>
/// <returns>架构实例</returns>
public IArchitecture GetArchitecture() => _mArchitecture;
/// <returns>查询结果</returns>
public T Do()
{
return OnDo();
}
/// <summary>
/// 设置架构实例
/// 获取架构实例
/// </summary>
/// <returns>架构实例</returns>
public IArchitecture GetArchitecture()
{
return _mArchitecture;
}
/// <summary>
/// 设置架构实例
/// </summary>
/// <param name="architecture">要设置的架构实例</param>
public void SetArchitecture(IArchitecture architecture) => _mArchitecture = architecture;
}
public void SetArchitecture(IArchitecture architecture)
{
_mArchitecture = architecture;
}
/// <summary>
/// 抽象方法，由子类实现具体的查询逻辑
/// </summary>
/// <returns>查询结果</returns>
protected abstract T OnDo();
}

6
GFramework.Core/query/ICanSendQuery.cs
View File

@ -3,7 +3,7 @@ using GFramework.Core.rule;
namespace GFramework.Core.query;
/// <summary>
/// 定义一个可以发送查询的接口契约
/// 该接口继承自IBelongToArchitecture，表示实现此接口的类型属于某个架构组件
/// 定义一个可以发送查询的接口契约
/// 该接口继承自IBelongToArchitecture，表示实现此接口的类型属于某个架构组件
/// </summary>
public interface ICanSendQuery : IBelongToArchitecture;
public interface ICanSendQuery : IBelongToArchitecture;

7
GFramework.Core/query/IQuery.cs
View File

@ -4,17 +4,16 @@ using GFramework.Core.system;
namespace GFramework.Core.query;
/// <summary>
/// 查询接口，定义了执行查询操作的契约
/// 查询接口，定义了执行查询操作的契约
/// </summary>
/// <typeparam name="TResult">查询结果的类型</typeparam>
public interface IQuery<out TResult> : ICanSetArchitecture, ICanGetModel, ICanGetSystem,
ICanSendQuery
{
/// <summary>
/// 执行查询操作并返回结果
/// 执行查询操作并返回结果
/// </summary>
/// <returns>查询的结果，类型为 TResult</returns>
TResult Do();
}
}

9
GFramework.Core/query/README.md
View File

@ -2,7 +2,8 @@
## 概述
Query 包实现了 CQRS（命令查询职责分离）模式中的查询部分。Query 用于封装数据查询逻辑，与 Command 不同的是，Query 有返回值且不应该修改系统状态。
Query 包实现了 CQRS（命令查询职责分离）模式中的查询部分。Query 用于封装数据查询逻辑，与 Command 不同的是，Query
有返回值且不应该修改系统状态。
## 核心接口
@ -11,6 +12,7 @@ Query 包实现了 CQRS（命令查询职责分离）模式中的查询部分。
标记接口，表示该类型可以发送查询。
**继承关系：**
```csharp
public interface ICanSendQuery : IBelongToArchitecture
```
@ -20,11 +22,13 @@ public interface ICanSendQuery : IBelongToArchitecture
查询接口，定义了查询的基本契约。
**核心成员：**
```csharp
TResult Do(); // 执行查询并返回结果
```
**继承的能力：**
- `ICanSetArchitecture` - 可设置架构
- `ICanGetModel` - 可获取 Model
- `ICanGetSystem` - 可获取 System
@ -37,6 +41,7 @@ TResult Do(); // 执行查询并返回结果
抽象查询基类，提供了查询的基础实现。
**使用方式：**
```csharp
public abstract class AbstractQuery<T> : IQuery<T>
{
@ -287,11 +292,13 @@ public class EnemyAISystem : AbstractSystem
## Command vs Query
### Command（命令）
- **用途**：修改系统状态
- **返回值**：无返回值（void）
- **示例**：购买物品、造成伤害、升级角色
### Query（查询）
- **用途**：读取数据，不修改状态
- **返回值**：有返回值
- **示例**：获取金币数量、检查技能冷却、查询玩家位置

9
GFramework.Core/rule/IBelongToArchitecture.cs
View File

@ -2,16 +2,15 @@ using GFramework.Core.architecture;
namespace GFramework.Core.rule;
/// <summary>
/// 定义一个接口，用于标识某个对象属于特定的架构体系。
/// 实现此接口的对象可以通过GetArchitecture方法获取其所属的架构实例。
/// 定义一个接口，用于标识某个对象属于特定的架构体系。
/// 实现此接口的对象可以通过GetArchitecture方法获取其所属的架构实例。
/// </summary>
public interface IBelongToArchitecture
{
/// <summary>
/// 获取当前对象所属的架构实例。
/// 获取当前对象所属的架构实例。
/// </summary>
/// <returns>返回实现IArchitecture接口的架构实例</returns>
IArchitecture GetArchitecture();
}
}

6
GFramework.Core/rule/ICanSetArchitecture.cs
View File

@ -3,13 +3,13 @@ using GFramework.Core.architecture;
namespace GFramework.Core.rule;
/// <summary>
/// 定义一个接口，用于设置架构实例
/// 定义一个接口，用于设置架构实例
/// </summary>
public interface ICanSetArchitecture
{
/// <summary>
/// 设置架构实例
/// 设置架构实例
/// </summary>
/// <param name="architecture">要设置的架构实例</param>
void SetArchitecture(IArchitecture architecture);
}
}

4
GFramework.Core/rule/README.md
View File

@ -11,6 +11,7 @@ Rule 包定义了框架的核心规则接口，这些接口规定了框架各个
标记接口，表示某个对象属于特定的架构体系。
**接口定义：**
```csharp
public interface IBelongToArchitecture
{
@ -19,6 +20,7 @@ public interface IBelongToArchitecture
```
**实现此接口的类型：**
- Controller
- System
- Model
@ -34,6 +36,7 @@ public interface IBelongToArchitecture
定义可以设置架构实例的能力。
**接口定义：**
```csharp
public interface ICanSetArchitecture
{
@ -42,6 +45,7 @@ public interface ICanSetArchitecture
```
**实现此接口的类型：**
- Command
- Query

29
GFramework.Core/system/AbstractSystem.cs
View File

@ -4,32 +4,41 @@ using GFramework.Core.rule;
namespace GFramework.Core.system;
/// <summary>
/// 抽象系统基类，实现系统接口的基本功能
/// 提供架构关联和初始化机制
/// 抽象系统基类，实现系统接口的基本功能
/// 提供架构关联和初始化机制
/// </summary>
public abstract class AbstractSystem : ISystem
{
private IArchitecture _mArchitecture;
/// <summary>
/// 获取当前系统所属的架构实例
/// 获取当前系统所属的架构实例
/// </summary>
/// <returns>返回系统关联的架构对象</returns>
IArchitecture IBelongToArchitecture.GetArchitecture() => _mArchitecture;
IArchitecture IBelongToArchitecture.GetArchitecture()
{
return _mArchitecture;
}
/// <summary>
/// 设置系统所属的架构实例
/// 设置系统所属的架构实例
/// </summary>
/// <param name="architecture">要关联的架构对象</param>
void ICanSetArchitecture.SetArchitecture(IArchitecture architecture) => _mArchitecture = architecture;
void ICanSetArchitecture.SetArchitecture(IArchitecture architecture)
{
_mArchitecture = architecture;
}
/// <summary>
/// 系统初始化方法，调用抽象初始化方法
/// 系统初始化方法，调用抽象初始化方法
/// </summary>
void ISystem.Init() => OnInit();
void ISystem.Init()
{
OnInit();
}
/// <summary>
/// 抽象初始化方法，由子类实现具体的初始化逻辑
/// 抽象初始化方法，由子类实现具体的初始化逻辑
/// </summary>
protected abstract void OnInit();
}
}

6
GFramework.Core/system/ICanGetSystem.cs
View File

@ -3,7 +3,7 @@ using GFramework.Core.rule;
namespace GFramework.Core.system;
/// <summary>
/// 定义一个接口，表示可以获取系统的对象。
/// 该接口继承自IBelongToArchitecture接口，用于标识那些属于系统架构并能够获取系统实例的类型。
/// 定义一个接口，表示可以获取系统的对象。
/// 该接口继承自IBelongToArchitecture接口，用于标识那些属于系统架构并能够获取系统实例的类型。
/// </summary>
public interface ICanGetSystem : IBelongToArchitecture;
public interface ICanGetSystem : IBelongToArchitecture;

10
GFramework.Core/system/ISystem.cs
View File

@ -6,15 +6,15 @@ using GFramework.Core.utility;
namespace GFramework.Core.system;
/// <summary>
/// 系统接口，定义了系统的基本行为和功能
/// 该接口继承了多个框架相关的接口，提供了系统初始化能力
/// 系统接口，定义了系统的基本行为和功能
/// 该接口继承了多个框架相关的接口，提供了系统初始化能力
/// </summary>
public interface ISystem : ICanSetArchitecture, ICanGetModel, ICanGetUtility,
ICanRegisterEvent, ICanSendEvent, ICanGetSystem
{
/// <summary>
/// 初始化系统
/// 在系统被创建后调用，用于执行系统的初始化逻辑
/// 初始化系统
/// 在系统被创建后调用，用于执行系统的初始化逻辑
/// </summary>
void Init();
}
}

6
GFramework.Core/system/README.md
View File

@ -11,6 +11,7 @@ System 包定义了业务逻辑层（Business Logic Layer）。System 负责处
标记接口，表示该类型可以获取其他 System。
**继承关系：**
```csharp
public interface ICanGetSystem : IBelongToArchitecture
```
@ -20,11 +21,13 @@ public interface ICanGetSystem : IBelongToArchitecture
System 接口，定义了系统的基本行为。
**核心成员：**
```csharp
void Init(); // 系统初始化方法
```
**继承的能力：**
- `ICanSetArchitecture` - 可设置架构
- `ICanGetModel` - 可获取 Model
- `ICanGetUtility` - 可获取 Utility
@ -39,6 +42,7 @@ void Init(); // 系统初始化方法
抽象 System 基类，提供了 System 的基础实现。
**使用方式：**
```csharp
public abstract class AbstractSystem : ISystem
{
@ -419,11 +423,13 @@ public class GameStateSystem : AbstractSystem
## System vs Model
### Model（数据层）
- **职责**：存储数据和状态
- **特点**：被动，等待修改
- **示例**：PlayerModel、InventoryModel
### System（逻辑层）
- **职责**：处理业务逻辑，协调 Model
- **特点**：主动，响应事件
- **示例**：CombatSystem、QuestSystem

6
GFramework.Core/utility/ICanGetUtility.cs
View File

@ -3,7 +3,7 @@
namespace GFramework.Core.utility;
/// <summary>
/// 定义一个接口，表示可以获取工具类的对象
/// 该接口继承自IBelongToArchitecture，表明实现此接口的类型属于某个架构组件
/// 定义一个接口，表示可以获取工具类的对象
/// 该接口继承自IBelongToArchitecture，表明实现此接口的类型属于某个架构组件
/// </summary>
public interface ICanGetUtility : IBelongToArchitecture;
public interface ICanGetUtility : IBelongToArchitecture;

6
GFramework.Core/utility/IUtility.cs
View File

@ -1,7 +1,7 @@
namespace GFramework.Core.utility;
/// <summary>
/// IUtility接口定义了通用工具类的基本契约
/// 该接口作为所有工具类实现的基础接口，提供统一的工具方法规范
/// IUtility接口定义了通用工具类的基本契约
/// 该接口作为所有工具类实现的基础接口，提供统一的工具方法规范
/// </summary>
public interface IUtility;
public interface IUtility;

7
GFramework.Core/utility/README.md
View File

@ -2,7 +2,8 @@
## 概述
Utility 包定义了工具类层。Utility 提供无状态的辅助功能，如数学计算、文件操作、序列化等通用工具方法。与 System 不同，Utility 不依赖架构状态，是纯粹的工具函数集合。
Utility 包定义了工具类层。Utility 提供无状态的辅助功能，如数学计算、文件操作、序列化等通用工具方法。与 System 不同，Utility
不依赖架构状态，是纯粹的工具函数集合。
## 核心接口
@ -11,6 +12,7 @@ Utility 包定义了工具类层。Utility 提供无状态的辅助功能，如
标记接口，表示该类型可以获取 Utility。
**继承关系：**
```csharp
public interface ICanGetUtility : IBelongToArchitecture
```
@ -20,6 +22,7 @@ public interface ICanGetUtility : IBelongToArchitecture
Utility 标记接口，所有工具类都应实现此接口。
**接口定义：**
```csharp
public interface IUtility
{
@ -419,12 +422,14 @@ public class LogUtility : IUtility
## Utility vs System
### Utility（工具层）
- **无状态** - 不存储业务数据
- **纯函数** - 相同输入产生相同输出
- **独立性** - 不依赖架构状态
- **可复用** - 可在多个项目中使用
### System（逻辑层）
- **有状态** - 可能存储临时状态
- **业务逻辑** - 处理特定业务流程
- **架构依赖** - 需要访问 Model

9
GFramework.Generator.Attributes/generator/enums/EnumExtensionsAttribute.cs
View File

@ -1,21 +1,20 @@

using System;
using System;
namespace GFramework.Generator.Attributes
{
/// <summary>
/// 标注在 enum 上，Source Generator 会为该 enum 生成扩展方法。
/// 标注在 enum 上，Source Generator 会为该 enum 生成扩展方法。
/// </summary>
[AttributeUsage(AttributeTargets.Enum)]
public sealed class GenerateEnumExtensionsAttribute : Attribute
{
/// <summary>
/// 是否为每个枚举项生成单独的 IsXXX 方法（默认 true）。
/// 是否为每个枚举项生成单独的 IsXXX 方法（默认 true）。
/// </summary>
public bool GenerateIsMethods { get; set; } = true;
/// <summary>
/// 是否生成一个 IsIn(params T[]) 方法以简化多值判断（默认 true）。
/// 是否生成一个 IsIn(params T[]) 方法以简化多值判断（默认 true）。
/// </summary>
public bool GenerateIsInMethod { get; set; } = true;
}

8
GFramework.Generator/GFramework.Generator.csproj
View File

@ -20,7 +20,7 @@
<ItemGroup>
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" PrivateAssets="all"/>
<PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" PrivateAssets="all"/>
<PackageReference Include="System.Collections.Immutable" Version="9.0.0" />
<PackageReference Include="System.Collections.Immutable" Version="9.0.0"/>
</ItemGroup>
<ItemGroup>
@ -33,12 +33,12 @@
<ItemGroup>
<None Include="$(OutputPath)\$(AssemblyName).dll" Pack="true"
PackagePath="analyzers/dotnet/cs" Visible="false"/>
<None Include="$(OutputPath)$(AssemblyName).dll" Pack="true" PackagePath="lib/netstandard2.0" />
<None Include="$(OutputPath)$(AssemblyName).dll" Pack="true" PackagePath="lib/netstandard2.0"/>
<None Include="$(OutputPath)\GFramework.Generator.Attributes.dll" Pack="true"
PackagePath="analyzers/dotnet/cs" Visible="false"/>
<None Update="README.md">
<Pack>true</Pack>
<PackagePath></PackagePath>
<Pack>true</Pack>
<PackagePath></PackagePath>
</None>
</ItemGroup>

1
GFramework.Generator/README.md
View File

@ -1,3 +1,4 @@
项目额外的简单代码生成器
目前已有的功能
- 为枚举添加两个扩展方法方便判断枚举值

193
GFramework.Generator/generator/enums/EnumExtensionsGenerator.cs
View File

@ -5,121 +5,118 @@ using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp.Syntax;
using Microsoft.CodeAnalysis.Text;
namespace GFramework.Generator.generator.enums
namespace GFramework.Generator.generator.enums;
[Generator]
public class EnumExtensionsGenerator : IIncrementalGenerator
{
[Generator]
public class EnumExtensionsGenerator : IIncrementalGenerator
private const string AttributeFullName = "GFramework.Generator.Attributes.GenerateEnumExtensionsAttribute";
public void Initialize(IncrementalGeneratorInitializationContext context)
{
private const string AttributeFullName = "GFramework.Generator.Attributes.GenerateEnumExtensionsAttribute";
// 1. 找到所有 EnumDeclarationSyntax 节点
var enumDecls = context.SyntaxProvider
.CreateSyntaxProvider(
(s, _) => s is EnumDeclarationSyntax,
(ctx, _) =>
(EnumDecl: (EnumDeclarationSyntax)ctx.Node, ctx.SemanticModel))
.Where(t => t.EnumDecl != null);
public void Initialize(IncrementalGeneratorInitializationContext context)
{
// 1. 找到所有 EnumDeclarationSyntax 节点
var enumDecls = context.SyntaxProvider
.CreateSyntaxProvider(
predicate: (s, _) => s is EnumDeclarationSyntax,
transform: (ctx, _) =>
(EnumDecl: (EnumDeclarationSyntax)ctx.Node, ctx.SemanticModel))
.Where(t => t.EnumDecl != null);
// 2. 解析为 symbol 并过滤带 Attribute 的 enum
var enumSymbols = enumDecls
.Select((t, _) =>
{
var model = t.SemanticModel;
var enumDecl = t.EnumDecl;
var symbol = model.GetDeclaredSymbol(enumDecl) as INamedTypeSymbol;
return symbol;
})
.Where(symbol => symbol != null)
.Select((symbol, _) =>
{
// 判断是否包含我们的 Attribute
var hasAttr = symbol.GetAttributes().Any(ad =>
ad.AttributeClass?.ToDisplayString() == AttributeFullName ||
ad.AttributeClass?.ToDisplayString().EndsWith(".GenerateEnumExtensionsAttribute") == true);
return (Symbol: symbol, HasAttr: hasAttr);
})
.Where(x => x.HasAttr)
.Collect();
// 3. 为每个 enum 生成代码
context.RegisterSourceOutput(enumSymbols, (spc, list) =>
// 2. 解析为 symbol 并过滤带 Attribute 的 enum
var enumSymbols = enumDecls
.Select((t, _) =>
{
foreach (var enumSymbol in list.Select(item => item.Symbol))
var model = t.SemanticModel;
var enumDecl = t.EnumDecl;
var symbol = model.GetDeclaredSymbol(enumDecl) as INamedTypeSymbol;
return symbol;
})
.Where(symbol => symbol != null)
.Select((symbol, _) =>
{
// 判断是否包含我们的 Attribute
var hasAttr = symbol.GetAttributes().Any(ad =>
ad.AttributeClass?.ToDisplayString() == AttributeFullName ||
ad.AttributeClass?.ToDisplayString().EndsWith(".GenerateEnumExtensionsAttribute") == true);
return (Symbol: symbol, HasAttr: hasAttr);
})
.Where(x => x.HasAttr)
.Collect();
// 3. 为每个 enum 生成代码
context.RegisterSourceOutput(enumSymbols, (spc, list) =>
{
foreach (var enumSymbol in list.Select(item => item.Symbol))
try
{
try
{
var src = GenerateForEnum(enumSymbol);
var hintName = $"{enumSymbol.Name}.EnumExtensions.g.cs";
spc.AddSource(hintName, SourceText.From(src, Encoding.UTF8));
}
catch (Exception ex)
{
// 发生异常时生成一个注释文件（避免完全静默失败）
var err = $"// EnumExtensionsGenerator failed for {enumSymbol?.Name}: {ex.Message}";
spc.AddSource($"{enumSymbol?.Name}.EnumExtensions.Error.g.cs",
SourceText.From(err, Encoding.UTF8));
}
var src = GenerateForEnum(enumSymbol);
var hintName = $"{enumSymbol.Name}.EnumExtensions.g.cs";
spc.AddSource(hintName, SourceText.From(src, Encoding.UTF8));
}
});
catch (Exception ex)
{
// 发生异常时生成一个注释文件（避免完全静默失败）
var err = $"// EnumExtensionsGenerator failed for {enumSymbol?.Name}: {ex.Message}";
spc.AddSource($"{enumSymbol?.Name}.EnumExtensions.Error.g.cs",
SourceText.From(err, Encoding.UTF8));
}
});
}
private static string GenerateForEnum(INamedTypeSymbol enumSymbol)
{
var ns = enumSymbol.ContainingNamespace.IsGlobalNamespace
? null
: enumSymbol.ContainingNamespace.ToDisplayString();
var enumName = enumSymbol.Name;
var fullEnumName = enumSymbol.ToDisplayString(); // 包含命名空间
var members = enumSymbol.GetMembers().OfType<IFieldSymbol>().Where(f => f.ConstantValue != null).ToArray();
var sb = new StringBuilder();
sb.AppendLine("// <auto-generated />");
sb.AppendLine("using System;");
if (!string.IsNullOrEmpty(ns))
{
sb.AppendLine($"namespace {ns}");
sb.AppendLine("{");
}
else
{
sb.AppendLine("namespace EnumExtensionsGenerated");
sb.AppendLine("{");
}
private static string GenerateForEnum(INamedTypeSymbol enumSymbol)
{
var ns = enumSymbol.ContainingNamespace.IsGlobalNamespace
? null
: enumSymbol.ContainingNamespace.ToDisplayString();
var enumName = enumSymbol.Name;
var fullEnumName = enumSymbol.ToDisplayString(); // 包含命名空间
var members = enumSymbol.GetMembers().OfType<IFieldSymbol>().Where(f => f.ConstantValue != null).ToArray();
sb.AppendLine($" public static partial class {enumName}Extensions");
sb.AppendLine(" {");
var sb = new StringBuilder();
sb.AppendLine("// <auto-generated />");
sb.AppendLine("using System;");
if (!string.IsNullOrEmpty(ns))
{
sb.AppendLine($"namespace {ns}");
sb.AppendLine("{");
}
else
{
sb.AppendLine("namespace EnumExtensionsGenerated");
sb.AppendLine("{");
}
sb.AppendLine($" public static partial class {enumName}Extensions");
sb.AppendLine(" {");
// 1. 单项 IsX 方法
// 1. 单项 IsX 方法
// 替换原第93行开始的 foreach 块
var memberChecks = members.Select(m =>
{
var memberName = m.Name;
var safeMethodName = $"Is{memberName}";
return $@" /// <summary>Auto-generated: 是否为 {memberName}</summary>
var memberChecks = members.Select(m =>
{
var memberName = m.Name;
var safeMethodName = $"Is{memberName}";
return $@" /// <summary>Auto-generated: 是否为 {memberName}</summary>
public static bool {safeMethodName}(this {fullEnumName} value) => value == {fullEnumName}.{memberName};
";
}).ToArray();
}).ToArray();
sb.Append(string.Join("", memberChecks));
sb.Append(string.Join("", memberChecks));
// 2. IsIn(params ...) 方法
sb.AppendLine($" /// <summary>Auto-generated: 判断是否属于指定集合</summary>");
sb.AppendLine(
$" public static bool IsIn(this {fullEnumName} value, params {fullEnumName}[] values)");
sb.AppendLine(" {");
sb.AppendLine(" if (values == null) return false;");
sb.AppendLine(" foreach (var v in values) if (value == v) return true;");
sb.AppendLine(" return false;");
sb.AppendLine(" }");
// 2. IsIn(params ...) 方法
sb.AppendLine(" /// <summary>Auto-generated: 判断是否属于指定集合</summary>");
sb.AppendLine(
$" public static bool IsIn(this {fullEnumName} value, params {fullEnumName}[] values)");
sb.AppendLine(" {");
sb.AppendLine(" if (values == null) return false;");
sb.AppendLine(" foreach (var v in values) if (value == v) return true;");
sb.AppendLine(" return false;");
sb.AppendLine(" }");
sb.AppendLine(" }");
sb.AppendLine("}"); // namespace
sb.AppendLine(" }");
sb.AppendLine("}"); // namespace
return sb.ToString();
}
return sb.ToString();
}
}

38
GFramework.csproj
View File

@ -25,37 +25,37 @@
<!-- 排除不需要参与打包/编译的目录 -->
<ItemGroup>
<None Include="README.md" Pack="true" PackagePath="" />
<None Remove="GFramework.Generator\**" />
<None Remove="GFramework.Generator.Attributes\**" />
<None Remove="GFramework.Core\**" />
<None Include="README.md" Pack="true" PackagePath=""/>
<None Remove="GFramework.Generator\**"/>
<None Remove="GFramework.Generator.Attributes\**"/>
<None Remove="GFramework.Core\**"/>
<Compile Remove="GFramework.Generator\**" />
<Compile Remove="GFramework.Generator.Attributes\**" />
<Compile Remove="GFramework.Core\**" />
<Compile Remove="GFramework.Generator\**"/>
<Compile Remove="GFramework.Generator.Attributes\**"/>
<Compile Remove="GFramework.Core\**"/>
<EmbeddedResource Remove="GFramework.Generator\**" />
<EmbeddedResource Remove="GFramework.Generator.Attributes\**" />
<EmbeddedResource Remove="GFramework.Core\**" />
<Compile Remove="GFramework.Godot\**" />
<EmbeddedResource Remove="GFramework.Godot\**" />
<None Remove="GFramework.Godot\**" />
<EmbeddedResource Remove="GFramework.Generator\**"/>
<EmbeddedResource Remove="GFramework.Generator.Attributes\**"/>
<EmbeddedResource Remove="GFramework.Core\**"/>
<Compile Remove="GFramework.Godot\**"/>
<EmbeddedResource Remove="GFramework.Godot\**"/>
<None Remove="GFramework.Godot\**"/>
<Compile Update="GFramework.Core.Godot\godot\extensions\NodeExtensions.cs">
<Link>GFramework.Godot\godot\extensions\NodeExtensions.cs</Link>
<Link>GFramework.Godot\godot\extensions\NodeExtensions.cs</Link>
</Compile>
<Compile Update="GFramework.Core.Godot\godot\extensions\UnRegisterExtension.cs">
<Link>GFramework.Godot\godot\extensions\UnRegisterExtension.cs</Link>
<Link>GFramework.Godot\godot\extensions\UnRegisterExtension.cs</Link>
</Compile>
<Compile Remove="GFramework.Core.Godot\**" />
<EmbeddedResource Remove="GFramework.Core.Godot\**" />
<None Remove="GFramework.Core.Godot\**" />
<Compile Remove="GFramework.Core.Godot\**"/>
<EmbeddedResource Remove="GFramework.Core.Godot\**"/>
<None Remove="GFramework.Core.Godot\**"/>
</ItemGroup>
<!-- 作为 Analyzer 引入本地 SourceGenerator -->
<ItemGroup>
<ProjectReference Include="GFramework.Generator\GFramework.Generator.csproj"
OutputItemType="Analyzer"
ReferenceOutputAssembly="false" />
ReferenceOutputAssembly="false"/>
<ProjectReference Include="GFramework.Generator.Attributes\GFramework.Generator.Attributes.csproj"/>
<ProjectReference Include="GFramework.Core\GFramework.Core.csproj"/>
</ItemGroup>

2
README.md
View File

@ -1,7 +1,9 @@
# 项目介绍
本项目参考(CV)自[QFramework](https://github.com/liangxiegame/QFramework)
# 为什么要有这个项目
- 原来的项目是单文件框架，我把框架拆成多个文件，方便管理
- 纯粹个人自用，要使用还是请访问[QFramework](https://github.com/liangxiegame/QFramework)
- 至于修改名字，是因为我为了方便会发布GuGet包，假设将来QFramework也要发布GuGet包，那么就会冲突了