Tolaria 的领域命令构建器模式把 224 行命令注册 Hook 拆分为可测试的领域模块【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本文基于 Tolaria 的架构决策记录 ADR-0029docs/adr/0029-domain-command-builder-pattern.md讲解该桌面 Markdown 知识库应用如何将命令面板Command Palette的命令定义从单体 Hook 中拆分为领域命令构建器 薄组装器的结构。读完你可以掌握CommandAction契约的设计、build*Commands(config)工厂函数的职责边界、组装器中useMemo分层缓存的实现方式以及这套模式与测试、Rust 侧模块划分的联动关系。背景问题224 行的脑方法ADR 的 Context 部分给出了明确的量化背景重构前useCommandRegistry是一个 224 行的脑方法brain method——它把命令面板的所有命令定义内联在一起涵盖导航、笔记操作、Git 操作、视图切换、设置、类型管理和过滤控制六大类。该文件是 CodeScene 标记的热区hotspot在 CodeScene 复杂度量表上得分 39而热区目标是 ≤9.5。这种单体结构导致每新增一个命令都必须触碰中央文件冲突面和评审成本随命令数量线性增长。问题本质不是代码写得不好而是单一模块承担了过多领域的命令形状知识导航命令关心侧边栏选中状态Git 命令关心修改文件数量视图命令关心缩放级别——这些状态互相无关却被硬编码在同一个 Hook 体内。核心决策build*Commands(config) 工厂 薄组装器ADR 的 Decision 部分规定将命令定义拆分为src/hooks/commands/下的聚焦领域模块每个模块导出一个build*Commands(config)工厂函数useCommandRegistry退化为一个薄组装器thin assembler负责调用各构建器并合并结果。共享类型放在commands/types.ts公开 API 从commands/index.ts统一再导出。这一结构在当前仓库中可以直接对照验证src/hooks/commands/ 目录包含文件职责types.tsCommandAction/CommandGroup契约与分组排序navigationCommands.ts搜索、跳转侧边栏分区、文件夹操作noteCommands.ts新建/保存/删除/归档笔记等gitCommands.ts提交推送、拉取、冲突处理viewCommands.ts布局、缩放、检查器开关settingsCommands.tsVault 管理、主题、语言typeCommands.ts按 Vault 内类型动态生成的命令filterCommands.ts笔记列表过滤条件aiAgentCommands.tsAI Agent 相关命令后续演进新增localizeCommands.ts组装后标签本地化后处理后续演进新增index.ts公开 API 再导出ADR 中列出的七个领域模块navigation/note/git/view/settings/type/filter全部落地且目录随后自然扩展到 AI 命令与本地化后处理恰好印证了决策中新增命令只改对应领域模块的预期路径。命令契约CommandAction所有领域模块共享同一份命令契约定义在 src/hooks/commands/types.tsexport type CommandGroup Navigation | Note | Git | View | Settings export interface CommandAction { id: string label: string group: CommandGroup shortcut?: string keywords?: string[] enabled: boolean execute: () void }各字段的工程含义id稳定标识符是命令快捷键路由、测试断言如findCommand(commands, commit-push)和本地化查表的主键group决定命令面板中的分组展示顺序groupSortKey按Navigation → Note → Git → View → Settings的固定顺序返回索引keywords供模糊搜索命中的同义词集合例如commit-push携带[git, save, sync]用户输入 sync 也能找到它enabled声明式的能力门控命令始终存在、但按状态启用/禁用而不是从列表中删除execute无参闭包把回调捕获进命令对象与 React 组件解耦。这个契约是构建器模式成立的前提只要输出统一为CommandAction[]组装器就不需要关心任何领域细节。一个真实的领域模块gitCommands以 src/hooks/commands/gitCommands.ts 为例模块内部定义了自己的GitCommandsConfig接口modifiedCount、isGitVault、repositories及各on*回调把配置面收敛到该领域真正需要的字段。模块对外只导出一个入口函数内部按 Vault 的 Git 状态做三段式分支export function buildGitCommands(config: GitCommandsConfig): CommandAction[] { if (config.gitFeaturesEnabled false) return [] if (config.isGitVault false) return buildInitializeGitCommand(config) return buildGitVaultCommands(config) }用户关闭 Git 功能feature flag时返回空数组——命令面板中 Git 组整体消失Vault 尚未初始化 Git 时只生成一条initialize-git命令正常 Git Vault 则生成commit-push、generate-commit-message、add-remote、git-pull、resolve-conflicts、view-changes等命令。值得注意的enabled门控写法{ id: commit-push, label: Commit Push, group: Git, keywords: [git, save, sync], enabled: modifiedCount 0, execute: onCommitPush },是否有待提交修改这一状态的判断逻辑完全位于 Git 领域模块内部而不是散落在组装器里——这正是 ADR Consequences 所说的每个领域模块只接收它需要的配置显式的、类型化的接口无 Hook 依赖。Navigation 模块 还展示了领域模块内部的二次拆分手法buildBaseCommands固定导航项、buildFolderCommands文件夹选中态操作含canRunFolderCommand这样的局部门控函数、insertInboxCommand按showInbox条件插入 Inbox 跳转最终由导出的buildNavigationCommands组合。领域模块对外仍只有一个工厂函数内部分层只服务于自身可读性。组装器实现useCommandRegistry 如何变薄重构后的 src/hooks/useCommandRegistry.ts 结构清晰分为三段配置面CommandRegistryConfig接口第 30-142 行集中声明组装器接收的全部 props包括回调、状态量与 feature flaggitFeaturesEnabled、aiFeaturesEnabled等领域构建Hook 函数体第 153-330 行里每个领域命令各自包在独立的useMemo中且依赖数组精确到该领域实际消费的字段例如const gitCommands useMemo(() buildGitCommands({ modifiedCount, gitFeaturesEnabled, isGitVault, repositories: gitRepositories, canAddRemote: config.canAddRemote ?? false, onAddRemote: config.onAddRemote, onCommitPush, onGenerateCommitMessage, onInitializeGit, onPull, onPullRepository, onResolveConflicts, onSelect, }), [ modifiedCount, gitFeaturesEnabled, isGitVault, gitRepositories, config.canAddRemote, config.onAddRemote, onCommitPush, onGenerateCommitMessage, onInitializeGit, onPull, onPullRepository, onResolveConflicts, onSelect, ])这种按领域分片的useMemo使状态变化被局部化修改数量变化只重算gitCommands不会波及其它分组 3.合并与后处理最终通过一次useMemo按Navigation → Note → Git → View → Settings → AI → 类型 → 过滤的顺序展开合并第 315-327 行再经 localizeCommandActions 按当前语言环境本地化标签后返回。组装器保留的唯一逻辑是少量跨领域的派生值如hasActiveNote、activeEntry、vaultTypes、folderCreateOptions因为它们服务于多个领域模块放在组装层比在各模块重复推导更合理。文件顶部还保留了向后兼容的再导出CommandAction、groupSortKey、extractVaultTypes等使既有导入路径继续可用。三个备选方案的取舍ADR 完整记录了三个被评估的方案这是该决策最有参考价值的部分Option A采纳领域构建器模块。每个模块拥有自己的命令形状并接收类型化配置useCommandRegistry是纯组装。ADR 记录其 CodeScene 得分为 9.58–10.0新文件全部达标代价是文件数量增多、导航路径变深Option B按文件拆分但保留一个大 Hook 调用子 Hook。子 Hook 仍需向下传递共享状态耦合方式与现状相同没有真正的复杂度收益Option C全局命令注册表命令者命令式注册。调用方完全解耦但可追踪性差、注册点失去 TypeScript 类型推断且对当前规模属于过度设计。A 与 B 的分水岭在于B 只解决了文件多没解决状态如何流动A 让每个领域模块以纯函数 显式配置对象的形式工作天然无 Hook 依赖因此可脱离 React 直接测试。可测试性收益领域模块独立测试拆分带来的直接红利是测试的领域化。仓库中同时存在组装器级测试 src/hooks/useCommandRegistry.test.ts通过renderHook注入vi.fn()回调断言命令的存在性、分组、enabled状态与回调透传。例如它断言commit-push在modifiedCount: 5时启用、在modifiedCount: 0时禁用resolve-conflicts位于Git组且携带conflict/merge关键字非 Git Vault 下出现initialize-git命令领域模块级测试如 gitCommands.test.ts、settingsCommands.test.ts、aiAgentCommands.test.ts直接以纯配置对象调用build*Commands并断言输出不需要任何 React 渲染环境。这与 Option C 的否决理由形成呼应由于配置对象是显式类型化的测试和类型系统都在注册点即工厂调用处保有完整推断可追踪性没有损失。与 Rust 侧的一致性ADR-0030 的同构决策ADR Consequences 明确指出该模式与 Rust commands/ 模块拆分ADR-0030 保持一致。ADR-0030 面对的是后端同构问题src-tauri/src/commands.rs增长到 937 行后被拆分为按领域组织的commands/模块vault.rs、git.rs、github.rs、ai.rs、system.rsmod.rs仅做再导出与共享工具。ADR-0030 的 Option A 描述中直接引用了mirrors the TypeScripthooks/commands/pattern (ADR-0029)。两条 ADR 同日2026-03-30落定说明这不是单点重构而是同一套代码健康策略在 Tauri 前后端的落地前端命令面板命令与后端 Tauri IPC 命令各自按领域切分mod.rs/commands/index.ts均扮演薄再导出层的角色新增命令时放入对应领域文件若无合适领域则新建文件而非塞进中央文件。演进观察与再评估触发条件ADR 为这个模式定义了明确的再评估触发条件当命令数量增长到组装器本身成为复杂度热区时需要重新评估。从当前源码结构看组装器已承载CommandRegistryConfig约百余字段的配置面和八个领域构建器调用且后续新增的 AI Agent 命令aiAgentCommands.ts、编辑器查找命令editorFindCommands.ts与本地化层localizeCommands.ts都是按新领域进新模块的路径演进的——组装器仍在增长但增长被限制在声明配置 转发层面。ADR-0030 则给出了后端侧的对应阈值参考单个领域文件超过约 300 行成为热区时再次拆分。这套模式的适用前提值得注意它建立在命令集合由应用自身静态知晓的基础上——Tolaria 的命令全部来自 UI 层execute只是调用回调解耦出的既有能力。若命令来源变为插件式外部注册才会真正需要考虑 Option C 的注册表形态。小结Tolaria 用 ADR-0029 演示了一个在 React 命令面板类 UI 中相当通用的解耦手法用统一的CommandAction契约把命令是什么与命令从哪来分离每个领域模块以纯工厂函数build*Commands(config)输出命令显式类型化配置无 Hook 依赖可脱离 React 单测组装器只做配置声明、按领域useMemo分片构建、顺序合并与本地化后处理与 Rust 侧commands/领域拆分ADR-0030保持前后端一致的代码组织并以量化指标CodeScene 热区 ≤9.5与明确的再评估触发条件闭环。新增一个命令的正确姿势因此变为判断它属于哪个领域 → 打开对应的build*Commands模块 → 添加一条CommandAction必要时扩展该模块的 config 接口→ 补上模块级测试。组装器、命令面板组件CommandPalette.tsx与其他领域模块均不需要改动。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考