【免费下载】 QFramework框架核心API详解与架构设计指南

2026-02-04 05:17:43作者：劳婵绚Shirley

前言

QFramework是一个轻量级、模块化的Unity游戏开发框架，它采用分层架构设计，提供了一套完整的游戏开发解决方案。本文将深入解析QFramework的核心API及其设计理念，帮助开发者更好地理解和使用这个框架。

一、架构核心（Architecture）

1.1 架构接口与实现

QFramework的核心是IArchitecture接口，它定义了框架的基础功能：

public interface IArchitecture {
    // 注册系统、模型和工具类
    void RegisterSystem<T>(T system) where T : ISystem;
    void RegisterModel<T>(T model) where T : IModel;
    void RegisterUtility<T>(T utility) where T : IUtility;
    
    // 获取系统、模型和工具类
    T GetSystem<T>() where T : class, ISystem;
    T GetModel<T>() where T : class, IModel;
    T GetUtility<T>() where T : class, IUtility;
    
    // 命令、查询和事件相关操作
    void SendCommand<T>(T command) where T : ICommand;
    TResult SendCommand<TResult>(ICommand<TResult> command);
    TResult SendQuery<TResult>(IQuery<TResult> query);
    void SendEvent<T>() where T : new();
    void SendEvent<T>(T e);
    
    // 事件监听管理
    IUnRegister RegisterEvent<T>(Action<T> onEvent);
    void UnRegisterEvent<T>(Action<T> onEvent);
    
    // 反初始化
    void Deinit();
}

Architecture<T>是IArchitecture的抽象实现，开发者需要继承这个类并实现Init方法来创建自己的架构：

public abstract class Architecture<T> : IArchitecture where T : Architecture<T>, new() {
    protected abstract void Init();
    
    // 提供单例访问点
    public static IArchitecture Interface {
        get {
            if (mArchitecture == null) {
                mArchitecture = new T();
                mArchitecture.Init();
            }
            return mArchitecture;
        }
    }
}

1.2 架构设计理念

QFramework采用分层架构设计，将游戏逻辑分为：

Model层：负责数据管理和业务逻辑
System层：负责系统级别的功能实现
Utility层：提供工具方法和辅助功能
Command层：处理具体的业务命令
Query层：负责数据查询

这种分层设计使得代码结构清晰，职责分明，便于维护和扩展。

二、核心组件详解

2.1 控制器（Controller）

IController接口是视图层与架构之间的桥梁，它集成了多种能力：

public interface IController : 
    IBelongToArchitecture,
    ICanSendCommand,
    ICanGetSystem,
    ICanGetModel,
    ICanRegisterEvent,
    ICanSendQuery,
    ICanGetUtility {
}

控制器通常与UI组件绑定，负责处理用户输入和界面交互。

2.2 系统（System）

系统是框架中的功能模块，ISystem接口定义如下：

public interface ISystem : 
    IBelongToArchitecture,
    ICanSetArchitecture,
    ICanGetModel,
    ICanGetUtility,
    ICanRegisterEvent,
    ICanSendEvent,
    ICanGetSystem,
    ICanInit {
}

开发者可以通过继承AbstractSystem来创建自定义系统：

public class AudioSystem : AbstractSystem {
    protected override void OnInit() {
        // 初始化音频系统
    }
    
    public void PlaySound(string soundName) {
        // 播放音效的实现
    }
}

2.3 模型（Model）

模型负责数据管理，IModel接口定义如下：

public interface IModel : 
    IBelongToArchitecture,
    ICanSetArchitecture,
    ICanGetUtility,
    ICanSendEvent,
    ICanInit {
}

继承AbstractModel创建自定义模型：

public class PlayerModel : AbstractModel {
    private int mScore;
    
    public int Score {
        get => mScore;
        set {
            if (mScore != value) {
                mScore = value;
                this.SendEvent(new ScoreChangedEvent(mScore));
            }
        }
    }
    
    protected override void OnInit() {
        // 初始化模型数据
    }
}

2.4 命令（Command）

命令模式用于封装业务逻辑，分为无返回值命令和有返回值命令：

// 无返回值命令
public class JumpCommand : AbstractCommand {
    protected override void OnExecute() {
        // 执行跳跃逻辑
    }
}

// 有返回值命令
public class CalculateDamageCommand : AbstractCommand<int> {
    protected override int OnExecute() {
        // 计算伤害并返回
        return 100;
    }
}

2.5 查询（Query）

查询模式用于获取数据：

public class GetPlayerLevelQuery : AbstractQuery<int> {
    protected override int OnDo() {
        // 查询并返回玩家等级
        return 10;
    }
}

三、事件系统

3.1 类型事件系统（TypeEventSystem）

QFramework提供了强大的事件系统：

// 注册事件监听
TypeEventSystem.Global.Register<PlayerDeadEvent>(OnPlayerDead);

// 发送事件
TypeEventSystem.Global.Send(new PlayerDeadEvent());

// 取消注册
TypeEventSystem.Global.UnRegister<PlayerDeadEvent>(OnPlayerDead);

3.2 可绑定属性（BindableProperty）

实现数据绑定和自动更新：

public class PlayerViewModel {
    public readonly BindableProperty<int> Hp = new BindableProperty<int>(100);
    
    public void TakeDamage(int damage) {
        Hp.Value -= damage;
    }
}

// 在UI中绑定
viewModel.Hp.RegisterWithInitValue(hp => {
    hpText.text = $"HP: {hp}";
});

四、依赖注入（IOC）

QFramework提供了简单的IOC容器：

// 注册服务
IOCContainer.Register<IAudioService>(new AudioService());

// 获取服务
var audioService = IOCContainer.Get<IAudioService>();

五、最佳实践

5.1 架构初始化

public class GameArchitecture : Architecture<GameArchitecture> {
    protected override void Init() {
        // 注册模型
        RegisterModel(new PlayerModel());
        
        // 注册系统
        RegisterSystem(new AudioSystem());
        
        // 注册工具类
        RegisterUtility(new JsonUtility());
    }
}

5.2 控制器使用示例

public class PlayerController : MonoBehaviour, IController {
    public IArchitecture GetArchitecture() {
        return GameArchitecture.Interface;
    }
    
    void Update() {
        if (Input.GetKeyDown(KeyCode.Space)) {
            this.SendCommand(new JumpCommand());
        }
    }
}

5.3 事件处理示例

public class UIScorePanel : MonoBehaviour, IOnEvent<ScoreChangedEvent> {
    void Start() {
        this.RegisterEvent<ScoreChangedEvent>();
    }
    
    public void OnEvent(ScoreChangedEvent e) {
        scoreText.text = e.NewScore.ToString();
    }
    
    void OnDestroy() {
        this.UnRegisterEvent<ScoreChangedEvent>();
    }
}