GFramework/GFramework.Core.Abstractions/controller/README.md

Controller 包使用说明

概述

Controller 包定义了控制器（Controller）的接口规范。控制器是 MVC 架构中的 C 层，负责处理用户交互、协调视图和模型，是连接表现层和业务层的桥梁。

注意：本框架使用依赖注入模式，Controller 通过构造函数或属性注入获取架构实例，而非使用全局单例。

核心接口

IController

控制器接口，定义了控制器需要实现的所有功能契约。

继承的能力接口：

• ICanSendCommand - 可发送命令
• ICanGetSystem - 可获取系统
• ICanGetModel - 可获取模型
• ICanRegisterEvent - 可注册事件
• ICanSendQuery - 可发送查询
• ICanGetUtility - 可获取工具

能力说明：

控制器拥有框架中最全面的能力集合，可以：

1. 发送命令执行业务逻辑
2. 获取系统调用服务
3. 获取模型读写数据
4. 注册事件监听变化
5. 发送查询获取信息
6. 获取工具使用辅助功能

使用示例

基础控制器实现（依赖注入模式）

using GFramework.Core.architecture;

// 通过依赖注入获取架构
public class PlayerController : IController
{
    private readonly IArchitecture _architecture;
    private readonly IUnRegisterList _unregisterList = new UnRegisterList();
    
    // 通过构造函数注入架构
    public PlayerController(IArchitecture architecture)
    {
        _architecture = architecture;
    }
    
    public void Initialize()
    {
        // 获取模型
        var playerModel = _architecture.GetModel<PlayerModel>();
        
        // 监听模型变化
        playerModel.Health.RegisterWithInitValue(OnHealthChanged)
            .AddToUnregisterList(_unregisterList);
        
        // 注册事件
        _architecture.RegisterEvent<PlayerLevelUpEvent>(OnPlayerLevelUp)
            .AddToUnregisterList(_unregisterList);
    }
    
    // 处理用户输入
    public void ProcessInput(double delta)
    {
        if (Input.IsActionJustPressed("attack"))
        {
            // 发送命令
            _architecture.SendCommand(new AttackCommand());
        }
        
        if (Input.IsActionJustPressed("use_item"))
        {
            // 发送查询
            var inventory = _architecture.SendQuery(new GetInventoryQuery());
            if (inventory.HasItem("potion"))
            {
                _architecture.SendCommand(new UseItemCommand("potion"));
            }
        }
    }
    
    private void OnHealthChanged(int newHealth)
    {
        // 更新 UI 显示
        UpdateHealthBar(newHealth);
    }
    
    private void OnPlayerLevelUp(PlayerLevelUpEvent e)
    {
        // 显示升级特效
        ShowLevelUpEffect();
    }
    
    public void Cleanup()
    {
        // 清理事件注册
        _unregisterList.UnRegisterAll();
    }
    
    private void UpdateHealthBar(int health) { /* UI 更新逻辑 */ }
    private void ShowLevelUpEffect() { /* 特效逻辑 */ }
}

UI 控制器示例

// UI 面板控制器
public class MainMenuController : IController
{
    [Inject] private IArchitecture _architecture;
    [Inject] private IUISystem _uiSystem;
    
    [Export] private Button _startButton;
    [Export] private Button _settingsButton;
    [Export] private Button _quitButton;
    
    public void Initialize()
    {
        // 绑定按钮事件
        _startButton.Pressed += OnStartButtonPressed;
        _settingsButton.Pressed += OnSettingsButtonPressed;
        _quitButton.Pressed += OnQuitButtonPressed;
        
        // 获取模型更新 UI
        var gameModel = _architecture.GetModel<GameModel>();
        UpdateUI(gameModel);
    }
    
    private void OnStartButtonPressed()
    {
        // 通过命令启动游戏
        _architecture.SendCommand<StartGameCommand>();
    }
    
    private void OnSettingsButtonPressed()
    {
        // 查询当前设置
        var settings = _architecture.SendQuery(new GetSettingsQuery());
        
        // 打开设置面板
        _uiSystem.OpenSettingsPanel(settings);
    }
    
    private void OnQuitButtonPressed()
    {
        // 发送退出命令
        _architecture.SendCommand<QuitGameCommand>();
    }
    
    private void UpdateUI(GameModel model) { /* UI 更新逻辑 */ }
}

复杂交互控制器

// 战斗控制器
public class CombatController : IController
{
    [Inject] protected IArchitecture _architecture;
    
    private IUnRegisterList _unregisterList = new UnRegisterList();
    private PlayerModel _playerModel;
    private CombatSystem _combatSystem;
    
    [PostConstruct]
    public void Init()
    {
        // 缓存常用引用
        _playerModel = _architecture.GetModel<PlayerModel>();
        _combatSystem = _architecture.GetSystem<CombatSystem>();
        
        // 注册多个事件
        _architecture.RegisterEvent<EnemySpawnedEvent>(OnEnemySpawned)
            .AddToUnregisterList(_unregisterList);
            
        _architecture.RegisterEvent<CombatEndedEvent>(OnCombatEnded)
            .AddToUnregisterList(_unregisterList);
        
        // 监听模型状态
        _playerModel.CombatState.Register(OnCombatStateChanged)
            .AddToUnregisterList(_unregisterList);
    }
    
    private void OnEnemySpawned(EnemySpawnedEvent e)
    {
        // 进入战斗状态
        _architecture.SendCommand(new EnterCombatCommand(e.Enemy));
    }
    
    private void OnCombatEnded(CombatEndedEvent e)
    {
        if (e.Victory)
        {
            // 查询奖励
            var rewards = _architecture.SendQuery(new CalculateRewardsQuery(e.Enemy));
            
            // 发放奖励
            _architecture.SendCommand(new GiveRewardsCommand(rewards));
        }
        else
        {
            // 处理失败
            _architecture.SendCommand<GameOverCommand>();
        }
    }
    
    private void OnCombatStateChanged(CombatState state)
    {
        // 根据战斗状态更新 UI
        _architecture.GetSystem<UISystem>().UpdateCombatUI(state);
    }
    
    public void Cleanup()
    {
        _unregisterList.UnRegisterAll();
    }
}

控制器职责

✅ 应该做的事

1. 处理用户输入

   • 键盘、鼠标、触摸输入
   • UI 按钮点击
   • 手势识别

2. 协调视图和模型

   • 监听模型变化更新视图
   • 将用户操作转换为命令

3. 管理界面逻辑

   • UI 元素的显示/隐藏
   • 动画播放控制
   • 视觉反馈

4. 事件监听

   • 注册关心的事件
   • 响应事件更新界面

❌ 不应该做的事

1. 不包含业务逻辑

   • 业务逻辑应该在 System 中
   • 控制器只负责调用和协调

2. 不直接修改模型

   • 应该通过 Command 修改模型
   • 避免直接访问 Model 的 setter

3. 不处理复杂计算

   • 复杂计算应该在 Query 或 System 中
   • 控制器保持简洁

4. 不保存核心状态

   • 核心状态应该在 Model 中
   • 控制器可以保存临时 UI 状态

生命周期管理

事件注销

public class MyController : IController
{
    [Inject] private IArchitecture _architecture;
    
    // 使用 UnRegisterList 统一管理
    private IUnRegisterList _unregisterList = new UnRegisterList();
    
    public void Initialize()
    {
        // 所有事件注册都添加到列表
        _architecture.RegisterEvent<GameEvent>(OnGameEvent)
            .AddToUnregisterList(_unregisterList);
            
        _architecture.GetModel<PlayerModel>().Health.Register(OnHealthChanged)
            .AddToUnregisterList(_unregisterList);
    }
    
    public void Cleanup()
    {
        // 统一注销所有事件
        _unregisterList.UnRegisterAll();
    }
}

最佳实践

1. 使用依赖注入获取依赖

   • 通过构造函数注入 IArchitecture
   • 使用 [Inject] 属性标记注入字段

2. 保持控制器轻量

   • 复杂逻辑放在 Command、Query、System 中
   • 控制器只做协调和转发

3. 合理使用缓存

   • 频繁使用的 Model、System 可以缓存引用
   • 平衡性能和内存占用

4. 统一管理事件注销

   • 使用 IUnRegisterList 统一管理
   • 在 Cleanup() 中统一注销

5. 命名规范

   • 控制器类名：XxxController
   • 使用 [Inject] 或构造函数注入获取架构

常见模式

数据绑定模式

public class ScoreController : IController
{
    [Inject] private IArchitecture _architecture;
    
    public void Initialize()
    {
        // 绑定模型数据到 UI
        _architecture.GetModel<GameModel>()
            .Score
            .RegisterWithInitValue(score => UpdateDisplay(score))
            .AddToUnregisterList(_unregisterList);
    }
    
    private void UpdateDisplay(int score)
    {
        // 更新分数显示
    }
}

状态机模式

public class PlayerStateController : IController
{
    [Inject] private IArchitecture _architecture;
    private Dictionary<PlayerState, Action> _stateHandlers;
    
    public void Initialize()
    {
        _stateHandlers = new Dictionary<PlayerState, Action>
        {
            { PlayerState.Idle, HandleIdleState },
            { PlayerState.Moving, HandleMovingState },
            { PlayerState.Attacking, HandleAttackingState }
        };
        
        _architecture.GetModel<PlayerModel>()
            .State
            .Register(OnStateChanged)
            .AddToUnregisterList(_unregisterList);
    }
    
    private void OnStateChanged(PlayerState state)
    {
        _stateHandlers[state]?.Invoke();
    }
}

与 Godot 集成

在 Godot 项目中，可以使用 GFramework.Godot 提供的扩展：

using GFramework.Godot;

public partial class GodotPlayerController : Node, IController
{
    [Inject] private IArchitecture _architecture;
    
    public override void _Ready()
    {
        // 使用 Godot 特定的自动注销扩展
        _architecture.RegisterEvent<PlayerDiedEvent>(OnPlayerDied)
            .UnRegisterWhenNodeExitTree(this);
            
        _architecture.GetModel<PlayerModel>()
            .Health
            .RegisterWithInitValue(OnHealthChanged)
            .UnRegisterWhenNodeExitTree(this);
    }
}

相关包

• architecture - 提供架构访问能力
• command - 控制器发送命令执行业务逻辑
• query - 控制器发送查询获取数据
• events - 控制器注册事件监听变化
• model - 控制器读取模型数据
• system - 控制器调用系统服务
• extensions - 提供便捷的扩展方法
• GFramework.Godot - Godot 特定的控制器扩展

---

许可证: Apache 2.0