SuperAPI AI 工具集

setup-ts-deep-modules

编程与开发

查看项目

更新于 11-07 16:46

技能介绍

用途

setup-ts-deep-modules 用于把 TypeScript 仓库中的每个包打造为“深模块”:以尽量小的接口承载尽量多的行为。一个包的公共表面是它的入口点(位于包根目录的文件),其子文件夹中的所有内容对外隐藏。该技能安装 dependency-cruiser 并配置规则,使入口点成为唯一入口,并验证规则确实会拦截违规。

技能中关于“深模块、接口、接缝、深度”等术语,会引用 codebase-design 技能的语言体系。

强制结构

src/packages/
  <name>/
    index.ts        ← 入口点(公开),供外部导入
    client.ts       ← 另一个入口点,包可以暴露多个
    lib/            ← 实现:对外隐藏,内部可互相引用
    tests/          ← 就近测试与 fixture(子文件夹,因此私有)

公共表面是该包根目录下的文件,而不是唯一指定的 index.ts。按约定实现放在 lib/、测试放在 tests/,使每个包具有相同的两文件夹形态。规则本身是通用的:任何子文件夹中的内容都是私有的,因此新增文件夹无需改动配置。

四条规则(均为 error)

  1. 入口点边界:包外代码(应用代码或其他包)只能导入该包的入口点(其根目录文件),不得导入其子文件夹中的任何内容。
  2. 包内自由引用:包自身文件之间可以自由互相导入。
  3. 测试通过入口点:<pkg>/tests/ 下的文件可以导入任何包的入口点以及自身 tests/ 内的 fixture,但不得导入任何包的子文件夹内部(包括自己的)。跨包的集成测试是允许的;深层导入不允许。
  4. 禁止循环依赖:不允许出现依赖循环。

包可暴露多个小入口点(如 index.ts、client.ts、server.ts),而非把所有内容汇聚到一个巨型 index.ts。不建议用于再导出整棵子树的 barrel 文件;保持入口点小、把实现藏在子文件夹中。

分层(哪些包可以依赖哪些包)是另一个关注点,本技能在配置中留作注释占位,由仓库自行填写。

使用步骤

  1. 检测环境:根据锁文件判断包管理器(pnpm-lock.yaml → pnpm,yarn.lock → yarn,bun.lockb → bun,否则 npm);如果存在 src/ 则包根目录为 src/packages,否则为 packages,若仓库已有明显不同的约定需向用户确认;检查是否已有 .dependency-cruiser.* 配置,若存在则不要覆盖,而是合并四条规则与选项并告知用户。
  2. 安装 dependency-cruiser:用检测到的包管理器安装为 devDependency。
  3. 编写配置:把 dependency-cruiser.config.cjs 复制到仓库根目录为 .dependency-cruiser.cjs,将 PACKAGES_ROOT 设为第 1 步检测到的根目录。规则基于路径深度且与扩展名无关,无需其他适配。
  4. 接入检查:添加 lint:boundaries 脚本:depcruise <packages-root>(或 depcruise src);并入仓库已有的总检查命令(运行 typecheck 的那个 check/ci/validate 脚本);不要改动 tsconfig 或添加路径别名。若无总检查脚本,添加 lint:boundaries 并提醒用户将其纳入 CI。
  5. 生成示例包:创建 <packages-root>/example/ 作为可复制模板——index.ts 为入口点,导出一个委托给内部文件的函数(使包明显是深的,而非直通);lib/impl.ts 为子文件夹内部文件,由 index.ts 导入且外部不可达;tests/example.test.ts 只导入 ../index(入口点)并针对公共函数断言。告知用户这是可复制或删除的起始模板。
  6. 验证规则确实生效:这是整个技能的完成标准。先运行 lint:boundaries,必须在干净的示例上通过;临时在 tests/example.test.ts 添加深层导入(如 import { thing } from "../lib/impl"),再次运行必须以 tests-through-entrypoints 失败;还原后再次运行必须通过。若第 2 次不失败,说明规则未正确接入,需修复后再完成。
  7. 记录约定:在包文件夹中写 README.md(<packages-root>/README.md),说明 src/packages/<name>/ 布局(入口点在根目录、lib/ 为实现、tests/ 为测试)、“只通过包入口点(根目录文件)导入”、以及如何运行 lint:boundaries;明确不建议 barrel 文件,改为多个小入口点而非通过一个 index 再导出整棵子树。然后在仓库的代理指令文件(存在 CLAUDE.md 则用之,否则 AGENTS.md,两者都无则创建 AGENTS.md)中添加一行指向该 README 的上下文提示,使代理能发现边界规则。

注意事项

  • 配置中的 $1 反向引用(dependency-cruiser 的分组匹配)让包可访问自身内部而外部不行,不要展开为按包拆分的独立规则。
  • 公开与私有由深度决定:包根目录文件为入口点,任何子文件夹内容为私有。约定子文件夹为 lib/(实现)与 tests/,但规则不硬编码它们:任何子文件夹都是私有的,新增文件夹无需改配置。新增入口点只需新增根目录文件(无需 barrel)。
  • 包是扁平的:根目录下一层直接子项;包的内部可以任意嵌套,但包不能包含另一个包。
  • 使用 .cjs(而非 .js),以便在 "type": "module" 仓库中也能使用 module.exports。

适用场景与限制

适用于采用 TypeScript、按包组织代码并希望通过自动化依赖规则强制“深模块”边界与入口点导入的仓库。技能会修改依赖、配置与检查脚本,建议在现有 CI 流程中运行验证。分层规则与具体依赖方向需仓库自行补充;收费、价格等信息资料未提供。