Readest Hardcover 进度同步parse-failed故障全剖析edition_id 错误回退的根因、修复与源码级验证【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest本文基于 Readest 仓库内问题跟踪记录apps/readest-app/.claude/memory/hardcover-progress-edition-id-4792.md以及src/services/hardcover/目录下 Hardcover 集成服务的真实源码完整还原一次典型第三方 API 集成故障认证成功、进度推送却整体失败。文章将从报错现象、根因链路、修复方案、当前源码状态四个层面展开帮助读者理解 Hasura Action 错误语义、GraphQL 变量可空性设计以及 Readest 中 Hardcover 同步的完整调用链可直接复用于排查同类API Key 认证成功但业务操作失败的问题。一、故障现象认证通过进度推送却整体失败Issue #4792发现于 v0.11.12记录了这样一个现象用户在 Readest 中完成了 Hardcover 的 API Key 认证GetUserId正常返回用户信息但一旦触发进度同步整个操作以失败告终控制台出现如下错误GraphQL Errors: [{message:parsing Hasura.GraphQL.Execute.Action.Types.ActionWebhookErrorResponse failed, key \message\ not found,extensions:{code:parse-failed}}]这个报错有两个关键特征在 Chrome 中以账号 chrox、书籍《罪与罚》实际复现验证HTTP 状态码为 200——网络请求本身成功错误完全发生在 GraphQL 层code: parse-failed与key message not found——这是 Hasura 在解析 Action 回调响应时抛出的错误而非 Hardcover 业务逻辑返回的业务错误。也就是说问题不在认证、不在网络、不在权限而在于发送给 Hardcover GraphQL API 的 mutation 参数本身非法导致 Hardcover 服务端的 Action 处理器抛异常返回了一个不符合 Hasura 约定缺少message字段的错误体最终被 Hasura 包装成通用的parse-failed。二、根因定位edition_id 为什么会等于 book_id顺着pushProgress的调用链逐层下钻根因浮出水面update_user_book_read即MUTATION_UPDATE_READ发送的edition_id: 713309其实是该书的book_id而不是真实的 edition id。update_user_book_read/insert_user_book_read在 Hardcover 端都是 Hasura Action由服务端 Action 处理器校验并写入非法的 edition 会让 Action 处理器抛错最终表现为上述parse-failed。那么edition_id book_id是怎么产生的可以分三步还原以下链路在修复后的当前仓库源码中依然可辨见 HardcoverClient.ts1. 按标题搜索路径不返回真实 editionReadest 本地书籍匹配 Hardcover 图书有两条路径有 ISBN 走 edition 查询extractISBNQUERY_GET_EDITION无 ISBN 走标题作者搜索。问题出在标题搜索这条路径上。记忆文档记录的是修复前的状态当时的QUERY_SEARCH_BOOKper_page: 1返回原始results文档没有 selectfeatured_edition_id实测命中文档中根本不存在该字段。而当前仓库中该查询已重构为QUERY_SEARCH_BOOKS只返回排序后的ids列表再由QUERY_GET_BOOKS批量水合hydrate完整行数据见 hardcover-graphql.ts彻底摆脱了对搜索索引文档字段形状的依赖——这是修复演进的一部分。2.editionId featured_edition_id ?? bookId的致命回退修复前的searchBookByTitle中有一行关键代码editionId featured_edition_id ?? bookId; // 修复前永远拿不到 featured_edition_id 时必回退 bookId由于标题搜索拿不到featured_edition_id这一行等价于editionId bookId。这就是edition_id book_id的直接来源。3.selectedEdition也为 null无法兜底修正随后QUERY_GET_BOOK_USER_DATA理论上可以通过用户已选的 edition 修正editionIdselectedEdition来自 user_book / read 上的edition字段。但实测中该书是用户未指定任何具体版本添加的user_book与user_book_reads的edition均为 null所以editionId最终保持为bookId一路带入 mutation 发送到服务端。4. 影响面任何无 ISBN、靠标题匹配且 Hardcover 书库条目中未选择具体版本的本地书籍都会把edition_id book_id发送出去触发同一故障。附带地标题搜索本身还存在匹配质量问题例如把《罪与罚》误匹配到一本 Harold Bloom 的评论著作这是另一层面的问题与 edition 回退无直接关系。三、修复方案PR #4794 的四处关键改动修复PR #4794分支fix/hardcover-progress-edition-id的总体原则是把不知道就猜改为不知道就明确为 null让 Hardcover 服务端用自己的默认版本逻辑兜底而不是由客户端传入一个非法 id。四处改动逐条对照当前源码验证如下。1.BookContext.editionId类型改为number | nullHardcoverClient.ts 中BookContext现在显式声明type BookContext { // Null when no real Hardcover edition is known (e.g. a title-search match with // no featured edition and no user-selected edition). Never fall back to the // book id here — Hardcover rejects a book id used as an edition_id (#4792). editionId: number | null; // ... };注释直接点明设计约束没有任何真实 edition 信息时即为 null绝不回退成 book id。2. 移除?? bookId回退当前toBookContextHardcoverClient.ts中 edition 的解析逻辑为const selectedEdition (this.isReadableEdition(activeRead?.edition) ? activeRead?.edition : null) ?? (this.isReadableEdition(userBook?.edition) ? userBook?.edition : null) ?? row.editions?.[0] ?? null; return { editionId: selectedEdition?.id ?? null, // ... };优先级为进行中的阅读记录read所选版本 → 书架条目user_book所选版本 → 该书最热门的可读版本 → 全都没有则为 null。旧的?? bookId回退已彻底删除。注意这里还引入了一个额外的语义约束audio-only 版本reading_format_id 2不算可读版本文本进度永远不会绑定到有声书版本上isReadableEdition见同文件 L129-L137。3. GraphQL mutation 中$edition_id改为可空hardcover-graphql.ts 中三处 mutation 的$edition_id均由必填改为Int可空# MUTATION_INSERT_READL150-L161 mutation InsertRead($user_book_id: Int!, $edition_id: Int, $progress_pages: Int!, $started_at: date!) { insert_user_book_read( user_book_id: $user_book_id user_book_read: { edition_id: $edition_id, progress_pages: $progress_pages, started_at: $started_at } ) { id error } } # MUTATION_UPDATE_READL163-L174 mutation UpdateRead($id: Int!, $progress_pages: Int!, $edition_id: Int, $started_at: date!) { update_user_book_read(id: $id, object: { edition_id: $edition_id, started_at: $started_at, progress_pages: $progress_pages }) { id error } } # MUTATION_INSERT_JOURNALL176-L196同样将 edition_id 置为可空4.insert_user_book在 edition 未知时整体省略该字段新建书架条目时ensureBookInLibraryHardcoverClient.ts不再是传 null而是从请求体中彻底省略edition_idobject: { book_id: context.bookId, // Omit edition_id entirely when unknown so Hardcover falls back to the // books default edition instead of rejecting an invalid one (#4792). ...(context.editionId ! null ? { edition_id: context.editionId } : {}), status_id: 2, },省略与传 null 是有区别的传null走 GraphQL 变量仍可能触发 Hasura 对 Action 输入结构的校验省略字段则让 Hardcover 服务端以自己的默认逻辑书的默认版本落库。5. 实测验证结论Issue 记录修复后的实测矩阵发送内容结果edition_id book_id旧行为parse-failed同步整体失败真实 edition iderror: null同步成功edition_id: nullerror: null且为 no-op不会清空已有版本最后一条尤其重要null 是安全值不会破坏用户此前已经绑定的版本。四、为什么这不是一次新回归历史时间线Issue 记录特意澄清修复前的 buggy 逻辑并非 Readest 近期引入的回归。editionId featured_edition_id ?? bookId的回退写法以及 read mutations 中的edition_id: context.editionId自该功能最初实现issue #37242026-04-03起就存在。它之所以此时集中爆发有三个叠加因素自动同步上线#46142026-06-16随 v0.11.10/v0.11.12 发布进度推送从手动触发变成每次翻页自动触发防抖故障从偶发变成高频必现BookMenu 新增Hardcover Sync → Push Progress手动入口进一步扩大了触发面可能叠加 Hardcover 服务端收紧了 edition 校验使过去能忍的非法参数直接报错。这一判断的价值在于排查同类问题时先怀疑最近上线的自动化流程放大了旧 bug而不是急于回滚或重写整个集成模块。五、围绕该故障的配套机制当前源码1. 自动/手动同步触发链路故障暴露的自动同步实现在 useHardcoverSync.ts自动推送翻页progress?.location变化和标注变化config?.booknotes变化触发防抖推送HARDCOVER_SYNC_DEBOUNCE_MS 1000010 秒见 L15。注释解释了为什么故意设得粗Hardcover 对 API 限流很严约 1 请求/1.15 秒且阅读会话进度不需要秒级精度手动推送BookMenu 的Hardcover Sync子菜单通过eventDispatcher.dispatch(hardcover-push-progress, ...)/hardcover-push-notes事件强制同步BookMenu.tsx手动路径带 toast 反馈自动路径静默错误只进 console收尾保障关闭书籍sync-book-progress事件时flush()挂起的防抖推送组件卸载时cancel()避免翻页后立刻关书丢失最后一次推送useHardcoverSync.ts匹配记忆同步成功后把 Hardcover 图书链接写入书配置rememberLink后续同步跳过标题搜索直接走书 id同时让错误匹配在Link Book界面可见可改。2. 客户端限流与 429 重试HardcoverClient内置两层保护HardcoverClient.tsthrottleRequest保证请求间隔不小于minRequestIntervalMs 1150毫秒request对 429 响应做指数退避重试初始 2 秒最多 3 次重试。这意味着自动同步即使频繁触发也不会把请求洪峰打到 Hardcover。3. Web 端代理转发Web 平台无法直连第三方 API跨域Readest 用 Next.js 路由转发客户端 POST 到/api/hardcover/graphqlroute.ts 原样转发authorization头并透传响应体与状态码。Tauri 桌面端则直连https://api.hardcover.app/v1/graphqlisTauriAppPlatform()分流见 HardcoverClient.ts。排障时 Web 端可以先看代理日志[Hardcover Proxy] response status确认后端收到的是否还是 200。4. 测试覆盖仓库为该模块维护了较完整的单元测试HardcoverClient.test.ts约 1069 行覆盖 accessToken 规范化自动补Bearer前缀、ISBN 从metadata.isbn/identifier/altIdentifier的多来源提取、syncBookNotes去重等核心行为useHardcoverSync.test.tsx覆盖自动/手动同步的 hook 逻辑HardcoverSyncMapStore.test.ts覆盖标注→期刊条目的映射存储。六、经验总结这类故障的排查方法论复盘整个 Issue可以提炼出几条可复用的排查路径分清错误层级parse-failed/ActionWebhookErrorResponse是 Hasura Action 层的包装错误业务错误一定在extensions或 Action 响应体内先别急着怀疑认证与网络验证HTTP 200 ≠ 成功本次故障全程 HTTP 200只在 GraphQLerrors数组里暴露说明客户端必须同时检查res.ok和json.errorsReadest 的request方法正是两者都查HardcoverClient.ts追查兜底默认值凡是出现a ?? b这种回退写法一旦 b 是看起来合法的 id极可能成为故障源——id 类字段应当宁缺毋滥unknown 就传 null 或省略让服务端权威决策对比时间线判断新旧自动化流程上线#4614放大了存量 bug#3724排查时应先问这个 bug 是什么时候引入的又是什么时候开始高频出现的两者答案不同往往指向不同的修复策略。对 Readest 的 Hardcover 集成而言修复后的核心语义可以概括为一句话editionId只在确认真实版本时才携带未知即为 null绝不把 book_id 冒充 edition_id——这个边界至今仍在BookContext的类型注释与ensureBookInLibrary的省略逻辑中坚守着HardcoverClient.ts是后续任何改动都不应触碰的红线。【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Readest Hardcover 进度同步 `parse-failed` 故障全剖析：edition_id 错误回退的根因、修复与源码级验证
Readest Hardcover 进度同步parse-failed故障全剖析edition_id 错误回退的根因、修复与源码级验证【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest本文基于 Readest 仓库内问题跟踪记录apps/readest-app/.claude/memory/hardcover-progress-edition-id-4792.md以及src/services/hardcover/目录下 Hardcover 集成服务的真实源码完整还原一次典型第三方 API 集成故障认证成功、进度推送却整体失败。文章将从报错现象、根因链路、修复方案、当前源码状态四个层面展开帮助读者理解 Hasura Action 错误语义、GraphQL 变量可空性设计以及 Readest 中 Hardcover 同步的完整调用链可直接复用于排查同类API Key 认证成功但业务操作失败的问题。一、故障现象认证通过进度推送却整体失败Issue #4792发现于 v0.11.12记录了这样一个现象用户在 Readest 中完成了 Hardcover 的 API Key 认证GetUserId正常返回用户信息但一旦触发进度同步整个操作以失败告终控制台出现如下错误GraphQL Errors: [{message:parsing Hasura.GraphQL.Execute.Action.Types.ActionWebhookErrorResponse failed, key \message\ not found,extensions:{code:parse-failed}}]这个报错有两个关键特征在 Chrome 中以账号 chrox、书籍《罪与罚》实际复现验证HTTP 状态码为 200——网络请求本身成功错误完全发生在 GraphQL 层code: parse-failed与key message not found——这是 Hasura 在解析 Action 回调响应时抛出的错误而非 Hardcover 业务逻辑返回的业务错误。也就是说问题不在认证、不在网络、不在权限而在于发送给 Hardcover GraphQL API 的 mutation 参数本身非法导致 Hardcover 服务端的 Action 处理器抛异常返回了一个不符合 Hasura 约定缺少message字段的错误体最终被 Hasura 包装成通用的parse-failed。二、根因定位edition_id 为什么会等于 book_id顺着pushProgress的调用链逐层下钻根因浮出水面update_user_book_read即MUTATION_UPDATE_READ发送的edition_id: 713309其实是该书的book_id而不是真实的 edition id。update_user_book_read/insert_user_book_read在 Hardcover 端都是 Hasura Action由服务端 Action 处理器校验并写入非法的 edition 会让 Action 处理器抛错最终表现为上述parse-failed。那么edition_id book_id是怎么产生的可以分三步还原以下链路在修复后的当前仓库源码中依然可辨见 HardcoverClient.ts1. 按标题搜索路径不返回真实 editionReadest 本地书籍匹配 Hardcover 图书有两条路径有 ISBN 走 edition 查询extractISBNQUERY_GET_EDITION无 ISBN 走标题作者搜索。问题出在标题搜索这条路径上。记忆文档记录的是修复前的状态当时的QUERY_SEARCH_BOOKper_page: 1返回原始results文档没有 selectfeatured_edition_id实测命中文档中根本不存在该字段。而当前仓库中该查询已重构为QUERY_SEARCH_BOOKS只返回排序后的ids列表再由QUERY_GET_BOOKS批量水合hydrate完整行数据见 hardcover-graphql.ts彻底摆脱了对搜索索引文档字段形状的依赖——这是修复演进的一部分。2.editionId featured_edition_id ?? bookId的致命回退修复前的searchBookByTitle中有一行关键代码editionId featured_edition_id ?? bookId; // 修复前永远拿不到 featured_edition_id 时必回退 bookId由于标题搜索拿不到featured_edition_id这一行等价于editionId bookId。这就是edition_id book_id的直接来源。3.selectedEdition也为 null无法兜底修正随后QUERY_GET_BOOK_USER_DATA理论上可以通过用户已选的 edition 修正editionIdselectedEdition来自 user_book / read 上的edition字段。但实测中该书是用户未指定任何具体版本添加的user_book与user_book_reads的edition均为 null所以editionId最终保持为bookId一路带入 mutation 发送到服务端。4. 影响面任何无 ISBN、靠标题匹配且 Hardcover 书库条目中未选择具体版本的本地书籍都会把edition_id book_id发送出去触发同一故障。附带地标题搜索本身还存在匹配质量问题例如把《罪与罚》误匹配到一本 Harold Bloom 的评论著作这是另一层面的问题与 edition 回退无直接关系。三、修复方案PR #4794 的四处关键改动修复PR #4794分支fix/hardcover-progress-edition-id的总体原则是把不知道就猜改为不知道就明确为 null让 Hardcover 服务端用自己的默认版本逻辑兜底而不是由客户端传入一个非法 id。四处改动逐条对照当前源码验证如下。1.BookContext.editionId类型改为number | nullHardcoverClient.ts 中BookContext现在显式声明type BookContext { // Null when no real Hardcover edition is known (e.g. a title-search match with // no featured edition and no user-selected edition). Never fall back to the // book id here — Hardcover rejects a book id used as an edition_id (#4792). editionId: number | null; // ... };注释直接点明设计约束没有任何真实 edition 信息时即为 null绝不回退成 book id。2. 移除?? bookId回退当前toBookContextHardcoverClient.ts中 edition 的解析逻辑为const selectedEdition (this.isReadableEdition(activeRead?.edition) ? activeRead?.edition : null) ?? (this.isReadableEdition(userBook?.edition) ? userBook?.edition : null) ?? row.editions?.[0] ?? null; return { editionId: selectedEdition?.id ?? null, // ... };优先级为进行中的阅读记录read所选版本 → 书架条目user_book所选版本 → 该书最热门的可读版本 → 全都没有则为 null。旧的?? bookId回退已彻底删除。注意这里还引入了一个额外的语义约束audio-only 版本reading_format_id 2不算可读版本文本进度永远不会绑定到有声书版本上isReadableEdition见同文件 L129-L137。3. GraphQL mutation 中$edition_id改为可空hardcover-graphql.ts 中三处 mutation 的$edition_id均由必填改为Int可空# MUTATION_INSERT_READL150-L161 mutation InsertRead($user_book_id: Int!, $edition_id: Int, $progress_pages: Int!, $started_at: date!) { insert_user_book_read( user_book_id: $user_book_id user_book_read: { edition_id: $edition_id, progress_pages: $progress_pages, started_at: $started_at } ) { id error } } # MUTATION_UPDATE_READL163-L174 mutation UpdateRead($id: Int!, $progress_pages: Int!, $edition_id: Int, $started_at: date!) { update_user_book_read(id: $id, object: { edition_id: $edition_id, started_at: $started_at, progress_pages: $progress_pages }) { id error } } # MUTATION_INSERT_JOURNALL176-L196同样将 edition_id 置为可空4.insert_user_book在 edition 未知时整体省略该字段新建书架条目时ensureBookInLibraryHardcoverClient.ts不再是传 null而是从请求体中彻底省略edition_idobject: { book_id: context.bookId, // Omit edition_id entirely when unknown so Hardcover falls back to the // books default edition instead of rejecting an invalid one (#4792). ...(context.editionId ! null ? { edition_id: context.editionId } : {}), status_id: 2, },省略与传 null 是有区别的传null走 GraphQL 变量仍可能触发 Hasura 对 Action 输入结构的校验省略字段则让 Hardcover 服务端以自己的默认逻辑书的默认版本落库。5. 实测验证结论Issue 记录修复后的实测矩阵发送内容结果edition_id book_id旧行为parse-failed同步整体失败真实 edition iderror: null同步成功edition_id: nullerror: null且为 no-op不会清空已有版本最后一条尤其重要null 是安全值不会破坏用户此前已经绑定的版本。四、为什么这不是一次新回归历史时间线Issue 记录特意澄清修复前的 buggy 逻辑并非 Readest 近期引入的回归。editionId featured_edition_id ?? bookId的回退写法以及 read mutations 中的edition_id: context.editionId自该功能最初实现issue #37242026-04-03起就存在。它之所以此时集中爆发有三个叠加因素自动同步上线#46142026-06-16随 v0.11.10/v0.11.12 发布进度推送从手动触发变成每次翻页自动触发防抖故障从偶发变成高频必现BookMenu 新增Hardcover Sync → Push Progress手动入口进一步扩大了触发面可能叠加 Hardcover 服务端收紧了 edition 校验使过去能忍的非法参数直接报错。这一判断的价值在于排查同类问题时先怀疑最近上线的自动化流程放大了旧 bug而不是急于回滚或重写整个集成模块。五、围绕该故障的配套机制当前源码1. 自动/手动同步触发链路故障暴露的自动同步实现在 useHardcoverSync.ts自动推送翻页progress?.location变化和标注变化config?.booknotes变化触发防抖推送HARDCOVER_SYNC_DEBOUNCE_MS 1000010 秒见 L15。注释解释了为什么故意设得粗Hardcover 对 API 限流很严约 1 请求/1.15 秒且阅读会话进度不需要秒级精度手动推送BookMenu 的Hardcover Sync子菜单通过eventDispatcher.dispatch(hardcover-push-progress, ...)/hardcover-push-notes事件强制同步BookMenu.tsx手动路径带 toast 反馈自动路径静默错误只进 console收尾保障关闭书籍sync-book-progress事件时flush()挂起的防抖推送组件卸载时cancel()避免翻页后立刻关书丢失最后一次推送useHardcoverSync.ts匹配记忆同步成功后把 Hardcover 图书链接写入书配置rememberLink后续同步跳过标题搜索直接走书 id同时让错误匹配在Link Book界面可见可改。2. 客户端限流与 429 重试HardcoverClient内置两层保护HardcoverClient.tsthrottleRequest保证请求间隔不小于minRequestIntervalMs 1150毫秒request对 429 响应做指数退避重试初始 2 秒最多 3 次重试。这意味着自动同步即使频繁触发也不会把请求洪峰打到 Hardcover。3. Web 端代理转发Web 平台无法直连第三方 API跨域Readest 用 Next.js 路由转发客户端 POST 到/api/hardcover/graphqlroute.ts 原样转发authorization头并透传响应体与状态码。Tauri 桌面端则直连https://api.hardcover.app/v1/graphqlisTauriAppPlatform()分流见 HardcoverClient.ts。排障时 Web 端可以先看代理日志[Hardcover Proxy] response status确认后端收到的是否还是 200。4. 测试覆盖仓库为该模块维护了较完整的单元测试HardcoverClient.test.ts约 1069 行覆盖 accessToken 规范化自动补Bearer前缀、ISBN 从metadata.isbn/identifier/altIdentifier的多来源提取、syncBookNotes去重等核心行为useHardcoverSync.test.tsx覆盖自动/手动同步的 hook 逻辑HardcoverSyncMapStore.test.ts覆盖标注→期刊条目的映射存储。六、经验总结这类故障的排查方法论复盘整个 Issue可以提炼出几条可复用的排查路径分清错误层级parse-failed/ActionWebhookErrorResponse是 Hasura Action 层的包装错误业务错误一定在extensions或 Action 响应体内先别急着怀疑认证与网络验证HTTP 200 ≠ 成功本次故障全程 HTTP 200只在 GraphQLerrors数组里暴露说明客户端必须同时检查res.ok和json.errorsReadest 的request方法正是两者都查HardcoverClient.ts追查兜底默认值凡是出现a ?? b这种回退写法一旦 b 是看起来合法的 id极可能成为故障源——id 类字段应当宁缺毋滥unknown 就传 null 或省略让服务端权威决策对比时间线判断新旧自动化流程上线#4614放大了存量 bug#3724排查时应先问这个 bug 是什么时候引入的又是什么时候开始高频出现的两者答案不同往往指向不同的修复策略。对 Readest 的 Hardcover 集成而言修复后的核心语义可以概括为一句话editionId只在确认真实版本时才携带未知即为 null绝不把 book_id 冒充 edition_id——这个边界至今仍在BookContext的类型注释与ensureBookInLibrary的省略逻辑中坚守着HardcoverClient.ts是后续任何改动都不应触碰的红线。【免费下载链接】readestReadest is a modern, feature-rich ebook reader designed for avid readers offering seamless cross-platform access, powerful tools, and an intuitive interface to elevate your reading experience.项目地址: https://gitcode.com/gh_mirrors/re/readest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考