You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
281 lines
12 KiB
281 lines
12 KiB
# 项目开发规范（AI 与人工必读）
|
|
|
|
> 更新日期：2026-08-17
|
|
> 适用范围：本仓库全部 TypeScript / 业务逻辑新增与修改
|
|
> Cursor 持久规则：`.cursor/rules/dev-standards.mdc`
|
|
|
|
本文档定义 **AI 智能体生成代码** 与 **人工协作开发** 的强制标准。违反项应在 Code Review 与合并前纠正。
|
|
|
|
---
|
|
|
|
## 1. 工程素养与全局视角
|
|
|
|
### 1.1 经验水准
|
|
|
|
以 **二十年资深程序员** 的标准审视每一行代码：熟悉常见技术实现、设计模式、引擎机制与平台差异，不写出「只会堆代码」的解法。
|
|
|
|
### 1.2 全局优先（含临时修 Bug）
|
|
|
|
**任何改动**——包括一行临时修 Bug——都必须从 **全局** 出发，综合评估：
|
|
|
|
| 维度 | 要求 |
|
|
|------|------|
|
|
| 架构性 | 是否符合分层（MX 框架 / 业务 / UI），是否破坏模块边界 |
|
|
| 可复用性 | 是否可沉淀为通用能力，避免复制粘贴 |
|
|
| 可扩展性 | 后续需求是否只需扩展而非推翻 |
|
|
| 高可靠性 | 异常路径是否可控，状态是否一致 |
|
|
| 安全性 | 输入、存档、网络、平台 API 是否安全使用 |
|
|
|
|
禁止「只改眼前这一处、不管上下游」的局部补丁式屎山。
|
|
|
|
### 1.3 长期记忆与整体分析
|
|
|
|
- 对话可能很长，**不能仅依赖当前会话上下文**；须结合 `docs/` 文档、架构分层与已有模块做 **整体分析**。
|
|
- 新会话开始前应查阅：`项目说明.md`、`项目分析报告.md`、相关 `需求-*` / `方案-*`。
|
|
- 架构级决策写入 `docs/`，形成项目 **长期记忆**，避免「聊着聊着忘了」或「新开会话全忘」。
|
|
|
|
---
|
|
|
|
## 2. 面向对象与代码组织
|
|
|
|
### 2.1 OOP 为默认范式
|
|
|
|
- 必须基于 **面向对象** 开发，运用软件工程中的封装、抽象、单一职责、依赖倒置等原则。
|
|
- **任何功能模块** 使用类 + 接口组织；逻辑归属清晰，不散落。
|
|
|
|
### 2.2 禁止全局函数
|
|
|
|
- **业务逻辑** 必须在 **接口或类** 中实现。
|
|
- **禁止** 新增裸全局函数承载业务逻辑。
|
|
- 例外（已存在、勿再扩散）：
|
|
- 引擎生命周期组件（`Component` 子类）
|
|
- 框架级单例入口（如 `gg`）
|
|
- 纯类型/常量模块的导出（无运行时逻辑）
|
|
|
|
### 2.3 文件与脚本粒度
|
|
|
|
- **禁止** 为一个小需求随意新增 TS 文件。
|
|
- 同类 **数据结构、接口定义** 合并到同一文件（如 `*Types.ts`、`*Defs.ts`）。
|
|
- 新增文件须有明确模块边界理由，并在文档或 PR 说明中可解释。
|
|
|
|
### 2.4 命名
|
|
|
|
- 接口、枚举、类、字段、函数名：**简化驼峰**，简洁易懂，**禁止过长名称**。
|
|
- 示例：`BattleFacade`（可）、`BattleSessionRuntimeFacadeManager`（过长，避免）。
|
|
|
|
---
|
|
|
|
## 3. 代码质量：简洁、无屎山、无擅自兜底
|
|
|
|
### 3.1 简洁可读
|
|
|
|
- 完全杜绝屎山：短函数、清晰分支、少嵌套；能自解释的代码优先于冗长注释。
|
|
- **通用框架代码**（`assets/mx/`）中 **不写业务逻辑注释**；框架层仅保留必要的模块/契约说明。
|
|
|
|
### 3.2 禁止擅自兜底
|
|
|
|
- **坚决禁止** 任何形式的静默兜底（默认值掩盖错误、吞异常、`??` 掩盖配表缺失、空实现假装成功等）。
|
|
- **允许**：显式 **容错警告**（`console.warn` / 受控日志 / 上报），让问题 **暴露** 给开发者或监控。
|
|
- 数据缺失、配表错误、资源加载失败等：**报错或中止当前流程**，由上游或策划修复，不得 AI 自行「猜一个能跑的值」。
|
|
|
|
### 3.3 变量与常量
|
|
|
|
- 实现功能时 **不随意新增** 变量/常量；能复用现有状态、参数、类字段的则复用。
|
|
- 新增须有必要性（生命周期、可读性、性能分帧等），避免无意义中间变量堆砌。
|
|
|
|
---
|
|
|
|
## 4. 文档注释规范
|
|
|
|
### 4.1 必须写文档注释的符号
|
|
|
|
以下 **全部** 须有标准 JSDoc 风格 **文档注释**（`/** ... */`），简洁明了：
|
|
|
|
- 数据结构定义（`interface`、`type` 别名若表达业务含义）
|
|
- 类
|
|
- 接口
|
|
- 枚举及 **每一个枚举项**
|
|
- 字段（`interface` / 类 public 成员）
|
|
- 函数 / 方法（含参数与返回值说明，若含义不直观）
|
|
|
|
### 4.2 注释风格
|
|
|
|
```typescript
|
|
/** 战斗会话对外门面，项目层唯一入口 */
|
|
export class BattleFacade {
|
|
/** 当前活跃会话；无战斗时为 null */
|
|
private _session: BattleSession | null = null;
|
|
|
|
/**
|
|
* 部署塔单位
|
|
* @param weapon1Id Weapon1 表 id
|
|
* @param row 逻辑行 0~11
|
|
* @param col 逻辑列 0~9
|
|
*/
|
|
deploy(weapon1Id: number, row: number, col: number): void { }
|
|
}
|
|
|
|
/** 章节难度 */
|
|
export enum ChapterDiff {
|
|
/** 普通 */
|
|
Normal = 2,
|
|
}
|
|
```
|
|
|
|
- 不写废话注释（`// 赋值`）；不写与代码矛盾的注释。
|
|
- **框架通用代码** 不写逐步逻辑注释；业务复杂流程可在 **业务层** 用简短注释说明非显而易见的规则。
|
|
|
|
---
|
|
|
|
## 5. 函数与语法约束
|
|
|
|
| 规则 | 说明 |
|
|
|------|------|
|
|
| 参数不换行 | 函数形参列表写在 **同一行**；过长时优先简化命名或减少参数，而非拆行 |
|
|
| 禁止函数内定义函数 | 不在方法体内 `function foo()` 或箭头函数承载可复用逻辑；提取为类私有方法 |
|
|
| 尽量避免闭包 | 回调、延迟逻辑定义为 **类方法**，显式 `bind` 或使用箭头类字段（注意 `onDestroy` 解绑） |
|
|
| 回调归属 | 事件、动画、加载完成等回调写在类中，生命周期内配对注册/注销 |
|
|
|
|
---
|
|
|
|
## 6. TypeScript 与 Cocos 平台约束
|
|
|
|
### 6.1 ES 版本与语法
|
|
|
|
- 遵循 Cocos Creator 推荐的 **ES 版本**（以项目 `tsconfig` 与引擎文档为准）。
|
|
- **禁止使用** 高风险、小游戏环境 **不稳定** 的语法与内置类型，例如：
|
|
- **`Set` / `Map`**（部分真机/小游戏解析或序列化异常；用数组 + 显式去重或项目内 `MembershipSet` 等等价结构）
|
|
- **禁止** 对 `Map`/`Set` 迭代器做展开或 `Array.from`：`[...map.keys()]`、`[...map.values()]`、`[...map.entries()]`、`[...map]`、`[...set]`、`Array.from(map.keys())`。web-mobile 会编成 `[].concat(iterator)`，得到空对象，随后 `.map` 崩。收数组用 `mapKeysToArray` / `mapValuesToArray` / `membershipToArray`；遍历用 `forEach`。
|
|
- 过度依赖新特性而未经平台验证的 API
|
|
|
|
### 6.2 Cocos Creator 官方文档
|
|
|
|
- 调用引擎能力（节点、组件、资源、`assetManager`、`director`、动画、物理等）时 **严格遵守官方文档**。
|
|
- 不臆造 API；不依赖未文档化行为；版本差异以 **3.8.8** 为准。
|
|
|
|
---
|
|
|
|
## 7. 需求边界（禁止擅自发挥）
|
|
|
|
| 情况 | 行为 |
|
|
|------|------|
|
|
| 需求不明确 | **必须询问用户** 并确认，不得猜测实现 |
|
|
| 用户未授权「自行发挥」 | **禁止** 自行扩展玩法、数值、交互 |
|
|
| 行业惯例 / 通用默认 | 允许（例：未规定飞行特效细节时，可自行设计「酷炫」表现） |
|
|
| 策划数值、流程、文案 | **禁止** AI 擅自更改；有疑问先问 |
|
|
|
|
---
|
|
|
|
## 8. 性能与帧循环
|
|
|
|
除架构要求外，必须考虑 **运行时性能**：
|
|
|
|
- **时间复杂度 / 空间复杂度**：热路径（`update`、战斗 tick、列表刷新）避免 O(n²) 与无谓分配。
|
|
- **帧循环**：能 **分帧** 的必须分帧（`FrameFlowHost`、分帧加载、延迟初始化）；能 **延迟** 的延迟（非关键路径不要阻塞首帧）。
|
|
- 避免在 `update` 内创建对象、查表、字符串拼接；缓存、池化、脏标记优先。
|
|
- 与 `LoadScheduler`、`ResourcePhaseGate` 等资源策略对齐，不在错误阶段猛加载。
|
|
|
|
---
|
|
|
|
## 9. 动画与异步生命周期
|
|
|
|
适用于 **Tween、插值、Spine、程序 Animation** 等一切动画：
|
|
|
|
- 视为 **异步逻辑**：开始、停止、完成、被覆盖、节点销毁须成对处理。
|
|
- **必须** 处理：停止动画、清除回调、组件 `onDestroy` 时取消未完成动画。
|
|
- 禁止：节点已销毁仍执行 tween 回调、重复注册未清理的 `complete` 导致崩溃或逻辑错乱。
|
|
- 动画与战斗暂停、UI 遮挡、场景切换的交互须明确（参考 `BattleUiPauseGate` 等现有门闩）。
|
|
|
|
---
|
|
|
|
## 10. 资源加载、使用与释放
|
|
|
|
资源相关代码为 **高危区**，须深度理解引擎资源机制与各真机环境：
|
|
|
|
| 要求 | 说明 |
|
|
|------|------|
|
|
| 加载 | 明确 bundle、路径、阶段；失败 **暴露错误**，不静默跳过 |
|
|
| 使用 | 持有引用期间节点有效；异步回调前校验 `isValid(node)` |
|
|
| 释放 | 与 `BundleLifecycle`、`gg.res` 策略一致；不提前释放仍被渲染/引用的资源 |
|
|
| 异常操作 | 考虑玩家快速切换界面、断网、重复点击、战斗中途退出 |
|
|
| 禁止 | **资源已释放仍参与渲染** 导致的崩溃（空纹理、无效 SpriteFrame 等） |
|
|
|
|
参考模块：`AssetService`、`BundleLifecycle`、`RuntimeLoadingGate`、`BattleBackgroundLoadGate`。
|
|
|
|
---
|
|
|
|
## 11. 内存、复用与对象池
|
|
|
|
实现代码时 **必须考虑内存**，不能完全不顾内存占用与 GC 压力。
|
|
|
|
### 11.1 复用优先
|
|
|
|
- 能复用的对象、数组、临时结构 **尽量复用**，避免热路径频繁 `new`。
|
|
- 与第 8 节性能要求一致：分帧、池化、脏标记、减少短命对象。
|
|
|
|
### 11.2 对象池
|
|
|
|
| 要求 | 说明 |
|
|
|------|------|
|
|
| 正确使用 | 出池用于显示/逻辑，用毕 **归还**；禁止泄漏（借出未还、重复归还） |
|
|
| 状态初始化 | 复用前 **深度分析** 该对象的全部使用方与字段含义；`onGet` / `reset` / `clear` 须 **完整重置状态**，不得残留上一轮数据 |
|
|
| 禁止新 Bug | 不得因池化引入逻辑错误（脏数据、错误 parent、未解绑事件、动画未停） |
|
|
| 与释放平衡 | 池化是为复用，不是无限囤积；池容量与释放策略须符合 `MemoryProfile` 档位 |
|
|
|
|
对象池适用：子弹、飘字、列表 Item、临时 Node 包装等高频创建/销毁对象。
|
|
|
|
### 11.3 释放字段与引用
|
|
|
|
- 除对象池外，**可释放** 的资源引用、大数组、缓存字段、事件监听、定时器，在生命周期结束时应 **显式释放或置空**。
|
|
- 释放前须分析：**是否仍被异步回调、动画、其他模块持有**。
|
|
- **禁止** 因过早释放引入崩溃或逻辑错误（与第 10 节资源释放原则一致：释放须安全，不释放须可解释）。
|
|
|
|
### 11.4 自检要点
|
|
|
|
- [ ] 出池对象所有业务字段已重置？
|
|
- [ ] 事件、 tween、Spine 监听已解绑？
|
|
- [ ] 节点 parent、active、组件引用已恢复默认？
|
|
- [ ] 归还后无外部仍持有该实例的强引用？
|
|
|
|
---
|
|
|
|
## 12. 与现有架构的关系
|
|
|
|
| 层级 | 路径 | 新代码原则 |
|
|
|------|------|------------|
|
|
| MX 框架 | `assets/mx/` | 无业务逻辑；可复用能力；不加业务注释 |
|
|
| 业务 | `assets/script/` | 玩法、配表、SDK 适配 |
|
|
| UI | `assets/script/ui/` | 展示与交互；通过门面访问战斗/数据 |
|
|
|
|
老项目复制代码 **不完全符合** 本规范；**新写与改动触及的代码** 须向本规范收敛，大规模遗留清理按 [`遗留代码收敛方案.md`](./遗留代码收敛方案.md) 与 `docs/需求-*` 排期。
|
|
|
|
### 遗留代码策略（摘要）
|
|
|
|
- **禁止** 无需求驱动的全库规范重构（易回归且可能重构即将删除的模块）。
|
|
- **新代码** 与 **本次修改触及的文件** 必须遵规范。
|
|
- 全库收敛分阶段见 `遗留代码收敛方案.md`。
|
|
|
|
---
|
|
|
|
## 13. 自检清单（提交前）
|
|
|
|
- [ ] 是否从全局/架构评估过，而非只改一处？
|
|
- [ ] 逻辑是否在类/接口中，无新增全局业务函数？
|
|
- [ ] 是否避免多余文件、多余变量？
|
|
- [ ] 接口/类/枚举/枚举项/字段/函数均有文档注释？
|
|
- [ ] 函数参数未换行？函数内无嵌套函数定义？
|
|
- [ ] 无静默兜底？问题是否暴露？
|
|
- [ ] 未使用 `Set`/`Map` 等不稳定结构（新代码）？
|
|
- [ ] 动画与资源：销毁/取消/释放是否完整？
|
|
- [ ] 对象池：出池重置完整、归还无泄漏、无脏状态？
|
|
- [ ] 可释放字段/引用：生命周期结束是否安全释放，且未过早释放？
|
|
- [ ] 热路径是否考虑分帧、内存与性能？
|
|
- [ ] 需求是否经用户确认，未擅自改策划？
|
|
|
|
---
|
|
|
|
## 14. 相关文档
|
|
|
|
- [项目说明.md](./项目说明.md) — 目录约定与项目背景
|
|
- [项目分析报告.md](./项目分析报告.md) — 代码基线架构
|
|
- [性能打点说明.md](./性能打点说明.md) — 性能打点（若沿用）
|
|
|