Files
SakuraHub/docs/在线搜索-书本章节导航-完整解决方案.md
2026-11-16 20:45:22 +08:00

44 KiB
Raw Permalink Blame History

在线搜索错误修复 与 书→目录→章节 导航流程 — 完整解决方案

分析日期:2026-06-21 参考项目:legado-with-MD3 涉及范围:Sakura Mobile (Flutter) 说明:本文档提供完整的问题分析与解决方案设计,不包含实际代码改动。


目录

  1. 总体结论
  2. 问题诊断
  3. P0:必须优先修改
  4. P1:第二阶段修改
  5. P2:后续增强
  6. 优先级总表
  7. 页面与数据流设计
  8. 数据模型扩展
  9. Legado 书源规则字段对照
  10. 附录:关键文件清单

一、总体结论

不要只修 UI,也不要只做错误提示兜底。

真正应该改成的完整流程是:

搜索页 (ExplorePage)
  ↓
在线书籍详情页 (OnlineBookDetailPage)  ← 合并 BookInfo + TOC 的 UI
  ├─ 书籍信息(封面、书名、作者、来源、简介)
  ├─ 章节列表(内嵌加载,不跳独立 TOC 页)
  │    ├─ 分页加载
  │    └─ 正序/倒序切换
  └─ 快捷操作:「从第一章开始阅读」「保存到书架」
       ↓
    阅读器 (OnlineMangaReaderPage / OnlineNovelReaderPage)
      ├─ 章节驱动(非 URL 驱动)
      ├─ 上一章 / 下一章 导航
      ├─ 下一章预加载
      └─ 阅读记录

核心理念:

页面合并,解析分层;
缓存前置,持久化后置;
目录回退要识别章节,不要盲扫链接;
阅读器必须从 URL 驱动改成章节驱动。

二、问题诊断

2.1 问题一:搜索结果显示 unknown:none

现象

用户在 APP 在线搜索漫画/小说时,搜索结果中某些条目显示为 unknown:none。

根因

位置:sakura_mobile/lib/src/core/legado_engine.dart:563-569

var message = error
    .toString()
    .replaceFirst(RegExp(r'^(Exception|StateError):\s*'), '');
if (message.trim() == '[unknown]: null' || message.trim() == 'null') {
  message = 'Target site returned an empty or invalid response.';
}

当前只匹配了 [unknown]: null 和 null,但 Dio 在不同平台、不同错误类型下会抛出多种格式的底层异常消息:

平台/场景 可能的错误消息 是否处理
Android [unknown]: null ✅ 已匹配
Android [unknown]: none ❌ 漏掉,原样展示
iOS Connection failed: unknown:none ❌ 漏掉
Windows 桌面 DioException [unknown]: null ❌ 部分匹配失败
超时 Connection timed out ❌ 漏掉
DNS 失败 No address associated with hostname ❌ 漏掉
编码错误 FormatException: Bad UTF-8 encoding ❌ 走 FormatException 分支,不友好

这些未处理的错误消息被原样透传到 SearchItem.errorMessage,最终在 UI 的 subtitle 中展示为 源名称 - unknown:none。

搜索结果字段提取失败的连锁反应

位置:legado_engine.dart:60-98

当书源的解析规则与目标网站 HTML 结构不匹配时:

  • title 为空 → 该结果被 .where() 过滤掉 → 整个源的搜索结果为空
  • author 为空 → subtitle 中显示为 null
  • detailUrl 为空 → 点击后 URL 为空 → 报错

2.2 问题二:缺少「书→目录→章节」导航流程

现象

用户搜索到一本书后,点击结果直接进入阅读器,而不是进入书籍详情页。结果是:

  1. 阅读器把书籍详情页 HTML 当正文展示 → 乱码/空白/无关图片
  2. 用户看不到章节列表,无法选择具体章节阅读

根因一:数据模型缺少三个关键规则模块

位置:sakura_mobile/lib/src/core/legado_models.dart:21-86

当前 LegadoSource 只包含搜索相关的规则字段:

searchUrl, searchListRule, searchNameRule, searchAuthorRule,
searchCoverRule, searchDetailRule, searchMethod, searchBody

完全缺失 Legado 标准书源中的三个关键规则模块:

模块 作用 关键字段
ruleBookInfo 解析书籍详情页 → 得到元数据 + 目录 URL name, author, cover, intro, tocUrl
ruleToc 解析目录页 → 得到章节列表 chapterList, chapterName, chapterUrl
ruleContent 解析章节页 → 得到正文/图片 content, nextChapterUrl, prevChapterUrl

这三个模块是 Legado 生态的标准配置,被数千个书源规则所遵循。当前项目只实现了其中的搜索模块。

根因二:搜索结果点击逻辑错误

位置:sakura_mobile/lib/src/pages/explore_page.dart:174-228 (_openItem 方法)

// 在线结果 → 直接打开阅读器(❌ 错误!)
if (mode == UnifiedSearchMode.manga) {
  Navigator.of(context).push(MaterialPageRoute(
    builder: (_) => OnlineMangaReaderPage(
      source: source, title: item.title,
      detailUrl: item.detailUrl ?? item.coverUrl ?? '',  // ← 书籍详情页 URL!
    ),
  ));
}

detailUrl 在 Legado 规则中的语义是书籍详情页 URL,不是章节内容 URL。这个 URL 指向的页面包含封面、书名、作者、简介、章节目录链接——唯独没有章节正文。

将此 URL 直接传入阅读器,阅读器会:

  • 漫画:调用 fetchImageUrls() → 提取详情页所有 <img> → 返回封面 + 广告图 + 导航图标
  • 小说:调用 fetchPlainText() → 提取详情页纯文本 → 返回简介混合着页面导航文字

根因三:阅读器缺少章节概念

两个在线阅读器都接收单一的 detailUrl 参数,没有:

  • 章节列表
  • 上一章/下一章导航
  • 阅读进度记录

三、P0:必须优先修改

这些是当前问题的直接根因,需要最先实施。

1. 修复 unknown:none 错误展示

修改位置:sakura_mobile/lib/src/core/legado_engine.dart → _shortError() 方法

目标:将所有 Dio 底层异常消息逐一映射为用户可读的中文提示,不再有原始异常消息泄漏到 UI。

错误消息映射表:

[unknown]: null        → 目标站点返回了空响应,请检查书源是否仍然有效
[unknown]: none        → 目标站点连接失败,请检查网络或更换书源
unknown:none           → 连接异常,书源可能已失效
Connection refused     → 目标站点拒绝了连接,可能需要 Cookie 或反爬处理
Connection timed out   → 连接超时,请稍后重试
No address associated  → 无法解析目标站点域名,请检查网络
Bad UTF-8 encoding     → 响应编码异常,请检查书源的 charset 配置
null                   → 目标站点返回了无效响应

实现思路:

String _shortError(Object error) {
  // 1. Dio 网络异常 — 按错误类型精准映射
  if (error is DioException) {
    final host = error.requestOptions.uri.host;
    final target = host.isEmpty ? '目标站点' : host;
    switch (error.type) {
      case DioExceptionType.connectionTimeout:
      case DioExceptionType.receiveTimeout:
      case DioExceptionType.sendTimeout:
        return '连接 $target 超时,请稍后重试。';
      case DioExceptionType.connectionError:
        return '无法连接 $target,请检查网络或更换书源。';
      case DioExceptionType.badResponse:
        final code = error.response?.statusCode ?? 0;
        if (code == 404) return '书源搜索接口已失效(404)。';
        if (code == 403 || code == 444) return '$target 拒绝了访问,可能需要 Cookie 配置。';
        return '$target 返回了异常状态(HTTP $code)。';
      default:
        break;
    }
  }

  // 2. FormatException — 编码/格式问题
  if (error is FormatException) {
    final msg = error.message.toLowerCase();
    if (msg.contains('utf') || msg.contains('encoding'))
      return '响应编码异常,请检查书源的 charset 配置。';
    return '书源规则期望 JSON 格式,但站点返回了其他内容。';
  }

  // 3. 原始消息归一化 — 兜底处理所有未分类的异常文本
  var message = error
      .toString()
      .replaceFirst(RegExp(r'^(Exception|StateError|DioException):\s*'), '');
  final trimmed = message.trim();

  // 按精确度从高到低匹配
  if (trimmed == '[unknown]: null' || trimmed == 'null')
    return '目标站点返回了空响应,请检查书源是否仍然有效。';
  if (trimmed == '[unknown]: none' || trimmed == 'unknown:none')
    return '连接异常,书源可能已失效。';
  if (trimmed.toLowerCase().contains('connection refused'))
    return '目标站点拒绝了连接。';
  if (trimmed.toLowerCase().contains('connection timed out'))
    return '连接超时,请稍后重试。';
  if (trimmed.toLowerCase().contains('no address associated'))
    return '无法解析目标站点域名,请检查网络。';

  // 4. 兜底截断,避免超长异常堆栈泄漏到 UI
  if (message.length > 120) message = '${message.substring(0, 120)}...';
  return message.isEmpty ? '未知错误' : message;
}

同时修改 UI 层(explore_page.dart::_SearchResultTile):

  • 当 item.author 为空时显示"未知作者"而非空白
  • 当 item.isError 时,subtitle 中的错误消息不应再包含原始异常类名

2. 扩展 LegadoSource 数据模型

修改位置:sakura_mobile/lib/src/core/legado_models.dart

当前模型只支持搜索规则。需要新增三个规则模块的字段。

新增字段:

class LegadoSource {
  // ===== 现有字段(保持不变)=====
  final String id;
  final String name;
  final String url;
  final int type;          // 0=小说, 2=漫画
  final bool enabled;
  final String? userAgent;
  final Map<String, String> headers;
  // ... 现有搜索规则字段 ...

  // ===== 🆕 BookInfo 规则(从 ruleBookInfo 解析)=====
  final String? bookInfoUrl;          // 详情页 URL 模板(可选,默认用搜索结果的 detailUrl)
  final String? bookInfoNameRule;     // 提取书名(CSS 选择器)
  final String? bookInfoAuthorRule;   // 提取作者
  final String? bookInfoCoverRule;    // 提取封面
  final String? bookInfoIntroRule;    // 提取简介
  final String? bookInfoTocRule;      // 提取目录页 URL ⭐ 最关键字段

  // ===== 🆕 TOC 规则(从 ruleToc 解析)=====
  final String? tocUrl;               // 目录页 URL 模板(可选,支持 {{page}})
  final String? tocListRule;          // 提取章节条目列表
  final String? tocNameRule;          // 提取章节名称
  final String? tocUrlRule;           // 提取章节链接
  final String? tocNextPageRule;      // 提取下一页目录的 URL(用于分页)

  // ===== 🆕 Content 规则(从 ruleContent 解析)=====
  final String? contentRule;          // 提取正文/图片内容
  final String? contentNextRule;      // 提取下一章链接
  final String? contentPrevRule;      // 提取上一章链接
}

fromJson() 中新增的解析逻辑:

// 从 ruleBookInfo 提取
final bookInfo = _map(json['ruleBookInfo']);
bookInfoNameRule = _firstString([
  bookInfo['name'], bookInfo['bookName'],
]);
bookInfoAuthorRule = _firstString([
  bookInfo['author'], bookInfo['bookAuthor'],
]);
bookInfoCoverRule = _firstString([
  bookInfo['coverUrl'], bookInfo['cover'],
]);
bookInfoIntroRule = _firstString([
  bookInfo['intro'], bookInfo['introduce'], bookInfo['desc'],
]);
bookInfoTocRule = _firstString([
  bookInfo['tocUrl'], bookInfo['chapterUrl'],
  bookInfo['catalogUrl'], bookInfo['directoryUrl'],
]);

// 从 ruleToc 提取
final toc = _map(json['ruleToc']);
tocListRule = _firstString([
  toc['chapterList'], toc['chapters'], toc['list'],
]);
tocNameRule = _firstString([
  toc['chapterName'], toc['name'], toc['title'],
]);
tocUrlRule = _firstString([
  toc['chapterUrl'], toc['url'], toc['href'],
]);
tocNextPageRule = _firstString([
  toc['nextTocUrl'], toc['nextPage'], toc['nextPageUrl'],
]);

// 从 ruleContent 提取
final content = _map(json['ruleContent']);
contentRule = _firstString([
  content['content'], content['text'], content['body'],
]);
contentNextRule = _firstString([
  content['nextChapterUrl'], content['next'], content['nextPage'],
]);
contentPrevRule = _firstString([
  content['prevChapterUrl'], content['prev'], content['prevPage'],
]);

copyWith 也需要同步扩展,确保 setEnabled() 等现有方法能正常工作。


3. 新增在线书籍详情页(合并 BookInfo + TOC UI)

新增文件:sakura_mobile/lib/src/pages/online_book_detail_page.dart

关键设计决策:不要创建独立的 OnlineTocPage。将 BookInfo 和章节列表放在同一个页面中,但数据加载保持两次独立请求(因为很多书源的 detailUrl ≠ tocUrl)。

┌──────────────────────────────────────┐
│  ← 返回       书籍详情         📤     │  AppBar
├──────────────────────────────────────┤
│                                      │
│        ┌──────────────┐              │
│        │              │              │  封面图
│        │   书籍封面    │              │  (CachedNetworkImage)
│        │              │              │
│        └──────────────┘              │
│                                      │
│  斗罗大陆                             │  书名(大标题)
│  唐家三少 · 笔趣阁 · 连载中           │  作者/来源/状态 一行
│                                      │
│  ┌──────────────────────────────┐    │
│  │ 简介                            │  简介卡片
│  │ 唐门外门弟子唐三,因偷学内门   │  (可展开/收起)
│  └──────────────────────────────┘    │
│                                      │
│  ┌──────────────────────────────┐    │
│  │  ▶ 从第一章开始阅读            │  快捷操作按钮
│  └──────────────────────────────┘    │
│  ┌──────────────────────────────┐    │
│  │  💾 保存到书架                │  保存操作
│  └──────────────────────────────┘    │
│                                      │
│  ──────── 章节目录 (共 336 章) ─────  │  分隔标题
│         [正序 ↑] [倒序 ↓]            │  排序切换
│                                      │
│  ┌──────────────────────────────────┐│
│  │ 📖 第一章 楔子                    ││  章节条目
│  └──────────────────────────────────┘│
│  ┌──────────────────────────────────┐│
│  │ 📖 第二章 唐三的武魂               ││
│  └──────────────────────────────────┘│
│  ┌──────────────────────────────────┐│
│  │ 📖 第三章 修炼之路                 ││
│  └──────────────────────────────────┘│
│  ┌──────────────────────────────────┐│
│  │ ... 更多章节(滚动加载)           ││  支持无限滚动
│  │     正在加载第2页...              ││  TOC 分页指示器
│  └──────────────────────────────────┘│
│                                      │
└──────────────────────────────────────┘

数据加载方式(分段异步):

第一步:请求 BookInfo(用 bookInfoRule 解析 detailUrl)
  → 拿到 title, author, cover, intro, tocUrl
  → 立即渲染页面上半部分(封面+书名+作者+简介+快捷按钮)
  → 章节列表区域显示骨架屏 loading

第二步:请求 TOC(用 chapterListRule 解析 tocUrl)
  → 拿到 List<OnlineChapter>
  → 章节列表区域从骨架屏切换为真实数据
  → 如果有 tocNextPageRule,继续加载后续页

两步之间不互相阻塞:BookInfo 失败 → 整个页面显示错误;TOC 失败 → 上半部分正常展示,下半部分显示"目录加载失败,点击重试"

重要:

合并页面 ≠ 合并请求

因为很多书源:
  detailUrl (书籍详情页)
  ≠
  tocUrl (章节目录页,可能是独立的分页 URL)

详情和目录必须允许两次独立的 HTTP 请求。

4. 修改搜索结果点击逻辑

修改位置:sakura_mobile/lib/src/pages/explore_page.dart → _openItem() 方法

当前逻辑(错误):

点击在线结果 → 直接打开 OnlineMangaReaderPage / OnlineNovelReaderPage
  (把 detailUrl 当成章节内容 URL 传给阅读器)

改为:

点击在线结果 → 打开 OnlineBookDetailPage(detailUrl)
  → 用户在详情页看到书籍信息 + 章节列表
  → 点击某个章节 → 打开阅读器(传入章节 URL)
  → 或点击「从第一章开始阅读」→ 自动打开第一个章节
void _openItem(SearchItem item) {
  // 云库结果(不变)
  if (item.artwork != null) {
    Navigator.of(context).push(
      MaterialPageRoute(builder: (_) => ArtworkDetailPage(artwork: item.artwork!)),
    );
    return;
  }
  if (item.novel != null) {
    Navigator.of(context).push(
      MaterialPageRoute(builder: (_) => NovelReaderPage(novel: item.novel!)),
    );
    return;
  }

  // 在线结果 — 🆕 改为跳转到详情页
  final online = item.online;
  if (item.isError) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(item.errorMessage ?? '搜索失败,请稍后再试。')),
    );
    return;
  }
  if (online == null) return;

  final source = ref.read(sourceManagerProvider).sourceById(online.sourceId);
  if (source == null) {
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('书源已不可用。')),
    );
    return;
  }

  // 🆕 跳转到在线书籍详情页
  Navigator.of(context).push(
    MaterialPageRoute(
      builder: (_) => OnlineBookDetailPage(
        source: source,
        initialTitle: item.title,
        initialAuthor: item.author,
        initialCoverUrl: item.coverUrl,
        detailUrl: item.detailUrl ?? '',
        mode: mode,  // manga 或 novel
      ),
    ),
  );
}

5. 增加会话级内存缓存

修改位置:sakura_mobile/lib/src/core/legado_engine.dart 或新建独立缓存文件

第一版用内存缓存即可,不要着急上 Hive/Isar。

/// 会话级内存缓存
class OnlineContentCache {
  // 存活时间:当次 APP 会话
  final _bookInfoCache = <String, OnlineBookInfo>{};
  final _tocCache = <String, List<OnlineChapter>>{};
  final _chapterCache = <String, OnlineChapterContent>{};

  // 缓存 key 规则:source.id + URL
  String _key(String sourceId, String url) => '$sourceId|$url';

  // BookInfo
  OnlineBookInfo? getBookInfo(String sourceId, String url) =>
      _bookInfoCache[_key(sourceId, url)];
  void putBookInfo(String sourceId, String url, OnlineBookInfo info) =>
      _bookInfoCache[_key(sourceId, url)] = info;

  // TOC(章节列表)
  List<OnlineChapter>? getToc(String sourceId, String tocUrl) =>
      _tocCache[_key(sourceId, tocUrl)];
  void putToc(String sourceId, String tocUrl, List<OnlineChapter> chapters) =>
      _tocCache[_key(sourceId, tocUrl)] = chapters;

  // Chapter(单章内容)
  OnlineChapterContent? getChapter(String sourceId, String chapterUrl) =>
      _chapterCache[_key(sourceId, chapterUrl)];
  void putChapter(String sourceId, String chapterUrl, OnlineChapterContent content) =>
      _chapterCache[_key(sourceId, chapterUrl)] = content;

  // 预加载下一章(阅读器中调用)
  void preloadNextChapter(String sourceId, String nextUrl) {
    // 由阅读器在后台触发,不阻塞当前阅读
  }

  void clear() {
    _bookInfoCache.clear();
    _tocCache.clear();
    _chapterCache.clear();
  }
}

缓存策略:

  • BookInfo:进入详情页时先查缓存,未命中才请求
  • TOC:目录可能有几百章,每次进页面重新请求既慢也会增加书源站点压力——优先读缓存
  • ChapterContent:只缓存当前章 + 预加载下一章,不要一口气缓存全部章节正文(容易占内存)

为什么阶段一不用持久化缓存:

  • 在线书源的内容可能变化(网站改版、章节更新),持久化缓存容易导致过期数据
  • 先跑通主流程,确认缓存策略合理后,P2 阶段再引入 Hive/Isar
  • 会话级缓存已能覆盖"用户在详情页和阅读器之间来回切换"的核心场景

6. 章节识别器回退策略(替代盲扫 <a> 标签)

修改位置:sakura_mobile/lib/src/core/legado_engine.dart → 新增 _chapterAwareFallback() 方法

问题:原方案中的 _fallbackSearchResults 和自动扫描 <a> 都太激进——会把导航链接、广告链接、面包屑链接都当成章节。

改进:引入"章节识别器"——即使用正则匹配章节标题特征,而非盲扫所有链接。

/// 章节标题特征正则
static final _chapterPatterns = [
  // 中文数字章节
  RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*[章节话卷回]'),
  // 中文数字话
  RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*话'),
  // 纯数字章节
  RegExp(r'第\s*\d+\s*[章节话卷回]'),
  // 英文章节
  RegExp(r'Chapter\s*\d+', caseSensitive: false),
  RegExp(r'Episode\s*\d+', caseSensitive: false),
  // 卷
  RegExp(r'Vol\.?\s*\d+', caseSensitive: false),
  RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*卷'),
  // 纯数字话
  RegExp(r'^\d+\s*[话章]'),
];

/// 判断文本是否像一个章节标题
bool _looksLikeChapterTitle(String text) {
  final trimmed = text.trim();
  if (trimmed.length < 2 || trimmed.length > 80) return false;
  for (final pattern in _chapterPatterns) {
    if (pattern.hasMatch(trimmed)) return true;
  }
  return false;
}

/// 回退目录解析:扫描 HTML 中的 <a> 标签,但只保留符合章节标题特征的
List<OnlineChapter> _fallbackTocParser(String body, String baseUrl) {
  final seen = <String>{};
  final chapters = <OnlineChapter>[];

  final links = RegExp(
    r"<a\b[^>]*\bhref=[\"']([^\"']+)[\"'][^>]*>(.*?)</a>",
    caseSensitive: false,
    dotAll: true,
  ).allMatches(body);

  for (final match in links) {
    final href = match.group(1)?.trim() ?? '';
    if (href.isEmpty || href.startsWith('#') ||
        href.toLowerCase().startsWith('javascript:')) continue;

    final title = _htmlToText(match.group(2) ?? '');
    if (!_looksLikeChapterTitle(title)) continue;  // ← 关键过滤

    final url = _resolveUrl(baseUrl, href);
    if (url.isEmpty || !seen.add(url)) continue;

    chapters.add(OnlineChapter(
      title: title,
      url: url,
      index: chapters.length + 1,
    ));
  }
  return chapters;
}

解析优先级:

1. 如果 tocListRule 可用 → 使用规则解析(精确)
2. 如果 tocListRule 不可用 → 使用章节识别器扫描(降级但可控)
3. 返回结果 ≤ 2 条 → 不做二次请求,直接展示(可能书源确实只有少量章节,也可能是网站结构不支持回退解析)

四、P1:第二阶段修改

这些依赖于 P0 的数据模型和详情页基础设施就绪。

1. 阅读器改造成章节驱动

修改位置:online_manga_reader_page.dart 和 online_novel_reader_page.dart

当前:读取器接收 detailUrl(其实是书籍详情页 URL),从中提取所有图片/文本。

改造后:读取器接收章节级参数。

class OnlineMangaReaderPage extends ConsumerStatefulWidget {
  const OnlineMangaReaderPage({
    super.key,
    required this.source,
    required this.bookTitle,          // 🆕 书名(用于 AppBar / 阅读记录)
    required this.chapters,           // 🆕 完整章节列表
    required this.currentChapterIndex,// 🆕 当前章节序号
    this.currentChapterUrl,           // 当前章节 URL(优先于从 chapters 取)
  });

  final LegadoSource source;
  final String bookTitle;
  final List<OnlineChapter> chapters;
  final int currentChapterIndex;
  final String? currentChapterUrl;
}

进入阅读器时的数据加载:

1. 从 chapters[currentChapterIndex].url 取章节 URL
2. 如果有 contentRule → 用 contentRule 解析
3. 如果没有 contentRule → 回退到现有的 fetchImageUrls / fetchPlainText
4. 用 contentNextRule 提取下一章 URL(优先于 chapters 数组)
5. 用 contentPrevRule 提取上一章 URL

阅读器底部导航:

┌───────────┬───────────┬───────────┐
│ ← 上一章   │  📋 目录   │  下一章 → │
└───────────┴───────────┴───────────┘
  • "上一章":currentChapterIndex > 0 时才可用
  • "下一章":currentChapterIndex < chapters.length - 1 或 contentNextRule 解析到了 URL 时才可用
  • "目录":Navigator.pop() 回到详情页(章节列表已缓存,无需重新加载)

2. 支持目录分页 {{page}}

修改位置:legado_engine.dart → 新增 _fetchPaginatedToc() 方法

问题:很多书源的目录是分页的,URL 模板包含 {{page}} 占位符,例如:

/chapterlist/123?page={{page}}

如果不处理分页,只能拿到第一页的章节(通常几十章),后面几百章全部丢失。

实现:

Future<List<OnlineChapter>> _fetchPaginatedToc(
  LegadoSource source,
  String tocUrlTemplate,
) async {
  final allChapters = <OnlineChapter>[];
  const maxPages = 20;  // 防止死循环
  String? nextPageUrl = tocUrlTemplate;

  for (int page = 1; page <= maxPages; page++) {
    // 1. 替换 {{page}} 占位符
    final url = nextPageUrl!
        .replaceAll('{{page}}', page.toString())
        .replaceAll('{page}', page.toString());

    // 2. 请求并解析当前页
    final body = await _fetchBody(source, url);
    final parser = RuleParser(body, baseUrl: source.url);

    // 3. 用规则解析章节条目
    final fragments = _safeSelectList(parser, source.tocListRule);
    for (final fragment in fragments) {
      final name = _safeSelect(parser, fragment, source.tocNameRule);
      final chapterUrl = _safeSelect(parser, fragment, source.tocUrlRule);
      if (name.isNotEmpty && chapterUrl.isNotEmpty) {
        allChapters.add(OnlineChapter(
          title: name,
          url: _resolveUrl(url, chapterUrl),
          index: allChapters.length + 1,
        ));
      }
    }

    // 4. 检查是否有下一页
    if (source.tocNextPageRule != null) {
      nextPageUrl = _safeSelect(parser, body, source.tocNextPageRule);
      if (nextPageUrl == null || nextPageUrl.isEmpty) break;  // 没有下一页了
    } else {
      // 如果没有 nextPageRule,尝试自动检测:如果当前页有 {{page}},则用 page+1 继续
      if (!tocUrlTemplate.contains('{{page}}') &&
          !tocUrlTemplate.contains('{page}')) {
        break;  // URL 模板中没有分页占位符,不继续
      }
      // 如果当前页返回的章节数与上一页相同,可能到底了,也停止
    }
  }

  return allChapters;
}

自动停止条件:

  • tocNextPageRule 返回空 → 停止
  • 当前页返回 0 条新章节 → 停止
  • 达到 maxPages(20 页)→ 停止并打日志
  • 当前页与上一页完全重复 → 停止(防止环形分页)

3. 章节预加载

修改位置:阅读器页面

策略:阅读当前章节时,后台预加载下一章内容。

用户正在读第 3 章
  │
  ├─ 立即请求:第 3 章内容(用 contentRule 解析)
  │
  └─ 后台请求:第 4 章内容(放入 chapterCache)
       │
       └─ 用户点"下一章" → 缓存命中 → 秒切
void _preloadNextChapter() {
  final nextIdx = currentChapterIndex + 1;
  if (nextIdx >= chapters.length) return;

  final nextChapter = chapters[nextIdx];
  final cacheKey = cache.key(source.id, nextChapter.url);

  if (cache.getChapter(source.id, nextChapter.url) != null) return; // 已缓存

  // 异步预加载,不阻塞当前渲染
  _engine.fetchChapterContent(source, nextChapter.url)
      .then((content) {
        cache.putChapter(source.id, nextChapter.url, content);
      })
      .catchError((_) {
        // 预加载失败静默忽略,用户点到下一章时再重试
      });
}

注意:

  • 只预加载下一章,不要一口气预加载全部(几百章的图片会爆内存)
  • 预加载失败静默忽略,点击"下一章"时再重新请求

4. 阅读记录

新增数据模型:

class OnlineReadingRecord {
  final String sourceId;
  final String sourceName;
  final String bookTitle;
  final String detailUrl;
  final String chapterUrl;
  final String chapterTitle;
  final int chapterIndex;
  final int totalChapters;
  final DateTime lastReadTime;
}

存储方式(P1 阶段):SharedPreferences 存储 JSON 数组,最多保留 50 条最近记录。

用途:

  • 「继续阅读」入口(在 ExplorePage 或首页)
  • 章节已读标记(在详情页章节列表中显示 ✓ 或灰色)
  • 返回详情页时自动定位到上次阅读的章节

记录时机:

  • 进入某章阅读 → upsert 阅读记录
  • 切换章节 → 更新阅读记录
  • 返回详情页 → 不记录(只记录"阅读"行为)

五、P2:后续增强

主流程稳定后再做这些。

1. 持久化缓存

从内存缓存升级到本地持久化:

方案 适用场景
Hive 轻量,适合存储 BookInfo / TOC / 阅读记录
Isar 功能更强,适合存储章节缓存 + 全文搜索
SQLite / sqflite 最灵活,适合复杂查询(按书源查、按时间查等)

建议:Hive 作为第一选择,因为数据模型简单且已广泛用于 Flutter 缓存场景。

持久化内容:

  • BookInfo → 按 sourceId + detailUrl 存储,有效期 24 小时
  • TOC → 按 sourceId + tocUrl 存储,有效期 12 小时
  • 阅读记录 → 永久存储,最多 200 条
  • 章节内容 → 只缓存最近阅读的 20 章

2. ContentType 支持

初期不需要设计 enum ContentType { text, image, mixed }。

因为已有 bookSourceType:

  • type == 0 → 小说 → contentRule 提取文本
  • type == 2 → 漫画 → contentRule 提取图片

mixed 类型(小说中插图片、漫画中插文字)可以后期再支持。

3. 高级 Legado 规则支持

后续逐步补充:

  • JSONPath 规则($.data.chapters[*])
  • Regex 规则(regex:...)
  • webJs 规则(需要 WebView 执行 JS 后取结果)
  • replaceRegex(正文净化,去广告/去水印)
  • 图片解密(部分漫画网站对图片做了简单加密,需要 JS 解密后 base64 展示)

这些是 Legado 生态的高级功能,不影响主体流程,可以逐步按需实现。

4. 更完整的兼容测试

  • 覆盖至少 10 个不同类型的书源(小说/漫画、GBK/UTF-8、分页/单页目录)
  • 测试老书源(只有搜索规则,没有 ruleBookInfo / ruleToc)的回退表现
  • 测试网络异常情况(超时、DNS 失败、404、403)

六、优先级总表

P0:必须优先修改
├─ 1. unknown:none 错误归一化
├─ 2. 扩展 LegadoSource 模型(ruleBookInfo / ruleToc / ruleContent)
├─ 3. 新增 OnlineBookDetailPage(合并 BookInfo + TOC UI)
├─ 4. BookInfo + TOC 分段异步加载
├─ 5. 搜索结果点击进入详情页(explore_page.dart 导航逻辑)
├─ 6. 会话级内存缓存(BookInfo / TOC / Chapter)
└─ 7. 章节识别器回退策略(替代盲扫 <a>)

P1:第二阶段修改
├─ 1. 阅读器改造成章节驱动(接收 chapters + currentChapterIndex)
├─ 2. contentRule 正式接入(提取章节正文/图片)
├─ 3. 目录分页 {{page}} 支持
├─ 4. 下一章预加载
└─ 5. 阅读记录(继续阅读 / 已读标记)

P2:后续增强
├─ 1. 持久化缓存(Hive)
├─ 2. ContentType / mixed 内容
├─ 3. 高级 Legado 规则支持(JSONPath / webJs / replaceRegex)
└─ 4. 更完整的兼容测试

七、页面与数据流设计

7.1 整体架构

┌─────────────────────────────────────────────────────────┐
│                    在线搜索 (ExplorePage)                 │
│  输入关键词 → 并发搜索已启用的书源 → 展示结果列表        │
└───────────────────────┬─────────────────────────────────┘
                        │ 用户点击某本书
                        ▼
┌─────────────────────────────────────────────────────────┐
│          在线书籍详情页 (OnlineBookDetailPage) 🆕        │
│                                                         │
│  ┌─── 上半部分:BookInfo ───┐                           │
│  │  封面 · 书名 · 作者 · 来源 │  ← 第一步加载            │
│  │  状态 · 简介              │                          │
│  │  [开始阅读] [保存到书架]   │                          │
│  └──────────────────────────┘                           │
│                                                         │
│  ┌─── 下半部分:TOC ────────┐                           │
│  │  章节目录 (共 336 章)     │  ← 第二步加载(独立请求) │
│  │  [正序] [倒序]            │                          │
│  │  第一章 · 第二章 · ...    │  支持分页加载            │
│  └──────────────────────────┘                           │
└───────────────────────┬─────────────────────────────────┘
                        │ 点击某章节
                        ▼
┌─────────────────────────────────────────────────────────┐
│       在线阅读器 (MangaReader / NovelReader) 🔧 改造     │
│                                                         │
│  AppBar: 第3话 / 共336话                                │
│  正文内容 / 漫画图片                                     │
│  [← 上一章] [📋 目录] [下一章 →]                         │
│                                                         │
│  接收参数: source, chapters, currentChapterIndex         │
│  预加载: 下一章内容(后台)                               │
│  记录: 阅读进度                                          │
└─────────────────────────────────────────────────────────┘

7.2 数据流

阶段 1 — 搜索:
  LegadoSource.searchUrl + keyword
    → HTTP GET/POST
    → searchListRule 提取条目列表
    → 每个条目: {title, author, coverUrl, detailUrl}

阶段 2 — 详情(先):
  detailUrl
    → HTTP GET
    → bookInfoRule 提取: {name, author, cover, intro, tocUrl}
    → 存入 bookInfoCache
    → 渲染页面顶部

阶段 3 — 目录(后):
  tocUrl
    → HTTP GET(支持 {{page}} 分页)
    → chapterListRule 提取: [{name, url}, ...]
    → 存入 tocCache
    → 渲染章节列表

阶段 4 — 阅读:
  chapter.url
    → HTTP GET
    → contentRule 提取: 正文文本 / 漫画图片 URL 列表
    → 存入 chapterCache
    → 展示内容
    → 后台预加载下一章

7.3 路由变更

当前 改造后
ExplorePage → OnlineMangaReaderPage(detailUrl) ❌ ExplorePage → OnlineBookDetailPage(detailUrl) → 点击章节 → OnlineMangaReaderPage(chapterUrl) ✅
ExplorePage → OnlineNovelReaderPage(detailUrl) ❌ ExplorePage → OnlineBookDetailPage(detailUrl) → 点击章节 → OnlineNovelReaderPage(chapterUrl) ✅

八、数据模型扩展

8.1 LegadoSource 新增字段

class LegadoSource {
  // ===== 现有字段(保持不变)=====
  final String id;
  final String name;
  final String url;
  final int type;          // 0=小说, 2=漫画
  final bool enabled;
  final String? userAgent;
  final Map<String, String> headers;
  final String? searchUrl;
  final String? searchListRule;
  final String? searchNameRule;
  final String? searchAuthorRule;
  final String? searchCoverRule;
  final String? searchDetailRule;
  final String? searchMethod;
  final String? searchBody;
  final String? ruleKind;
  final String? charset;
  final String? urlEncoding;

  // ===== 🆕 BookInfo =====
  final String? bookInfoUrl;
  final String? bookInfoNameRule;
  final String? bookInfoAuthorRule;
  final String? bookInfoCoverRule;
  final String? bookInfoIntroRule;
  final String? bookInfoTocRule;       // ⭐ 最关键:目录页 URL

  // ===== 🆕 TOC =====
  final String? tocUrl;
  final String? tocListRule;
  final String? tocNameRule;
  final String? tocUrlRule;
  final String? tocNextPageRule;       // 目录分页

  // ===== 🆕 Content =====
  final String? contentRule;
  final String? contentNextRule;
  final String? contentPrevRule;
}

8.2 新增运行时数据模型

/// 在线书籍详情
class OnlineBookInfo {
  final String title;
  final String? author;
  final String? coverUrl;
  final String? intro;
  final String tocUrl;            // ⭐ 目录页 URL
  final String? status;           // 连载中/已完结
  final String? category;
  final String? updateTime;
  final String sourceName;        // 来源书源名称
}

/// 在线章节
class OnlineChapter {
  final String title;
  final String url;
  final int index;                // 从 1 开始
  bool isRead;                    // 是否已读(阅读记录反填)
}

/// 在线章节内容
class OnlineChapterContent {
  final String title;
  final String? textContent;      // 小说正文
  final List<String>? imageUrls;  // 漫画图片
  final String? nextChapterUrl;   // 下一章 URL(contentNextRule 解析结果)
  final String? prevChapterUrl;   // 上一章 URL
}

/// 阅读记录
class OnlineReadingRecord {
  final String sourceId;
  final String sourceName;
  final String bookTitle;
  final String detailUrl;
  final String chapterUrl;
  final String chapterTitle;
  final int chapterIndex;
  final int totalChapters;
  final DateTime lastReadTime;
}

8.3 fromJson / copyWith / toJson 变更

  • fromJson:新增 12 个字段的解析逻辑(见上文 P0-2)
  • copyWith:新增 12 个字段的传递(确保 setEnabled() 等不丢失数据)
  • toJson:新增 12 个字段的序列化(确保持久化到 SharedPreferences 时保留)

九、Legado 书源规则字段对照

9.1 完整的 Legado 书源 JSON 示例

{
  "bookSourceName": "示例书源",
  "bookSourceUrl": "https://www.example.com",
  "bookSourceType": 0,
  "bookSourceCharset": "gbk",

  "ruleSearch": {
    "url": "/search?keyword={{key}}&page={{page}}",
    "bookList": ".result-list .item",
    "name": ".book-title",
    "author": ".author",
    "coverUrl": "img@src",
    "detailUrl": "a@href"
  },

  "ruleBookInfo": {
    "name": "h1.book-title",
    "author": ".author span",
    "coverUrl": ".book-cover img@src",
    "intro": ".book-desc",
    "tocUrl": ".catalog-btn@href"
  },

  "ruleToc": {
    "chapterList": ".chapter-list li",
    "chapterName": "a",
    "chapterUrl": "a@href",
    "nextTocUrl": ".next-page@href"
  },

  "ruleContent": {
    "content": "#chapter-content",
    "nextChapterUrl": ".next-chapter@href",
    "prevChapterUrl": ".prev-chapter@href"
  }
}

9.2 字段映射表

Legado 字段路径 Sakura LegadoSource 字段 P0/P1
bookSourceName name ✅ 已有
bookSourceUrl url ✅ 已有
bookSourceType type ✅ 已有
bookSourceCharset charset ✅ 已有
ruleSearch.url searchUrl ✅ 已有
ruleSearch.bookList searchListRule ✅ 已有
ruleSearch.name searchNameRule ✅ 已有
ruleSearch.author searchAuthorRule ✅ 已有
ruleSearch.coverUrl searchCoverRule ✅ 已有
ruleSearch.detailUrl searchDetailRule ✅ 已有
ruleBookInfo.name bookInfoNameRule 🆕 P0
ruleBookInfo.author bookInfoAuthorRule 🆕 P0
ruleBookInfo.coverUrl bookInfoCoverRule 🆕 P0
ruleBookInfo.intro bookInfoIntroRule 🆕 P0
ruleBookInfo.tocUrl bookInfoTocRule 🆕 P0 ⭐
ruleToc.chapterList tocListRule 🆕 P0
ruleToc.chapterName tocNameRule 🆕 P0
ruleToc.chapterUrl tocUrlRule 🆕 P0
ruleToc.nextTocUrl tocNextPageRule 🆕 P1
ruleContent.content contentRule 🆕 P1
ruleContent.nextChapterUrl contentNextRule 🆕 P1
ruleContent.prevChapterUrl contentPrevRule 🆕 P1

十、附录:关键文件清单

修改的文件

文件 角色 P0 P1 P2
sakura_mobile/lib/src/core/legado_models.dart 数据模型 🔧
sakura_mobile/lib/src/core/legado_engine.dart 解析引擎 🔧 🔧 🔧
sakura_mobile/lib/src/core/legado_rule_parser.dart 规则解析器
sakura_mobile/lib/src/pages/explore_page.dart 搜索页导航 🔧
sakura_mobile/lib/src/pages/online_manga_reader_page.dart 漫画阅读器 🔧
sakura_mobile/lib/src/pages/online_novel_reader_page.dart 小说阅读器 🔧
sakura_mobile/lib/src/core/providers.dart Riverpod 视需要

新增的文件

文件 角色 P0 P1 P2
sakura_mobile/lib/src/pages/online_book_detail_page.dart 在线书籍详情页(合并 UI) 🆕
sakura_mobile/lib/src/core/online_cache.dart 会话级内存缓存 🆕

总结

以「能落地开发」为最终目标,本方案的核心建议是:

  1. 先修 _shortError() — 把 unknown:none 等所有 Dio 底层异常映射为中文提示,这是最小的改动但立刻消除最明显的 bug。

  2. 再补模型 — LegadoSource 补全 ruleBookInfo、ruleToc、ruleContent 字段,fromJson/copyWith/toJson 全部对齐。不补齐模型,后面所有的页面都无从谈起。

  3. 再做合并式详情页 — OnlineBookDetailPage 把 BookInfo + TOC 放在同一个页面,但数据加载分两次独立请求。不跳独立 TOC 页面,用户体验更流畅。

  4. 接章节阅读 — 阅读器接收 chapters + currentChapterIndex,从 URL 驱动改成章节驱动。这是解决"点开书直接显示乱码"问题的终点。

  5. 最后补分页和高级规则 — 目录分页 {{page}}、章节预加载、阅读记录、持久化缓存——这些让体验从"能用"到"好用"。

页面合并,解析分层;
缓存前置,持久化后置;
目录回退要识别章节,不要盲扫链接;
阅读器必须从 URL 驱动改成章节驱动。