211 lines
8.9 KiB
Markdown
211 lines
8.9 KiB
Markdown
# 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`
|
||
|
||
---
|
||
|