ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Bruno architecture.md 架构审查员详解:审计 @usebruno/* 单仓库的依赖 DAG 与平台边界

Bruno architecture.md 架构审查员详解:审计 @usebruno/* 单仓库的依赖 DAG 与平台边界 Bruno architecture.md 架构审查员详解审计 usebruno/* 单仓库的依赖 DAG 与平台边界【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno本文以 Bruno 仓库中 架构与依赖边界审查员 的定义文档为主体结合其引用的 架构规则、输出契约 与 编排说明逐条核对各包package.json的真实声明完整还原这位审查员的评审基线、严重度判定标准以及它所守护的usebruno/*依赖 DAG 与四条硬性平台约束。读完后你能够理解 Bruno 单仓库的包分层与依赖方向掌握一次架构审查中 blocker / suggestion / 非问题 的判定逻辑并能用统一输出契约复现同样的评审结论。一、它是什么code-review 技能中的一个镜头Bruno 的本地代码审查以 code-review 技能 为入口把一次 diff 评审拆分为 8 个并行运行的聚焦镜头lens每个镜头是一个自包含的检查清单文件位于reviewers/目录下审查员文件视角文件范围Scopereviewers/correctness.md正确性与根因全部源码除tests/**reviewers/architecture.md架构与依赖边界packages/**reviewers/conventions.md编码规范与可读性全部文件reviewers/react.mdReact — 应用文件packages/bruno-app/**reviewers/cross-platform.md跨平台macOS/Windows/Linux全部文件reviewers/security.md安全与数据安全全部源码除tests/**reviewers/dsl-changes.md磁盘 DSL 与序列化向后兼容bruno-app、bruno-electron、bruno-cli、bruno-lang、bruno-filestore、bruno-schema(-types)、bruno-convertersreviewers/e2e-tests.mdPlaywright E2E 测试tests/**架构审查员只认领packages/**这一范围任何不在packages/下的改动如tests/、scripts/都与它无关。编排方在派发时给每个子代理一份固定简报要求其先读共享契约 reviewers/_contract.md再读对应的reviewers/file.md及其指向的规则文件且只在自己的镜头内、按文件指定的严重度评审。所有审查员共享同一份人设与输出契约定义在 _contract.md人设企业团队中精通 TypeScript、JavaScript、Node.js 与 Electron 的资深审查员每个 finding 用一句话写清只在被追问时展开对文档、指南或注释与仓库实际不一致时以仓库为准从不引用未经源码核实过的行号也不虚构示例值。输出格式扁平列表一行一个 findingblocker|suggestion|nit | file:line | one-sentence finding范围干净时只返回no findings不允许为了凑数而编造 nit。二、评审基线.claude/rules/architecture.md的两个章节架构审查员本身不重复列出规则细节它的指令是对照 .claude/rules/architecture.md 审查 diff——具体读其Dependency direction ownership boundaries章节当 diff 触及某个package.json时还要读Declared dependencies must match real imports章节。该规则文件带有paths: [packages/**/*]前置声明即凡改动落在packages/下它都会被自动附加给协作者/Agent 作为硬约束这与审查员的 scope 完全对齐。规则文件还指出完整的单仓库地图构建工具、请求管线、沙箱、文件格式、核心数据模型类型、依赖版本在按需参考文档 .claude/reference/architecture.md 中——该文件不会被自动加载应在做非平凡的跨包或架构性工作前主动阅读。其中与本文主题直接相关的信息包括bruno-js、bruno-lang、bruno-schema、bruno-toml、bruno-cli、bruno-electron等包没有构建步骤直接从src/被消费而bruno-common、bruno-requests、bruno-filestore、bruno-converters、bruno-query、bruno-graphql-docs、bruno-schema-types这 7 个包会产出dist/编辑后需要重新构建。TypeScript 版本在包之间并不统一例如 bruno-common/package.json 的 devDependencies 声明typescript ^5.8.3而 bruno-converters/package.json 与 bruno-filestore/package.json 均为^4.8.4。三、依赖 DAG叶库、中层消费者与顶层消费者规则的核心断言是各包package.json中声明的内部usebruno/*依赖构成一条严格的 DAG有向无环图。新代码必须尊重它——循环依赖或向上依赖是架构缺陷而不是便利。完整分三层叶库零内部usebruno/*依赖bruno-common、bruno-lang、bruno-query、bruno-requests、bruno-graphql-docs、bruno-schema、bruno-schema-types、bruno-toml。中层消费者bruno-js → (common, query)bruno-converters → (common, schemaschema-types 作为 devDep)bruno-filestore → (common, langschema-types 作为 devDep)顶层消费者依赖只流入、绝不流出bruno-cli → (common, converters, filestore, js, lang, requests)bruno-electron → (common, converters, filestore, js, lang, requests, schema)bruno-app → (common, converters, graphql-docs, schema)本文用当前仓库各包 manifest 逐条核对了这些边结果与规则一致规则断言manifest 证据bruno-common 零内部依赖、零运行时依赖bruno-common/package.json 中dependencies: {}bruno-js → common、querybruno-js/package.json 依赖usebruno/common 0.1.0、usebruno/query 0.1.0bruno-cli → common、converters、filestore、js、lang、requestsbruno-cli/package.json 恰好声明这六个usebruno/*包bruno-converters → common、schemaruntimeschema-types 为 devDepbruno-converters/package.jsondependencies含usebruno/common、usebruno/schemadevDependencies含usebruno/schema-types 0.0.1bruno-filestore → common、langruntimeschema-types 为 devDepbruno-filestore/package.jsondependencies含usebruno/common、usebruno/langdevDependencies含usebruno/schema-typesbruno-electron → common、converters、filestore、js、lang、requests、schemabruno-electron/package.json包名为未加 scope 的bruno全部声明且额外声明了usebruno/sqlite从源码结构看当前 bruno-app/package.json 实际声明的内部包为usebruno/common、usebruno/graphql-docs、usebruno/schema、usebruno/sqlite与规则文本列出的(common, converters, graphql-docs, schema)略有出入规则提到 converters 而未提 sqlite。这正说明实际边清单以各包package.json为准是审查时的正确做法也是 manifest 漂移检查的一部分。四、四条硬性平台约束blocker 级违规规则文件用 5 条 guardrails 把 DAG 落地为可执行约束。审查员文档把其中会被判blocker的违规逐条列举1. bruno-common 是浏览器安全的底层叶库它运行在 web 渲染进程bruno-app中而不只是 Node因此必须保持平台中立禁止任何 Node 内建模块fs、path、os、crypto、child_process、node:*也禁止依赖任何自身会引入 Node 的包。它当前发布零运行时依赖要保持这一状态同时它不依赖任何其他usebruno/*包——一个需要 Node 或其他 bruno 包的工具函数应当放到别的包里。bruno-common/package.json 中dependencies: {}的现状印证了这条约束。审查中bruno-common里出现一条 Node 内建导入或一条其他usebruno/*导入即为 blocker。2. 共享/库包不得反向 import bruno-app 或 bruno-electron渲染进程专属或 Electron 专属代码不得下沉到库包里以求被上层导入——方向永远是叶库被消费、而不是反向引用顶层包。任何向上的新内部依赖或构成环的依赖典型例子某个共享库 import 了usebruno/app或usebruno/electron都是 blocker。3. bruno-js 必须保持无 Electronbruno-js 同时运行在Electron 主进程和 CLI 两个宿主中bruno-cli的 manifest 里声明了usebruno/js 0.12.0证实 CLI 直接消费它。往bruno-js里加electron或 IPC 导入会直接弄坏 CLI因此判 blocker。规则的分工表述是沙箱逻辑属于 bruno-js宿主接线host wiring属于 bruno-electron。这也解释了为什么bruno-js的package.json里连electron都不在依赖中。4. bruno-schema-types 是纯类型包禁止运行时导入bruno-schema-types只含 TypeScript 类型定义用纯tsc构建是 converters 与 filestore 的devDependency两处 manifest 均已验证分别位于 bruno-converters/package.json 与 bruno-filestore/package.json 的devDependencies。可以从中导入类型永远不要往里加运行时代码也不要在运行时 import 它——import ...usebruno/schema-types出现在运行时代码中即 blocker。5. bruno-schemaYup与 bruno-schema-typesTS 类型并存且分工明确两者是不同的包且都活着usebruno/schema用 Yup 做集合/请求的运行时校验被 app 与 converters 使用bruno-app/package.json 与 bruno-converters/package.json 的dependencies均声明usebruno/schema 0.7.0usebruno/schema-types提供编译期类型被 filestore 与 converters 以 devDep 使用。数据模型的一次改动通常同时触及两者——审查时若 diff 只改了其中一侧值得追问另一侧是否遗漏。五、suggestion 级发现分层错位与 manifest 漂移审查员文档还定义了两类suggestion建议级发现代码放错了包/层典型情形渲染进程专属逻辑被写进共享库宿主/Electron 接线被推进bruno-js往bruno-common里加了一个其实需要其他包的工具函数引入了一个本可以留在本地局部的新共享依赖。manifest 漂移manifest drift——对照规则的第二章节判定且以导入方自己的package.json为基准阅读一个包的package.json就是契约workspace 的依赖提升hoisting会掩盖违约——某个 import 之所以能解析仅仅是因为兄弟包或根目录恰好把它拉了进来这就是潜在断点latent break测试/构建专用的包应放devDependenciesdependencies里的东西会连同其传递依赖树一起发布给使用者当一次改动移除了某个声明的最后一个消费者应当顺手删掉这条声明。六、严重度判定表与非问题把审查员文档的完整判定标准汇总为一张可复用的决策表情形严重度新增的内部usebruno/*依赖指向上层包或构成环如共享库 importusebruno/app/usebruno/electronblockerbruno-common导入 Node 内建fs/path/os/crypto/child_process/node:*或导入任何其他usebruno/*包blockerbruno-js导入electron/ IPC它还要在 CLI 中运行blocker对bruno-schema-types的运行时 import它是纯类型包blocker代码放错包/层渲染逻辑进共享库、宿主接线进bruno-js、bruno-common里塞入依赖其他包的 util、本可局部保留的新共享依赖suggestionmanifest 漂移声明与真实 import 不匹配对照导入方自己的package.jsonsuggestionDAG 中已存在的依赖边符合既有方向的新向下依赖非问题Not a finding注意最后一行向下依赖消费更低层级的包只要不破坏 DAG就不会成为发现——审查的目标是保护依赖方向而不是要求最小化依赖。每条 finding 必须给出file:line并按上述契约输出一句话结论。七、编排视角这位审查员如何被调用按 SKILL.md 的流程架构审查员在一次完整评审中的位置是获取 diff默认评审提交区间git diff main...HEAD先git fetch确认基分支最新陈旧基线会放大 diff评审未提交改动时则一次性把git diff HEAD冻结到临时文件让所有审查员看到相同字节。枚举变更文件git diff --name-only若没有任何packages/**改动该镜头整体跳过——这解释了为什么它的 Scope 只写packages/**。并行扇出编排方在单条消息中同时派出所有在范围内的审查员架构审查员拿到的是 diff 来源 packages/**glob 固定简报先读 _contract.md再读 architecture.md 及其指向的 .claude/rules/architecture.md。合并上报收集全部 finding去掉完全重复项两个镜头标记同一file:line时保留更高严重度按文件重新分组每条带blocker / suggestion / nit标签与file:line。八、复现一次架构审查的最小步骤结合本文人工或 Agent 执行一次 Bruno 架构审查可以按如下顺序用git diff --name-only main...HEAD过滤出packages/**下的变更文件无变更则结束。对每个被改动的包读其package.json的dependencies/devDependencies中usebruno/*条目与 .claude/rules/architecture.md 的三层 DAG 对照新边是否向下、是否成环、是否指向 app/electron。若 diff 触及packages/bruno-common/src/**全文检查是否出现fs、path、os、crypto、child_process、node:*等其他包的导入。若触及packages/bruno-js/src/**检查是否出现require(electron)/ IPC 相关导入。若触及运行时文件检查是否存在对usebruno/schema-types的运行时 import类型导入本身合法。若触及任何package.json逐条核对 import 与声明漏声明、dependencies与devDependencies放错位置、失去最后消费者的残留声明均按 suggestion 报告。按blocker|suggestion|nit | file:line | 一句话结论输出无问题则只输出no findings。这套规则文件定基线、审查员文件定判定、契约文件定输出、manifest 定事实的分工使 Bruno 的架构审查在本地与 CISKILL.md提到 CI 侧由同源的自动化评审镜像同一套规则之间保持一致它不依赖评审人的个人口味而是把依赖 DAG 与平台约束固化为可复核、可复现的 checklist。【免费下载链接】brunoOpensource IDE For Exploring and Testing APIs (lightweight alternative to Postman/Insomnia)项目地址: https://gitcode.com/GitHub_Trending/br/bruno创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表