Yuedu项目API文档：书源规则编写参考

「阅读」APP作为一款开源小说阅读工具，其核心功能依赖于书源规则（Book Source Rule）的解析能力。本文档将详细介绍书源规则的基本结构、编写规范及常见场景处理方案，帮助运营人员快速掌握规则编写技巧。

书源规则基础架构

书源规则本质是一个JSON格式的配置文件，用于定义小说网站的解析逻辑。标准书源文件需包含以下核心字段：

字段名	类型	描述	必要性
name	String	书源名称（如"起点中文网"）	必需
url	String	网站首页地址	必需
searchUrl	String	搜索接口URL模板	必需
searchList	String	搜索结果列表的CSS选择器	必需
bookName	String	书名提取规则	必需
author	String	作者提取规则	必需
latestChapter	String	最新章节提取规则	可选

完整字段说明可参考官方文档：README.md

规则文件组织结构

项目采用集中式书源管理模式，所有规则文件统一存放在根目录下，典型结构如下：

Yuedu/
├── shuyuan.json        # 主书源文件（已集成所有规则）
├── index.html          # 书源导入引导页
└── README.md           # 项目说明文档

核心解析规则编写

1. URL模板语法

搜索接口URL需使用{{key}}占位符接收用户输入，例如：

{
  "searchUrl": "https://example.com/search?q={{key}}&page={{page}}"
}

• {{key}}：自动替换为用户搜索关键词
• {{page}}：分页参数，从1开始自增

2. 选择器语法

采用CSS选择器+属性提取的复合语法，基础格式为：选择器@属性

语法示例	说明
.book-item@href	提取class为book-item元素的href属性
.title@text	提取class为title元素的文本内容
#content@html	提取id为content元素的HTML内容

高级用法可参考：index.html中的示例配置

3. 内容处理函数

支持文本替换、正则提取等高级处理，格式为：函数名(参数1,参数2)

常用函数示例：

{
  "bookName": "text()|replace(\\s+连载中,)",
  "chapterList": ".chapter@href|regex(/chapter-(\\d+)/,1)"
}

常见问题解决方案

反爬机制处理

部分网站会对频繁请求进行限制，可通过以下方式缓解：

{
  "headers": {
    "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1",
    "Referer": "{{url}}"
  },
  "interval": 1000  // 请求间隔(毫秒)
}

动态加载内容处理

对于JavaScript渲染的页面，需启用WebView渲染模式：

{
  "render": true,
  "renderWait": 3000  // 等待渲染时间(毫秒)
}

规则调试与验证

调试工具

「阅读」APP内置书源调试功能，路径：
我的 > 书源管理 > 右上角菜单 > 书源编辑 > 调试

验证流程

graph TD
    A[编写规则] --> B[导入本地书源]
    B --> C[搜索测试书籍]
    C --> D{结果是否正常?}
    D -->|是| E[完成编写]
    D -->|否| F[检查选择器语法]
    F --> B

规则示例库

基础小说站规则

{
  "name": "示例小说网",
  "url": "https://example.com",
  "searchUrl": "https://example.com/search?wd={{key}}",
  "searchList": ".result-item",
  "bookName": ".book-title@text",
  "author": ".book-author@text",
  "coverUrl": ".book-img@src",
  "describe": ".intro@text|substring(0,150)",
  "chapterUrl": ".book-title@href",
  "chapterList": "#chapter-list li",
  "chapterName": "a@text",
  "content": "#content@html|replace(<br>,,g)"
}

特殊场景适配

图片验证码处理

{
  "needVerify": true,
  "verifyImgUrl": ".verify-img@src",
  "verifySubmitUrl": "https://example.com/verify",
  "verifyCookie": "verify_token"
}

规则维护最佳实践

1. 版本控制：建议使用Git进行规则版本管理，仓库地址：https://gitcode.com/gh_mirrors/yu/Yuedu

2. 定期检测：通过「阅读」APP的「书源检测」功能（路径：我的 > 书源管理 > 批量操作 > 检测）定期验证规则有效性

3. 社区协作：发现失效规则可提交Issues至项目仓库，协作流程参考：README.md

性能优化建议

• 减少DOM操作：优先使用@text而非@html提取文本
• 合理设置缓存：通过cacheTime字段设置结果缓存时间（单位：分钟）
• 避免嵌套解析：复杂页面建议使用webViewRender: true

常见错误排查

错误现象	可能原因	解决方案
搜索无结果	选择器不匹配	使用浏览器开发者工具检查DOM结构
内容乱码	编码问题	添加charset: "GBK"字段
频繁403	IP被封禁	配置proxy: true启用代理

更多问题排查可参考：index.html中的故障排除指南

扩展功能开发

自定义脚本支持

高级用户可通过script字段注入JavaScript代码扩展解析能力，例如：

{
  "script": "function formatContent(html) { return html.replace(/\\n+/g, '<br>'); }"
}

规则加密与解密

为保护优质书源，可对规则进行AES加密处理：

{
  "encrypt": true,
  "key": "yuedu2023"  // 固定加密密钥
}

附录：工具资源

1. 规则生成器：访问index.html使用在线规则生成工具
2. 选择器调试：推荐使用Chrome开发者工具的Elements面板
3. 书源分享平台：
   • 源仓库：https://www.yckceo.com/yuedu/shuyuan
   • Yiove综合书源库：https://shuyuan.yiove.com/complex

上图展示了从书源导入到完成阅读的全流程（图源自项目资源）

通过本文档的指导，您已掌握书源规则编写的核心技能。建议从简单规则开始实践，逐步尝试复杂场景适配。如有疑问，可查阅项目文档或提交Issues获取社区支持。