SuperAPI AI 工具集

setup-domain-boundaries

编程与开发

查看项目

更新于 11-04 02:23

技能介绍

用途

本技能为按域名(domain)或分层(layer)组织的项目安装一条跨域导入边界规则:一个模块只能通过另一个模块的公开入口文件(port)访问它,不能直接导入其内部路径。该做法适用于任何被拆分为命名域或分层的项目,各层的本地名称可以自定。资料中的 Argo 实例(.dependency-cruiser.json 与 ADR-0044)仅作为示例参考,应复制其做法结构而非逐字照搬,各层命名需自行确定。

主要步骤与能力

  1. 命名分层映射:为当前仓库写明层根目录(每个域所在目录,Argo 为 apps/desktop/src/domains/<domain>/)、域内各层以及哪一层是 port(允许其他域导入的唯一文件或目录;Argo 为 contract、main、preload、renderer,各域以 port.ts 作为 port)。即使项目没有内部分层,也需确定唯一的入口点(如 index.ts、barrel 或域的顶层文件)作为 port。还需列出豁免层,即不应被本域外部访问的层,通常除 port 外的所有层都属于此类。该映射即全部泛化基础,后续规则只按此映射读取,不依赖任何具体域名。

  2. 确认唯一前提:已禁止相对导入:规则匹配的是导入字符串而非解析后的文件,因此只有当所有跨目录导入都已通过统一别名(Argo 为 @/domains/<domain>/...)进行时才成立,因为相对导入(如 ../../other-domain/main/store)会以规则看不到的字符串到达同一文件。需先确认仓库已禁止 ../ 和嵌套 ./ 导入(Argo 使用 Biome 的 noRestrictedImports 组 ["../*", "./*/*"]),否则应先添加该禁令;后续若放宽该禁令,会使边界规则在无提示的情况下失效,这一依赖关系应记录在规则旁边。

  3. 选定一种路径别名约定:一个别名根映射到第 1 步的层根目录(Argo 通过 tsconfig.json 的 paths 与打包器对应别名,将 @/domains/<domain> 映射到 apps/desktop/src/domains/<domain>);没有它,规则就没有可匹配的规范字符串。

  4. 用反向引用编写 port-only 规则:以一条带捕获组的规则统一表述,而非为每个域名手写一个覆盖块。示例结构(保持原样):

{
  "forbidden": [
    {
      "name": "domain-port-only",
      "severity": "error",
      "comment": "A domain reaches another domain's internal layers only through its port file.",
      "from": { "path": "^<layer-root>/([^/]+)/" },
      "to": {
        "path": "^<layer-root>/[^/]+/(<internal-layers>)/",
        "pathNot": ["^<layer-root>/$1/", "/<port-file>$"]
      }
    }
  ]
}

其中 $1 为 from 捕获的域名,pathNot 重新允许回到同一域的导入以及对任意域 port 文件的导入,其余匹配 to.path 的导入均被拒绝。一条规则即可覆盖层根目录下现在及将来新增的所有域名,新域名无需新增块。

  1. 为何选用 dependency-cruiser 而非仓库现有 linter:若项目 linter 有受限导入规则可先尝试;Argo 使用 Biome 的 noRestrictedImports 但在此规则上放弃,原因可推广到任何按字面导入字符串而非解析路径匹配的 linter:Biome 的 overrides 数组不会跨匹配同一文件的块合并单个规则配置,只有最后匹配的块整体生效,按域名逐一覆盖的写法会与任何涉及相同路径的覆盖冲突,配置取决于块顺序而非作为一条规则可读;Biome 没有正则反向引用原语,无法用一条规则表达“只通过 X/port.ts 访问域 X”,其 no-restricted-imports 只能禁止固定 glob 列表;biomejs/biome discussion #6245 是尚未实现的 Nx 式模块边界请求,#5595(已关闭)中维护者确认 noRestrictedImports 是当前唯一替代方案,即本方案避免的每块固定 glob 形式。dependency-cruiser 的 from/to 加捕获组可用一条规则两行完成同一目标。需接受其代价:规则匹配导入字符串而非编译器解析结果;在第 2 步相对导入禁令存在时二者对当前可写的导入一致,但未来的别名重映射或再导出链可能使二者不一致,这是为单一引擎和单一规则有意牺牲解析保真度。

  2. 接入已有的质量校验流程:将 dependency-cruiser 运行作为独立脚本(Argo 为 quality:boundaries)加入聚合质量命令,而非并入 linter 步骤,使边界违例显示为自身失败而非另一规则名的 lint 失败。

  3. 验证规则生效后移除证明:添加一个导入另一域内部层(非其 port)的导入,确认校验流程拒绝,然后移除;再添加对该域 port 文件的导入并确认通过。验证须针对当前仓库刚写好的规则进行,在其他项目或旧版配置上的验证不适用。

适用场景与限制

适用于按域或分层组织、需要强约束跨域访问入口的项目。未覆盖的事项:组合根(合法地将多个域连接起来的入口点)需要单独豁免,以独立的 pathNot 条目或单独规则明确说明,它不属于第 1 步的分层映射,也不会自动继承豁免;导入循环不在本规则范围内,本规则只判断方向性(谁可访问谁),不判断循环(访问是否回环),循环检查是另一条独立规则。