[docs][refactor]: 将旧 01~06 中文教程合并整理为 modules/frameworks 文件夹结构
- 删除 01~05 旧中文教程目录 - 将 03 核心功能教程拆分为各 framework 模块的子文档 - 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/ - 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md - 更新所有交叉链接与文档关联表 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
269
rules/20-开发规则.md
Normal file
269
rules/20-开发规则.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 开发规则
|
||||
|
||||
> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
|
||||
|
||||
## 基本原则
|
||||
|
||||
- 优先遵循项目已有模式。
|
||||
- 修改范围保持在当前功能或模块内。
|
||||
- 不手动修改生成代码，除非生成器不可用且已记录原因。
|
||||
- 不直接修改 `Assets/ThirdPlugins/` 或 embedded package，除非必须且记录原因。
|
||||
- 正常分析项目时忽略 Unity/IDE 本地状态目录。
|
||||
- 运行时代码不引用 Editor 程序集。
|
||||
- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。
|
||||
|
||||
---
|
||||
|
||||
## C# 规则
|
||||
|
||||
### 命名
|
||||
|
||||
- 类名、结构体、枚举、属性、方法使用 PascalCase。
|
||||
- 私有字段使用 `m_` + PascalCase，例如 `m_UserName`、`m_BagPage`。
|
||||
- 方法参数使用 `_` + camelCase，例如 `_username`、`_maxpage`。
|
||||
- 局部变量使用 camelCase。
|
||||
- 常量：同一文件内保持一致，优先使用全大写 + 下划线（如 `C_FRAME_ROOT_PATH`）或 PascalCase。
|
||||
- 抽象类优先加 `Abs` 前缀，例如 `AbsHFSingleMonoBehaviour<T>`、`AbsHFAssetRequest`。
|
||||
- 单例管理器优先继承 `AbsHFSingleMonoBehaviour<T>` 或 `AbsHFSingleRunTime<T>`。
|
||||
- Hotfix 类名可优先加 `HF` 前缀，例如 `HFLoginManager`、`HFBagManager`。
|
||||
- 业务类型枚举可按用途加前缀，例如 `enItemType`、`enCurrencySubItemType`。
|
||||
- 事件枚举可按用途加前缀，例如 `enHFSTCEvent`、`enHFCTCEvent`。
|
||||
|
||||
### 代码组织
|
||||
|
||||
- 一个 `.cs` 文件原则上只放一个主要类型；小枚举可多个共存。
|
||||
- 类型可见性排序按项目已有风格；如无风格，按 public → protected → internal → private。
|
||||
- 公共 API 添加中文 XML 文档注释或行内注释，说明用途、参数、返回值。
|
||||
- 只在解释非显然意图时添加注释，不写无意义注释。
|
||||
|
||||
### 日志与异常
|
||||
|
||||
- 异常只用于异常情况，不用于正常流程控制。
|
||||
- 错误日志包含方法名和关键上下文，不包含敏感信息。
|
||||
- 写日志时保持附近文件风格；优先使用项目统一的日志封装（如有）。
|
||||
|
||||
### 其他
|
||||
|
||||
- 优先遵循附近文件风格。同一文件/同一目录下风格应保持一致。
|
||||
- 保持 public API 小而明确。
|
||||
- 避免超长方法和深层嵌套。
|
||||
|
||||
---
|
||||
|
||||
## 核心库访问规则
|
||||
|
||||
### 核心库范围
|
||||
|
||||
以下目录属于核心库，业务代码应只读访问，修改需走框架团队 Issue 流程：
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| `Assets/StrayFog/Core` | 基础框架核心 |
|
||||
| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 |
|
||||
| `Assets/Game/GameGeneralScripte` | 通用工具层 |
|
||||
|
||||
### 访问方式
|
||||
|
||||
业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库：
|
||||
|
||||
```csharp
|
||||
// ✅ 正确：通过统一入口访问
|
||||
HFFunCatalogue.UIManager.OpenWindow<LoginWindow>();
|
||||
HFFunCatalogue.Asset.LoadAsset<GameObject>("path");
|
||||
HFFunCatalogue.Scene.LoadScene("MainScene");
|
||||
|
||||
// ❌ 禁止：直接访问核心库
|
||||
HFUIWindowMgr.Instance.OpenWindow<LoginWindow>(); // 禁止
|
||||
HFABMgr.Instance.LoadAsset<GameObject>("path"); // 禁止
|
||||
```
|
||||
|
||||
### 禁止操作
|
||||
|
||||
| 禁止行为 | 后果 |
|
||||
|---------|------|
|
||||
| 修改核心库源代码 | 破坏框架稳定性 |
|
||||
| 删除/重命名核心库文件 | 编译错误 |
|
||||
| 直接实例化核心库内部类 | 违反封装原则 |
|
||||
| 绕过 `HFFunCatalogue` 直接调用核心库单例 | 难以维护和测试 |
|
||||
|
||||
### 修改流程
|
||||
|
||||
1. 业务人员发现问题/需求 → 提交 Issue 到框架团队
|
||||
2. 框架团队评估需求
|
||||
3. 合理：开发修复 → 代码审查 → 发布新版本 → 业务团队更新引用
|
||||
4. 不合理：反馈拒绝
|
||||
|
||||
---
|
||||
|
||||
## 业务代码结构
|
||||
|
||||
### 目录组织
|
||||
|
||||
业务代码主要位于 `Assets/Game/GameHFScripte/GameFunction/`，按职责分目录：
|
||||
|
||||
```
|
||||
Assets/Game/GameHFScripte/GameFunction/
|
||||
├── Event/ # 消息处理
|
||||
│ ├── ServerToClient/ # 服务器到客户端消息
|
||||
│ ├── ClientToClient/ # 客户端内部消息
|
||||
│ └── Handle/ # 消息处理器
|
||||
├── GameRoot/ # 框架调用入口
|
||||
├── Logic/ # 游戏主要业务逻辑（存放各功能 Manager）
|
||||
├── UIWindows/ # UI 窗口业务逻辑
|
||||
├── GameEntity/ # 游戏实体
|
||||
├── SoundManagerPro/ # 音效管理
|
||||
├── SceneManager/ # 场景管理
|
||||
└── SDK/ # SDK 集成
|
||||
```
|
||||
|
||||
### 文件命名
|
||||
|
||||
| 文件类型 | 命名规则 | 示例 |
|
||||
|---------|---------|-----|
|
||||
| 窗口类 | `XXXWindow.cs` | `LoginWindow.cs` |
|
||||
| 组件类 | `XXXComponent.cs` | `ItemCellComponent.cs` |
|
||||
| 管理器类 | `XXXManager.cs` | `UIManager.cs` |
|
||||
| 数据类 | `XXXData.cs` | `PlayerData.cs` |
|
||||
| 配置类 | `XXXConfig.cs` | `SkillConfig.cs` |
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 性能优化
|
||||
|
||||
- 频繁创建销毁的对象必须使用对象池。
|
||||
- 合理设置对象池初始容量。
|
||||
- 及时释放不再使用的资源。
|
||||
- 使用异步加载避免卡顿。
|
||||
- 合理使用资源缓存。
|
||||
- 将图标打包到 SpriteAtlas。
|
||||
- 滚动列表优先使用 `SFUI_ScrollRect.BindEvent`。
|
||||
|
||||
### 代码组织
|
||||
|
||||
- 每个类只负责一个功能，避免庞大的 God 类。
|
||||
- 通过管理器获取依赖，而非硬编码。
|
||||
- 使用接口解耦依赖关系。
|
||||
- 保持 public API 小而明确。
|
||||
- 避免超长方法和深层嵌套。
|
||||
|
||||
### 错误处理
|
||||
|
||||
- 异常只用于异常情况，不用于正常流程控制。
|
||||
- 在关键路径添加异常处理。
|
||||
- 记录错误日志便于排查，但不包含敏感信息。
|
||||
- 检查参数合法性，处理空引用情况。
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 如何扩展核心库功能？
|
||||
|
||||
通过继承抽象类或实现接口来扩展，不要直接修改核心库代码。
|
||||
|
||||
### 核心库有 Bug 怎么办？
|
||||
|
||||
提交 Issue 到框架团队，由框架团队修复并发布新版本。
|
||||
|
||||
### 如何调试核心库代码？
|
||||
|
||||
可以设置断点调试，但不允许修改代码。
|
||||
|
||||
### 常用核心库 API
|
||||
|
||||
| 类别 | 管理器 | 常用方法 |
|
||||
|-----|-------|---------|
|
||||
| 对象池 | `HFObjectMemPool` | `GetItem()`, `GiveBack()` |
|
||||
| 事件 | `IHFEventHandle` | `AddListener()`, `Dispatch()` |
|
||||
| 资源 | `HFABMgr` | `OnStartLoad()` |
|
||||
| 相机 | `HFCameraManager` | `AddCamera()`, `GetCamera()` |
|
||||
|
||||
---
|
||||
|
||||
## Unity 资源规则
|
||||
|
||||
### Prefab
|
||||
|
||||
- Prefab 修改保持聚焦，避免无意义的大范围 reserialize。
|
||||
- UI Prefab 命名与窗口/面板对应，例如 `Login.prefab`、`ItemWindow.prefab`。
|
||||
- 通用 UI 组件/Item 使用 `Item` 后缀，例如 `AvatarItem.prefab`、`ResourceItem.prefab`。
|
||||
- 记录无法从代码复现的手动 Unity Editor 操作。
|
||||
|
||||
### Scene
|
||||
|
||||
- 场景按用途命名，例如 `LoginScene`、`BattleScene`。
|
||||
- 不要直接在场景里堆放运行时动态加载的资源。
|
||||
|
||||
### Sprite Atlas
|
||||
|
||||
- 按业务或 UI 模块划分图集，例如 `SpriteAtlasAssets/Shop`、`SpriteAtlasAssets/Login`。
|
||||
- 图集内图片按功能子目录组织，避免单张图集过大。
|
||||
|
||||
### Material / Shader
|
||||
|
||||
- 优先使用项目已有 Shader，不随意引入新 Shader。
|
||||
- Material 实例在运行时通过代码创建，避免直接修改共享 Material。
|
||||
|
||||
### Audio
|
||||
|
||||
- 音效、背景音乐分目录存放。
|
||||
- 短音效优先使用 AudioClip + AudioSource 池，长音乐注意卸载。
|
||||
|
||||
### 本地化资源
|
||||
|
||||
- 资源按语言分目录，例如 `GameHFResource/CN/`、`GameHFResource/EN/`。
|
||||
- 多语言共用资源放在不带语言后缀的公共目录。
|
||||
|
||||
---
|
||||
|
||||
## 配置和数据规则
|
||||
|
||||
- 优先修改源表、proto 或 schema，而不是生成输出。
|
||||
- 数据/schema 修改后，按项目流程重新生成。
|
||||
- 缺失的生成步骤记录到 [工作流清单](40-工作流清单.md) 或对应模块文档。
|
||||
- 详细规则见 [数据/配置框架](../modules/frameworks/数据配置框架.md)。
|
||||
|
||||
---
|
||||
|
||||
## 网络和 Protobuf 规则
|
||||
|
||||
- `.proto` 是消息结构源头。
|
||||
- schema 修改后重新生成 C# 输出。
|
||||
- route/message-id 映射变化要和 schema 变化一起记录。
|
||||
- 详细规则见 [网络框架](../modules/frameworks/网络系统.md)。
|
||||
|
||||
---
|
||||
|
||||
## UI 框架规则
|
||||
|
||||
UI 窗口、Prefab、层级、生命周期、事件释放和 UIMono 绑定规则见 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。
|
||||
|
||||
---
|
||||
|
||||
## 文档编写规则
|
||||
|
||||
- 每个 `.md` 文件末尾必须包含 **文档关联** 表。
|
||||
- 模块文档变更必须同步更新 [模块索引](../modules/模块索引.md)。
|
||||
- 不要在多个文档中重复维护同一份事实表。
|
||||
- 使用相对路径链接，确保在 GitHub / IDE / AI 工具中均可点击。
|
||||
- 代码示例必须可编译（或明确标注为伪代码）。
|
||||
|
||||
---
|
||||
|
||||
## 文档关联
|
||||
|
||||
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
|
||||
|
||||
| 文档 | 关联原因 |
|
||||
|---|---|
|
||||
| [rules/项目规则入口.md](项目规则入口.md) | 开发规则是项目规则入口索引的关键规则 |
|
||||
| [rules/10-架构说明.md](10-架构说明.md) | 程序集边界、依赖方向与 C# / Unity 规则互相引用 |
|
||||
| [modules/模块索引.md](../modules/模块索引.md) | 模块索引中的框架模块文档是开发规则的具体落地 |
|
||||
| [UI 框架](../modules/frameworks/UI窗口系统/README.md) | UI 命名、Prefab、层级等规则的具体说明 |
|
||||
| [网络框架](../modules/frameworks/网络系统.md) | 网络、Protobuf 规则的具体说明 |
|
||||
| [数据/配置框架](../modules/frameworks/数据配置框架.md) | 配置表、生成输出规则的具体说明 |
|
||||
| [实体系统](../modules/frameworks/实体系统/README.md) | Entity 编码规范与核心库访问规则落地 |
|
||||
| [通用框架](../modules/frameworks/通用框架/README.md) | 核心库范围与通用层规则落地 |
|
||||
| [对象池与运行时对象管理](../modules/frameworks/内存对象管理/README.md) | 对象池最佳实践落地 |
|
||||
Reference in New Issue
Block a user