Bruno 单体仓库依赖边界：严格的 @usebruno 依赖 DAG 与五条包所有权守护规则

Bruno 单体仓库依赖边界严格的 usebruno 依赖 DAG 与五条包所有权守护规则【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/brunoBruno 是一个以 npm workspaces 组织的 monorepo其内部包usebruno/*之间的依赖方向被.claude/rules/architecture.md明确规定为一个严格有向无环图DAG。本文完整继承该规则文档的核心内容——三级依赖分层、五条守护护栏、声明依赖与真实导入一致性要求——并结合当前仓库中各包package.json的实际声明逐条佐证帮助你在为 Bruno 新增代码或做跨包改动前准确判断「这个 import 该放哪个包、这个依赖该不该声明」避免引入循环依赖或向上依赖这类架构级缺陷。一、核心规则内部依赖必须是严格 DAG规则文档的开篇即给出总纲内部usebruno/*依赖即每个包package.json中的声明构成一个严格 DAG新代码必须遵守它——循环依赖或向上依赖是架构 bug而不是图省事的便利。文档同时指明了一份按需查阅的参考文档整个 monorepo 的完整地图构建工具、请求管线、沙箱、文件格式、核心数据模型类型、依赖版本位于 .claude/reference/architecture.md并要求在进行任何非平凡的跨包或架构性工作之前先阅读它。也就是说.claude/rules/architecture.md定义的是「不可破坏的不变量」invariants而 reference 文档提供的是「地图」——两者配合使用规则文档常驻生效参考文档在跨包工作时按需展开。当前仓库共有 16 个 workspace 包见根目录 package.json 的workspaces字段packages/bruno-app、bruno-electron、bruno-cli、bruno-common、bruno-converters、bruno-schema、bruno-schema-types、bruno-query、bruno-js、bruno-lang、bruno-tests、bruno-toml、bruno-graphql-docs、bruno-requests、bruno-filestore、bruno-sqlite。理解依赖方向正是从这个清单出发。二、依赖方向与所有权边界三级分层规则文档将全部内部包按依赖位置划分为三层。以下完整继承原文档的划分并在后文用各包package.json的实际声明逐层验证1. 叶子库Leaf libs——零内部依赖bruno-common、bruno-lang、bruno-query、bruno-requests、bruno-graphql-docs、bruno-schema、bruno-schema-types、bruno-toml被列为零内部usebruno/*依赖的叶子库。从源码结构看packages/bruno-common/package.json 的dependencies字段就是一个空对象{}是这一层级的最严格实例。需要指出一个与当前代码的细微出入packages/bruno-requests/package.json 的dependencies中实际声明了usebruno/common: 0.1.0即 bruno-requests 目前指向基础叶子。可以推断规则文档中「零内部依赖」的枚举对 bruno-requests 的描述偏保守实际它是仅依赖bruno-common的准叶子——方向依然向下不破坏 DAG但新代码不应在这条边之外再增加任何内部依赖。2. 中间消费者Mid consumersbruno-js→ (bruno-common,bruno-query)bruno-converters→ (bruno-common,bruno-schemabruno-schema-types作为 devDependency)bruno-filestore→ (bruno-common,bruno-langbruno-schema-types作为 devDependency)与当前package.json逐一比对包规则文档声明的内部依赖当前 package.json 实际声明bruno-jscommon、queryusebruno/common: 0.1.0、usebruno/query: 0.1.0bruno-converterscommon、schema运行时schema-typesdevdependenciesusebruno/common: ^0.1.0、usebruno/schema: ^0.7.0devDependenciesusebruno/schema-types: 0.0.1bruno-filestorecommon、lang运行时schema-typesdevdependenciesusebruno/common: 0.1.0、usebruno/lang: 0.12.0devDependenciesusebruno/schema-types: 0.0.1三者的运行时/编译期划分与规则文档完全一致bruno-schema-types只出现在devDependencies中这正呼应了后文守护规则第 4 条「types-only」。3. 顶层消费者Top consumers——依赖只进不出「things flowintothem, never out」bruno-cli→ (bruno-common,bruno-converters,bruno-filestore,bruno-js,bruno-lang,bruno-requests)bruno-electron→ (bruno-common,bruno-converters,bruno-filestore,bruno-js,bruno-lang,bruno-requests,bruno-schema)bruno-app→ (bruno-common,bruno-converters,bruno-graphql-docs,bruno-schema)实际package.json验证结果包当前实际声明的内部运行时依赖bruno-clicommon、converters、filestore、js、lang、requests —— 与文档完全一致bruno-electroncommon、converters、filestore、js、lang、requests、schema另加usebruno/sqlite: 0.1.0bruno-appcommon、graphql-docs、schema另加usebruno/sqlite: 0.1.0两个值得注意的补充事实其一bruno-electron的包名不带作用域name: bruno它是唯一以非usebruno/*命名对外分发的包因此「依赖只进不出」对它的约束更为关键其二当前 workspace 已新增packages/bruno-sqlite并被bruno-app与bruno-electron以usebruno/sqlite 0.1.0声明规则文档的顶层枚举尚未覆盖这一新增包——它的依赖方向同样是「流入顶层消费者」符合 DAG但做架构判断时应把它一并纳入心智模型。三、五条守护护栏Guardrails规则文档列出了 DAG 所强制的五条具体护栏下面逐条完整说明并给出仓库证据。护栏 1bruno-common 是「浏览器安全」的基础叶子它运行在 Web 渲染进程bruno-app中而不仅是 Node 环境因此必须保持平台中立禁止使用 Node 内建模块fs、path、os、crypto、child_process、node:*禁止依赖任何自身会拉入 Node 的第三方包当前保持零运行时依赖——packages/bruno-common/package.json中dependencies: {}印证了这一点文档要求「保持这个状态」不依赖任何其他usebruno/*包。需要 Node 能力或需要其他 bruno 包的工具函数必须放到别的包里。护栏 2共享库/库包禁止 import bruno-app 或 bruno-electron渲染进程专属或 Electron 专属的代码不允许为了「让上层可导入」而下推push down到某个库中。任何在packages/bruno-common、bruno-js等库包里出现require(electron)或从bruno-app源码导入的行为都是对所有权边界的违反。护栏 3bruno-js 必须保持 Electron-freebruno-js同时在两个宿主中运行Electron 主进程bruno-electron → js与命令行bruno-cli → js见 bruno-cli/package.json 中的usebruno/js: 0.12.0。一旦在 bruno-js 中加入electron/IPC 导入CLI 路径即被破坏。规则文档给出的分工是沙箱逻辑sandbox logic属于 bruno-js宿主接线host wiring属于 bruno-electron。bruno-js 的 package.json 中确实没有任何 electron 相关依赖其main直接指向src/index.js无构建产物从源码直接消费。护栏 4bruno-schema-types 是 types-only 包它是 converters/filestore 的devDependency用纯tsc构建packages/bruno-schema-types/package.json 的build: tsc -p tsconfig.jsondevDependencies中仅有typescript无 rollup 等运行时构建工具。规则要求只从它导入类型永远不要往里面加运行时代码也不要出现对它的运行时 import。这与第二层级中bruno-converters、bruno-filestore把它放在devDependencies的声明方式互为印证。护栏 5bruno-schemaYup与 bruno-schema-typesTS 类型是两个独立且都存活的包bruno-app与bruno-converters使用usebruno/schema做运行时校验两者dependencies中均有usebruno/schema: ^0.7.0/0.7.0bruno-filestore与bruno-converters使用usebruno/schema-types做编译期类型两者devDependencies中均有usebruno/schema-types: 0.0.1数据模型的任何改动通常同时触及两者——这是跨包改动时最容易漏掉的一条。四、声明的依赖必须匹配真实的导入规则文档最后一节强调package.json就是契约而 workspace 的依赖提升hoisting会掩盖对契约的违背。具体执行要点有三每个 import 都必须在导入方自己的 manifest 里声明。某个模块仅因为兄弟包或根目录恰好拉了它才解析成功属于「潜伏的断裂」——一旦工作区结构变化就会炸掉。测试与构建专用包必须放进devDependencies。dependencies里的东西会连同其传递依赖树一起发布给用户各叶子库prepack脚本如npm run test npm run build配合files字段dist、src、package.json决定了最终发布内容dependencies的膨胀会直接放大用户安装的体积。当某次改动移除了某个声明的最后一个消费者时要同步删掉这条声明保持声明与实际导入严格同步。与契约配套的还有一层根级版本钉死。当前根 package.json 的overrides字段硬钉了axios: 1.18.0、rollup: 3.30.0等关键版本还有tar、pbkdf2、electron-store/conf等。这意味着在某个叶子包里单独升级 axios 或 rollup 是无效的——真正生效的是根级 override升级必须改根package.json。各叶子包package.json中的overrides: { rollup: 3.30.0 }如 bruno-common、bruno-requests、bruno-filestore也保持了与根级一致。五、实践自检清单新增代码前如何验证合规综合规则文档与各包package.json的证据跨包改动前可以按以下清单自检依赖方向新 import 是否指向 DAG 的下方叶子 → 中间消费者 → 顶层消费者若bruno-app/bruno-electron/bruno-cli之外的包需要引用它们即为向上依赖属于架构 bug。平台约束改动落在bruno-common中时是否引入了 Node 内建模块或会拉入 Node 的依赖落在bruno-js中时是否引入了electron或 IPC 调用schema 双改涉及集合/请求数据模型时是否同时检查了usebruno/schema运行时 Yup 校验与usebruno/schema-types编译期 TS 类型manifest 一致性新增的 import 是否写入了导入方自己的dependencies/devDependencies测试/构建专用依赖是否误入dependencies被移除的最后一个 import 是否连带删除了声明版本升级要升 axios/rollup 时改的是否是根 package.json 的overrides而不是叶子包里的版本号架构级工作前置非平凡的跨包改动是否已先通读 .claude/reference/architecture.md 获取完整 monorepo 地图构建工具分布、请求管线、沙箱模式、文件格式、关键依赖主版本小结.claude/rules/architecture.md用不到 50 行定义了一套可执行的架构不变量以严格 DAG 约束usebruno/*内部依赖方向以五条护栏锁定关键包bruno-common浏览器安全、bruno-js双宿主运行、bruno-schema-types纯类型的所有权边界再以「声明必须匹配真实导入」堵住 workspace hoisting 带来的隐性违约。本文所有佐证均来自当前仓库的实际package.json声明若未来仓库演进例如bruno-requests收敛掉对bruno-common的运行时依赖或bruno-sqlite被补入规则文档的枚举应以仓库实际内容为准重新核对本文表格。【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考