mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-03-26 06:16:43 +08:00
a79f02c987
- 新增 Core API 参考文档，涵盖架构与模块、数据模型与系统、命令与查询等核心组件 - 添加事件系统接口详细文档，包括 IEvent、IEventBus、IUnRegister 等接口说明 - 提供完整的 API 使用示例路径、最佳实践与性能建议 - 包含架构图、依赖关系图与故障排查指南 - 添加测试用例参考与扩展方法说明 - [skip ci]
22 KiB
22 KiB
游戏功能模块
**本文档引用的文件** - [UiRouterBase.cs](file://GFramework.Game/ui/UiRouterBase.cs) - [UiTransitionPipeline.cs](file://GFramework.Game/ui/UiTransitionPipeline.cs) - [IUiRouter.cs](file://GFramework.Game.Abstractions/ui/IUiRouter.cs) - [IUiTransitionHandler.cs](file://GFramework.Game.Abstractions/ui/IUiTransitionHandler.cs) - [UiLayer.cs](file://GFramework.Game.Abstractions/enums/UiLayer.cs) - [SettingsSystem.cs](file://GFramework.Game/setting/SettingsSystem.cs) - [SettingsModel.cs](file://GFramework.Game/setting/SettingsModel.cs) - [SettingsPersistence.cs](file://GFramework.Game/setting/SettingsPersistence.cs) - [ISettingsSystem.cs](file://GFramework.Game.Abstractions/setting/ISettingsSystem.cs) - [FileStorage.cs](file://GFramework.Game/storage/FileStorage.cs) - [ScopedStorage.cs](file://GFramework.Game/storage/ScopedStorage.cs) - [JsonSerializer.cs](file://GFramework.Game/serializer/JsonSerializer.cs) - [GameStateMachineSystem.cs](file://GFramework.Game/state/GameStateMachineSystem.cs)目录
简介
本文件面向GFramework游戏功能模块，围绕以下主题提供系统化、可操作的技术文档：
- UI系统（UiRouterBase）的页面栈管理、层级系统与过渡管道实现
- 设置系统（SettingsSystem）的配置管理、持久化存储与实时应用机制
- 状态管理系统（GameStateMachineSystem）的有限状态机实现、状态转换逻辑与状态持久化策略
- 存储系统（FileStorage、ScopedStorage）的数据持久化方案与序列化器（JsonSerializer）实现
- 游戏抽象接口设计（IUiRouter、ISettingsSystem等）的理念、职责与使用方法
- 每个模块的配置选项、API参考与实际使用示例
- 最佳实践与性能优化建议
项目结构
本模块位于GFramework.Game与GFramework.Game.Abstractions两个工程中，分别提供具体实现与抽象接口。核心模块包括：
- UI路由与过渡：UiRouterBase、UiTransitionPipeline、IUiRouter、IUiTransitionHandler、UiLayer
- 设置系统：SettingsSystem、SettingsModel、SettingsPersistence、ISettingsSystem
- 存储系统：FileStorage、ScopedStorage、JsonSerializer
- 状态系统：GameStateMachineSystem
graph TB
subgraph "UI"
UIR["UiRouterBase"]
UIP["UiTransitionPipeline"]
IUR["IUiRouter 接口"]
IUTH["IUiTransitionHandler 接口"]
UL["UiLayer 枚举"]
end
subgraph "设置"
SS["SettingsSystem"]
SM["SettingsModel"]
SP["SettingsPersistence"]
ISS["ISettingsSystem 接口"]
end
subgraph "存储"
FS["FileStorage"]
SC["ScopedStorage"]
JS["JsonSerializer"]
end
subgraph "状态"
GSM["GameStateMachineSystem"]
end
UIR --> UIP
UIR -.实现.-> IUR
UIP -.处理.-> IUTH
UIR --> UL
SS --> SM
SS -.使用.-> ISS
SP --> FS
SP --> SC
FS --> JS
图表来源
- UiRouterBase.cs
- UiTransitionPipeline.cs
- IUiRouter.cs
- IUiTransitionHandler.cs
- UiLayer.cs
- SettingsSystem.cs
- SettingsModel.cs
- SettingsPersistence.cs
- ISettingsSystem.cs
- FileStorage.cs
- ScopedStorage.cs
- JsonSerializer.cs
- GameStateMachineSystem.cs
章节来源
- UiRouterBase.cs
- UiTransitionPipeline.cs
- IUiRouter.cs
- IUiTransitionHandler.cs
- UiLayer.cs
- SettingsSystem.cs
- SettingsModel.cs
- SettingsPersistence.cs
- ISettingsSystem.cs
- FileStorage.cs
- ScopedStorage.cs
- JsonSerializer.cs
- GameStateMachineSystem.cs
核心组件
- UI路由与过渡
- UiRouterBase：提供页面栈管理、层级管理、路由守卫、过渡管道注册与执行
- UiTransitionPipeline：按阶段与优先级执行UI切换处理器
- IUiRouter/IUiTransitionHandler：定义路由与过渡扩展点的接口契约
- UiLayer：定义页面层与浮层的层级体系
- 设置系统
- SettingsSystem：集中应用设置，触发事件
- SettingsModel：聚合数据设置与可应用设置
- SettingsPersistence：封装设置的加载、保存、删除与批量操作
- ISettingsSystem：对外暴露设置应用接口
- 存储系统
- FileStorage：基于文件系统的键值存储，带key级锁保证线程安全
- ScopedStorage：为存储键加前缀的作用域包装器
- JsonSerializer：基于Newtonsoft.Json的序列化实现
- 状态系统
- GameStateMachineSystem：在上下文感知的状态机之上提供类型查询与断言能力
章节来源
- UiRouterBase.cs
- UiTransitionPipeline.cs
- IUiRouter.cs
- IUiTransitionHandler.cs
- UiLayer.cs
- SettingsSystem.cs
- SettingsModel.cs
- SettingsPersistence.cs
- ISettingsSystem.cs
- FileStorage.cs
- ScopedStorage.cs
- JsonSerializer.cs
- GameStateMachineSystem.cs
架构总览
UI系统通过“页面栈 + 层级系统 + 过渡管道”的组合实现UI导航与切换；设置系统通过“模型 + 持久化 + 应用器”三层协作实现配置的读取、应用与事件通知；存储系统提供线程安全的键值存储与作用域隔离；状态系统在通用状态机之上提供类型化查询。
sequenceDiagram
participant Caller as "调用方"
participant Router as "UiRouterBase"
participant Pipeline as "UiTransitionPipeline"
participant Handlers as "IUiTransitionHandler"
participant Root as "IUiRoot"
participant Factory as "IUiFactory"
Caller->>Router : Push(uiKey, param, policy, instancePolicy)
Router->>Router : BeforeChange(event)
Router->>Pipeline : ExecuteAsync(event, BeforeChange)
Pipeline->>Handlers : HandleAsync(event)
Handlers-->>Pipeline : 完成/超时/取消
Router->>Factory : GetOrCreate(uiKey, instancePolicy)
Factory-->>Router : IUiPageBehavior
Router->>Root : AddUiPage(page)
Router->>Router : OnEnter/OnShow(page)
Router->>Router : AfterChange(event)
Router->>Pipeline : ExecuteAsync(event, AfterChange)
Pipeline->>Handlers : HandleAsync(event)
图表来源
详细组件分析
UI系统：页面栈管理、层级系统与过渡管道
- 页面栈管理
- 支持Push（基于uiKey或已有页面）、Pop、Replace、Clear等操作
- 栈顶元素通过Peek/PeekKey/IsTop/Contains等方法访问
- 过渡策略（UiTransitionPolicy）与实例策略（UiInstancePolicy）控制页面生命周期与复用
- 层级系统（非栈）
- 通过UiLayer枚举区分Page、Overlay、Modal、Toast、Topmost等
- Show/Hide/ClearLayer管理浮层显示与回收
- 过渡管道
- UiTransitionPipeline按阶段（BeforeChange/AfterChange）与优先级执行处理器
- 支持超时、取消令牌、错误继续策略
- 路由守卫
- 支持注册/移除守卫，按优先级执行进入/离开守卫，支持中断与异常处理
classDiagram
class UiRouterBase {
+int Count
+void BindRoot(root)
+void Push(...)
+void Pop(policy)
+void Replace(...)
+void Clear()
+string PeekKey()
+IUiPageBehavior Peek()
+bool IsTop(uiKey)
+bool Contains(uiKey)
+void RegisterHandler(handler, options)
+void UnregisterHandler(handler)
+void AddGuard(guard)
+void RemoveGuard(guard)
}
class UiTransitionPipeline {
+void RegisterHandler(handler, options)
+void UnregisterHandler(handler)
+Task ExecuteAsync(event, phases, ct)
}
class IUiRouter
class IUiTransitionHandler
class UiLayer
UiRouterBase ..> UiTransitionPipeline : "使用"
UiRouterBase ..|> IUiRouter
UiTransitionPipeline --> IUiTransitionHandler : "执行"
UiRouterBase --> UiLayer : "使用"
图表来源
章节来源
设置系统：配置管理、持久化存储与实时应用
- SettingsSystem
- 负责集中应用设置，遍历模型中的设置节并调用可应用设置的Apply方法
- 发送应用开始/完成事件，异常时发送失败事件并向上抛出
- SettingsModel
- 聚合两类设置：数据设置（ISettingsData）与可应用设置（IApplyAbleSettings）
- 提供GetData/RegisterApplicator/GetApplicator/TryGet/All等方法
- SettingsPersistence
- 基于存储接口（IStorage）实现设置的Load/Save/Delete/LoadAll/SaveAll
- 通过事件总线发布加载、保存、删除、批量保存等事件
- 键名规则：Settings_{TypeName}
flowchart TD
Start(["开始"]) --> GetSection["获取设置节<br/>TryGet/GetData"]
GetSection --> CheckApply{"是否实现IApplyAbleSettings?"}
CheckApply --> |否| End(["结束"])
CheckApply --> |是| SendApplying["发送SettingsApplyingEvent"]
SendApplying --> Apply["调用Apply()"]
Apply --> Success{"是否成功?"}
Success --> |是| SendApplied["发送SettingsAppliedEvent(true)"]
Success --> |否| SendFailed["发送SettingsAppliedEvent(false, ex)"] --> Throw["抛出异常"]
SendApplied --> End
Throw --> End
图表来源
章节来源
存储系统：数据持久化与序列化
- FileStorage
- 基于文件系统，键转路径时进行安全清理与路径校验，防止路径逃逸
- 每个key持有独立锁对象，确保并发读写安全
- 支持同步/异步读写、存在性检查、删除
- 使用ISerializer进行序列化/反序列化
- ScopedStorage
- 对所有键统一添加前缀，形成作用域隔离
- 提供Scope方法创建子作用域
- JsonSerializer
- 基于Newtonsoft.Json的Serialize/Deserialize实现
classDiagram
class FileStorage {
-string _rootPath
-string _extension
-ConcurrentDictionary~string,object~ _keyLocks
-ISerializer _serializer
+bool Exists(key)
+Task~bool~ ExistsAsync(key)
+T Read~T~(key)
+T Read~T~(key, default)
+Task~T~ ReadAsync~T~(key)
+void Write~T~(key, value)
+Task WriteAsync~T~(key, value)
+void Delete(key)
}
class ScopedStorage {
-IStorage _inner
-string _prefix
+bool Exists(key)
+Task~bool~ ExistsAsync(key)
+T Read~T~(key)
+T Read~T~(key, default)
+Task~T~ ReadAsync~T~(key)
+void Write~T~(key, value)
+Task WriteAsync~T~(key, value)
+void Delete(key)
+IStorage Scope(scope)
}
class JsonSerializer {
+string Serialize~T~(value)
+T Deserialize~T~(data)
}
FileStorage --> JsonSerializer : "使用"
ScopedStorage --> IStorage : "包装"
图表来源
章节来源
状态管理系统：有限状态机与查询
- GameStateMachineSystem
- 在通用状态机系统基础上提供类型化查询：IsIn()与Get()
- 便于在业务层以强类型方式判断与获取当前状态
章节来源
抽象接口设计与使用方法
- IUiRouter
- 职责：UI导航与切换的统一入口，包含Push/Pop/Replace/Clear、层级管理、守卫与处理器注册
- 使用要点：通过BindRoot绑定UI根节点；在RegisterHandlers中注册默认处理器；利用策略参数控制页面生命周期
- ISettingsSystem
- 职责：集中应用设置，支持单类型、多类型与全部设置的应用
- 使用要点：在系统初始化后调用ApplyAll或按需调用Apply
- 其他接口
- IUiTransitionHandler：定义处理器优先级、适用阶段、过滤条件与异步处理逻辑
- UiLayer：定义页面层与浮层的层级体系，用于Show/Hide等非栈管理
章节来源
依赖关系分析
- UI路由依赖
- 依赖IUiRoot与IUiFactory以管理页面生命周期与实例复用
- 通过UiTransitionPipeline与IUiTransitionHandler解耦过渡逻辑
- 通过路由守卫实现可插拔的进入/离开控制
- 设置系统依赖
- SettingsSystem依赖ISettingsModel；SettingsModel聚合数据与应用器
- SettingsPersistence依赖IStorage与事件总线，负责持久化与批量操作
- 存储系统依赖
- FileStorage依赖ISerializer；ScopedStorage依赖IStorage
- 状态系统依赖
- GameStateMachineSystem基于通用状态机系统，提供类型化查询
graph LR
UIR["UiRouterBase"] --> |使用| IUR["IUiRouter"]
UIR --> |注册| UIP["UiTransitionPipeline"]
UIP --> |执行| IUTH["IUiTransitionHandler"]
SS["SettingsSystem"] --> |读取| SM["SettingsModel"]
SP["SettingsPersistence"] --> |读写| IStorage["IStorage"]
FS["FileStorage"] --> |实现| IStorage
SC["ScopedStorage"] --> |包装| IStorage
FS --> JS["JsonSerializer"]
GSM["GameStateMachineSystem"] --> |扩展| StateMachine["通用状态机"]
图表来源
- UiRouterBase.cs
- UiTransitionPipeline.cs
- IUiRouter.cs
- IUiTransitionHandler.cs
- SettingsSystem.cs
- SettingsModel.cs
- SettingsPersistence.cs
- FileStorage.cs
- ScopedStorage.cs
- JsonSerializer.cs
- GameStateMachineSystem.cs
章节来源
- UiRouterBase.cs
- UiTransitionPipeline.cs
- SettingsSystem.cs
- SettingsModel.cs
- SettingsPersistence.cs
- FileStorage.cs
- ScopedStorage.cs
- JsonSerializer.cs
- GameStateMachineSystem.cs
性能考量
- UI过渡
- 使用AfterChange异步执行避免阻塞主线程
- 通过UiInstancePolicy控制实例复用，减少频繁创建/销毁开销
- 路由守卫应尽量短小、异步化，避免长时间阻塞
- 存储
- FileStorage按key加锁，避免并发写冲突；读多写少场景建议使用异步读取
- ScopedStorage提供作用域隔离，避免键冲突与命名污染
- JsonSerializer序列化成本与数据大小相关，建议对大对象分片或压缩
- 设置系统
- ApplyAll按需调用，避免频繁全量应用
- SettingsPersistence的批量保存可减少多次IO
故障排查指南
- UI路由
- 若Push被忽略：确认IsTop判断与路由守卫返回值
- Pop被拦截：检查离开守卫CanLeaveAsync返回值
- 过渡卡住：检查UiTransitionHandler超时与ContinueOnError配置
- 设置系统
- Apply失败：查看SettingsAppliedEvent携带的异常信息
- 加载不到数据：确认键名规则Settings_{TypeName}与存储路径一致
- 存储
- 文件不存在：确认键名与扩展名、目录创建逻辑
- 并发写冲突：确认key锁是否生效，避免跨key共享同一锁对象
- 路径逃逸：检查键名中是否包含非法字符或“..”
章节来源
- UiRouterBase.cs
- UiRouterBase.cs
- UiTransitionPipeline.cs
- SettingsSystem.cs
- FileStorage.cs
- FileStorage.cs
结论
本模块通过清晰的抽象接口与可插拔的实现，提供了稳定可靠的UI导航、设置管理、数据持久化与状态管理能力。遵循本文档的最佳实践与配置建议，可在保证性能与可维护性的前提下快速构建复杂的游戏功能模块。
附录
- API参考与配置选项
- UI路由
- Push/Pop/Replace/Clear：支持策略参数与实例策略
- RegisterHandler/UnregisterHandler：注册过渡处理器与选项
- AddGuard/RemoveGuard：注册路由守卫与优先级
- 设置系统
- Apply/ApplyAll/Apply(IEnumerable)：应用设置
- SettingsModel：GetData/RegisterApplicator/TryGet/All
- SettingsPersistence：Load/Save/Delete/LoadAll/SaveAll
- 存储系统
- FileStorage：Write/Read/Exists/Delete，支持同步/异步
- ScopedStorage：Scope创建子作用域
- JsonSerializer：Serialize/Deserialize
- UI路由
- 实际使用示例（步骤说明）
- UI页面切换
- 在模块初始化中注册UiRouter与IUiRoot
- 在RegisterHandlers中注册默认过渡处理器
- 调用Push/Pop/Replace进行页面切换
- 设置应用
- 在SettingsModel中注册可应用设置
- 通过SettingsSystem.ApplyAll应用设置
- 使用SettingsPersistence.Load/Save进行持久化
- 数据存储
- 使用FileStorage进行键值读写
- 使用ScopedStorage进行作用域隔离
- 使用JsonSerializer进行序列化
- UI页面切换