UnityAI/rules/20-开发规则.md

开发规则

本文档是 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 统一入口访问核心库：

// ✅ 正确：通过统一入口访问
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 修改后，按项目流程重新生成。
• 缺失的生成步骤记录到 工作流清单 或对应模块文档。
• 详细规则见 数据/配置框架。

---

网络和 Protobuf 规则

• .proto 是消息结构源头。
• schema 修改后重新生成 C# 输出。
• route/message-id 映射变化要和 schema 变化一起记录。
• 详细规则见 网络框架。

---

UI 框架规则

UI 窗口、Prefab、层级、生命周期、事件释放和 UIMono 绑定规则见 UI 框架。

---

文档编写规则

• 每个 .md 文件末尾必须包含 文档关联 表。
• 模块文档变更必须同步更新 模块索引。
• 不要在多个文档中重复维护同一份事实表。
• 使用相对路径链接，确保在 GitHub / IDE / AI 工具中均可点击。
• 代码示例必须可编译（或明确标注为伪代码）。

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
rules/项目规则入口.md	开发规则是项目规则入口索引的关键规则
rules/10-架构说明.md	程序集边界、依赖方向与 C# / Unity 规则互相引用
modules/模块索引.md	模块索引中的框架模块文档是开发规则的具体落地
UI 框架	UI 命名、Prefab、层级等规则的具体说明
网络框架	网络、Protobuf 规则的具体说明
数据/配置框架	配置表、生成输出规则的具体说明
实体系统	Entity 编码规范与核心库访问规则落地
通用框架	核心库范围与通用层规则落地
对象池与运行时对象管理	对象池最佳实践落地