Legado 阅读 3.0 书源调试完全指南:逐级验证搜索、发现、详情、目录与正文规则
Legado 阅读 3.0 书源调试完全指南:逐级验证搜索、发现、详情、目录与正文规则
书源(BookSource)规则编写完成后,能否正确解析目标网站,取决于搜索、发现、详情、目录、正文各环节规则是否与网页实际结构匹配。本文基于 Legado 阅读 3.0(legado-with-MD3)内置的源调试功能,完整讲解调试入口、五种调试目标的输入格式与判定逻辑、调试日志的解读方法,并结合仓库源码(Debug.kt、BookSourceDebugViewModel.kt、BookSourceDebugScreen.kt)说明其底层工作方式,帮助你快速定位规则问题、写出可直接投入使用的书源。
调试入口:源编辑页底部的「调试」按钮
编写完书源规则后,进入「我的书源 → 编辑」页面,页面底部即「调试」按钮。点击后进入调试界面,其 UI 结构可在 BookSourceDebugScreen.kt 中看到:顶部显示当前书源名称,下方是一排目标类型切换芯片(搜索 / 发现 / 详情 / 目录 / 正文),选中目标后输入对应的调试内容,点击悬浮的播放按钮即可开始调试;运行中按钮变为「停止」,右上角可「清空日志」。
调试逻辑与界面展示是分离的:界面层由 BookSourceDebugScreen 负责,状态管理由 BookSourceDebugViewModel 负责,真正的规则解析执行由 Debug 单例对象(Debug.kt)统一调度。Debug.startDebug(viewModelScope, currentSource, key) 会启动一个调试 Session,Session 通过 Channel 持续向界面推送带时间戳与耗时的日志事件,实现逐条实时刷新。
调试搜索:验证搜索规则能否返回书籍列表
切换到「搜索」目标,在输入框中填入搜索关键字,点击开始后,调试引擎会把该关键字作为搜索词发起请求。
输入示例:
系统
源码层面,关键字会进入 Debug.startDebug 的分支判定(Debug.kt 中的 key.isAbsUrl()、key.contains("::")、key.startsWith("++")、key.startsWith("--") 之外的分支即为搜索),随后调用 WebBook.searchBook(scope, bookSource, key, 1) 执行搜索解析(见 WebBook.kt 的 searchBookAwait)。
值得注意的是,BookSourceDebugViewModel 在加载书源时会自动生成一组示例输入(BookSourceDebugViewModel.kt 的 load() 方法):如果书源在「搜索」规则中配置了 checkKeyWord 字段,则优先以该字段作为示例关键字;否则默认提供「我的」和「系统」两个示例。也就是说,即使书源配置了特殊的关键字规则(如需要特定触发词),也能一键复现验证。
调试发现:标题::URL 格式与 {{page}} 分页
「发现」目标用于验证发现页(分类页/榜单页)规则。输入格式为 标题::URL,冒号前是自定义标题(仅用于日志展示),冒号后是发现页地址,支持 {{page}} 分页变量。
输入示例:
排行榜::https://www.example.com/rank?page={{page}}
从 Debug.kt 的分支逻辑看,key.contains("::") 的输入会按 :: 分割,前半部分作为日志中的分类名,后半部分作为 URL,然后调用 WebBook.exploreBook(scope, bookSource, url, 1) 解析发现页,并自动把 {{page}} 替换为当前页码(调试时固定从第 1 页开始)。
BookSourceDebugViewModel 还会通过 exploreKinds()(实现在 BookSourceExtensions.kt)读取书源「发现」规则中配置的每个分类,把分类标题与 URL 自动填充为示例芯片,点击即可直接调试对应分类页,无需手工输入 URL。
调试详情页:直接输入书籍详情页 URL
「详情」目标用于验证详情页规则能否正确提取书名、作者、简介等信息。直接输入一本书籍详情页的完整地址即可。
输入示例:
https://www.example.com/book/12345
因为详情页输入以 http(s) 开头,符合 key.isAbsUrl() 分支,调试引擎会构造一个临时的 Book 对象(设置 origin 为当前书源、bookUrl 为输入的 URL),调用 WebBook.getBookInfo 执行详情解析(Debug.kt 的 infoDebug)。如果详情规则中配置了「目录链接规则」且成功匹配到目录地址,日志会输出「≡已获取目录链接,跳过详情页」并直接进入目录解析,这是书源性能优化的常见写法。
调试目录页:++ 前缀启用正则匹配
「目录」目标验证目录页规则。前缀 ++ 表示使用正则匹配方式处理目录页,即目录 URL 被视为正则表达式来匹配实际地址。
输入示例:
++https://www.example.com/read/12345
在 Debug.kt 中,key.startsWith("++") 分支会去掉 ++ 前缀(key.substring(2)),把剩余部分作为目录 URL 存入 Book.tocUrl,调用 WebBook.getChapterList 解析目录,随后取目录中的第一个正文章节继续验证正文规则。调试输出会直接显示解析出的章节目录,你可以核对章节标题、章节链接、卷名是否符合预期。
调试正文页:-- 前缀启用正则匹配
「正文」目标验证正文页规则。前缀 -- 表示使用正则匹配方式,正文 URL 按正则处理。
输入示例:
--https://www.example.com/chapter/12345/67890
对应 Debug.kt 的 key.startsWith("--") 分支:去掉前缀后构造临时 Book 与 BookChapter(章节标题固定为「调试」),调用 WebBook.getContent(..., needSave = false) 解析正文。needSave = false 表示本次调试不会把解析结果写入书架或本地缓存,因此你可以放心地反复调试任何章节地址,不会污染已收藏书籍的数据。
解读调试日志:过程、响应、错误与完成
调试过程中,结果会以日志卡片形式实时显示在界面中。每条日志都带有相对调试开始时间的耗时(格式为 +x.xxx s)与绝对时间戳。事件类型与卡片配色一一对应(见 BookSourceDebugScreen.kt 的 DebugEntryCard):
| 日志类型 | 含义 | 卡片配色 |
|---|---|---|
| 过程(Message) | 解析步骤提示,如「⇒ 开始访问详情页」「︾ 开始解析目录页」 | 中性色 |
| 搜索/发现响应(SearchSource) | 搜索或发现页提取到的书籍列表 | 主色容器 |
| 详情响应(InfoSource) | 详情页提取到的书籍信息 | 主色容器 |
| 目录响应(TocSource) | 目录页提取到的章节列表 | 主色容器 |
| 正文响应(ContentSource) | 正文页提取到的正文内容 | 主色容器 |
| 错误(Error) | 请求失败或规则执行异常,含堆栈信息 | 错误色容器 |
| 完成(Completed) | 该链路解析结束 | 强调色容器 |
界面顶部还提供四个过滤芯片:全部 / 过程 / 响应 / 错误,可以只查看某一类日志;点击任意日志卡片会弹出 Markdown 浮层,方便完整阅读被截断的正文内容。调试日志列表最多保留 1000 条(MAX_LOG_ENTRIES),运行期间界面会自动滚动到最新一条。
这些事件由 Debug.kt 的 log() 方法产生:方法内部用状态码区分事件类型(-1 错误、10 搜索源、20 详情源、30 目录源、40 正文源、1000 完成),并用 [mm:ss.SSS] 格式记录相对时间;日志前缀符号也有固定语义——⇒ 表示开始执行某一步、︾ 表示开始解析某类页面、︽ 表示解析完成、≡ 表示条件跳转(如跳过详情页)、未获取到书籍/没有正文章节 表示提取结果为空。从源码结构看,这些符号是调试输出约定,帮助你快速判断当前执行到了哪个环节。
完整调试链路:一次运行,四级联动
调试不是孤立的单步执行:当输入的是搜索关键字或发现 URL 时,调试引擎会自动把整条解析链路串联起来(见 Debug.kt):
搜索/发现页解析 → 取第一本书 → 详情页解析 → 取第一个章节 → 目录页解析 → 正文页解析
具体而言,searchDebug / exploreDebug 解析出书籍列表后,会自动取第一本书进入 infoDebug(详情);详情解析完成后若拿到目录链接,则进入 tocDebug(目录);目录解析完成后自动取目录中的第一个正文章节(若存在则取第二个章节,用于验证下一章规则)进入 contentDebug(正文)。因此,一次「调试搜索」就能完整走通一本书的搜索 → 详情 → 目录 → 正文全流程,任何一环出错都会以「错误」日志中断并在对应环节显示堆栈信息。
若只想单独验证某一环,则按前文所述分别使用详情/目录/正文目标输入 URL(目录、正文记得加 ++、-- 前缀)。
常见问题排查技巧
- 搜索有结果但详情为空:检查详情页规则的选择器是否匹配,用「详情」目标单独输入一本书的 URL 复现,看「详情响应」日志实际提取到了哪些字段。
- 发现页分类报错:用「发现」目标输入
标题::URL,确认{{page}}变量是否被正确替换;也可点击 ViewModel 自动生成的分类示例芯片快速定位是哪个分类出了问题。 - 目录/正文提取异常:确认 URL 前是否加了
++/--前缀(正则匹配方式),并核对正则表达式是否与真实地址匹配。 - 规则包含 JS:如果规则中使用了
java.log(),调试时其输出会直接显示在日志中(见 docs/dev/debug.md 的调试技巧),这是排查 JS 规则逻辑最直接的手段。 - 每个调试项独立运行:不同目标之间互不影响,可以逐个排查,避免一次改动多个规则导致问题来源难以定位。
调试日志能直接展示规则实际提取到的内容,与你的预期逐项比对,即可快速锁定是选择器(CSS/XPath/正则)错误、URL 拼接错误还是 JS 逻辑错误,从而高效完成书源的编写与迭代。