游戏引擎 / 系统课时

整理目录和模块依赖方向

整理目录和模块依赖方向

文件虽然按目录分开,业务逻辑却反过来导入 UI,修改一个组件仍会牵动全局。本节用领域计算、服务编排和入口三层建立单向依赖,通过完整多文件例程验证导入路径,并说明如何识别循环依赖与过度使用汇总导出。

学习目标

  • 根据职责安排模块位置和依赖方向。
  • 区分运行时导入与类型专用导入。
  • 沿调用链定位反向依赖与循环初始化风险。

目录名要对应真实职责

领域层保存不依赖引擎的规则,服务层组织规则,组件或程序入口处理环境交互。目录可以按功能再划分,但层的依赖应保持明确。移动文件不会自动修复循环依赖;真正要改的是哪个模块引用谁,以及初始化时谁需要谁的运行时值。

下面使用 domain/hit.ts、services/battle.ts 与 main.ts 三个文件。入口依赖服务,服务依赖领域,领域不认识入口。Cocos 项目可以把 main 的职责换成一个组件适配入口,领域和服务仍不应导入 cc 或场景组件。

模块依赖方向

用完整文件验证关系

以下文件构成完整纯 TypeScript 主例程,保留实际目录。文件:domain/hit.ts。

ts
export function afterHit(hp: number, damage: number): number {
    // 最底层只处理输入与输出,没有环境副作用。
    return Math.max(0, hp - damage);
}

该规则由服务调用。文件:services/battle.ts。

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。

ts
import { battle } from './services/battle';
// 入口只调用服务,不绕过它重复实现伤害流程。
console.log(battle(50, [10, 20]));

预期输出:

text
20

查找循环依赖的根因

从报错或异常入口沿 import 方向追踪,若最后又回到原模块,就存在循环。尤其警惕模块顶层立即读取对方导出的实例:双方都期待另一边已初始化时,运行结果可能依赖模块求值顺序。把调用延后有时能避开现象,却不一定消除职责混乱。

共享类型可以提取到独立协议文件,通过 import type 引入;运行时函数与对象则保持明确单向引用。在 Creator 的隔离模块规则下,重导出类型使用 export type。不要用一个巨大 index.ts 汇总所有组件和服务,再让底层模块从它导入,否则容易隐藏反向依赖。

迁移后检查真实入口

修改路径后重新执行项目类型检查,确认所有入口都包含在检查范围。单个文件编译通过不代表未引用的其他组件没有错误。Creator 自身构建不能代替严格类型检查,也不应为方便终端验证覆盖引擎生成的配置。

搬动目录时先保持行为不变,只改文件位置和导入路径,再运行同一个入口对照输出。确认依赖迁移成功后再调整业务实现,能避免路径错误与规则变化同时发生,减少定位时需要猜测的变量。

当前例程的领域函数由可信服务提供参数;若以后公开给更多调用方,校验责任需要重新说明。拆分目录的验收应看一条需求修改能否集中发生、导入关系能否解释,以及纯逻辑能否独立运行。规则依据 TypeScript 模块 与 Cocos 3.8 语言支持。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

整理目录和模块依赖方向

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通