API文档

/api/tags

获取标签信息，支持多种参数筛选和字段定制。

请求方式	GET /api/tags

请求参数

参数	类型	必填	说明
hot	int	否	返回最热门的前N个标签（按作品数量排序）
random	int	否	随机返回N个标签
fields	string	否	指定返回字段，逗号分隔，如fields=name,alias
novel_title	string	否	根据作品名返回该作品的标签

返回字段

字段	类型	说明
id	int	标签ID
name	string	标签名称
alias	string	标签别名（用于URL）
abbr	string	拼音首字母缩写
novel_count	int	该标签下作品数量

/api/author

获取作者信息，支持按ID或笔名查询。

请求方式	GET /api/author

请求参数

参数	类型	必填	说明
id	int	否	作者ID，精确查找
pen_name	string	否	作者笔名，精确查找

返回字段

字段	类型	说明
id	int	作者ID
pen_name	string	笔名
alias	string	别名/马甲
real_name	string	本名
nationality	string	国籍
gender	string	性别
ethnicity	string	民族
age	int	年龄
province	string	省份
identity	string	身份/职业
signed_website	string	签约网站
bio	string	个人简介
avatar	object	头像对象，含 String（头像URL）和 Valid（是否有效）
is_dead	bool	是否已去世
created_at	string	创建时间（ISO8601）
updated_at	string	更新时间（ISO8601）

/api/novel

获取小说列表或单本详情，支持多种筛选、字段定制和分页。

请求方式	GET /api/novel

请求参数

参数	类型	必填	说明
id	int	否	小说ID，返回单本详情，和分页参数互斥
user_id	int	否	用户ID，返回该用户最近阅读小说（配合 fields=note 返回读书笔记）
page	int	否	页码，默认1
size	int	否	每页数量，默认20，最大100
fields	string	否	只返回指定字段，逗号分隔，如 fields=title,cover
exclude	string	否	排除指定字段，逗号分隔，如 exclude=summary
author	string	否	作家笔名筛选
author_id	int	否	作家ID筛选
tag	string	否	标签别名筛选
keyword	string	否	关键字模糊搜索
random	int/bool	否	1为随机返回N本小说（配合size）
guest	int	否	以该作品ID为基础，返回猜你喜欢的6本小说

返回字段

字段	类型	说明
id	int	小说ID
title	string	书名
alias	string	别名/短链
author_id	int	作者ID
pen_name	string	作者笔名
author_alias	string	作者马甲
author_realname	string	作者本名
genre	string	题材分类
word_count	int	字数
status	string	连载状态
publish_date	string	首发日期（YYYY-MM-DD）
complete_date	string	完结日期（YYYY-MM-DD）
summary	string	简介（可用 exclude 排除）
cover	object	封面对象，含 String（图片URL）和 Valid
original_site	string	首发站点名称，如"起点中文网"
read_link	string	试读链接URL，若有则页面显示"试读"按钮
avg_rating	float	平均评分
rating_count	int	评分人数
is_public	bool	是否公开
created_at	string	创建时间（ISO8601）
updated_at	string	更新时间（ISO8601）
badges	array	获得的徽章（对象数组）
tags	array	标签（对象数组）
first_order	int	首订人数
achievements	int	盟主/成就数字
note	string	用户读书笔记（需带 user_id 且 fields 包含 note）

分页与返回结构

{
  "page": 1,
  "size": 20,
  "total": 123,
  "novels": [
    {
      "id": 1,
      "title": "小说名",
      "cover": {"String": "/cover/xxx.jpg", "Valid": true},
      "status": "连载中",
      "avg_rating": 8.9,
      "pen_name": "作家名",
      "word_count": 123456,
      "publish_date": "2020-01-01",
      "first_order": 100,
      "achievements": 5,
      "note": "用户读书笔记内容"
      // ... 其它字段 ...
    }
  ]
}

单本详情返回结构

{
  "novel": {
    "id": 123,
    "title": "三体",
    "alias": "3body",
    "author_id": 1,
    "pen_name": "刘慈欣",
    "author_alias": "大刘",
    "author_realname": "刘慈欣",
    "genre": "科幻",
    "word_count": 300000,
    "status": "已完结",
    "publish_date": "2008-01-01",
    "complete_date": "2010-01-01",
    "summary": "黑暗森林法则...",
    "cover": {"String": "/cover/3body.jpg", "Valid": true},
    "original_site": "起点中文网",
    "read_link": "https://www.qidian.com/book/123",
    "avg_rating": 9.2,
    "rating_count": 10000,
    "is_public": true,
    "created_at": "2008-01-01T00:00:00Z",
    "updated_at": "2024-06-07T12:00:00Z",
    "badges": [ { "id": 1, "name": "金奖" } ],
    "tags": [ { "id": 2, "name": "科幻" } ],
    "first_order": 100,
    "achievements": 5
  }
}

示例请求

• 获取单本详情（不含 summary 字段）：
  GET /api/novel?id=123&exclude=summary
• 获取某作家所有小说：
  GET /api/novel?author=刘慈欣&fields=title,word_count,status
• 获取随机1本小说：
  GET /api/novel?random=1&size=1&fields=title,pen_name
• 获取用户最近阅读小说及笔记：
  GET /api/novel?user_id=1001&fields=title,note

注意事项

• fields 和 exclude 可灵活组合，建议前端只请求所需字段，提升性能。
• cover 字段为对象，需取 String 属性为图片URL。
• badges、tags 字段为对象数组，结构见实际返回。
• note 字段仅在带 user_id 且 fields 包含 note 时返回。
• publish_date、complete_date 格式为 YYYY-MM-DD，如无则为空字符串。
• first_order、achievements 字段为数字，分别表示首订和盟主数。

/api/avatar

生成动物风格头像，支持多种参数和动物类型。

请求方式	GET /api/avatar

请求参数

参数	类型	必填	说明
size	int	否	头像尺寸，默认200，范围50-500
seed	int/string	否	随机种子，相同种子生成相同头像
style	string	否	头像风格，animal=动物头像（默认）
animal	string	否	指定动物类型，支持： cat 猫、dog 狗、rabbit 兔子、bear 熊、fox 狐狸、tiger 老虎、lion 狮子、monkey 猴子、pig 猪、panda 熊猫、frog 青蛙、chick 小鸡、duck 鸭子、cow 奶牛、sheep 羊、squirrel 松鼠、koala 考拉、hippo 河马、giraffe 长颈鹿、penguin 企鹅、horse 马、deer 鹿、elephant 大象、wolf 狼、mouse 老鼠、owl 猫头鹰、camel 骆驼、crocodile 鳄鱼、zebra 斑马、goat 山羊、hedgehog 刺猬、raccoon 浣熊、whale 鲸鱼、dolphin 海豚、shark 鲨鱼、eagle 鹰、parrot 鹦鹉、turtle 乌龟、snake 蛇、bat 蝙蝠

效果演示

示例请求

GET /api/avatar?size=200&seed=1&style=animal&animal=bear

/api/search

综合搜索作家与作品，支持关键词、分页等参数。

请求方式	GET /api/search

请求参数

参数	类型	必填	说明
keyword	string	是	搜索关键词，支持作家名或作品名模糊匹配
author_page	int	否	作家分页页码，默认1
novel_page	int	否	作品分页页码，默认1

返回字段

字段	类型	说明
author_page	int	当前作家页码
author_total	int	作家总数
authors	array	作家列表，见下方结构
novel_page	int	当前作品页码
novel_total	int	作品总数
novels	array	作品列表，见下方结构

作家对象结构

字段	类型	说明
id	int	作家ID
pen_name	string	笔名
avatar	object	头像对象，含 String（头像URL）和 Valid

作品对象结构

字段	类型	说明
id	int	作品ID
title	string	书名
cover	object	封面对象，含 String（图片URL）和 Valid
status	string	连载状态，如"连载中"或"已完结"
pen_name	string	作家笔名

示例请求

GET /api/search?keyword=天地&author_page=1&novel_page=1

示例响应

{
  "author_page": 1,
  "author_total": 0,
  "authors": [],
  "novel_page": 1,
  "novel_total": 3,
  "novels": [
    {
      "cover": {"String": "/data/novel/天地龙魂.avif", "Valid": true},
      "id": 1509,
      "pen_name": "高楼大厦",
      "status": "已完结",
      "title": "天地龙魂"
    },
    ...
  ]
}