用途:在 Rayfin VS Code 扩展(packages/tools/vscode)里,让扩展宿主作为 tRPC 服务端,React webview 作为客户端,通过 postMessage 进行类型安全的 RPC 通信。
主要能力:客户端用 useTrpcClient() 钩子创建 tRPC 客户端,经自定义 vscodeLink 以 send/onReceive 桥接 postMessage;服务端 WebviewController 通过 setupTrpc()、callerFactory(appRouter) 派发查询、变更、订阅和 abort。每个 webview 维护自己的路由,再统一挂到 appRouter 的 commonRouter 下。
创建流程:一,用 BaseRouterContext 扩展出视图专属 RouterContext;二,用 router() 和 publicProcedureWithTelemetry 定义过程,输入用 zod 校验;三,在 appRouter.ts 注册;四,实现继承 WebviewController 的控制器并调用 setupTrpc(trpcContext);五,在 WebviewRegistry 注册 React 组件,键名须与控制器构造参数 webviewName 一致。
遥测与取消:publicProcedureWithTelemetry 经 trpcToTelemetry 中间件保证 ctx.telemetry 可用,自动生成 rayfin.rpc.{type}.{path} 事件并记录错误、耗时与取消状态;publicProcedure 无 telemetry,仅适合无外部调用的场景。每个操作有独立 AbortController,客户端 abort() 或 unsubscribe() 会发送 abort 或 subscription.stop,服务端 ctx.signal 相应置为已中止;长循环中应检查 myCtx.signal?.aborted。
订阅:服务端用 async generator 定义 subscription 并 yield 批次,客户端 subscribe 提供 onData、onComplete、onError,可 unsubscribe 停止。
限制与注意:过程上下文转换须用 WithTelemetry<RouterContext> 或 RouterContext,勿用 any;ctx 视为只读;输入应始终定义 .input(z.object({...}));commonRouter 负责错误上报、遥测、问卷、打开 URL 等横切关注,视图路由不应重复实现。webviewName 在控制器构造中是注册键,在 tRPC 上下文里是遥测标签,两者取值不同,不可混淆。原始资料未提供收费、平台与性能数据。