You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

4.6 KiB

模块开发

新建简单接口

pnpm module:new greeting
pnpm format

命令创建 src/main/modules/greeting.ts,在 src/main/trpc/app-router.ts 接入 router。接口的角色、输入、输出和执行函数在一个位置定义,不额外生成 contracts 路由或 handler 注册。已有模块和同名路由不会覆盖。带连字符的名字转换为驼峰命名空间,例如 my-tool 对应 trpc.myTool.echo。

生成的模块:

import { z } from 'zod'
import { router, procedure } from '../trpc/runtime'

export function createGreetingRouter() {
  return router({
    echo: procedure(['main'])
      .input(z.string().max(1000))
      .output(z.string())
      .query(({ input }) => input)
  })
}

Renderer 调用仍然是 await trpc.greeting.echo.query('Hello')。新增方法只修改模块;新增模块再接入一次应用组合。

职责与依赖

位置 职责
contracts/src/.ts 共享数据模型和 schema,例如 Settings、Note、FileGrant
src/main/modules/ 模块 router 和业务服务,直接调用,不按方法名二次分发
src/main/trpc/runtime.ts context、角色中间件、统一错误处理
src/main/trpc/app-router.ts 明确组合各模块 router
src/main/trpc/events.ts 组合类型化事件流
packages/desktop/rpc 可信窗口、来源校验与请求容量
packages/electron-trpc IPC 消息、订阅传输、取消与 listener 清理

复杂逻辑放在 service/repository 中,router 只负责边界校验和调用。factory 使用 Pick<AppContext, 'storage'> 声明依赖;主进程内部直接调用服务,模块不导入其他模块的注册实现。业务页面按子路径导入共享模型,例如 @template/contracts/settings。只有真正共享的模型需要添加到 contracts,过程专属 schema 就地定义。

每个 query/mutation 都声明 .output(...),每个 procedure 用 procedure(['main', 'settings']) 明确授权角色。可用角色是 main/settings/about。缺失或不匹配的角色默认拒绝,修改授权属于安全变更,需更新权限回归测试。

renderer 只允许类型导入 src/main/trpc/app-router.ts 的 AppRouter,不能导入任何主进程运行时。客户端参数和结果由实际 procedure 推导。

共享外部依赖的固定版本放在 pnpm-workspace.yaml 的 catalog,各使用包显式声明 catalog:;peerDependencies 使用 catalog:peers,本地依赖使用 workspace:*。更新后执行 pnpm install 并提交 lockfile。

事件

共享事件数据模型放在 contracts,在 events.ts 创建 RpcEvent(schema)。procedure 决定订阅角色,stream 负责校验每次载荷、按 owner 投递并复查来源:

changed: procedure(['main']).subscription(({ ctx }) => events.files.subscribe(ctx))
// 主进程服务回调;窗口私有数据必须携带 owner。
events.files.emit(data, owner)

Renderer 使用 trpc.files.changed.subscribe(undefined, { onData, onError }),卸载时 unsubscribe。首次读数据前可等待 onStarted,避免初始化竞态。窗口刷新、关闭或传输销毁会自动退订;事件流自身也在根 Scope 中销毁。

后台行为与资源清理

仅需要提供静态 API 的模块不注册生命周期模块。监听系统主题、定时任务等常驻行为使用 AppModule 并加入 src/main/modules/index.ts 的 lifecycleModules,声明依赖并用 scope.add 清理。它与 API router 组装分开,职责不会重复。带原生资源的 router factory 可以接收 Scope,例如菜单关闭回调。禁止在 import 时初始化数据库、注册 listener 或创建窗口。

不要提供凭据明文 IPC getter;需要凭据的业务请求在主进程执行,只向 renderer 返回允许展示的结果。意外异常统一脱敏;仅明确可公开的服务错误使用 PublicError。

数据库与移除模块

数据库升级在 src/main/migrations/index.ts 追加连续版本;已发布迁移不可修改。业务 repository 属于对应模块,迁移由入口传给通用 SQLite 适配器。

从 app-router.ts 移除对应 router 即撤销 API。完全移除功能时,继续移除 UI、相关事件和后台模块;底层服务不再需要时,从 AppContext 和 bootstrap 删除构造与清理。用 pnpm check 和真实 Electron 测试验证,不以隐藏按钮代替授权撤销。