basil
/
vampire-like
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
vampire-like/docs/AssemblyOrganization.md

8.9 KiB
Raw Permalink Blame History

SepCore 程序集组织规范

本文档定义 Assets/GameMain/Scripts 下 C# 代码的程序集（Assembly Definition）拆分规则，用于指导新代码的归属判断和现有代码的维护。

1. 设计原则

1.1 核心约束

  • 单向依赖：下层不引用上层，上层可以引用下层。
  • GameEntry 红线：凡是有 GameEntry. 引用的代码，一律不能放在 Base。
  • 框架适配：UnityGameFramework 是组件化平级协作架构，GameEntry 作为全局访问点天然要求它能看到所有 Component。因此 Component 及其扩展方法统一归到 Runtime，不放在 Base。

1.2 依赖方向

SepCore.Procedure（编排层）
    ↓ 可引用
SepCore.Presentation（表现层）
    ↓ 可引用
SepCore.Runtime（运行时基础设施层）
    ↓ 可引用
SepCore.Base（核心定义层）

Editor 程序集独立，引用除 Presentation 外的所有运行时程序集：

SepCore.Editor
    ↓ 可引用
SepCore.Procedure / SepCore.Runtime / SepCore.Base / UnityGameFramework.*

2. 各层职责与判断标准

2.1 SepCore.Base — 核心定义层

定位：最稳定、最少变化、零外部依赖的纯基础设施。

判断标准：

  • 不引用 GameEntry
  • 不引用任何自定义 MonoBehaviour Component
  • 不引用 UnityGameFramework.Runtime 中的具体 Component（框架基础类型如 EntityLogic 除外）
  • 以数据结构、常量、枚举、纯算法为主

当前归属目录：

目录 说明
Base/DataTable/ DR* 数据表行定义、BinaryReaderExtension、DataTableExtension
Base/Definition/Constant/ Constant.* 常量
Base/Definition/DataStruct/ BuildInfo、VersionInfo 等纯数据结构
Base/Definition/Enum/ SceneType、UIFormType 等枚举
Base/Entity/EntityData/ EntityDataBase（纯数据类）
Base/Entity/EntityLogic/ EntityBase（继承框架 EntityLogic，无 GameEntry 引用）
Base/Utility/ AssetUtility、WebUtility、LitJsonHelper（纯静态工具）

2.2 SepCore.Runtime — 运行时基础设施层

定位：所有 GameFrameworkComponent、全局访问点（GameEntry）、以及对框架组件的扩展方法。

判断标准：

  • 包含 GameEntry. 引用
  • 继承或扩展框架 Component（如 DefaultLocalizationHelper、UIFormLogic）
  • 对 SoundComponent、UIComponent、EntityComponent 等做扩展方法
  • 自定义的 GameFrameworkComponent（如 BuiltinDataComponent）

当前归属目录：

目录 说明
Runtime/BuiltinComponent/ EntityExtension、SoundExtension、UIComponentExtension、XmlLocalizationHelper
Runtime/UIBase/ UGuiForm（基类）、UIExtension、DialogParams、UGuiGroupHelper、CommonButton
Runtime/Base/ GameEntry.cs、GameEntry.Builtin.cs、GameEntry.Custom.cs
Runtime/CustomComponent/BuiltinData/ BuiltinDataComponent.cs
Runtime/Debugger/ ChangeLanguageDebuggerWindow.cs

引用配置：

  • UnityGameFramework.Runtime
  • GameFramework
  • SepCore.Base

2.3 SepCore.Presentation — 表现层

定位：最顶层的业务 UIForm，只包含具体界面的逻辑，不含可复用的 UI 基础设施。

判断标准：

  • 继承 UGuiForm（Runtime 层基类）或直接继承 MonoBehaviour
  • 不向外暴露被其他 Component/Procedure 直接引用的类型（除非通过 GameObject 或基类解耦）
  • 允许调用 GameEntry.*

当前归属目录：

目录 说明
UI/ DialogForm、UpdateResourceForm

引用配置：

  • SepCore.Runtime
  • SepCore.Base
  • UnityGameFramework.Runtime
  • GameFramework

2.4 SepCore.Procedure — 编排层

定位：游戏生命周期流程（Procedure），作为最顶层协调者，可以引用所有人。

判断标准：

  • 继承 ProcedureBase
  • 直接引用具体 UIForm 类型（如 UpdateResourceForm）是允许的，因为 Procedure 是最顶层

当前归属目录：

目录 说明
Procedure/ ProcedureBase + 所有 Procedure 子类

引用配置：

  • SepCore.Presentation
  • SepCore.Runtime
  • SepCore.Base
  • UnityGameFramework.Runtime
  • GameFramework

2.5 SepCore.Editor — 编辑器扩展层

定位：编辑器工具、自定义 Inspector、构建事件等，仅在 Editor 下编译。

引用配置：

  • UnityGameFramework.Editor
  • UnityGameFramework.Runtime
  • SepCore.Runtime
  • SepCore.Base
  • GameFramework

注意：Editor 不引用 SepCore.Presentation，避免编辑器逻辑依赖业务表现层。

3. 程序集引用矩阵

引用方 \ 被引用方 Base Runtime Presentation Procedure Editor
Base — ✗ ✗ ✗ ✗
Runtime ✓ — ✗ ✗ ✗
Presentation ✓ ✓ — ✗ ✗
Procedure ✓ ✓ ✓ — ✗
Editor ✓ ✓ ✗ ✗ —

4. 常见反模式

4.1 Base 层引用 GameEntry

❌ 错误：把 XmlLocalizationHelper、ChangeLanguageDebuggerWindow 等引用 GameEntry 的文件放在 Base。

✅ 正确：凡是调用 GameEntry.* 的文件，一律放到 Runtime 或更高层。

4.2 Runtime 层引用 Presentation 的具体类型

❌ 错误：BuiltinDataComponent 持有 UpdateResourceForm 类型的字段。

✅ 正确：BuiltinDataComponent 暴露 GameObject，由 Procedure（最顶层）通过 GetComponent<UpdateResourceForm>() 获取。

4.3 GameEntry 留在 Base

❌ 错误：GameEntry.Custom.cs 引用了 BuiltinDataComponent（Runtime），但 GameEntry 放在 Base。

✅ 正确：GameEntry 的所有 partial 文件必须和 BuiltinDataComponent 在同一程序集，即 Runtime。

4.4 扩展方法乱放在 Utility/

❌ 错误：把 SoundComponent.PlayMusic 这类扩展方法放在 Utility/SoundExtension.cs。

✅ 正确：对 Component 的扩展方法跟着被扩展方走，放在 BuiltinComponent/（Runtime）下，或按模块分散到各子系统的 Runtime 目录中。

5. 命名空间约定

程序集拆分后，命名空间保持与原始文件夹路径一致，便于代码导航：

程序集 命名空间示例
SepCore.Base SepCore.DataTable、SepCore.Definition、SepCore.Utility
SepCore.Runtime SepCore.Runtime（根命名空间）、SepCore.UI、SepCore.Entity、SepCore.Sound
SepCore.Presentation SepCore.UI（与 Runtime 共享，因为 DialogForm 等原本就在 SepCore.UI）
SepCore.Procedure SepCore.Procedure
SepCore.Editor SepCore.Editor

允许 Runtime 和 Presentation 共享同一个根命名空间（如 SepCore.UI），因为 C# 命名空间可以跨程序集。Presentation 的 DialogForm 在 SepCore.UI 下，Runtime 的 UGuiForm 也在 SepCore.UI 下，这是合法的。

6. 新增代码决策流程

当不确定新文件该放哪一层时，按以下顺序判断：

  1. 是否只在 Editor 使用？ → SepCore.Editor
  2. 是否继承 ProcedureBase？ → SepCore.Procedure
  3. 是否继承 UGuiForm 或 MonoBehaviour 且是具体业务界面？ → SepCore.Presentation
  4. 是否引用 GameEntry、是否是 Component、是否是对 Component 的扩展？ → SepCore.Runtime
  5. 其余所有纯数据/定义/工具 → SepCore.Base