GFramework/docs/zh-CN/getting-started/architecture-overview.md

架构概览

GFramework 采用经典的五层架构模式，结合 CQRS 和事件驱动设计，为游戏开发提供清晰、可维护的架构基础。

核心架构模式

五层架构

┌─────────────────────────────────────────┐
│             View / UI                    │  ← 用户界面层
├─────────────────────────────────────────┤
│            Controller                    │  ← 控制层
├─────────────────────────────────────────┤
│             System                       │  ← 业务逻辑层
├─────────────────────────────────────────┤
│              Model                       │  ← 数据层
├─────────────────────────────────────────┤
│             Utility                      │  ← 工具层
└─────────────────────────────────────────┘

跨层操作机制

Command ──┐
Query   ──┼──→  跨层操作（修改/查询数据）
Event   ──┘

生命周期阶段

初始化：Init → BeforeUtilityInit → AfterUtilityInit → BeforeModelInit → AfterModelInit → BeforeSystemInit → AfterSystemInit → Ready
销毁：Destroy → Destroying → Destroyed

核心组件详解

1. Architecture（架构）

应用的中央调度器，负责管理所有组件的生命周期。

public class GameArchitecture : Architecture
{
    protected override void Init()
    {
        // 注册所有组件
        RegisterModel(new PlayerModel());
        RegisterSystem(new CombatSystem());
        RegisterUtility(new StorageUtility());
    }
}

主要职责：

• 组件注册和管理
• 生命周期协调
• 依赖注入
• 跨组件通信协调

2. Model（数据模型）

应用的状态存储层，只负责数据的存储和管理。

public class PlayerModel : AbstractModel
{
    public BindableProperty<int> Health { get; } = new(100);
    public BindableProperty<string> Name { get; } = new("Player");
    
    protected override void OnInit()
    {
        // 监听自身数据变化
        Health.Register(OnHealthChanged);
    }
    
    private void OnHealthChanged(int newHealth)
    {
        if (newHealth <= 0)
            this.SendEvent(new PlayerDiedEvent());
    }
}

设计原则：

• 只存储数据，不包含业务逻辑
• 使用 BindableProperty 实现响应式数据
• 通过事件通知数据变化

3. System（业务系统）

应用的业务逻辑处理层。

public class CombatSystem : AbstractSystem
{
    protected override void OnInit()
    {
        // 监听战斗相关事件
        this.RegisterEvent<EnemyAttackEvent>(OnEnemyAttack);
        this.RegisterEvent<PlayerAttackEvent>(OnPlayerAttack);
    }
    
    private void OnEnemyAttack(EnemyAttackEvent e)
    {
        var playerModel = this.GetModel<PlayerModel>();
        playerModel.Health.Value -= e.Damage;
        this.SendEvent(new PlayerTookDamageEvent { Damage = e.Damage });
    }
}

职责范围：

• 处理具体的业务逻辑
• 响应事件并修改模型数据
• 发送新的事件通知其他组件

4. Controller（控制器）

连接 UI 和业务逻辑的桥梁。

public class PlayerController : IController
{
    private IArchitecture _architecture;
    private PlayerModel _playerModel;
    
    public PlayerController(IArchitecture architecture)
    {
        _architecture = architecture;
        _playerModel = architecture.GetModel<PlayerModel>();
        
        // 监听模型变化并更新 UI
        _playerModel.Health.RegisterWithInitValue(UpdateHealthDisplay);
    }
    
    public void OnPlayerInput(Vector2 direction)
    {
        // 将用户输入转换为命令
        _architecture.SendCommand(new MovePlayerCommand { Direction = direction });
    }
    
    private void UpdateHealthDisplay(int health)
    {
        // 更新 UI 显示
        Console.WriteLine($"Player Health: {health}");
    }
}

核心功能：

• 接收用户输入
• 发送命令到系统
• 监听模型变化更新 UI
• 协调 UI 和业务逻辑

5. Utility（工具类）

提供无状态的辅助功能。

public class StorageUtility : IUtility
{
    public void SaveData<T>(string key, T data)
    {
        // 实现数据保存逻辑
    }
    
    public T LoadData<T>(string key, T defaultValue = default)
    {
        // 实现数据加载逻辑
        return defaultValue;
    }
}

使用场景：

• 数据存储和读取
• 数学计算工具
• 字符串处理
• 网络通信辅助

通信机制

1. Command（命令）

用于修改应用状态的操作：

public class MovePlayerCommand : AbstractCommand
{
    public Vector2 Direction { get; set; }
    
    protected override void OnDo()
    {
        // 执行移动逻辑
        this.SendEvent(new PlayerMovedEvent { Position = CalculateNewPosition() });
    }
}

2. Query（查询）

用于查询应用状态：

public class GetPlayerHealthQuery : AbstractQuery<int>
{
    protected override int OnDo()
    {
        var playerModel = this.GetModel<PlayerModel>();
        return playerModel.Health.Value;
    }
}

3. Event（事件）

组件间通信的主要机制：

// 发送事件
this.SendEvent(new PlayerDiedEvent());

// 监听事件
this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);

响应式编程

BindableProperty

public class PlayerModel : AbstractModel
{
    public BindableProperty<int> Health { get; } = new(100);
    public BindableProperty<string> Name { get; } = new("Player");
}

// 使用方式
playerModel.Health.Value = 50; // 自动触发所有监听器
playerModel.Health.Register(newValue => {
    Console.WriteLine($"Health changed to: {newValue}");
});

数据绑定优势

• 自动更新：数据变化自动通知监听者
• 内存安全：自动管理监听器生命周期
• 类型安全：编译时类型检查
• 性能优化：只在值真正改变时触发

最佳实践

1. 分层职责明确

// ✅ 正确：Model 只存储数据
public class PlayerModel : AbstractModel
{
    public BindableProperty<int> Health { get; } = new(100);
}

// ❌ 错误：Model 包含业务逻辑
public class PlayerModel : AbstractModel
{
    public void TakeDamage(int damage) // 业务逻辑应该在 System 中
    {
        Health.Value -= damage;
    }
}

2. 事件驱动设计

// ✅ 正确：使用事件解耦
public class CombatSystem : AbstractSystem
{
    private void OnPlayerAttack(PlayerAttackEvent e)
    {
        // 处理攻击逻辑
        this.SendEvent(new EnemyDamagedEvent { Damage = CalculateDamage() });
    }
}

// ❌ 错误：直接调用其他组件
public class CombatSystem : AbstractSystem
{
    private void OnPlayerAttack(PlayerAttackEvent e)
    {
        var enemySystem = this.GetSystem<EnemySystem>(); // 紧耦合
        enemySystem.TakeDamage(CalculateDamage());
    }
}

3. 命令查询分离

// ✅ 正确：明确区分命令和查询
public class MovePlayerCommand : AbstractCommand { }  // 修改状态
public class GetPlayerPositionQuery : AbstractQuery<Vector2> { }  // 查询状态

// ❌ 错误：混合读写操作
public class PlayerManager 
{
    public void MoveAndGetPosition(Vector2 direction, out Vector2 position) // 职责不清
    {
        // ...
    }
}

架构优势

1. 可维护性

• 清晰的职责分离
• 松耦合的组件设计
• 易于定位和修复问题

2. 可测试性

• 组件可独立测试
• 依赖可轻松模拟
• 支持单元测试和集成测试

3. 可扩展性

• 新功能通过添加组件实现
• 现有组件无需修改
• 支持插件化架构

4. 团队协作

• 统一的架构规范
• 易于新人上手
• 减少代码冲突

下一步学习

• 深入了解 Architecture 组件
• 掌握事件系统
• 学习命令查询模式
• 探索属性系统