# 查询层模式查询层是 UI 组件和服务层之间的反应式桥梁。它使用 TanStack Query 和 WellCrafted 工厂将纯服务功能与缓存、反应性和状态管理包装在一起。 ## 何时应用此技能当您需要执行以下操作时，请使用此模式： * 创建消耗服务的查询或突变 * 将服务层错误转换为面向用户的错误类型 * Implement runtime service selection based on user settings * 添加乐观缓存更新以实现即时 UI 反馈 *了解双接口模式（反应式与命令式） ## 核心架构 ┌──────────────┐ ┐──────────────┐ ┌──────────────┐ │ UI │ --> │ RPC/查询 │ --> │ 服务 │ │ 组件 │ │ 层 │ │ （纯） │ └──────────────┘ └──────────────┘ └──────────────┘ ↑ │ └────────────────────┘ 反应式更新 **查询层职责：** * 使用注入的设置/配置调用服务 * 将服务错误转换为面向用户的错误类型进行显示 * 管理 TanStack 查询缓存以实现乐观更新 * 提供双重接口：反应式（`.options`）和命令式（`.execute()`） ## 错误转换模式 **关键**：服务错误应在查询层边界转换为面向用户的错误类型。 ### 三层错误流程服务层→查询层→UI层 TaggedError<'Name'> → UserFacingError → Toast 通知（特定领域）（显示就绪）（显示） ### 标准错误转换从 'wellcrafted/result' 导入 { Err, Ok }; // 在查询层 - 将服务错误转换为面向用户的错误 const { 数据，错误 } = 等待 services.recorder.startRecording(params); 如果（错误）{ 返回错误（{ title: '❌开始录音失败', 描述：错误消息，操作：{ 类型：'更多详细信息'，错误 }， }); } 返回确定（数据）； ### 现实世界的例子 // 简单的错误转换枚举设备：defineQuery({ 查询密钥：recorderKeys.devices， queryFn: async () => { const { 数据，错误 } =等待 recorderService().enumerateDevices(); 如果（错误）{ 返回错误（{ title: '❌ 枚举设备失败', 描述：错误消息，操作：{ 类型：'更多详细信息'，错误 }， }); } 返回确定（数据）； }, }), // 服务消息不够时自定义描述停止记录：defineMutation({ mutationFn: async ({ toastId }) => { const { data: blob, error } = wait recorderService().stopRecording({ sendStatus }); 如果（错误）{ 返回错误（{ title: '❌无法停止录制', 描述：错误消息，操作：{ 类型：'更多详细信息'，错误 }， }); } if (!recordingId) { 返回错误（{ title: '❌ 缺少录音 ID', description: '发生内部错误：未设置录制 ID。', }); } 返回 Ok({ blob, RecordingId }); }, }), ### 反模式：双重包装永远不要包装已经包装的错误： // ❌ 不好：双重包装如果（错误）{ const userError = Err({ title: 'Failed', description: error.message }); notify.error.execute({ id: nanoid(), ...userError.error }); // 不要传播！返回用户错误； } // ✅ 好：转换一次，直接使用如果（错误）{ 返回错误（{ title: '❌开始录音失败', 描述：错误消息， }); } // 在 onError 钩子中，error 已经是面向用户的类型 onError: (错误) => 通知.错误.执行(错误), ## 运行时依赖注入查询层根据用户设置动态选择服务实现。 ### 服务选择模式 // 来自transcription.ts - 在提供者之间切换异步函数 transcribeBlob(blob: Blob): Promise> { 常量选定服务= settings.value['transcription.selectedTranscriptionService']; 开关（选定的服务）{ 案例“OpenAI”：返回等待 services.transcriptions.openai.transcribe(blob, { apiKey: settings.value['apiKeys.openai'], modelName: settings.value['transcription.openai.model'], 输出语言：settings.value['transcription.outputLanguage'], 提示：settings.value['transcription.prompt'], 温度：settings.value['转录.温度'], }); 案例“Groq”：返回等待 services.transcriptions.groq.transcribe(blob, { apiKey: settings.value['apiKeys.groq'], modelName: settings.value['transcription.groq.model'], 输出语言：settings.value['transcription.outputLanguage'], 提示：settings.value['transcription.prompt'], 温度：settings.value['转录.温度'], }); // ...更多案例默认：返回错误（{ title: '⚠️ 未选择转录服务', description: '请在设置中选择转录服务。', }); } } ### 录音机服务选择 // 基于平台+设置的选择导出函数 recorderService() { // 在浏览器中，始终使用导航记录器 if (!window.__TAURI_INTERNALS__) 返回 services.navigatorRecorder; // 在桌面上，使用设置常量记录器映射 = { 导航器：services.navigatorRecorder， ffmpeg：桌面服务.ffmpegRecorder， cpal: 桌面服务.cpalRecorder, }; return recorderMap[settings.value['recording.method']]; } ## 双接口模式每个查询/突变都提供两种使用方式： ### Reactive Interface: `.options` 在 Svelte 组件中用于自动状态管理。在访问器函数内传递 `.options` （静态对象）： <脚本语言=“ts”> 从 '@tanstack/svelte-query' 导入 { createQuery, createMutation }; 从'$lib/query'导入{rpc}； // 反应式查询 - 包装在访问器函数中，访问 .options（无括号） const 录音 = createQuery(() => rpc.db.recordings.getAll.options); // 反应性突变 - 相同模式 const deleteRecording = createMutation( () => rpc.db.recordings.delete.options, ）； {#if 录音.isPending} <旋转器/> {:else if 录音错误} <错误消息={recordings.error.description} /> {：其他} {#each Recordings.data 作为录音} <录音卡 {录音} onDelete={() => deleteRecording.mutate(录音)} /> {/每个} {/如果} ### 命令式接口：`.execute()` / `.fetch()` 在事件处理程序和工作流程中使用，无需反应性开销： // 在事件处理程序或工作流程中异步函数handleBulkDelete(recordings: Recording[]) { for（录音的常量录音）{ const { 错误 } = 等待 rpc.db.recordings.delete.execute(recording); 如果（错误）{ 通知.错误.执行(错误); 返回; } } notification.success.execute({ title: '所有录音已删除' }); } // 在顺序工作流程中异步函数 stopAndTranscribe(toastId: string) { const { 数据：blobData，错误：stopError } = 等待 rpc.recorder.stopRecording.execute({ toastId }); 如果（停止错误）{ 通知.错误.执行(stopError); 返回; } // 继续转录... } ### 何时使用每个将 `.options` 与 createQuery/createMutation 一起使用 |使用`.execute()`/`.fetch()` ---|--- 元件数据显示|事件处理程序需要加载旋转器|顺序工作流程自动重新获取通缉|一次性操作需要反应状态 |外部组件上下文缓存同步|性能关键路径 ## 缓存管理 ### 乐观更新模式立即更新缓存，然后与服务器同步：创建：定义突变（{ mutationKey: ['db', 'recordings', 'create'] as const, mutationFn: async (params: { 录音: 录音; 音频: Blob }) => { const { 错误 } = 等待 services.db.recordings.create(params); 如果（错误）返回 Err（错误）； // 乐观缓存更新 - UI 立即更新 queryClient.setQueryData<记录[]>( dbKeys.recordings.all， (oldData) => [...(oldData || []), params.recording], ）； queryClient.setQueryData<记录>( dbKeys.recordings.byId(params.recording.id), 参数记录，）； // 无效以在后台重新获取新数据 queryClient.invalidateQueries({ queryKey: dbKeys.recordings.all }); queryClient.invalidateQueries({ queryKey: dbKeys.recordings.latest }); 返回确定（未定义）； }, }), ### 查询键模式分层组织密钥以实现有针对性的失效：导出常量 dbKeys = { 录音：{ all: ['db', 'recordings'] as const, 最新：['db', '录音', '最新'] as const, byId: (id: string) => ['db', 'recordings', id] as const, }, 转换：{ all: ['db', 'transformations'] as const, byId: (id: string) => ['db', 'transformations', id] as const, }, }; ## 查询定义示例 ### 基本查询导出常量数据库= { 录音：{ getAll: 定义查询({ 查询键：dbKeys.recordings.all， queryFn: () => services.db.recordings.getAll(), }), }, }; ### 使用初始数据进行查询获取最新：defineQuery({ 查询键：dbKeys.recordings.latest， queryFn: () => services.db.recordings.getLatest(), // 如果可用则使用缓存数据初始数据：() => 查询客户端 .getQueryData(dbKeys.recordings.all) ?.toSorted((a, b) => 新日期（b.timestamp）.getTime（） - 新日期（a.timestamp）.getTime（） )[0] ??空，初始数据更新时间：() => queryClient.getQueryState(dbKeys.recordings.all)?.dataUpdatedAt, }), ### 带访问器的参数化查询 getById: (id: 访问器<字符串>) => 定义查询({ queryKey: dbKeys.recordings.byId(id()), queryFn: () => services.db.recordings.getById(id()), 初始数据：() => 查询客户端 .getQueryData(dbKeys.recordings.all) ?.find((r) => r.id === id()) ??空， }), ### 回调突变开始录制：defineMutation({ 突变密钥：recorderKeys.startRecording， mutationFn: async ({ toastId }) => { const { 数据，错误 } = 等待 recorderService().startRecording(params, { sendStatus: (选项) => notify.loading.execute({ id: toastId, ...选项 }), }); 如果（错误）{ 返回错误（{ title: '❌开始录音失败', 描述：错误消息，操作：{ 类型：'更多详细信息'，错误 }， }); } 返回确定（数据）； }, // 突变完成后状态无效 onSettled: () => queryClient.invalidateQueries({ queryKey: recorderKeys.recorderState }), }), ## RPC 命名空间所有查询都捆绑到统一的“rpc”命名空间中： // 查询/index.ts 导出常量 rpc = { 分贝，录音机, transcription, 剪贴板, 声音，分析，通知， // ...所有功能模块作为常量； // 在应用程序的任何地方使用从'$lib/query'导入{rpc}； // 反应式（在组件中） const query = createQuery(() => rpc.db.recordings.getAll.options); // 命令式（在处理程序/工作流程中） const { 数据，错误 } = 等待 rpc.recorder.startRecording.execute({ toastId }); ## 通知 API 示例查询层可以协调多个服务：导出常量通知 = { 成功：定义突变（{ mutationFn：异步（选项：NotifyOptions）=> { // 显示 toast 和操作系统通知 services.toast.success（选项）；等待 services.notification.show({ ...选项, 变体: '成功' }); 返回确定（未定义）； }, }), 错误：定义突变（{ mutationFn：异步（错误：UserError）=> { services.toast.error(错误); 等待 services.notification.show({ ...错误, 变体: '错误' }); 返回确定（未定义）； }, }), 加载：defineMutation({ mutationFn：异步（选项：LoadingOptions）=> { // 仅用于加载状态的 toast（没有操作系统通知垃圾邮件） services.toast.loading(选项); 返回确定（未定义）； }, }), }; ## 关键规则 1. **始终在查询边界处转换错误** \- 绝不返回原始服务错误 2. **使用`.options`（无括号）** \- 这是一个静态对象，包含在 Svelte 的访问器中 3. **永远不要双重换行错误** \- 每个错误都只换行一次 4. **服务是纯粹的，查询注入设置** \- 服务采用显式参数 5. **在`.ts`文件中使用`.execute()`** \-`createMutation`需要组件上下文 6. **乐观地更新缓存** \- 更好的突变用户体验 ## 参考文献 * 详细架构请参见 `apps/whispering/src/lib/query/README.md` * 服务的实现方式参见`services-layer`技能 * 请参阅 trySync/tryAsync 模式的“错误处理”技巧

查询层

包含技能