Cherry Studio Data API 类型系统全解析从 Schema 定义到端到端类型安全的 IPC 数据层【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本篇技术指南围绕 Cherry Studio 的 DataApi 类型系统展开系统讲解src/shared/data/api/目录下的核心类型定义、路径解析、分页类型、错误处理与 Schema 组织约定并结合仓库源码与真实 domain 示例如topics、messages说明如何新增一个领域 Schema。读完本文你将掌握 DataApi 的端到端类型推导机制客户端调用 → 路由 → handler 实现全链路类型约束、offset/cursor 两种分页模式的使用边界以及如何用DataApiErrorFactory构建结构化、可序列化、可重试判定的错误体系。DataApi 类型系统定位DataApi 是 Cherry Studio 在 Renderer 与 Main 进程之间提供类型安全 IPC 通信的数据层。它只服务于「业务数据」——即用户使用过程中累积、有独立数据库表、可无限增删改且丢失不可挽回的数据对话主题 topic、消息 message、文件 file 等数据量可能增长到 GB 级而不是通用的 RPC 层。系统控制、外部服务集成、命令式操作、无数据库支撑的无状态查询等应继续走传统 IPC handlersrc/main/ipc.ts或生命周期服务具体边界见 API Design Guidelines —— DataApi Scope Boundaries。类型系统的全部基础设施位于 src/shared/data/api/与分页、排序等跨领域约定文档data-pagination-guide.md、data-ordering-guide.md配套使用。目录结构与文件职责src/shared/data/api/ ├── types.ts # 核心请求/响应类型与 API 工具类型 ├── paths.ts # 路径模板字面量类型工具 ├── errors.ts # 错误处理ErrorCode、DataApiError 类、工厂 └── schemas/ ├── apiSchemas.ts # Schema 组合合并所有领域 schema └── *.ts # 各领域独立 schema文件职责types.ts核心类型DataRequest、DataResponse、ApiClient与 schema 工具类型AssertValidSchemas、ApiImplementation、HandlersFor等paths.ts模板字面量类型把/items/:id解析为/items/${string}并提供ConcreteApiPaths/TemplateApiPaths/ResponseForPath等路径推导工具errors.tsErrorCode枚举、DataApiError类、DataApiErrorFactory工厂、可重试错误配置schemas/apiSchemas.ts用交叉类型把所有领域 schema 组合成统一的ApiSchemasschemas/*.ts各领域 API 定义与 DTO从源码结构看types.ts还承担了「数据变更通知协议」类型的定义GetMethodApiPaths、CollectionGetPaths、ScalarGetPaths与DataApiDataChangeEffect见下文「数据变更通知的类型的类型约束」小节它并非单纯的请求/响应类型文件。Schema 文件组织按「返回实体领域」划分schema 文件按被操作或返回的实体的领域组织而不是按 URL 前缀组织。路径中的父级资源:topicId、:providerId只起到限定作用域的作用并不决定路由归属于哪个文件路由返回实体归属文件/topics/:topicId/messagesMessagemessages.ts/topics/:topicId/treeTreeMessage 派生的视图messages.ts/topics/:id/active-nodeActiveNodeResponseTopic 状态topics.ts当路由的 URL 父级与返回实体不一致时以返回实体为准。例如 topics.ts 中ActiveNodeResponse定义在/topics/:id/active-node之下但它的语义是 Topic 的状态activeNodeId因此归属topics.ts而非独立文件。导入约定DataApi 没有 barrel 文件不提供聚合导出的 index这要求开发者按来源精确导入基础设施类型直接从模块导入——核心类型、分页与查询参数在types错误在errors路径工具在pathsimport type { DataRequest, DataResponse, ApiClient, // 分页类型 OffsetPaginationParams, OffsetPaginationResponse, CursorPaginationParams, CursorPaginationResponse, PaginationResponse, // 查询参数类型 SortParams, SearchParams } from shared/data/api/types // 分页类型守卫同样位于 types import { isOffsetPaginationResponse, isCursorPaginationResponse } from shared/data/api/types import { ErrorCode, DataApiError, DataApiErrorFactory, isDataApiError, toDataApiError } from shared/data/api/errors领域 DTO 直接从对应 schema 文件导入// Topic 领域 import type { Topic, CreateTopicDto, UpdateTopicDto } from shared/data/api/schemas/topics // Message 领域 import type { Message, CreateMessageDto } from shared/data/api/schemas/messages这一约定在 schemas/apiSchemas.ts 的文件头注释中也有明确说明且整个仓库的 domain schema 文件如topics.ts、messages.ts均遵循「实体 schema 与类型位于shared/data/types/API 层 schema 位于schemas/」的分层惯例。分页类型两种模式端到端约束DataApi 支持两种分页模式查询参数可组合使用。本节是类型引用——关于模式选择offset vs cursor、cursor 排他性语义、实战示例与客户端派生见 分页指南。请求参数类型字段适用场景OffsetPaginationParamspage?、limit?传统翻页导航page从 1 开始CursorPaginationParamscursor?、limit?无限滚动、实时 feed。cursor是排他性边界——cursor 所指条目本身不会被返回见 分页指南 § Wire ContractSortParamssortBy?、sortOrder?排序sortOrder为asc/desc按需组合SearchParamssearch?文本搜索按需组合在路由的query中用组合例如query?: OffsetPaginationParams SortParams SearchParams。响应类型类型字段说明OffsetPaginationResponseTitems、total、page基于页码的结果CursorPaginationResponseTitems、nextCursor?基于游标的结果nextCursor缺失即无更多数据PaginationResponseT两者的联合两种模式均可接受时使用用isOffsetPaginationResponse/isCursorPaginationResponse收窄类型守卫与推断工具types.ts提供两个运行时类型守卫与两个条件类型推断工具// 类型守卫判断是 offset 还是 cursor 响应 export function isOffsetPaginationResponseT(response: PaginationResponseT): response is OffsetPaginationResponseT { return page in response total in response } export function isCursorPaginationResponseT(response: PaginationResponseT): response is CursorPaginationResponseT { return !(page in response) } // 条件类型从响应类型反推分页模式与条目类型 export type InferPaginationModeR R extends OffsetPaginationResponseany ? offset : R extends CursorPaginationResponseany ? cursor : never export type InferPaginationItemR R extends OffsetPaginationResponseinfer T ? T : R extends CursorPaginationResponseinfer T ? T : never此外types.ts还定义了服务层的列表查询约定ListOptions含sortBy白名单createdAt | updatedAt | name | orderKeysearch为对 name/description 的大小写不敏感LIKE %kw%匹配。模式是端点的固有属性不可由调用方配置。一个端点要么是 offset 要么是 cursor在 schema 中一次性声明混用是编译期错误而非运行时挂起——usePaginatedQuery拒绝 cursor 路径、useInfiniteQuery拒绝 offset 路径路径泛型通过OffsetPaginatedPath/CursorPaginatedPath约束二者都由InferPaginationMode派生见 useDataApi.ts。模式选择的工程建议来自分页指南任何无界增长、或「最新优先读取同时持续写入」的数据消息、会话、翻译/绘画历史优先用cursor——offset 的page * limit窗口在两次请求之间插入数据时会静默跳过或重复行UI 需要离散翻页控件或精确总数时assistants、MCP servers优先用offset。cursor 响应也可以额外携带total如知识库、文件列表。客户端派生公式// OffsetPaginationResponse const pageCount Math.ceil(total / limit) const hasNext page * limit total const hasPrev page 1 // CursorPaginationResponse const hasNext nextCursor ! undefinedRenderer 侧使用usePaginatedQueryoffset与useInfiniteQueryuseInfiniteFlatItemscursor时这些推导已内建仅当直接调用DataApiService时才需要手工派生。每个分页 hook 都会把路径泛型约束到匹配的分页形状cursor/offset 路径混用是编译期错误。新增一个领域 Schema三步完整流程第一步创建 schema 文件以下示例来自 api-types.md 的示意实际工程中字段原子 schema 通常定义在shared/data/types/下并由领域文件复用如 topics.ts 从../../types/topic导入TopicSchema、TopicNameSchemaimport * as z from zod import type { OffsetPaginationParams, OffsetPaginationResponse, SearchParams, SortParams } from ../apiTypes // 实际路径为 shared/data/api/types // 字段原子field atoms——在实体、DTO、查询之间共享 export const TopicNameSchema z.string().trim().min(1).max(128) // 实体 schemaz.strictObject 拒绝未知字段 export const TopicSchema z.strictObject({ id: z.uuidv4(), name: TopicNameSchema, createdAt: z.iso.datetime() }) export type Topic z.infertypeof TopicSchema // DTO —— 从实体白名单选取见 api-design-guidelines.md 的 Zod Schema DTO 约定 export const CreateTopicSchema TopicSchema.pick({ name: true }) export type CreateTopicDto z.infertypeof CreateTopicSchema // API Schema —— 校验由 index.ts 中的 AssertValidSchemas 完成 export type TopicSchemas { /topics: { GET: { query?: OffsetPaginationParams SortParams SearchParams response: OffsetPaginationResponseTopic // response 必填 } POST: { body: CreateTopicDto response: Topic } } /topics/:id: { GET: { params: { id: string } response: Topic } } }组合级校验schema 会在schemas/apiSchemas.ts的组合点通过AssertValidSchemas做编译期验证仅允许合法 HTTP 方法GET、POST、PUT、DELETE、PATCH每个端点必须声明response字段非法 schema 会在组合点产生 TypeScript 编译错误。AssertValidSchemas的实现机制types.ts由两个工具类型构成ValidateMethods把非HttpMethod的方法映射为never类型ValidateResponses把缺失response的端点映射为带错误提示的{ error: Endpoint X.Y is missing response field }。二者相交后任何一处违规都会让类型推导失败。设计准则新建 schema 前请先阅读 API Design Guidelines确认路径命名、HTTP 方法与错误处理约定。第二步在 apiSchemas.ts 注册schema 组合文件的唯一职责是把所有领域 schema 组合为ApiSchemasimport type { TopicSchemas } from ./topics // AssertValidSchemas 提供兜底校验——即使某个 schema 文件忘了单独校验也能被发现 export type ApiSchemas AssertValidSchemasTopicSchemas MessageSchemas当前仓库已组合的领域包括共 25 个TopicSchemas、MessageSchemas、TemporaryChatSchemas、ModelSchemas、ProviderSchemas、PaintingsSchemas、TranslateSchemas、FileSchemas、McpServerSchemas、KnowledgeSchemas、MiniAppSchemas、NoteSchemas、AssistantSchemas、TagSchemas、PromptSchemas、GroupSchemas、PinSchemas、AgentSchemas、SkillSchemas、AgentSessionMessageSchemas、AgentSessionSchemas、AgentWorkspaceSchemas、AgentChannelSchemas、JobSchemas、SearchSchemas、AiUsageRecordSchemas。第三步在 handlers 目录实现处理器在src/main/data/api/handlers/中实现对应端点。Handler 是薄层提取参数、调用 service、转换响应不允许包含业务逻辑业务逻辑在src/main/data/services/层。类型安全特性路径解析模板字面量类型paths.ts用模板字面量类型把具体路径映射回 schema 路径使客户端能用「真实路径」调用并获得精确返回类型// 具体路径 /topics/abc123 映射到 schema 路径 /topics/:id api.get(/topics/abc123) // TypeScript 知道返回 Topic其核心是ResolvedPath递归类型/test/items/:id→/test/items/${string}/topics/:id/messages→/topics/${string}/messages。再由ResolvedPath对ApiSchemas的每个键做映射得到所有合法具体路径的联合ConcreteApiPathsTemplateApiPaths则是 schema 键本身含:param占位符的联合。ApiPath ConcreteApiPaths | TemplateApiPaths是所有数据 hookuseQuery/useMutation/useInfiniteQuery/usePaginatedQuery统一接受的路径类型模板路径会触发params必填约束具体路径则禁止传入params。配套的类型提取工具ParamsForPath/QueryParamsForPath/BodyForPath/ResponseForPath通过SchemaKeyForPath模板路径走快路径、具体路径走MatchApiPath反向匹配定位 schema 键再按方法提取对应字段类型——这正是ApiClient接口types.ts能对get/post/put/delete/patch分别推导 query、body、response 类型的底层机制。穷尽式 Handler 检查ApiImplementation类型要求所有 schema 端点都有 handler 实现——缺失任何端点都会导致编译错误// TypeScript 会在缺少任意端点时报错 const handlers: ApiImplementation { /topics: { GET: async () { /* ... */ }, POST: async ({ body }) { /* ... */ } } // 缺少 /topics/:id 会引发编译错误 }ApiHandler类型还根据 schema 声明自动决定params/query/body是必填还是可选通过HasRequiredQuery/HasRequiredBody/HasRequiredParams三个辅助类型handler 返回值可以是数据本身T自动推断状态码或{ data: T, status: SuccessStatusCode }自定义状态码。SuccessStatus常量定义了 200 / 201 / 202 / 204配套isCustomStatusResult类型守卫判断 handler 是否返回了自定义状态码格式。另外HandlersForSchemas提供按模块子 schema划分的 handler 映射给定 schema 子集如TopicSchemas产出必须穷尽实现该 schema 全部路径方法的 handler 记录同时把路径收窄到本模块自己的 schema防止拼写错误与跨模块泄漏并在该作用域内保持穷尽性保证。类型安全客户端ApiClient提供完全类型化的方法const topic await api.get(/topics/123) // 返回 Topic const topics await api.get(/topics, { query: { page: 1, limit: 20, search: hello } }) // 返回 OffsetPaginationResponseTopic await api.post(/topics, { body: { name: New } }) // body 被推导为 CreateTopicDto真实示例topics 领域 schema 的部分端点topics.ts 展示了真实的 schema 结构例如GET /topicscursor 分页 可选名称搜索limit默认 50最大 200返回CursorPaginationResponseTopic列表是服务端组合视图——置顶主题在前关联pin表按pin.orderKey排序未置顶的按topic.orderKey ASC, id ASC排序cursor 编码了「分区 最后边界」以无缝跨分区翻页DELETE /topics?ids...批量删除全有或全无任一 ID 无效则整体失败/topics/latest声明在/topics/:id之前由服务端路由精确匹配避免latest被误当成 topic id/topics/:id/move、/topics/:id/active-node、/topics/:id/duplicate等动作端点以及通过 OrderEndpoints/topics注入的重排序端点。错误处理类型安全 自动重试判定错误系统提供类型安全的错误处理与自动重试能力核心实现位于 errors.ts。用法一览import { DataApiError, DataApiErrorFactory, ErrorCode, isDataApiError, toDataApiError } from shared/data/api/errors // 推荐用工厂创建错误 throw DataApiErrorFactory.notFound(Topic, id) throw DataApiErrorFactory.validation({ name: [Name is required] }) throw DataApiErrorFactory.timeout(fetch topics, 3000) throw DataApiErrorFactory.database(originalError, insert topic) // 或用类直接创建 throw new DataApiError( ErrorCode.NOT_FOUND, Topic not found, 404, { resource: Topic, id: abc123 } ) // 判断是否可重试供自动重试逻辑使用 if (error instanceof DataApiError error.isRetryable) { await retry(operation) } // 判断错误类型 if (error instanceof DataApiError) { if (error.isClientError) { // 4xx —— 请求本身的问题 } else if (error.isServerError) { // 5xx —— 服务端问题 } } // 把任意错误转换为 DataApiError const apiError toDataApiError(unknownError, context) // 序列化供 IPC 传输Main → Renderer const serialized apiError.toJSON() // 从 IPC 响应反序列化Renderer const reconstructed DataApiError.fromJSON(response.error)ErrorCode 枚举与状态码映射ErrorCode枚举共 16 个错误码通过ERROR_STATUS_MAP映射到 HTTP 状态码通过ERROR_MESSAGES提供默认消息类别错误码HTTP 状态说明客户端错误BAD_REQUEST400请求格式或参数非法INVALID_OPERATION400当前状态下操作非法非校验错误UNAUTHORIZED401未认证或凭证无效PERMISSION_DENIED403已认证但权限不足NOT_FOUND404资源不存在METHOD_NOT_ALLOWED405端点不支持该 HTTP 方法CONFLICT409资源冲突重名、唯一约束违反VALIDATION_ERROR422请求体未通过校验RATE_LIMIT_EXCEEDED429请求过于频繁服务端错误INTERNAL_SERVER_ERROR500未预期错误DATABASE_ERROR500数据库操作失败SERVICE_UNAVAILABLE503服务暂时不可用TIMEOUT504请求超时应用专用RESOURCE_LOCKED423资源被其他操作临时锁定可重试CONCURRENT_MODIFICATION409乐观锁冲突多窗口编辑同一主题等DATA_INCONSISTENT409数据完整性违反不可重试需排查修复MIGRATION_ERROR500数据迁移失败每个错误码还配有结构化 details 类型ErrorDetailsMap映射ValidationErrorDetails字段级错误、NotFoundErrorDetails、DatabaseErrorDetails、TimeoutErrorDetails、ResourceLockedErrorDetails、ConcurrentModificationErrorDetails等DetailsForCodeT会根据错误码推导出对应的 details 类型。DataApiError 类DataApiErrorT extends ErrorCode是带类型的错误类提供isRetryable基于RETRYABLE_ERROR_CODES配置判定isClientError/isServerError按状态码区间4xx / 5xx判定toJSON()序列化为SerializedDataApiError供 IPC 传输不含堆栈主进程日志为准静态方法fromJSON()从 IPC 响应重建与fromError()把普通 Error 包装默认INTERNAL_SERVER_ERROR。DataApiErrorFactory工厂类提供语义化的创建方法比直接用类更推荐类型更精确create、validation、notFound、database、internal、permissionDenied、timeout、invalidOperation、conflict、dataInconsistent、resourceLocked、concurrentModification。例如notFound(resource, id)会生成Topic with id abc123 not found这样的消息并附带{ resource, id }详情。可重试错误码以下错误码被RETRYABLE_ERROR_CODES集合自动判定为可重试临时性失败重试可能成功SERVICE_UNAVAILABLE503TIMEOUT504RATE_LIMIT_EXCEEDED429DATABASE_ERROR500INTERNAL_SERVER_ERROR500RESOURCE_LOCKED423对应的isRetryableErrorCode(code)函数可直接查询任意错误码是否可重试。toDataApiError 的转换策略toDataApiError(error, context)把任意未知错误归一化为DataApiError已是DataApiError→ 原样返回是序列化错误isSerializedDataApiError→ 通过fromJSON重建是 ZodError通过.name ZodError鸭子类型判断避免引入 zod 依赖→ 把issues转换为字段级fieldErrors生成 422VALIDATION_ERROR是普通Error→ 包装为INTERNAL_SERVER_ERROR其他未知值 → 生成带上下文信息的INTERNAL_SERVER_ERROR。序列化与反序列化SerializedDataApiError结构code/message/status/details/requestContext承载在DataResponse.error字段中跨 IPC 传输DataApiError.toJSON()负责序列化DataApiError.fromJSON()负责重建isSerializedDataApiError负责运行时判定。数据变更通知的类型约束从源码看types.ts还承载了数据变更通知协议的类型化约束GetMethodApiPaths、CollectionGetPaths、ScalarGetPaths、DataApiDataChangeEffect。要点包括只有声明了GET的模板路径才是合法的通知目标GetMethodApiPaths——纯POST路径如/messages/:id/siblings没有可收敛的读状态集合路径CollectionGetPaths由 GET 响应形状判定裸数组或分页响应是集合其余是标量ScalarGetPaths集合与标量的联合成员资格由快照类型测试__tests__/dataChange.types.test.ts钉住schema 变更导致分类翻转时会呈现为可评审的 diffDataApiDataChangeEffect用可判别联合让「非法状态不可表达」标量端点无kind集合端点有projection行内容变化、membership按dimension维度的成员变化、order按dimension排序的位置变化三种 kind。写入提交后主进程广播受影响的读模型渲染端各自订阅并决定收敛动作SQLite 始终是唯一事实来源——effect 不携带实体行、字段 diff、CRUD 动词或命令。架构概览Renderer Main ──────────────────────────────────────────────────── DataApiService ──IPC──► IpcAdapter ──► ApiServer │ │ │ ▼ ApiClient MiddlewareEngine (typed) │ ▼ Handlers (typed)Renderer通过类型安全的ApiClient接口使用DataApiServiceIPC请求经IpcAdapter序列化同时负责validateSender拒绝不可信发送方MainApiServer按路径与方法路由请求经MiddlewareEngine中间件管线处理类型安全从客户端调用到 handler 实现的端到端类型一致。完整的分层职责Handler → Service → SQLite Drizzle ORM与「Repository 模式强烈不推荐」的约定见 DataApi 系统总览客户端用法见 DataApi in Renderer服务端实现见 DataApi in MainRESTful 约定见 API Design Guidelines分页模式细节见 分页指南。实践要点速查新增领域建 schema 文件字段原子共享→ 在 apiSchemas.ts 加入交叉组合 → 在 src/main/data/api/handlers/ 实现 handler三步走全程有编译期兜底AssertValidSchemasApiImplementation。导入规范基础设施类型按模块导入types/errors/paths领域 DTO 从 schema 文件直导不依赖 barrel。分页端点模式固定不可配置cursor 是排他性边界列表 cursor 采用「警告并回退首页」策略搜索 cursor 采用「422 抛出」策略见 分页指南 § Full-Text Search Pagination二者策略不可混用。错误优先用DataApiErrorFactory4xx 不自动重试6 个可重试错误码由RETRYABLE_ERROR_CODES统一配置跨 IPC 传输用toJSON()/fromJSON()。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考