游戏引擎 / 系统课时
整理目录和模块依赖方向
整理目录和模块依赖方向
文件虽然按目录分开,业务逻辑却反过来导入 UI,修改一个组件仍会牵动全局。本节用领域计算、服务编排和入口三层建立单向依赖,通过完整多文件例程验证导入路径,并说明如何识别循环依赖与过度使用汇总导出。
学习目标
- 根据职责安排模块位置和依赖方向。
- 区分运行时导入与类型专用导入。
- 沿调用链定位反向依赖与循环初始化风险。
目录名要对应真实职责
领域层保存不依赖引擎的规则,服务层组织规则,组件或程序入口处理环境交互。目录可以按功能再划分,但层的依赖应保持明确。移动文件不会自动修复循环依赖;真正要改的是哪个模块引用谁,以及初始化时谁需要谁的运行时值。
下面使用 domain/hit.ts、services/battle.ts 与 main.ts 三个文件。入口依赖服务,服务依赖领域,领域不认识入口。Cocos 项目可以把 main 的职责换成一个组件适配入口,领域和服务仍不应导入 cc 或场景组件。

用完整文件验证关系
以下文件构成完整纯 TypeScript 主例程,保留实际目录。文件:domain/hit.ts。
export function afterHit(hp: number, damage: number): number {
// 最底层只处理输入与输出,没有环境副作用。
return Math.max(0, hp - damage);
}该规则由服务调用。文件:services/battle.ts。
import { afterHit } from '../domain/hit';
export function battle(hp: number, damages: readonly number[]): number {
if (!Number.isFinite(hp) || hp < 0) throw new Error('invalid hp');
let current = hp;
for (const damage of damages) {
// 服务在使用领域规则前检查开放输入。
if (!Number.isFinite(damage) || damage < 0) throw new Error('invalid damage');
current = afterHit(current, damage);
}
return current;
}文件:main.ts,统一 strict 编译所有文件后运行 dist/main.js。
import { battle } from './services/battle';
// 入口只调用服务,不绕过它重复实现伤害流程。
console.log(battle(50, [10, 20]));预期输出:
20查找循环依赖的根因
从报错或异常入口沿 import 方向追踪,若最后又回到原模块,就存在循环。尤其警惕模块顶层立即读取对方导出的实例:双方都期待另一边已初始化时,运行结果可能依赖模块求值顺序。把调用延后有时能避开现象,却不一定消除职责混乱。
共享类型可以提取到独立协议文件,通过 import type 引入;运行时函数与对象则保持明确单向引用。在 Creator 的隔离模块规则下,重导出类型使用 export type。不要用一个巨大 index.ts 汇总所有组件和服务,再让底层模块从它导入,否则容易隐藏反向依赖。
迁移后检查真实入口
修改路径后重新执行项目类型检查,确认所有入口都包含在检查范围。单个文件编译通过不代表未引用的其他组件没有错误。Creator 自身构建不能代替严格类型检查,也不应为方便终端验证覆盖引擎生成的配置。
搬动目录时先保持行为不变,只改文件位置和导入路径,再运行同一个入口对照输出。确认依赖迁移成功后再调整业务实现,能避免路径错误与规则变化同时发生,减少定位时需要猜测的变量。
当前例程的领域函数由可信服务提供参数;若以后公开给更多调用方,校验责任需要重新说明。拆分目录的验收应看一条需求修改能否集中发生、导入关系能否解释,以及纯逻辑能否独立运行。规则依据 TypeScript 模块 与 Cocos 3.8 语言支持。