✨ feat(api): 统一响应格式并完善参数体系与文档

- 正文参数支持语义值(plain/html/keep/remove)与别名(img_mode/review_mode),URL 参数优先于配置
- 修复纯文本被段评强制包回 HTML、HTML 模式段评注入失效的问题
- 修复 PKCS7 填充弱校验导致漫画/正文偶发解密乱码返回 200 的问题
- 搜索结果展平:去 search_tabs 层与 selected_tab_idx/server_ab_params,提升 has_more/next_offset
- 全接口解包字符串形式的 JSON 字段(category_schema 等),缓存出口幂等处理
- 序列化关闭 HTML 转义,video/audio 播放链接可直接复制播放
- video 响应透传 CENC 加密状态(key_seed/kid/encryption_method)
- 新增 gzip 中间件,JSON/文本响应压缩约 81%,二进制透传
- 漫画默认输出模式改为 proxy(url 模式链接 404 且内容加密不可用)
- openapi.yaml:补全 23 个路径参数定义、tab_type 完整枚举、CDN 签名说明,示例更新
This commit is contained in:
chenxin committed 2026-10-09 21:01:18 +08:00
1 parent bfb4290c15
commit 1a4997e031
25 files changed
+489 -199

No files matched your search

+13 -11
View File
@@ -143,7 +143,7 @@ go run ./cmd/fanqie
| 接口 | 方法 | 说明 | 参数 |
| ------ | ------ | ------ | ------ |
| `/search` | GET | 搜索书籍 | `query`(或 `key`), `tab_type`, `offset`(`search_tabs` 仅返回匹配 `tab_type` 的 tab) |
| `/search` | GET | 搜索书籍 | `query`(或 `key`), `tab_type`, `offset`(结果在顶层 `data`,已按 `tab_type` 过滤展平) |
| `/detail` | GET | 书籍详情 | `book_id` |
| `/info` | GET | 书籍详情(同 detail) | `book_id` |
| `/catalog` | GET | 章节目录 | `book_id` |
@@ -163,8 +163,8 @@ go run ./cmd/fanqie
| 接口 | 方法 | 说明 | 参数 |
| ------ | ------ | ------ | ------ |
| `/chapter_review` | GET | 章节评论 | `book_id`, `item_id` |
| `/review` | GET | 书评列表 | `book_id`, `item_id`, `para`, `comment_id`, `offset`, `limit` |
| `/review_html` | GET | 评论 HTML | `book_id`, `item_id`, `para` |
| `/review` | GET | 书评列表 | `book_id`, `item_id`, `para`, `comment_id`, `sort`, `offset`, `count` |
| `/review_html` | GET | 评论 HTML | `book_id`, `item_id`, `para`, `sort`, `page`, `page_size` |
### 分类相关
@@ -205,16 +205,18 @@ GET http://localhost:40180/catalog?book_id=xxx
### 获取章节内容
```bash
GET http://localhost:40180/content?book_id=xxx&chapter_id=xxx
GET http://localhost:40180/content?item_id=xxx
```
支持以下 URL 参数覆盖默认配置:
| 参数 | 说明 | 可选值 |
| ------ | ------ | ------ |
| `text_mode` | 文本模式 | `plain`(纯文本), `html`(HTML) |
| `img_mode` | 图片模式 | `remove`(移除), `keep`(保留) |
| `review_mode` | 评论模式 | `remove`(移除), `keep`(保留) |
| `text_mode` | 文本模式 | `plain`(纯文本), `html`(HTML), 或 `1`/`0` |
| `img_mode`(或 `image_mode`) | 图片模式 | `remove`(移除), `keep`(保留), 或 `0`/`1` |
| `review_mode`(或 `review`) | 评论模式 | `keep`(启用段评), `remove`(禁用), 或 `1`/`0` |
纯文本输出(`text_mode=plain` 或配置 `remove_html_tags: true`)时不注入段评标记——`<comment>` 为 XML 标签,纯文本无法承载;需要段评时配置 `remove_html_tags: false`。
### 批量获取
@@ -268,10 +270,10 @@ fanqie:
# 漫画处理
manga:
# 输出模式:
# - "proxy": 代理模式
# - "url": 直接返回图片 URL
# - "proxy": 代理模式(图片已解密,推荐;"url" 返回的原始链接 404 且内容加密不可用)
# - "data_uri": Base64 编码
output_mode: "url"
# - "url": 直接返回图片 URL(不可用)
output_mode: "proxy"
# 缓存配置
cache:
@@ -336,7 +338,7 @@ cp .env.example .env
| `fanqie.algorithm` | 签名算法 `gorgon` / `8404` | `gorgon` |
| `fanqie.signature` | 签名方法 `sign2` / `sign4` | `sign4` |
| `fanqie.content.*` | 正文内容处理选项 | 见上文 |
| `fanqie.manga.output_mode` | 漫画输出模式 | `url` |
| `fanqie.manga.output_mode` | 漫画输出模式 | `proxy` |
| `cache.enabled` | 是否启用正文内容缓存 | `true` |
| `cache.backend` | SQL 存储后端 `sqlite` / `postgres` | `sqlite` |
| `cache.sqlite_path` | SQLite 数据库路径 | `./cache.db` |