API文档

/api/author

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

请求方式	GET /api/author

请求参数

参数	类型	必填	说明
id	int	否	作者ID，精确查找
pen_name	string	否	作者笔名，精确查找
dead	int	否	是否只返回已去世作家，1为只返回已去世，0为只返回在世，不传为全部
page	int	否	页码，默认1
page_size	int	否	每页数量，默认24

返回字段

字段	类型	说明
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本
sort	string	否	排行榜/排序类型，支持： read 按已读人数排行 rating 按评分排行（只返回有评分的作品） word_count 按字数排行 first_order 按首订排行 average_sub 按均订排行（只返回有均订数据的作品） max_sub 按高订排行（只返回有高订数据的作品） achievements 按盟主排行 date 按发布日期/完结日期排序（配合 date_type）
order	string	否	排序方式，asc（升序）或 desc（降序），默认 desc
date_type	string	否	"发布" 或 "完结"，配合 sort=date 或 year_month 使用
year_month	string	否	年月筛选，如 202405，配合 date_type 使用
year_list	string	否	"发布" 或 "完结"，返回有数据的年份数组
badge_id	int	否	徽章ID，筛选拥有该徽章的所有作品，支持分页和字段过滤

返回字段

字段	类型	说明
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	首订人数
average_sub	int	均订（平均订阅数）
max_sub	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,
      "average_sub": 80,
      "max_sub": 120,
      "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,
    "average_sub": 80,
    "max_sub": 120,
    "achievements": 5
  }
}

返回结构补充

• 年份列表（year_list=发布 或 year_list=完结）

  {
    "years": [2020, 2021, 2022, 2023, 2024]
  }

• 阅读人数排行（sort=read）

  {
    "page": 1,
    "size": 20,
    "total": 100,
    "novels": [
      {
        "id": 1,
        "title": "小说名",
        "cover": "...",
        "status": "连载中",
        "pen_name": "作家名",
        "read_count": 1234
      }
    ]
  }

• 年月筛选（date_type 和 year_month 搭配）

  {
    "page": 1,
    "size": 20,
    "total": 10,
    "novels": [
      {
        "title": "小说名",
        "publish_date": "2024-05-01",
        "complete_date": "",
        "status": "连载中",
        "pen_name": "作家名",
        "cover": "..."
      }
    ]
  }

更多示例

• 评分排行：
  GET /api/novel?sort=rating&order=desc&page=1&size=10&fields=title,cover,avg_rating,rating_count
• 字数排行：
  GET /api/novel?sort=word_count&order=desc&page=1&size=10&fields=title,cover,word_count
• 首订排行：
  GET /api/novel?sort=first_order&order=desc&page=1&size=10&fields=title,cover,first_order
• 盟主排行：
  GET /api/novel?sort=achievements&order=desc&page=1&size=10&fields=title,cover,achievements
• 高订排行：
  GET /api/novel?sort=max_sub&order=desc&page=1&size=10&fields=title,cover,max_sub
• 按发布日期排序：
  GET /api/novel?sort=date&date_type=发布&order=desc&page=1&size=10&fields=title,cover,publish_date
• 按完结日期排序：
  GET /api/novel?sort=date&date_type=完结&order=desc&page=1&size=10&fields=title,cover,complete_date
• 获取有数据的年份：
  GET /api/novel?year_list=发布 或 GET /api/novel?year_list=完结
• 猜你喜欢：
  GET /api/novel?guest=530&fields=title,cover
• 均订排行：
  GET /api/novel?sort=average_sub&order=desc&page=1&size=10&fields=title,cover,average_sub

注意事项

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

/api/coin

获取金币交易记录、金币排行榜。需登录。

请求方式	GET /api/coin

请求参数

参数	类型	必填	说明
page	int	否	页码，默认1
page_size	int	否	每页数量，默认20，最大100
all	int	否	1为查询所有用户的金币记录（需有权限），否则只查当前用户
top	int	否	1为返回金币排行榜（分页），否则返回金币记录

返回字段

字段	类型	说明
records	array	金币交易记录数组（非排行榜模式）
rankings	array	金币排行榜数组（排行榜模式）
total	int	总记录数
page	int	当前页码
total_pages	int	总页数

金币记录对象字段

字段	类型	说明
id	int	记录ID
user_id	int	用户ID
username	string	用户名
amount	int	变动金额（正为收入，负为支出）
type	string	变动类型（如signin、game_reward等）
description	string	描述
related_id	object	关联ID（如游戏/导出等）
created_at	string	创建时间（ISO8601）

排行榜对象字段

字段	类型	说明
user_id	int	用户ID
username	string	用户名
avatar_path	string	头像URL（如为空请用 /api/avatar?size=28&seed=用户名 兜底）
coin_balance	int	金币余额
rank	int	排名

请求示例

GET /api/coin?page=1&page_size=20
GET /api/coin?all=1&page=1&page_size=20
GET /api/coin?top=1&page=1&page_size=9

返回示例（排行榜）

{
  "page": 1,
  "total": 454,
  "total_pages": 51,
  "rankings": [
    {"user_id":1,"username":"dianso","avatar_path":"/data/user/1/avatar.svg","coin_balance":27672,"rank":1},
    {"user_id":416,"username":"白夜染心","avatar_path":"/data/user/416/avatar_1748186248394.png","coin_balance":5772,"rank":2},
    {"user_id":202,"username":"呵呵","avatar_path":"","coin_balance":1704,"rank":4}
  ]
}

返回示例（金币记录）

{
  "page": 1,
  "total": 277,
  "total_pages": 14,
  "records": [
    {"id":2870,"user_id":1,"username":"dianso","amount":105,"type":"signin","description":"每日签到奖励","related_id":{"Int64":0,"Valid":false},"created_at":"2025-06-29T00:20:19+08:00"}
  ]
}

说明

• 排行榜模式（top=1）和金币记录模式返回结构不同。
• 排行榜头像如为空，前端可用 /api/avatar?size=28&seed=用户名 兜底。
• 金币记录 amount 为正表示收入，为负表示支出。
• type 字段详见前端 type->中文映射。

/api/badges

获取所有徽章及其发放数量。

请求方式	GET /api/badges

请求参数

返回字段

字段	类型	说明
id	int	徽章ID
name	string	徽章名称
color	string	徽章颜色（HEX）
text_color	string	徽章文字颜色（HEX）
description	string	徽章描述
logo	string	徽章图片URL
count	int	获得该徽章的作品数量

示例

GET /api/badges

返回：
[
  {
    "id": 1,
    "name": "精品作品",
    "color": "#FFD700",
    "text_color": "#000000",
    "description": "获得精品作品称号的小说",
    "logo": "/static/img/badges/gold.png",
    "count": 12
  },
  {
    "id": 2,
    "name": "月票冠军",
    "color": "#00BFFF",
    "text_color": "#ffffff",
    "description": "月票排行第一的作品",
    "logo": "/static/img/badges/champion.png",
    "count": 5
  }
]