Skip to main content

Unity 代码规范

适用于 Project2 Unity 客户端的 C# 代码开发。目标是让代码可读、稳定、可复用，减少回归风险并提高 handoff 质量。

1. 适用范围​

  • 适用于 Unity 客户端全部脚本、编辑器扩展、测试辅助脚本。
  • 不适用纯热更新配置脚本（仅做数据定义），但该脚本也建议遵守本文命名与注释风格。
  • 本规范优先级：项目内已有实现风格 > 本文 > 个人偏好。

2. 命名规范​

2.1 类与接口​

  • 类名使用 PascalCase，以职责命名（如 LevelLoadCoordinator）。
  • 接口名必须以 I 开头（如 IStateMachineNode）。
  • 脚本名与主类名保持一致。
  • 组件类建议带语义后缀：
    • Manager：状态/生命周期管理器。
    • Controller：输入、流程、UI/场景控制。
    • Model：仅承载状态与数据转换。
    • Service：跨场景服务。

2.2 成员命名​

  • 字段优先级：private 字段用 _camelCase（如 _levelId），public 与 serialized 字段用 PascalCase 或保持 Inspector 对应含义。
  • 常量使用 UPPER_SNAKE_CASE 或 PascalCase（仓库统一一种即可，禁止混杂）。
  • 布尔值应以 Is/Has/Can/Should 开头。
  • 协程方法用动词现在分词命名（如 LoadLevelAsyncRoutine 可接受，推荐 LoadLevelAsync，并在调用处注释）。

2.3 枚举与方法​

  • 枚举项使用 PascalCase。
  • 方法名使用动词开头，避免与字段同名。
  • 同步方法与异步方法分别体现差异（如 LoadConfig / LoadConfigAsync）。
  • 回调类型参数命名含事件语义（如 OnSceneEnter）。

3. 目录与文件组织​

  • 一个脚本文件只放一个主类，特殊情况下可放同名子类作为内部私有结构。
  • 文件夹按职责分层：
    • Runtime/：游戏运行时脚本。
    • UI/：界面相关逻辑。
    • Data/：配置、模型、解析逻辑。
    • Services/：跨系统服务。
    • Editor/：编辑器工具脚本。
  • 禁止把临时脚本、一次性测试脚本留在运行时代码目录。

4. 生命周期与事件管理​

  • Awake 仅做基础字段初始化与引用缓存，不应触发异步流程。
  • OnEnable/OnDisable 只做事件订阅和取消订阅。
  • Start/OnStart 进行首次轻量初始化，不应包含重度计算。
  • Update/LateUpdate/FixedUpdate 只保留高频更新逻辑，避免复杂判断链和大内存分配。
  • 使用 UnityEvent / C# 事件时，必须在 OnDisable/OnDestroy 中移除监听，禁止匿名委托导致泄露。

5. 性能与内存约束​

  • Update 内禁止 GetComponent、FindObjectOfType、FindObjectsOfType、LINQ 大规模查询。
  • 避免每帧 new 大对象、string.Concat 拼接、装箱、Lambda 捕获大对象。
  • 对 List、Dictionary 访问采用对象池或复用缓存集合。
  • 频繁调用 ToList()、Select().ToArray() 属于高风险行为，需要改造。
  • 非必须不要在循环里 GetComponent<T>()。
  • 资源异步加载避免在单帧内发起过量请求。

6. 并发与异步​

  • 同一职责避免嵌套大量回调，优先用 async/await（或统一协程约定）封装。
  • 异步任务失败必须记录原因与恢复路径，不允许“吞掉异常后继续执行”。
  • 需要取消的异步流程必须持有 CancellationToken 或状态标记，并明确终止条件。
  • 超时与重试策略要有日志输出和上报。

7. 错误处理与日志​

  • 业务可恢复错误：记录 Warn + 用户可见提示策略。
  • 关键流程错误：记录 Error，附带关键信息（角色/关卡/用户/配置版本/资源路径）。
  • 禁止使用 print 进行业务日志。
  • 日志中禁止输出账号完整信息和 token，严格脱敏。

8. 代码审阅红线（必须项）​

  • 禁止 GameObject.Find 在热路径中调用。
  • 禁止在 Update 中动态创建/销毁大量临时对象。
  • 禁止 UnityEngine.Random 的非确定性结果影响玩法公平结算。
  • 禁止魔法字符串直接写 UI 文案 key，统一走文案常量或配置。
  • 禁止与业务逻辑同层混入渲染/播放特效细节，必须分层处理。

9. 可测性要求​

  • 公开行为入口需便于 mock 或脚本注入依赖，减少 static 强耦合。
  • 关键业务逻辑需有单元测试骨架（至少覆盖边界条件和失败场景）。
  • 与配置版本相关逻辑必须有版本对齐测试，防止旧版本数据导致行为歧义。

10. 文档与交付​

  • 每个新模块需要提供：
    • 职责说明（1-3 行）
    • 关联配置与依赖
    • 关键生命周期点（Load/Enter/Exit/Dispose）
    • 主要回归场景和失败恢复策略

执行检查清单（MR 级）​

  • 生命周期方法职责拆分正确，无污染性副作用
  • 更新循环中无高频反模式（查找/获取组件/动态分配）
  • 事件监听成对注册与解绑
  • 异常路径可观测（日志 + 失败动作）
  • 关键模块具备基础回归测试