7.2 KiB
架构与取舍
单向依赖
flowchart TD
Main[src/main 组合与模块] --> Desktop[packages/desktop 适配器]
Main --> Core[packages/core]
Main --> Contracts[packages/contracts 共享模型]
Desktop --> Core
Desktop --> Contracts
Desktop --> Transport[packages/electron-trpc]
Preload[src/preload] --> Transport
Renderer[src/renderer] --> Contracts
Renderer --> Transport
Renderer --> UI[packages/ui]
Renderer --> Preload
Renderer → Preload 表示调用桥接 API,而不是导入 preload 源码。基础包从不导入 src/main。desktop 中的行为通过构造参数和接口注入,应用入口负责组装。
为什么没有直接复制所有 workspace 包
旧项目的部分分包仍引用应用文件工具和路由。机械复制会保留反向依赖、单例初始化副作用与失效模块。新模板分离纯工具、浏览器契约、tRPC 路由、IPC 传输、桌面适配器和 UI,在 src/main/modules 中按能力分组。业务增多后再根据稳定边界拆包。
IPC
每个 API 只在主进程所属业务模块中定义一次:procedure 的允许角色、输入 schema、输出 schema、query/mutation/subscription 类型以及服务调用放在一起。复杂业务逻辑由注入的 service/repository 执行。
contracts/src/settings.ts、files.ts、notes.ts 等只提供共享数据模型;它们不维护路由名称、方法清单或授权策略。过程专属输入 schema 就地定义,跨层使用的模型才进入 contracts。src/main/trpc/runtime.ts 提供统一 context 类型、角色中间件和错误脱敏,app-router.ts 组合模块 router。移除一个 router 即撤销对应 API,不再需要同步删除 handler 注册表。
renderer 只对主进程的 AppRouter 做类型导入,通过单一客户端调用;ESLint 禁止导入服务器运行时代码。输入输出类型由实际 procedure 推导,query/mutation 使用 .output(...) 在跨进程前校验返回值。订阅使用独立 RpcEvent<T>,每次 emit 校验载荷,私有事件指定 owner,发送前复查来源。
preload 只暴露固定 electron-trpc 通道的 sendMessage/onMessage。RpcGateway 只管理可信窗口、精确主 frame 来源、频率和并发限额,不包含业务方法和分发清单。procedure 的角色元数据决定可调用窗口,公共 middleware 默认拒绝未授权调用;业务 resolver 直接调用服务。
flowchart LR
Client[renderer tRPC client] --> Bridge[preload 固定桥接]
Bridge --> Transport[electron-trpc 传输]
Transport --> Gateway[RpcGateway 来源与限流]
Gateway --> Procedure[模块 procedure 权限与输入输出]
Procedure --> Service[业务服务或 repository]
electron-trpc 使用仓库内独立适配包,沿用原项目的分进程入口方式,适配固定的 tRPC 11 版本。来源校验、schema、角色权限、限流、错误脱敏与订阅清理由不同层承担;取消和响应发送时同样验证来源。普通请求支持超时和 AbortSignal,取消只终止响应投递并通知 procedure signal,不回滚业务,也不会提前释放仍在执行的业务并发容量。每窗口最多 8 个处理中请求、32 个订阅。导航和关闭按 owner 撤销订阅,退出移除全局 IPC listener。适配器目前只支持 JSON 兼容数据,不配置 SuperJSON 等自定义 transformer。主进程内部服务仍直接调用,不经过 IPC。
生命周期
startModules 先验证依赖图,再排序初始化。每个模块收到自己的 Scope,通过 scope.add 注册清理。模块初始化失败时连同部分已初始化的资源一起回滚。退出时反向销毁,单个清理错误不会阻断其他资源。
基础服务由入口组装,业务路由由模块 factory 创建并在 app-router.ts 组合。可选的文件、存储、凭证和更新能力由 app.config.json 决定是否构造,清理随构造一起登记。类型结构保持稳定,禁用能力显式返回 DISABLED;renderer 从实际服务生成的 capabilities 决定展示。启动参数只能进一步关闭能力,见 capabilities.md。移除 router 仍可永久移除 API;若永久删除底层实现,还需要删除相应依赖和源码。模板避免通用 service locator,让依赖可以通过类型和构造参数直接查到。
router factory 使用 Pick<AppContext, ...> 声明所需服务,编译期只能访问声明的服务;这不构成进程内安全沙箱。需要常驻监听、定时任务的模块通过 AppModule<...> 和 lifecycleModules 初始化,与静态 API 组合分开。菜单等资源的 router factory 接收 Scope 注册清理,不在 import 时产生副作用。
数据
配置与少量 JSON 使用同步原子写入,避免竞态与复杂写入队列。它们有大小限制,不适合大量数据。SQLite 使用 WAL、参数化语句和单次事务升级。生产中追加迁移,不能修改已发布的迁移。主进程数据库和窗口状态不直接暴露为任意 CRUD。
应用配置的版本迁移由 src/main/settings/store.ts 持有,独立于通用 JsonStore。读取时保留合法用户值、递归补齐对象字段、只恢复异常字段;写入仍严格校验。迁移前保留原文件备份,失败或检测到配置降级时不写盘。版本元信息只留在磁盘,renderer 继续使用 Settings 模型。操作约定见 settings.md。
Renderer
Vue Router 使用懒加载与 hash routing。app.info 返回主进程确认的 role,路由守卫限制次级窗口;最终 IPC 授权仍由主进程执行。app 层协调初始化、外观与布局,pages 组合功能,features 按功能拥有状态、操作、订阅和清理。Pinia 只管理跨页面共享的配置与应用信息;配置 store 不操作 DOM。useTask 按功能管理反馈,功能异步提交检查作用域和代次。UI 包只负责展示。配置和更新共享 useSnapshotStream:先建立订阅再读取快照,重连前清理旧会话,代次与事件版本阻止旧结果提交。重连由用户明确触发,不重试 mutation。详细开发规则见 renderer.md。
标题栏参考 Zephyr 的 NavBar:WindowService 使用 titleBarStyle: hidden,Windows/Linux 开启原生按钮覆盖层,macOS 保留交通灯按钮。UiTitleBar 只负责展示、拖动区域和插槽,交互区域标记为 no-drag,通过系统提供的标题栏安全区域避让窗口按钮。原生按钮覆盖层及内部内容区高度固定为 36px,自定义标题栏为 37px,多出的 1px 通过独立伪元素绘制底部分隔带,避免非整数缩放下 CSS 边框取整影响按钮居中。应用容器固定为窗口高度,标题栏不收缩,下方侧栏与内容区独立滚动,滚动条从标题栏底部开始。调整高度时保持这一差值。主进程监听 nativeTheme.updated 同步按钮颜色,并在服务销毁时解除监听。
基础与业务
笔记是展示 SQLite 的业务示例,不是框架必须支持的数据模型。JSON 草稿、文件编辑器和凭据页面同样是能力演示。AI、Monaco、托盘、全局快捷键、远程内容可以作为额外模块加入;这些能力应声明权限、生命周期和平台支持,不在基础模板中隐式开启。