# 服务层模式该技能记录了如何在 Whispering 架构中实现服务。服务是纯粹的、独立的业务逻辑，没有 UI 依赖项，会返回“Result”类型以进行错误处理。 ## 何时应用此技能当您需要执行以下操作时，请使用此模式： * 创建具有特定于域的错误处理的新服务 * 添加带有结构化上下文的错误类型（如 HTTP 状态代码） * 了解服务如何组织和导出 * 实施特定于平台的服务变体（桌面与网络） ## 核心架构服务遵循三层架构：**服务** → **查询** → **UI** ┌──────────────┐ ┐──────────────┐ ┌──────────────┐ │ UI │ --> │ RPC/查询 │ --> │ 服务 │ │ 组件 │ │ 层 │ │ （纯） │ └──────────────┘ └──────────────┘ └──────────────┘ **服务是：** * **Pure** ：接受显式参数，无隐藏依赖 * **Isolated** : No knowledge of UI state, settings, or reactive stores * **可测试** ：使用模拟参数轻松进行单元测试 * **一致** ：所有返回 `Result` 类型以进行统一的错误处理 ## 使用defineErrors创建错误每个服务都使用 wellcrafted 中的“defineErrors”定义特定于域的错误。错误被分组到一个命名空间对象中，其中每个键都成为一个变体。导入 {defineErrors, type InferError, type InferErrors, extractErrorMessage } from 'wellcrafted/error'; import { Err, Ok, type Result, tryAsync, trySync } from 'wellcrafted/result'; // 命名空间风格的错误定义——名称描述域 const CompletionError = 定义错误({ 连接失败: ({ 原因 }: { 原因: 未知 }) => ({ 消息：`连接失败：${extractErrorMessage(cause)}`, 原因， }), EmptyResponse: ({ 提供者标签 }: { 提供者标签: 字符串 }) => ({ 消息：`${providerLabel} API 返回空响应`, 提供商标签， }), 缺少参数: ({ 参数 }: { 参数: 字符串 }) => ({ 消息：`${param} 是必需的`, 参数， }), }); // 类型派生 — 用同名类型隐藏 const 类型 CompletionError = InferErrors; 类型 ConnectionFailedError = InferError 类型； // 调用站点 - 每个变体直接返回 Err<...> 返回 CompletionError.ConnectionFailed({ 原因: 错误 }); 返回 CompletionError.EmptyResponse({providerLabel: 'OpenAI' }); return CompletionError.MissingParam({ param: 'apiKey' }); ###defineErrors 是如何工作的 `defineErrors({ ... })` 接受工厂函数的对象并返回命名空间对象。每个键都成为一个变体： * **`name` is auto-stamped** from the key (e.g., key `NotFound` → `error.name === 'NotFound'`) * **工厂函数是消息生成器** - 它返回 `{ message, ...fields }` * **每个变体直接返回 `Err<...>` ** — 不需要单独的 `FooErr` 构造函数 * **类型使用 `InferError` / `InferErrors`** — 不是 `ReturnType` // 无输入变体（静态消息） const RecorderError = 定义错误({ 忙：() => ({ message: '录音已在进行中', }), }); // 用法 — 不需要参数返回 RecorderError.Busy(); // 具有派生字段的变体 — 构造函数从原始输入中提取 const HttpError = 定义错误({ 响应: ({ 响应, 正文 }: { 响应: { 状态: 数字 }; 正文: 未知 }) => ({ 消息：`HTTP ${response.status}：${extractErrorMessage(body)}`，状态：响应.状态，身体， }), }); // 用法 — 传递原始对象，构造函数派生字段返回 HttpError.Response({ 响应，正文：等待响应.json() }); // error.message → “HTTP 401：未经授权” // error.status → 401（源自响应，平放在对象上） // 错误名称→“响应” ### 代码库中的错误类型示例 // 静态消息，无需输入 const RecorderError = 定义错误({ 忙：() => ({ message: '录音已在进行中', }), }); RecorderError.Busy() // 单个命名空间中的多个相关错误 const HttpError = 定义错误({ 连接: ({ 原因 }: { 原因: 未知 }) => ({ message: `无法连接到服务器: ${extractErrorMessage(cause)}`, 原因， }), 响应: ({ 响应, 正文 }: { 响应: { 状态: 数字 }; 正文: 未知 }) => ({ 消息：`HTTP ${response.status}：${extractErrorMessage(body)}`，状态：响应.状态，身体， }), 解析：({ 原因 }: { 原因: 未知 }) => ({ message: `无法解析响应正文: ${extractErrorMessage(cause)}`, 原因， }), }); // Union type for the whole namespace 类型 HttpError = InferErrors; // 单独的变体类型类型 ConnectionError = InferError; ## 反模式：受歧视的联合输入 **错误工厂输入中的字符串文字联合是一种代码味道。**当变体的输入包含像“reason: 'a' |”这样的字段时。 'b' | 'c'` 或 `操作：'x' | 'y'| 'z'`，您正在创建一个子判别式，该子判别式重复了顶层已提供的 `defineErrors` 内容。 ### 问题 // 不好：子判别力强制双重缩小和不诚实的类型 const ShortcutError = DefineErrors({ 无效加速器：（输入：{ 原因：“无效格式”| '无密钥代码' | '多个密钥代码'；加速器？：字符串； // 可选，因为某些原因不使用它 }) => { 常量消息 = { invalid_format: `格式无效：'${input.accelerator}'`, no_key_code: '未找到有效的密钥代码', multiple_key_codes: '不允许使用多个按键代码', }; return { message: messages[input.reason], ...input }; }, }); **为什么这不好：** 1. **双重缩小**：消费者必须缩小“error.name”，然后缩小“error.reason” 2. **不诚实的类型** ： `accelerator` 是可选的，因为某些原因不需要它，但类型并没有表达哪些类型需要它 3. **模糊的意图**：“原因”字段正在执行判别式的工作 - 这就是变体名称的用途 ### 修复：分成单独的变体 // 好：每个变体都有它需要的字段 const ShortcutError = DefineErrors({ InvalidFormat: ({ accelerator }: { accelerator: string }) => ({ 消息：`加速器格式无效：'${accelerator}'`，加速器, }), 无键代码：() => ({ message: '在按下的按键中找不到有效的按键代码', }), 多个按键代码：() => ({ message: '加速器中不允许使用多个按键代码', }), }); **为什么这样更好：** * **单次缩小** : `error.name === 'NoKeyCode'` — 完成 * **诚实类型** : `InvalidFormat` 需要 `accelerator`，`NoKeyCode` 不需要任何东西 * **自记录**：变体名称描述错误，不需要查找表 ### 当这适用时每当您看到以下内容时就拆分： * `原因：'a' | 'b' | 'c'` 带有消息查找表 * `操作：'x' | 'y'| 'z'` 每个操作有不同的消息 * `errorKind: ...` 或 `type: ...` 充当子判别式 * 存在的可选字段是因为“某些变体”不使用它们 “defineErrors”的要点在于，每个变体都是一等公民，有自己的名称和形状。将它们折叠在字符串联合后面可以节省几行定义，但代价是较弱的类型和每个消费者的双重缩小。 ### 异常：当它确实是一个错误时如果字符串文字确实是一个_field_而不是一个子判别式——例如，消费者没有打开它——那么就可以了： // OK：“操作”是用于记录的元数据，而不是子判别式 const FsError = 定义错误({ ReadFailed: ({ 路径, 原因 }: { 路径: 字符串; 原因: 未知 }) => ({ message: `无法读取'${path}': ${extractErrorMessage(cause)}`, 路径，原因， }), WriteFailed: ({ 路径, 原因 }: { 路径: 字符串; 原因: 未知 }) => ({ message: `无法写入 '${path}': ${extractErrorMessage(cause)}`, 路径，原因， }), }); ## 反模式：工厂输入上的条件逻辑 **如果变体构造函数在其自己的输入字段上使用 if/switch 来决定消息或行为，则每个分支都应该是其自己的变体。** 这是上面字符串文字联合规则的概括 - 构造函数内的任何分支都意味着多个错误隐藏在一个变体中。 ### 问题 // 不好：构造函数在输入上分支——多个错误隐藏在一个变体中 const FormError = 定义错误({ 验证: ({ 字段, 值, 接收类型 }: { 字段？：字符串； // Optional because not every branch uses it 值？：字符串； // 可选，因为并非每个分支都使用它收到的类型？：字符串； // 可选，因为并非每个分支都使用它 }) => ({ 消息：(() => { if (field === 'email' && value) return `无效的电子邮件地址：'${value}'`; if (字段 === '密码' && 值) return `密码太弱：必须至少 8 个字符`; if (字段 === '确认密码') return '密码不匹配'; if (receivedType) return `无效的表单数据：预期的字符串，得到 ${receivedType}`; return '表单提交失败'; })(), 场, 值，收到的类型， }), }); **症状：** 1. **不诚实的可选**：字段是可选的，因为没有一个调用站点会使用它们全部 - 类型取决于每个错误实际携带的内容 2. **隐藏分支**：消费者必须检查 `name` 之外的字段才能知道真正的错误类型 — `name === 'Validation'` 不会告诉您任何信息 3. **不可输入的消息**：消息取决于运行时字段组合，因此 TypeScript 无法缩小到特定的消息形状 ### 修复：将每个分支展平为自己的变体 // 好：每个分支都成为自己的变体，具有诚实的必填字段 const FormError = 定义错误({ 无效电子邮件：（{值}：{值：字符串}）=>（{ message: `无效的电子邮件地址: '${value}'`, 值， }), 弱密码：() => ({ message: '密码太弱：必须至少为 8 个字符', }), 密码不匹配：() => ({ message: '密码不匹配', }), InvalidFormData: ({ receiveType }: { receiveType: string }) => ({ message: `无效的表单数据：预期的字符串，得到 ${receivedType}`, 收到的类型， }), 提交失败: () => ({ message: '表单提交失败', }), }); **为什么这样更好：** * **Honest types** : `InvalidEmail` requires `value`, `WeakPassword` takes nothing — no dishonest optionals * **单一缩小** : `error.name === 'InvalidEmail'` 告诉你一切 * **可输入的消息**：每个变体都有确定的消息形状 ### 经验法则如果构造函数根据其输入进行分支来决定消息，则每个分支应该是其自己的变体。分支是你将多个不同错误合并为一个的证据。这适用于： * **消息构造中的 If/else 链**（包括 IIFE） * **输入字段上的 Switch 语句** * **三元表达式** 在根本不同的消息之间进行选择 * **查找表** 以输入字段为键（由上面的字符串文字联合规则覆盖） > 另请参阅：`docs/core/error-system.mdx` §“3b. 避免工厂输入上的条件逻辑”，获取带有完整示例的规范参考。 ## 服务实现模式 ### 基本服务结构导入 {defineErrors, type InferErrors, extractErrorMessage } from 'wellcrafted/error'; import { Err, Ok, type Result, tryAsync, trySync } from 'wellcrafted/result'; // 1. 定义特定领域的错误——变体名称描述故障模式 const AutostartError = DefineErrors({ 检查失败: ({ 原因 }: { 原因: 未知 }) => ({ message: `无法检查自动启动: ${extractErrorMessage(cause)}`, 原因， }), EnableFailed: ({ cause }: { cause: unknown }) => ({ message: `无法启用自动启动: ${extractErrorMessage(cause)}`, 原因， }), DisableFailed: ({ 原因 }: { 原因: 未知 }) => ({ message: `无法禁用自动启动: ${extractErrorMessage(cause)}`, 原因， }), }); 类型 AutostartError = InferErrors; // 2. 创建返回服务对象的工厂函数导出函数createAutostartService() { 返回{ 异步 isEnabled(): Promise> { 返回 tryAsync({ 尝试：() => isEnabled(), 捕获：（错误）=> AutostartError.CheckFailed({ 原因: 错误 }), }); }, 异步启用(): Promise> { 返回 tryAsync({ 尝试：() => 启用(), 捕获：（错误）=> AutostartError.EnableFailed({ 原因: 错误 }), }); }, }; } // 3. 导出“Live”实例（生产单例）导出类型 AutostartService = ReturnType; 导出 const AutostartServiceLive = createAutostartService(); ### 现实示例：记录器服务 // 来自 apps/whispering/src/lib/services/isomorphic/recorder/navigator.ts const RecorderError = 定义错误({ 已录制：() => ({ message: '录音已经在进行中。请停止当前录音。', }), StreamAcquisition: ({ 原因 }: { 原因: 未知 }) => ({ message: `获取录制流失败：${extractErrorMessage(cause)}`, 原因， }), InitFailed: ({ 原因 }: { 原因: 未知 }) => ({ 消息：`无法初始化记录器。 ${extractErrorMessage(原因)}`, 原因， }), }); 类型 RecorderError = InferErrors; 导出函数 createNavigatorRecorderService(): RecorderService { 让 activeRecording: ActiveRecording |空=空；返回{ getRecorderState: async(): Promise< 结果 > => { 返回 Ok(activeRecording ? 'RECORDING' : 'IDLE'); }, 开始录音：异步（参数：NavigatorRecordingParams， { 发送状态 }, ): Promise<结果> => { // 验证状态如果（活动记录）{ 返回 RecorderError.AlreadyRecording(); } // 获取流（调用另一个服务） const { 数据：streamResult，错误：acquireStreamError } = 等待 getRecordingStream({ selectedDeviceId, sendStatus }); 如果（获取流错误）{ 返回 RecorderError.StreamAcquisition({ 原因：获取流错误， }); } // 初始化媒体记录器 const { 数据：mediaRecorder，错误：recorderError } = trySync({ 尝试：（）=> new MediaRecorder(stream, { 位每秒：数字（比特率Kbps）* 1000， }), 捕获：（错误）=> RecorderError.InitFailed({ 原因: 错误 }), }); 如果（记录器错误）{ cleanupRecordingStream(流); 返回错误（记录器错误）； } // 存储状态并开始主动录音 = { 录音ID, 流，媒体记录器，记录块：[]， }; mediaRecorder.start(TIMESLICE_MS); 返回确定（设备结果）； }, }; } 导出 const NavigatorRecorderServiceLive = createNavigatorRecorderService(); ## 命名空间导出模式服务按层次结构组织并重新导出为命名空间对象： ### 文件夹结构服务/ ├── 桌面/ # 仅限桌面（Tauri） │ ├── index.ts # 重新导出为desktopServices │ ├── 命令.ts │ └── ffmpeg.ts ├── 同构/ # 跨平台 │ ├── index.ts # 作为服务重新导出 │ ├── 转录/ │ │ ├── index.ts # 重新导出为转录名称空间 │ │ ├── 云/ │ │ │ ├── openai.ts │ │ │ └── groq.ts │ │ └── 本地/ │ │ └── 耳语cpp.ts │ └── 完成/ │ ├── 索引.ts │ └── openai.ts ├── 类型.ts └──index.ts # 主入口点 ### 索引文件模式 // 服务/同构/转录/index.ts 从 './cloud/openai' 导出 { OpenaiTranscriptionServiceLive as openai }; 从 './cloud/groq' 导出 { GroqTranscriptionServiceLive as groq }；从 './local/whispercpp' 导出 { WhispercppTranscriptionServiceLive as Whispercpp }； // 服务/同构/index.ts 导入 * 作为来自 './transcription' 的转录；从 './completion' 导入 * 作为补全；导出常量服务 = { 数据库：DbServiceLive，声音：PlaySoundServiceLive， transcriptions, // 命名空间导入 completions, // 命名空间导入作为常量； // services/index.ts（主条目）从“./isomorphic”导出{服务}；从'./desktop'导出{desktopServices}； ### 消费服务 // In query layer or anywhere 从“$lib/services”导入{services,desktopServices}； // 通过命名空间访问等待 services.transcriptions.openai.transcribe(blob, options); 等待 services.transcriptions.groq.transcribe(blob, options); 等待 services.db.recordings.getAll(); 等待desktopServices.ffmpeg.compressAudioBlob（blob，选项）； ## 特定于平台的服务对于每个平台需要不同实现的服务： ### 定义共享接口 // 服务/同构/text/types.ts 导出类型 TextService = { readFromClipboard(): Promise<结果<字符串 |空，文本错误>>； copyToClipboard(text: string): Promise>; writeToCursor(text: string): Promise>; }; ### 按平台实施 // 服务/同构/文本/desktop.ts const TextError = 定义错误({ ClipboardWriteFailed: ({ 原因 }: { 原因: 未知 }) => ({ message: `剪贴板写入失败: ${extractErrorMessage(cause)}`, 原因， }), }); 导出函数createTextServiceDesktop(): TextService { 返回{ 复制到剪贴板：（文本）=> 尝试异步（{ 尝试: () => writeText(text), // Tauri API 捕获：（错误）=> TextError.ClipboardWriteFailed({ 原因: 错误 }), }), }; } // 服务/同构/文本/web.ts 导出函数 createTextServiceWeb(): TextService { 返回{ 复制到剪贴板：（文本）=> 尝试异步（{ 尝试： () => navigator.clipboard.writeText(text), // 浏览器 API 捕获：（错误）=> TextError.ClipboardWriteFailed({ 原因: 错误 }), }), }; } ### 构建时平台检测 // 服务/同构/文本/index.ts 导出 const TextServiceLive = window.__TAURI_INTERNALS__ ？创建文本服务桌面() : 创建TextServiceWeb(); ## 错误消息最佳实践写入错误消息： * **用户友好**：用简单的语言解释发生了什么 * **可操作** ：建议用户可以做什么 * **详细** ：包括调试的技术细节 ### Choosing the right approach * **静态消息的无输入变体**（例如，`Busy: () => ({ message: '...' })`） * **基于字段的变体** 当消息是根据结构化输入计算时 * **单独的变体** 当不同的错误条件需要不同的字段时（请参阅上面的反模式部分） const RecorderError = 定义错误({ // 静态消息——无需输入忙：() => ({ message: '录音已在进行中', }), // 根据字段计算出的消息 HttpResponse: ({ 状态 }: { 状态: 数字 }) => ({ 消息：`HTTP ${status} 响应`, 状态， }), // 用上下文包装未知原因麦克风不可用: ({ 原因 }: { 原因: 未知 }) => ({ message: `无法连接到所选麦克风：${extractErrorMessage(cause)}`, 原因， }), // 带有文件上下文的用户可操作消息 ConfigParseFailed: ({ 文件名, 原因 }: { 文件名: 字符串; 原因: 未知 }) => ({ 消息：`无法解析配置文件。请检查 ${filename} 是否包含有效的 JSON。 ${extractErrorMessage(原因)}`, 文件名，原因， }), }); ## 关键规则 1. **服务从不导入设置** \- 将配置作为参数传递 2. **服务从不导入 UI 代码** \- 没有 toast，没有通知，没有 WhisperingError 3. **始终返回结果类型** \- 绝不抛出错误 4. **使用trySync/tryAsync** \- 详情参见错误处理技巧 5. **导出工厂 + 实时实例** \- 用于测试的工厂，用于生产的实时实例 6. **使用defineErrors命名空间** \- 将相关错误分组到单个命名空间下 7. **使用 InferError/InferErrors 派生类型** \- 不是 `ReturnType` 8. **变体名称描述故障模式** \- 切勿使用“Service”、“Error”或“Failed”等通用名称。命名空间提供域上下文（`RecorderError`），因此变体必须说明_出了什么问题_（`AlreadyRecording`、`InitFailed`、`StreamAcquisition`）。 `RecorderError.Service` 毫无意义 — `RecorderError.AlreadyRecording` 告诉你到底发生了什么。 9. **分割可区分的联合输入** \- 每个变体都有自己的名称和形状。如果构造函数在其输入（if/switch/ternary）上分支来决定消息，则每个分支应该是它自己的变体 10. **在构造函数中转换 Cause，而不是调用站点** \- 接受 `cause:unknown` 并在工厂的消息模板内调用 `extractErrorMessage(cause)`。调用站点传递原始错误：“{ Cause: error }”。这将消息提取集中在组成消息的地方，并保持调用站点的干净。 ## 参考文献 * 有关架构详细信息，请参阅“apps/whispering/src/lib/services/README.md” * See the `query-layer` skill for how services are consumed * 请参阅 trySync/tryAsync 模式的“错误处理”技巧

服务层

包含技能