Files
SakuraHub/docs/在线搜索与阅读-源码架构总结.md
2026-11-16 20:45:22 +08:00

51 KiB
Raw Permalink Blame History

在线搜索与阅读 — 源码架构总结

总结日期:2026-06-21 源码范围:sakura_mobile/lib/src/core/ + sakura_mobile/lib/src/pages/ 说明:本文档梳理在线搜索→详情→目录→阅读全流程的现有源码结构,不做方案设计。


目录

  1. 文件清单与职责
  2. 核心类关系图
  3. Provider 依赖注入
  4. 数据模型详解
  5. 搜索引擎 LegadoEngine
  6. 规则解析器 RuleParser
  7. 书源管理 SourceManager
  8. 统一搜索 UnifiedSearch
  9. 页面层源码
  10. 缓存与阅读记录
  11. 完整调用链路

一、文件清单与职责

Core 层(核心引擎 + 数据模型)

文件 行数 核心职责
legado_models.dart 515 所有数据模型:LegadoSource、OnlineBookInfo、OnlineChapter、OnlineChapterContent、OnlineReadingRecord、UnifiedSearchResult、SourceRepo
legado_engine.dart 956 在线内容引擎:HTTP 请求、搜索、BookInfo 解析、TOC 解析、章节内容解析、编码处理、错误归一化
legado_rule_parser.dart 262 HTML/JSON/Regex 规则解析器:CSS 选择器、JSONPath、Regex 三种解析方式
source_manager.dart 368 书源生命周期管理:导入、启用/禁用、订阅更新、健康检查、SharedPreferences 持久化
unified_search.dart 173 统一搜索编排:合并云库搜索 + 在线书源搜索,返回 SearchSection 列表
online_cache.dart 25 会话级内存缓存:BookInfo、TOC、ChapterContent 三级缓存
online_reading_history.dart 57 阅读记录持久化:SharedPreferences 存储最近 50 条记录
providers.dart 32 Riverpod 依赖注入:5 个全局 Provider
api_client.dart — 云端 API 客户端(搜索用 gallery() / novels())
session.dart — 会话管理(登录态)

Pages 层(UI 页面)

文件 行数 核心职责
explore_page.dart 503 在线搜索页:输入框、漫画/小说切换、结果列表展示、点击跳转
online_book_detail_page.dart 338 在线书籍详情页(合并 BookInfo + TOC UI):封面、书名、作者、简介、章节列表、正序/倒序、继续阅读
online_manga_reader_page.dart 208 在线漫画阅读器:PageView 图片浏览、上一章/下一章/目录导航、预加载、阅读记录
online_novel_reader_page.dart 195 在线小说阅读器:文本展示、字体缩放、上一章/下一章/目录导航、预加载、阅读记录

二、核心类关系图

┌──────────────────────────────────────────────────────────────┐
│                        providers.dart                        │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │ Session      │  │SourceManager │  │  LegadoEngine     │   │
│  │ Controller   │  │  (书源管理)   │  │  (在线内容引擎)    │   │
│  └──────┬───────┘  └──────┬───────┘  └────────┬──────────┘   │
│         │                 │                    │              │
│  ┌──────▼───────┐         │                    │              │
│  │SakuraApiClient│        │                    │              │
│  │ (云端API)     │        │                    │              │
│  └──────┬───────┘         │                    │              │
│         │                 │                    │              │
│  ┌──────▼─────────────────▼────────────────────▼──────────┐  │
│  │                   UnifiedSearch                        │  │
│  │   (编排:cloudFuture + onlineFuture → SearchSection)    │  │
│  └────────────────────────┬──────────────────────────────┘  │
└───────────────────────────┼────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
  ExplorePage      OnlineBookDetailPage    OnlineXxxReaderPage
  (搜索UI)          (详情+目录UI)            (阅读UI)

LegadoEngine 内部结构

LegadoEngine
├── Dio _http                        ← HTTP 客户端(15s 连接超时,20s 接收超时)
├── OnlineContentCache cache         ← 会话级缓存
│
├── 搜索 ───────────────────────────
│   ├── search()                     ← 单源搜索(构建请求 → 获取响应 → 解析结果)
│   ├── searchAll()                  ← 多源并发搜索(每批 10 个,Future.wait)
│   ├── _buildSearchRequest()        ← 构建搜索 URL + 编码关键词
│   ├── _applySearchTemplate()       ← 替换 {{key}} / {{page}} 占位符
│   └── _fallbackSearchResults()     ← 回退:扫描 <a> 标签
│
├── 详情 ───────────────────────────
│   ├── fetchBookInfo()              ← 解析书籍详情页 → OnlineBookInfo
│
├── 目录 ───────────────────────────
│   ├── fetchToc()                   ← 解析章节目录(带缓存)
│   ├── _fetchPaginatedToc()         ← 分页目录加载(最多 20 页)
│   └── _fallbackChapters()          ← 回退:章节识别器扫描 <a>
│
├── 内容 ───────────────────────────
│   ├── fetchChapterContent()        ← 解析章节内容 → OnlineChapterContent
│   ├── fetchPlainText()             ← 旧 API:从 URL 提取纯文本(无规则)
│   ├── fetchImageUrls()             ← 旧 API:从 URL 提取图片(无规则)
│   └── _extractImageUrls()          ← 图片提取(含 data-src/data-original)
│
├── 编解码 ─────────────────────────
│   ├── _encodeKeyword()             ← URL 关键词编码(GBK/UTF-8/平台通道)
│   ├── _decodeBody()                ← 响应体解码(GBK/UTF-8/Latin1)
│   └── _charsetFromContentType()    ← 从 Content-Type 提取 charset
│
├── HTTP ───────────────────────────
│   ├── _fetchBody()                 ← 统一 HTTP 请求(GET/POST,字节响应 + 状态码检查)
│   ├── _debugDioException()         ← Dio 异常日志
│   └── _debugHttpResponse()         ← HTTP 错误日志
│
├── 工具 ───────────────────────────
│   ├── _resolveUrl()                ← 相对 URL → 绝对 URL
│   ├── resolveResourceUrl()         ← 公开版 URL 解析
│   ├── _htmlToText()                ← HTML → 纯文本
│   ├── _plainTextFromJson()         ← JSON → 提取文本字段
│   ├── _imageUrlsFromJson()         ← JSON → 提取图片 URL
│   ├── _safeSelect() / _safeSelectList()  ← 规则解析安全包装
│   ├── _shortError()                ← 错误消息归一化(中文映射表)
│   └── parseSources()               ← JSON 文本 → List<LegadoSource>
│
└── 数据类 ─────────────────────────
    └── _LegadoRequest { method, url, body }

三、Provider 依赖注入

文件:sakura_mobile/lib/src/core/providers.dart

// 1. 会话管理(登录态)— StateNotifier
final sessionProvider = StateNotifierProvider<SessionController, SessionState>(...);

// 2. 云端 API 客户端 — 依赖 sessionProvider
final apiClientProvider = Provider<SakuraApiClient>((ref) {
  ref.watch(sessionProvider);
  return ref.read(sessionProvider.notifier).client();
});

// 3. 书源管理器 — ChangeNotifier(UI 可监听 busy/message 状态)
final sourceManagerProvider = ChangeNotifierProvider<SourceManager>((ref) {
  final manager = SourceManager();
  manager.initializeIfFirstRun();  // 首次运行提示导入书源
  return manager;
});

// 4. 在线引擎 — 单例
final legadoEngineProvider = Provider<LegadoEngine>((ref) => LegadoEngine());

// 5. 统一搜索 — 组合 apiClient + sourceManager + engine
final unifiedSearchProvider = Provider<UnifiedSearch>((ref) {
  return UnifiedSearch(
    api: ref.watch(apiClientProvider),
    sourceManager: ref.watch(sourceManagerProvider),
    engine: ref.watch(legadoEngineProvider),
  );
});

Provider 消费方式(在各页面中):

// 获取一次值(不监听变化)
final engine = ref.read(legadoEngineProvider);

// 监听变化(UI 自动刷新)
final manager = ref.watch(sourceManagerProvider);

四、数据模型详解

4.1 LegadoSource(书源规则)

文件:legado_models.dart:21-306

完整的 Legado 书源模型,包含四个规则模块。

构造函数参数(共 29 个字段):

class LegadoSource {
  // === 基础字段 ===
  final String id;           // 派生自 name+url 的 hash
  final String name;         // bookSourceName
  final String url;          // bookSourceUrl
  final int type;            // 0=小说, 2=漫画
  final bool enabled;

  // === HTTP 配置 ===
  final String? userAgent;
  final Map<String, String> headers;  // 含 Cookie
  final String? charset;              // gbk / utf-8
  final String? urlEncoding;          // 关键词 URL 编码字符集
  final String? ruleKind;             // css / json / regex

  // === Search 规则(ruleSearch)===
  final String? searchUrl;            // 搜索 URL 模板,含 {{key}} {{page}}
  final String? searchListRule;       // 结果条目列表选择器
  final String? searchNameRule;       // 书名选择器
  final String? searchAuthorRule;     // 作者选择器
  final String? searchCoverRule;      // 封面选择器
  final String? searchDetailRule;     // 详情链接选择器 → detailUrl
  final String? searchMethod;         // GET / POST
  final String? searchBody;           // POST body 模板

  // === BookInfo 规则(ruleBookInfo)===
  final String? bookInfoUrl;          // 详情页 URL 模板
  final String? bookInfoNameRule;
  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;      // 下一页目录选择器

  // === Content 规则(ruleContent)===
  final String? contentRule;          // 正文内容选择器
  final String? contentNextRule;      // 下一章链接选择器
  final String? contentPrevRule;      // 上一章链接选择器
}

类型判断:

  • isNovel → type == 0
  • isManga → type == 2

fromJson 解析逻辑(legado_models.dart:130-261):

  1. 从 json['ruleSearch'] 提取搜索规则(13 种 key 备选)
  2. 从 json['ruleBookInfo'] 提取详情规则(4 种 key 备选)
  3. 从 json['ruleToc'] 提取目录规则(5 种 key 备选)
  4. 从 json['ruleContent'] 提取内容规则(3 种 key 备选)
  5. 从 json['header'] / json['headers'] 提取请求头(支持 Map / JSON 字符串 / 冒号分隔行三种格式)
  6. 从 json['cookie'] 合并 Cookie 到 headers

copyWith 方法(legado_models.dart:93-128):

  • 唯一可变参数:enabled
  • 所有规则字段原样传递(不可变对象)

toJson 方法(legado_models.dart:263-305):

  • 输出完整的 Legado 兼容 JSON
  • 包含 ruleSearch / ruleBookInfo / ruleToc / ruleContent 四个顶层 key
  • 空值不输出(if (xxx != null) 条件添加)

字段名对照表(输出 JSON key → Legado 标准名):

内部字段 JSON key
name bookSourceName
url bookSourceUrl
type bookSourceType
searchListRule ruleSearch.bookList
bookInfoTocRule ruleBookInfo.tocUrl
tocListRule ruleToc.chapterList
contentRule ruleContent.content

4.2 OnlineBookInfo(运行时书籍详情)

class OnlineBookInfo {
  final String title;            // 书名(来自 bookInfoNameRule 解析或搜索结果的 initialTitle)
  final String? author;
  final String? coverUrl;
  final String? intro;           // 简介
  final String tocUrl;           // 目录页 URL ⭐
  final String sourceName;       // 来源书源名称
}

来源:LegadoEngine.fetchBookInfo() 解析 detailUrl 指向的页面。


4.3 OnlineChapter(运行时章节条目)

class OnlineChapter {
  final String title;    // 章节标题
  final String url;      // 章节内容 URL
  final int index;       // 序号(从 1 开始)
}

来源:LegadoEngine.fetchToc() 解析目录页。


4.4 OnlineChapterContent(运行时章节内容)

class OnlineChapterContent {
  final String title;                // 章节标题
  final String? textContent;         // 小说正文(纯文本)
  final List<String> imageUrls;      // 漫画图片 URL 列表
  final String? nextChapterUrl;      // 下一章 URL(contentNextRule 解析结果)
  final String? prevChapterUrl;      // 上一章 URL
}

来源:LegadoEngine.fetchChapterContent() 解析章节页。


4.5 OnlineReadingRecord(阅读记录)

class OnlineReadingRecord {
  final String sourceId;         // 书源 ID
  final String sourceName;       // 书源名称
  final String bookTitle;        // 书名
  final String detailUrl;        // 书籍详情页 URL
  final String chapterUrl;       // 当前阅读的章节 URL
  final String chapterTitle;     // 当前阅读的章节标题
  final int chapterIndex;        // 章节序号(0-based)
  final int totalChapters;       // 总章节数
  final DateTime lastReadTime;   // 最后阅读时间
}

存储:OnlineReadingHistory → SharedPreferences JSON 数组,最多 50 条。


4.6 UnifiedSearchResult(搜索结果条目)

class UnifiedSearchResult {
  final String sourceId;       // 书源 ID
  final String sourceName;     // 书源名称
  final String title;          // 书名
  final String? author;
  final String? coverUrl;
  final String? detailUrl;     // 书籍详情页 URL(非章节 URL)
  final String? errorMessage;  // 非空表示搜索失败

  bool get isError => errorMessage?.trim().isNotEmpty == true;
}

两种构造方式:

  • 正常结果:UnifiedSearchResult(sourceId:, sourceName:, title:, ...)
  • 错误结果:UnifiedSearchResult.error(sourceId:, sourceName:, errorMessage:) → title 固定为"搜索失败"

4.7 SearchItem / SearchSection(搜索页 UI 数据)

class SearchItem {
  final String title;
  final String sourceName;
  final String? author;
  final String? coverUrl;
  final String? detailUrl;
  final Artwork? artwork;               // 云库漫画
  final Novel? novel;                   // 云库小说
  final UnifiedSearchResult? online;    // 在线源结果
  final String? errorMessage;

  bool get isCloud => artwork != null || novel != null;
  bool get isError => errorMessage?.trim().isNotEmpty == true;
}

class SearchSection {
  final String id;       // 'cloud' | 'online'
  final String title;    // '我的云库' | '在线源'
  final List<SearchItem> items;
}

五、搜索引擎 LegadoEngine

文件:legado_engine.dart(956 行)

5.1 初始化

class LegadoEngine {
  LegadoEngine({Dio? http})
    : _http = http ?? Dio(BaseOptions(
        connectTimeout: Duration(seconds: 15),
        receiveTimeout: perSourceTimeout,  // 20s
        headers: {
          'User-Agent': 'Mozilla/5.0 ... Chrome/120 ...',
          'Accept': 'text/html,...',
          'Accept-Language': 'zh-CN,zh;q=0.9',
        },
      ));

  static const maxConcurrency = 10;      // 单批并发数
  static const perSourceTimeout = Duration(seconds: 20);
  final OnlineContentCache cache = OnlineContentCache();  // 会话缓存实例
}

5.2 搜索方法

search() — 单源搜索

输入: LegadoSource, keyword, page
  ↓
1. 检查 searchUrl / searchListRule 非空
2. _buildSearchRequest(source, searchUrl, keyword, page)
   → _encodeKeyword(source, keyword)    // GBK/UTF-8 百分号编码
   → _applySearchTemplate(template, encodedKeyword, page)
      // 替换 {{key}} {{keyword}} {key} {keyword} <key> <keyword>
      //       searchKey %s {{page}} {page} <page>
   → resolveResourceUrl(source.url, rawUrl)  // 相对→绝对
   → 返回 _LegadoRequest(method, url, body)
3. _fetchBody(source, url)  // HTTP GET/POST
4. RuleParser(body) 解析
5. _safeSelectList(parser, searchListRule) → 提取结果条目片段
6. 每个片段提取: title/author/coverUrl/detailUrl
7. 过滤空 title
8. 如果规则解析无结果 → _fallbackSearchResults()

searchAll() — 多源并发搜索

输入: List<LegadoSource>, keyword
  ↓
循环: start=0; start < sources.length; start += 10
  每批最多 10 个源,Future.wait 并发
  每个源: search(source, keyword)
    .timeout(20s)
    .catchError() → UnifiedSearchResult.error()
  结果追加到 results 列表

关键:searchAll 不做跨源去重。同一本书出现在 5 个书源中 → 5 条结果。

错误处理:

  • 超时 → 返回带 errorMessage 的错误结果,不影响其他源
  • 其他异常 → 同上

_fallbackSearchResults() — 搜索回退

当 searchListRule 解析不到结果时触发:

  1. 扫描 HTML 中所有 <a> 标签
  2. 标题必须包含搜索关键词(完全匹配)
  3. 过滤 # 和 javascript: 链接
  4. 最多返回 30 条

_applySearchTemplate() — 占位符替换

支持的占位符(按替换优先级):

{{key}} → encodedKeyword     {{page}} → pageText
{{keyword}} → encodedKeyword  {page} → pageText
{{searchKey}} → encodedKeyword <page> → pageText
{key} → encodedKeyword
{keyword} → encodedKeyword
{searchKey} → encodedKeyword
<key> → encodedKeyword
<keyword> → encodedKeyword
<searchKey> → encodedKeyword
searchKey → encodedKeyword  // 无包裹的字符串直接替换
%s → encodedKeyword          // printf 风格(仅替换第一个)

5.3 详情方法

fetchBookInfo() — 解析书籍详情

输入: LegadoSource, detailUrl, {initialTitle, initialAuthor, initialCoverUrl}
  ↓
1. 查缓存: cache.getBookInfo(source.id, absoluteUrl)
2. _fetchBody(source, absoluteUrl)
3. RuleParser(body) → 逐一提取:
   → bookInfoNameRule → parsedTitle
   → bookInfoAuthorRule → parsedAuthor
   → bookInfoCoverRule → parsedCover
   → bookInfoIntroRule → parsedIntro
   → bookInfoTocRule → parsedToc
4. 确定 tocUrl:
   - 优先: parsedToc
   - 其次: source.tocUrl
   - 兜底: absoluteUrl (即 detailUrl 本身)
5. title 兜底: initialTitle → '未命名作品'
6. 写入 bookInfoCache
7. 返回 OnlineBookInfo

5.4 目录方法

fetchToc() — 解析章节目录

输入: LegadoSource, tocUrl
  ↓
1. 查缓存: cache.getToc(source.id, absoluteUrl)
2. 未命中 → _fetchPaginatedToc(source, absoluteUrl)
3. 写入 tocCache
4. 返回 List<OnlineChapter>

_fetchPaginatedToc() — 分页目录加载

输入: LegadoSource, template (含 {{page}} 的 URL)
  ↓
初始化: chapters=[], seenUrls={}, seenPages={}, nextUrl=template, page=1
循环条件: page <= 20 && nextUrl != null
  1. 替换 {{page}} / {page} → requestedUrl
  2. seenPages 去重 → break
  3. _fetchBody → body
  4. RuleParser(body) → tocListRule → fragments
  5. 遍历 fragments:
     → tocNameRule → title
     → tocUrlRule → url
     → seenUrls 去重
     → chapters.add(OnlineChapter(title, url, index))
  6. 如果 fragments 为空:
     → _fallbackChapters(body)  // 章节识别器回退
  7. 如果本页新增 0 条 → break
  8. 检查 tocNextPageRule → 有则更新 nextUrl
     否则如果 template 含 {{page}} → 继续 page++
     否则 → nextUrl = null(停止)
返回 chapters

_fallbackChapters() — 章节识别器回退

当 tocListRule 不可用时触发:

  1. 正则匹配 <a> 标签
  2. 标题必须匹配章节特征正则:
    r'(第\s*[0-9一二三四五六七八九十百千万零〇两]+\s*[章节卷回话]|chapter\s*\d+|episode\s*\d+)'
    
  3. 按出现顺序排列

与搜索回退的区别:搜索回退要求标题包含搜索关键词,目录回退要求标题匹配章节正则。后者更精准,避免把导航链接当章节。

5.5 内容方法

fetchChapterContent() — 解析章节内容

输入: LegadoSource, OnlineChapter
  ↓
1. 查缓存: cache.getChapter(source.id, absoluteUrl)
2. _fetchBody → body
3. RuleParser(body) → contentRule → content(主内容)
4. 如果是漫画:
   → contentRule 提取 fragments 列表
   → 合并 fragments 为 contentBody
5. 如果是小说:
   → contentBody = content.isEmpty ? body : content
6. 提取导航:
   → contentNextRule → nextChapterUrl
   → contentPrevRule → prevChapterUrl
7. 构建 OnlineChapterContent:
   - 小说: textContent = _plainTextFromJson(contentBody) || _htmlToText(contentBody)
   - 漫画: imageUrls = _extractImageUrls(contentBody, absoluteUrl)
   - nextChapterUrl / prevChapterUrl
8. 写入 chapterCache
9. 返回 OnlineChapterContent

fetchPlainText() — 旧 API(无规则)

输入: LegadoSource, url
  ↓
_fetchBody → body
_json 文本提取优先 → _plainTextFromJson(body)
回退 HTML → _htmlToText(body)

fetchImageUrls() — 旧 API(无规则)

输入: LegadoSource, url
  ↓
如果 url 本身是图片 → 直接返回 [url]
否则 _fetchBody → body
  HTML img 扫描: <img src="...">
  JSON 图片扫描: _imageUrlsFromJson(body)
  合并去重

两者都是旧 API,不依赖 contentRule,直接从 HTML/JSON 中暴力提取。

5.6 HTTP 层

_fetchBody() — 统一 HTTP 请求

输入: LegadoSource, url, {method, data}
  ↓
1. 校验 URL(非空、有 scheme)
2. 构建 headers:
   - Referer: source.url
   - ...source.headers(含 Cookie)
   - User-Agent: source.userAgent ?? 默认 UA
3. 发起请求:
   - GET:  _http.get<List<int>>(url, options: ResponseType.bytes, followRedirects: true, validateStatus: _ => true)
   - POST: _http.post<List<int>>(url, data: data, ...)
4. 捕获 DioException → _debugDioException() 打日志 → rethrow
5. 检查 statusCode:
   - 404 → throw 'Source search endpoint is missing or expired.'
   - 403/444 → throw 'Source refused access...'
   - 其他 >= 400 → throw 'HTTP $code from $host.'
6. 解码响应体: _decodeBody(bytes, declaredCharset: source.charset, contentType: headers['content-type'])

关键设计:

  • ResponseType.bytes — 始终以字节数组接收,避免 Dio 自动用错误编码解码
  • validateStatus: (_) => true — 不抛 DioException,自己检查状态码
  • followRedirects: true — 自动跟随重定向

5.7 编解码层

_encodeKeyword() — URL 关键词编码

输入: LegadoSource, keyword
  ↓
确定编码: source.urlEncoding ?? source.charset ?? 'utf-8'
  ↓
utf-8     → Uri.encodeQueryComponent(keyword)
gbk/gb2312/gb18030 → gbk.encode(keyword) → 手动百分号编码
其他编码 → _encodingChannel.invokeMethod('encodeQuery') → 平台原生编码
          MissingPluginException → throw

_decodeBody() — 响应体解码

输入: List<int> bytes, declaredCharset, contentType
  ↓
确定 charset: declaredCharset ?? _charsetFromContentType(contentType)
  ↓
latin1/iso-8859-1/windows-1252 → latin1.decode(bytes)
gbk/gb2312/gb18030 → gbk.decode(bytes) // FormatException → latin1 兜底
其他/未指定 → utf8.decode(bytes) // FormatException → latin1 兜底

_charsetFromContentType() — 提取 charset

// 从 "text/html; charset=gbk" 中提取 "gbk"
RegExp(r'charset=([^;]+)')

5.8 错误处理

_shortError() — 错误消息归一化

完整的错误消息映射链(按优先级):

1. DioException 类型匹配:
   connectionTimeout/receiveTimeout/sendTimeout
     → '连接 {host} 超时,请稍后重试。'
   connectionError
     → '无法连接 {host},请检查网络或更换书源。'
   badResponse + 404
     → '书源搜索接口已失效(404)。'
   badResponse + 403/444
     → '{host} 拒绝了访问,可能需要 Cookie 配置。'
   badResponse + 其他
     → '{host} 返回了异常状态(HTTP {code})。'

2. FormatException:
   含 utf/encoding → '响应编码异常,请检查书源的 charset 配置。'
   其他 → '书源规则期望 JSON 格式,但站点返回了其他内容。'

3. 原始字符串归一化:
   '[unknown]: null' / 'null' → '目标站点返回了空响应...'
   '[unknown]: none' / 含 'unknown:none' → '连接异常,书源可能已失效。'
   含 'connection refused' → '目标站点拒绝了连接。'
   含 'connection timed out' → '连接超时,请稍后重试。'
   含 'no address associated' → '无法解析目标站点域名,请检查网络。'

4. 兜底:
   message > 120 字符 → 截断
   空字符串 → '未知错误'

六、规则解析器 RuleParser

文件:legado_rule_parser.dart(262 行)

6.1 支持的三种解析类型

通过 _resolveKind() 自动识别:

规则前缀:
  "json:"  或 "$."    → json  模式
  "regex:"           → regex 模式
  其他               → css   模式(默认)

6.2 CSS 模式

selectList() — 多元素选择

1. 清理选择器(去掉 @attr 后缀)
2. html_parser.parse(body) → document
3. document.querySelectorAll(cleanSelector)
4. 每个元素 → outerHtml
5. 如果 querySelectorAll 抛异常(畸形选择器)→ 降级到 _legacyCssFragments()

select() — 单元素选择

1. 检查 @attr 后缀(如 "img@src" → 提取 src 属性值)
2. html_parser.parse(fragment) → document
3. document.querySelector(cleanSelector)
4. 有 @attr → element.attributes[attr]
5. 无 @attr → element.text
6. 如果 querySelector 抛异常 → 降级到 _legacyCssText()

_legacyCssFragments() — 正则降级

提取选择器开头的 tag 名 → 正则匹配 <tag ...>...</tag> → 返回 outerHtml

_legacyCssText() — 正则降级

提取 tag 名 → 正则匹配 → @attr 提取属性值 / 默认提取 innerText

6.3 JSON 模式(JSONPath)

支持的语法:

$.data              → 取 data 字段
$.data.chapters     → 取 data.chapters 字段
$.data.chapters[*]  → 取 chapters 数组全部元素
$.data.items[0]     → 取 items 数组第 1 个元素
$.data.list[2].name → 取 list[2].name
["complex-key"]     → 支持引号包裹的 key(自动转为 .key)

JsonPath 解析流程(_jsonPath()):

1. 去掉前缀: json: 或 $.
2. 按 . 分割 path
3. 逐段遍历:
   - segment 以 [*] 结尾 → 取数组全量
   - segment 含 [n] → 取数组第 n 个元素
   - 普通 key → _child(node, key)
4. _child() 递归:
   - key 为空 → 返回 node
   - node is Map → node[key]
   - node is List → node.map(item => _child(item, key))

JSON Body 预处理(_jsonBody()):

1. 去掉 UTF-8 BOM(0xFEFF)
2. 检测 JSONP 格式: callback({...})
   → 正则提取括号内 JSON
3. jsonDecode

6.4 Regex 模式

selectList() — Regex 全量匹配:

去掉 "regex:" 前缀
RegExp(rule, dotAll: true).allMatches(body)
  → 有捕获组: match.group(1)
  → 无捕获组: match.group(0)
过滤空值

select() — Regex 首次匹配:

去掉 "regex:" 前缀
RegExp(rule, dotAll: true).firstMatch(fragment)
  → match.group(1) ?? match.group(0)

6.5 规则多值支持

_ruleAlternatives() — 支持 || 分隔的多个规则备选:

// "div.title || h1.title || .book-name" → 三个规则依次尝试
// 第一个有结果的规则立即返回

七、书源管理 SourceManager

文件:source_manager.dart(368 行)

7.1 生命周期

构造 → load() → initializeIfFirstRun()
         ↓
    SharedPreferences 读取已保存书源
         ↓
    _loaded = true → notifyListeners()
         ↓
    startAutoUpdateTimer()  // 每 6 小时检查订阅更新

7.2 书源导入

importFromRepo(SourceRepo) — 从仓库导入

1. 如果是订阅源 → _addSubscription(url)
2. HTTP GET repo.url
3. importFromJsonText(response.body)

importFromUrl(String) — 从自定义 URL 导入

HTTP GET url → importFromJsonText(response.body)

importFromJsonText(String) — 解析 JSON 并入库

1. _engine.parseSources(body) → List<LegadoSource>
2. 遍历 imported:
   - _sources.indexWhere(id 匹配) → 更新现有源
   - 否则 → 追加新源
3. _save() → SharedPreferences
4. notifyListeners()

parseSources() — JSON → 书源列表

1. 检测 HTML(body 以 <!doctype / <html / < 开头)→ throw FormatException('source-html')
2. jsonDecode(body)
3. 如果是 List → 直接用
4. 如果是 Map → _sourceListFromMap(decoded)
   // 尝试 key: sources / bookSources / data / list / items / results
5. 每个 Map 条目 → LegadoSource.fromJson()
6. 过滤 url 为空的源

7.3 书源查询

// 全部书源(不可变列表)
List<LegadoSource> get sources;

// 已启用书源
List<LegadoSource> get enabledSources;

// 已启用的小说源(type == 0)
List<LegadoSource> get enabledNovelSources;

// 已启用的漫画源(type == 2)
List<LegadoSource> get enabledMangaSources;

// 按 ID 查找
LegadoSource? sourceById(String sourceId);

7.4 书源状态管理

// 启用/禁用某个书源
setEnabled(sourceId, enabled) → _save() → notifyListeners()

// 健康检查(HTTP GET 搜索 URL,最多检查 10 个源)
checkEnabledSources() → Future.wait(targets.map(_checkSource)) → List<SourceCheckResult>

7.5 持久化

// 存储 key
_sourcesKey = 'legado_sources_v1'
_initializedKey = 'source_manager_initialized_v1'
_subscriptionsKey = 'legado_subscription_urls_v1'
_lastSubscriptionUpdateKey = 'legado_last_subscription_update_v1'

// 书源存储格式
jsonEncode(_sources.map(source.toJson()).toList())
// 即完整的 Legado 兼容 JSON 数组,含 ruleSearch/ruleBookInfo/ruleToc/ruleContent

八、统一搜索 UnifiedSearch

文件:unified_search.dart(173 行)

8.1 搜索编排

Future<List<SearchSection>> search({query, mode}) {
  // 1. 并行发起两个搜索
  cloudFuture  = mode==manga ? _searchCloudManga(query) : _searchCloudNovels(query)
  onlineFuture = engine.searchAll(sources, query)
                   .then(items => items.map(SearchItem.online))

  // 2. 等待两个 Future 都完成(Future.wait)
  results = await Future.wait([cloudFuture, onlineFuture])

  // 3. 组装 SearchSection
  return [
    if (results[0].isNotEmpty) SearchSection(id: 'cloud',  title: '我的云库', items: results[0]),
    if (results[1].isNotEmpty) SearchSection(id: 'online', title: '在线源',   items: results[1]),
  ]
}

8.2 云库搜索

_searchCloudManga(query) → api.gallery(search: query, contentType: 'manga')
  → rows.map(Artwork.fromJson).map(SearchItem.cloudArtwork)

_searchCloudNovels(query) → api.novels(search: query)
  → rows.map(Novel.fromJson).map(SearchItem.cloudNovel)

8.3 SearchItem 工厂方法

SearchItem.cloudArtwork(artwork) → title, sourcePlatform, author, coverUrl, artwork
SearchItem.cloudNovel(novel)     → title, sourcePlatform, author, coverPath, novel
SearchItem.online(result)        → title, sourceName, author, coverUrl, detailUrl, online, errorMessage
SearchItem.error(sourceName, msg)→ title='搜索失败', sourceName, errorMessage

九、页面层源码

9.1 ExplorePage — 在线搜索页

文件:explore_page.dart(503 行)

状态管理:

final search = TextEditingController();   // 搜索输入框
late UnifiedSearchMode mode;              // manga / novel
Future<List<SearchSection>>? future;      // 搜索结果 Future
final savingOnline = <String>{};          // 正在保存的 item key 集合

搜索触发:

_submit() {
  query = search.text.trim();
  if (query.isEmpty) return;
  setState(() {
    future = ref.read(unifiedSearchProvider).search(query: query, mode: mode);
  });
}

模式切换(漫画 ↔ 小说):

SegmentedButton → onSelectionChanged → mode = newMode; future = null;

搜索状态展示(FutureBuilder 四种状态):

future == null           → 空状态(搜索引导文案)
ConnectionState.waiting  → CircularProgressIndicator
snapshot.hasError        → 错误状态(cloud_off 图标 + 文案)
sections.isEmpty         → 无结果状态(search_off 图标 + 文案)
有结果                   → Column: section 标题 + SearchResultTile 列表

搜索结果点击 — _openItem():

item.artwork != null
  → ArtworkDetailPage(artwork)            // 云库漫画:本地详情页

item.novel != null
  → NovelReaderPage(novel)                // 云库小说:本地阅读器

item.isError
  → SnackBar(errorMessage)                // 错误提示

online != null
  → source = sourceManager.sourceById(online.sourceId)
  → source == null → SnackBar('书源已不可用')
  → OnlineBookDetailPage(                 // 🆕 在线结果 → 详情页
      source, initialTitle, initialAuthor,
      initialCoverUrl, detailUrl, onSave
    )

保存到书架 — _saveOnlineItem():

1. fetchBookInfo(source, detailUrl) → info
2. fetchToc(source, info.tocUrl) → chapters
3. fetchChapterContent(source, chapters.first) → content
4. 漫画: api.importOnlineManga(...) → 跳转到 ArtworkDetailPage
5. 小说: api.importOnlineNovel(...) → 跳转到 NovelReaderPage
6. 异常: SnackBar('保存失败:$error')

UI 组件:

  • _SourceSummary — 已启用书源数量卡片
  • _SearchResultTile — 搜索结果条目(封面缩略图 + 标题 + 作者/来源 + 保存按钮)
    • subtitle 三要素:作者(未知作者兜底) - 来源名称 - 云库/在线
    • 错误条目:粉色背景 + warning 图标 + errorMessage
  • _ResultThumb — 封面缩略图(CachedNetworkImage,160×220,有 fallback 图标)
  • _ExploreEmptyState — 空状态占位

9.2 OnlineBookDetailPage — 在线书籍详情页

文件:online_book_detail_page.dart(338 行)

接收参数:

source: LegadoSource       // 书源
detailUrl: String          // 书籍详情页 URL
initialTitle: String       // 搜索结果中的书名(兜底)
initialAuthor: String?     // 搜索结果中的作者(兜底)
initialCoverUrl: String?   // 搜索结果中的封面(兜底)
onSave: Future<void> Function()?  // 保存回调

状态管理:

OnlineBookInfo? info;          // BookInfo 解析结果
List<OnlineChapter> chapters;  // 章节列表
Object? infoError;             // BookInfo 加载错误
Object? tocError;              // TOC 加载错误
bool loadingInfo = true;       // BookInfo 加载中
bool loadingToc = true;        // TOC 加载中
bool descending = false;       // 章节排序(正序/倒序)
bool saving = false;           // 保存中
OnlineReadingRecord? readingRecord;  // 阅读记录

加载流程 — _load():

1. detailUrl 为空 → 显示错误
2. engine.fetchBookInfo(source, detailUrl, ...) → info
3. setState: loadingInfo=false, loadingToc=true
4. _loadToc(info.tocUrl)
5. OnlineReadingHistory.find(sourceId, detailUrl) → readingRecord
6. 异常 → setState: infoError=error, loadingInfo=false, loadingToc=false

分段加载 — _loadToc(url):

1. setState: tocError=null, loadingToc=true
2. engine.fetchToc(source, url) → chapters
3. setState: loadingToc=false
4. 异常 → setState: tocError=error, loadingToc=false

关键设计:BookInfo 和 TOC 是两次独立的 HTTP 请求(因为 detailUrl ≠ tocUrl),但 UI 合并在同一页面。BookInfo 先渲染,TOC 区域独立 loading。

章节点击 — _openChapter(index):

source.isManga
  → OnlineMangaReaderPage(source, title, chapters, currentChapterIndex: index, detailUrl)
  → push
  → 回来后重新查阅读记录 → 刷新已读标记

source.isNovel
  → OnlineNovelReaderPage(同上)

页面结构:

AppBar: '书籍详情'
  ↓
上半部分(BookInfo 渲染):
  Row:
    封面 (CachedNetworkImage, 104×142)
    Column: 书名(headlineSmall) + 作者 + 来源(灰色) + 章节数(粉色)
  简介 ExpansionTile(可展开/收起)
  操作按钮:
    FilledButton: '从第一章开始阅读' / '继续阅读'(根据 readingRecord)
    OutlinedButton: '保存到书架'(条件显示)

下半部分(TOC 渲染):
  Row: '章节目录(共 N 章)' + 正序/倒序切换按钮
  三种状态:
    loading → CircularProgressIndicator
    error → _ErrorState(重试按钮)
    chapters.isEmpty → 空状态文案
    有数据 → ListView of ListTile:
      - leading: menu_book 图标
      - title: 章节名称
      - trailing: 已读 ✓ 或 chevron_right
      - onTap: _openChapter(chapter.index - 1)

9.3 OnlineMangaReaderPage — 在线漫画阅读器

文件:online_manga_reader_page.dart(208 行)

接收参数:

source: LegadoSource
title: String                    // 书名
chapters: List<OnlineChapter>    // 完整章节列表
currentChapterIndex: int         // 当前章节序号(0-based)
detailUrl: String                // 书籍详情 URL(用于阅读记录)

状态管理:

late int chapterIndex = widget.currentChapterIndex;
late Future<OnlineChapterContent> contentFuture = _load();
final pageController = PageController();
int pageIndex = 0;               // 当前漫画页(PageView 内)

加载流程 — _load():

1. engine.fetchChapterContent(source, chapter) → content
2. OnlineReadingHistory.save(OnlineReadingRecord(...))
3. 预加载下一章:
   next = chapterIndex + 1
   if next < chapters.length:
     engine.fetchChapterContent(source, chapters[next])
       .catchError(...)  // 预加载失败静默忽略
4. return content

章节切换 — _move(delta):

target = chapterIndex + delta
if target < 0 || target >= chapters.length → return
setState:
  chapterIndex = target
  pageIndex = 0
  contentFuture = _load()
pageController.jumpToPage(0)

页面结构:

AppBar: '章节标题(3/336)'
  ↓
FutureBuilder<OnlineChapterContent>:
  error → _MangaState('这个章节暂时没有加载成功。', retry)
  loading → CircularProgressIndicator
  data.imageUrls.isEmpty → _MangaState('这一章还没有找到漫画页面...', retry)
  data.imageUrls:
    Stack:
      PageView.builder:
        InteractiveViewer → Image.network(pages[index], headers: source.headers)
      Positioned(右下角): '3/18' 页数指示器

bottomNavigationBar:
  [← 上一章]  [📋 目录(pop)]  [下一章 →]
  - 上一章: chapterIndex > 0 可用
  - 下一章: chapterIndex < chapters.length - 1 可用

9.4 OnlineNovelReaderPage — 在线小说阅读器

文件:online_novel_reader_page.dart(195 行)

接收参数:

source: LegadoSource
title: String                    // 书名
chapters: List<OnlineChapter>    // 完整章节列表
currentChapterIndex: int         // 当前章节序号(0-based)
detailUrl: String                // 书籍详情 URL(用于阅读记录)

状态管理:

late int chapterIndex = widget.currentChapterIndex;
late Future<OnlineChapterContent> contentFuture = _load();
double fontSize = 18;            // 可调字号(14-26)

加载流程 — _load():与漫画阅读器完全相同的逻辑。

页面结构:

AppBar: '章节标题(3/336)'
  actions: [缩小字体] [放大字体]

body → FutureBuilder:
  error → _ReaderState('章节加载失败', retry)
  loading → CircularProgressIndicator
  data.textContent 为空 → _ReaderState('这一章还是空白', retry)
  data.textContent:
    ListView:
      Text(章节标题, titleLarge)
      Text(正文, fontSize: fontSize, height: 1.75)

bottomNavigationBar: 与漫画阅读器完全相同的三按钮导航

十、缓存与阅读记录

10.1 OnlineContentCache — 会话级内存缓存

文件:online_cache.dart(25 行)

class OnlineContentCache {
  final _bookInfo  = <String, OnlineBookInfo>{};         // key: sourceId|url
  final _toc       = <String, List<OnlineChapter>>{};    // key: sourceId|tocUrl
  final _chapters  = <String, OnlineChapterContent>{};   // key: sourceId|chapterUrl

  // 缓存 key 规则
  String _key(String sourceId, String url) => '$sourceId|$url';

  // BookInfo
  getBookInfo(sourceId, url) → _bookInfo[key]
  putBookInfo(sourceId, url, value) → _bookInfo[key] = value

  // TOC(返回不可变列表)
  getToc(sourceId, url) → _toc[key]
  putToc(sourceId, url, value) → _toc[key] = List.unmodifiable(value)

  // Chapter
  getChapter(sourceId, url) → _chapters[key]
  putChapter(sourceId, url, value) → _chapters[key] = value
}

缓存生命周期:当次 APP 会话(进程存活期间)。APP 杀死后缓存消失。

缓存消费者:

  • fetchBookInfo() → 查/写 _bookInfo
  • fetchToc() → 查/写 _toc
  • fetchChapterContent() → 查/写 _chapters

10.2 OnlineReadingHistory — 阅读记录持久化

文件:online_reading_history.dart(57 行)

存储方式:SharedPreferences,key = online_reading_history_v1

数据格式:JSON 数组,每个元素是 OnlineReadingRecord.toJson()

static Future<void> save(OnlineReadingRecord record) {
  1. 读取现有记录 → all()
  2. 删除同一本书的旧记录(按 sourceId + detailUrl 去重)
  3. 新记录插入到数组头部(最近阅读排在前面)
  4. 超过 50 条 → 截断尾部
  5. 写回 SharedPreferences
}

static Future<OnlineReadingRecord?> find(sourceId, detailUrl) {
  遍历 all() → 匹配 sourceId + detailUrl → 返回第一条
}

static Future<List<OnlineReadingRecord>> all() {
  从 SharedPreferences 读取 → jsonDecode → List.map(OnlineReadingRecord.fromJson)
}

调用的地方:

  • 进入章节时:OnlineReadingHistory.save()(在 _load() 中)
  • 进入详情页时:OnlineReadingHistory.find()(显示"继续阅读"还是"从第一章开始")
  • 从阅读器返回时:OnlineReadingHistory.find()(刷新章节已读标记)

十一、完整调用链路

11.1 搜索链路

用户输入 "海贼王" → 按回车
  ↓
ExplorePage._submit()
  ↓
UnifiedSearch.search(query: "海贼王", mode: manga)
  ↓ 并行
  ├─ _searchCloudManga("海贼王")
  │   → SakuraApiClient.gallery(search: "海贼王", contentType: 'manga')
  │   → HTTP GET /api/v1/gallery?search=海贼王&content_type=manga
  │   → List<Artwork> → SearchItem.cloudArtwork()
  │
  └─ LegadoEngine.searchAll(enabledMangaSources, "海贼王")
      ↓ 分批(每批 10 个)
      ├─ search(源1, "海贼王")
      │   ├─ _encodeKeyword(源1, "海贼王") → GBK/UTF-8 编码
      │   ├─ _applySearchTemplate(源1.searchUrl, encoded, page=1)
      │   │   → "https://example.com/search?keyword=%E6%B5%B7%E8%B4%BC%E7%8E%8B"
      │   ├─ _fetchBody(源1, url) → HTTP GET → 字节数组 → _decodeBody → HTML 字符串
      │   ├─ RuleParser(html).selectList(源1.searchListRule)
      │   │   → fragments = ["<div class='item'>...", "<div class='item'>..."]
      │   └─ 遍历 fragments:
      │       ├─ select(fragment, searchNameRule) → "海贼王"
      │       ├─ select(fragment, searchAuthorRule) → "尾田荣一郎"
      │       ├─ select(fragment, searchDetailRule) → "/book/123"
      │       └─ UnifiedSearchResult(title:"海贼王", detailUrl:"https://.../book/123")
      │
      ├─ search(源2, "海贼王") → 同上...
      └─ ...
  ↓
Future.wait → List<SearchSection>:
  [SearchSection(id:'cloud',  items: [...]),
   SearchSection(id:'online', items: [UnifiedSearchResult...])]
  ↓
ExplorePage FutureBuilder → 渲染结果列表

11.2 详情链路

用户点击搜索结果中的 "海贼王"
  ↓
ExplorePage._openItem(item)
  ↓  item.online.detailUrl = "https://example.com/book/123"
Navigator.push(OnlineBookDetailPage(
  source: 源1,
  detailUrl: "https://example.com/book/123",
  initialTitle: "海贼王",
  initialAuthor: "尾田荣一郎",
))
  ↓
OnlineBookDetailPage._load()
  ↓
LegadoEngine.fetchBookInfo(源1, "https://example.com/book/123")
  ├─ cache.getBookInfo(源1.id, url) → 未命中
  ├─ _fetchBody(源1, url) → HTML 字符串
  ├─ RuleParser(html) → 提取:
  │   ├─ bookInfoNameRule → "海贼王"
  │   ├─ bookInfoAuthorRule → "尾田荣一郎"
  │   ├─ bookInfoCoverRule → "https://example.com/img/cover.jpg"
  │   ├─ bookInfoIntroRule → "拥有财富、名声、权力..."
  │   └─ bookInfoTocRule → "/book/123/catalog"
  ├─ tocUrl = "https://example.com/book/123/catalog"
  ├─ cache.putBookInfo(...)
  └─ return OnlineBookInfo(title:"海贼王", tocUrl:"https://.../catalog", ...)
  ↓
setState → loadingInfo=false, info=OnlineBookInfo, loadingToc=true
  ↓ 上半部分立即渲染(封面+书名+作者+简介+按钮)
  ↓
_loadToc("https://example.com/book/123/catalog")
  ↓
LegadoEngine.fetchToc(源1, "https://example.com/book/123/catalog")
  ├─ cache.getToc(源1.id, url) → 未命中
  ├─ _fetchPaginatedToc(源1, url)
  │   ├─ page=1: _fetchBody → HTML
  │   │   RuleParser → tocListRule → fragments
  │   │   每 fragment: tocNameRule="第1话" + tocUrlRule="/book/123/ch1"
  │   │   → chapters.add(OnlineChapter("第1话", "https://.../ch1", index:1))
  │   │   ...
  │   ├─ tocNextPageRule → 有 → nextUrl = "?page=2"
  │   ├─ page=2: 同上...
  │   └─ tocNextPageRule → 空 → 停止
  ├─ cache.putToc(...) → List<OnlineChapter>(共 1130 条)
  └─ return chapters
  ↓
setState → loadingToc=false, chapters=[1130条]
  ↓ 下半部分渲染章节列表
  ↓
OnlineReadingHistory.find(源1.id, detailUrl) → readingRecord 或 null

11.3 阅读链路

用户在详情页点击 "第1话"
  ↓
OnlineBookDetailPage._openChapter(0)  // index 从 0 开始
  ↓
Navigator.push(OnlineMangaReaderPage(
  source: 源1,
  title: "海贼王",
  chapters: [1130条],
  currentChapterIndex: 0,
  detailUrl: "https://example.com/book/123",
))
  ↓
OnlineMangaReaderPage._load()
  ↓
chapter = chapters[0] → {title:"第1话", url:"https://.../ch1"}
  ↓
LegadoEngine.fetchChapterContent(源1, chapter)
  ├─ cache.getChapter(源1.id, url) → 未命中
  ├─ _fetchBody(源1, url) → HTML
  ├─ RuleParser(html) → contentRule → "#chapter-content" 的 innerHtml
  ├─ _extractImageUrls(contentBody, absoluteUrl)
  │   ├─ RegExp: <img src="..."> / data-src / data-original
  │   └─ JSON 图片扫描
  ├─ contentNextRule → "/book/123/ch2" → nextChapterUrl
  ├─ contentPrevRule → 空 → prevChapterUrl=null
  ├─ cache.putChapter(...)
  └─ return OnlineChapterContent(
       title: "第1话",
       imageUrls: ["https://.../img01.jpg", "https://.../img02.jpg", ...],
       nextChapterUrl: "https://.../ch2",
     )
  ↓
OnlineReadingHistory.save(OnlineReadingRecord(
  sourceId, sourceName, bookTitle, detailUrl,
  chapterUrl, chapterTitle, chapterIndex:0, totalChapters:1130,
  lastReadTime: now,
))
  ↓
预加载下一章:
  engine.fetchChapterContent(源1, chapters[1])
    .catchError(...)  // 后台静默,失败不影响当前阅读
  ↓
渲染 PageView:
  Image.network("https://.../img01.jpg") ← 第1页
  Image.network("https://.../img02.jpg") ← 第2页
  ...

用户点击 "下一章"
  ↓
_move(1) → chapterIndex = 1
  ↓
setState → contentFuture = _load()
  ↓
engine.fetchChapterContent(源1, chapters[1])
  ├─ cache 命中!(已预加载) → 秒切
  └─ _load() 内部再次 save 阅读记录 + 预加载第3章

附录:关键设计要点总结

数据流方向

LegadoSource (静态规则,SharedPreferences 持久化)
  ↓
LegadoEngine (规则驱动解析,HTTP + 缓存)
  ↓
OnlineBookInfo / OnlineChapter / OnlineChapterContent (运行时数据,内存缓存)
  ↓
UI Pages (ExplorePage / OnlineBookDetailPage / ReaderPages)

编码处理链

搜索关键词:
  _encodeKeyword(source, keyword)
    → gbk.encode / Uri.encodeQueryComponent / 平台通道

响应体:
  _fetchBody → ResponseType.bytes
    → _decodeBody(bytes, source.charset, content-type charset)
      → gbk.decode / utf8.decode / latin1.decode

缓存策略

BookInfo    → 进入详情页时缓存,同一书源 + 同一 detailUrl 只请求一次
TOC         → 进入详情页时缓存,同一书源 + 同一 tocUrl 只请求一次
Chapter     → 阅读时缓存当前章 + 预加载下一章
阅读记录     → SharedPreferences 持久化,跨会话保留

回退策略优先级

规则解析优先:
  1. 用书源声明的 rule 解析(CSS/JSON/Regex)
  2. 规则为空或无结果 → 回退
     - 搜索: _fallbackSearchResults (全 <a> 扫描 + 关键词过滤)
     - 目录: _fallbackChapters (章节正则过滤的 <a> 扫描)
     - 内容: _htmlToText / _extractImageUrls (从 HTML 暴力提取)