API文档

/api/author

获取作家列表，支持分页、筛选和搜索功能。

请求参数

返回字段

列表查询返回示例

{
  "authors": [
    {
      "id": 1,
      "pen_name": "刘慈欣",
      "alias": "大刘",
      "real_name": "刘慈欣",
      "nationality": "中国",
      "gender": "男",
      "ethnicity": "汉族",
      "age": 60,
      "province": "山西",
      "identity": "作家、工程师",
      "signed_website": "起点中文网",
      "achievements": "雨果奖获得者",
      "bio": "中国科幻作家，代表作《三体》系列。",
      "avatar": {"String": "/avatar/liucixin.jpg", "Valid": true},
      "is_dead": false,
      "is_public": true,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2024-06-07T12:00:00Z"
    }
  ],
  "total_authors": 156,
  "total_pages": 7,
  "page": 1,
  "page_size": 24
}

单个查询返回示例

{
  "authors": [
    {
      "id": 1,
      "pen_name": "刘慈欣",
      "alias": "大刘",
      "real_name": "刘慈欣",
      "nationality": "中国",
      "gender": "男",
      "ethnicity": "汉族",
      "age": 60,
      "province": "山西",
      "identity": "作家、工程师",
      "signed_website": "起点中文网",
      "achievements": "雨果奖获得者",
      "bio": "中国科幻作家，代表作《三体》系列。",
      "avatar": {"String": "/avatar/liucixin.jpg", "Valid": true},
      "is_dead": false,
      "is_public": true,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2024-06-07T12:00:00Z"
    }
  ],
  "total_authors": 1,
  "total_pages": 1,
  "page": 1,
  "page_size": 1
}

字段过滤返回示例

{
  "authors": [
    {
      "id": 1,
      "pen_name": "刘慈欣",
      "avatar": "/avatar/liucixin.jpg"
    }
  ],
  "total_authors": 156,
  "total_pages": 156,
  "page": 1,
  "page_size": 1
}

请求示例

• 获取所有作者（分页）：
  GET /api/author?page=1&page_size=20
• 通过ID查找作者：
  GET /api/author?id=1
• 通过笔名查找作者：
  GET /api/author?pen_name=刘慈欣
• 获取已去世作者：
  GET /api/author?dead=1&page=1&page_size=10
• 获取在世作者：
  GET /api/author?dead=0&page=1&page_size=10
• 获取随机作者：
  GET /api/author?random=6
• 只返回指定字段：
  GET /api/author?fields=id,pen_name,avatar

注意事项

• 使用 id 或 pen_name 参数时，返回单个作者的包装格式。
• avatar 字段为对象格式，包含 String（URL）和 Valid（是否有效）。
• 使用 fields 参数时，avatar 字段会简化为字符串格式。
• dead 参数支持字符串格式："1"、"0"。
• size 和 page_size 参数功能相同，推荐使用 page_size。

/api/novel

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

请求参数

返回字段

列表查询返回示例

{
  "page": 1,
  "size": 20,
  "total": 1234,
  "novels": [
    {
      "id": 1,
      "title": "三体",
      "alias": "Three-Body",
      "author_id": 10,
      "pen_name": "刘慈欣",
      "genre": "科幻",
      "word_count": 300000,
      "status": "已完结",
      "publish_date": "2008-01-01T00:00:00Z",
      "complete_date": "2010-01-01T00:00:00Z",
      "summary": "地球往事三部曲之一。",
      "first_order": 1000,
      "average_sub": 800,
      "max_sub": 1200,
      "achievements": 50,
      "original_site": "起点中文网",
      "read_link": "https://www.qidian.com/book/1",
      "avg_rating": 9.5,
      "rating_count": 10000,
      "is_public": true,
      "cover": {"String": "/covers/1.jpg", "Valid": true},
      "created_at": "2008-01-01T00:00:00Z",
      "updated_at": "2010-01-01T00:00:00Z"
    }
  ]
}

请求示例

• 获取小说列表：
  GET /api/novel?page=1&size=20
• 通过ID查找小说：
  GET /api/novel?id=1
• 通过标题查找小说：
  GET /api/novel?title=三体
• 按作者筛选：
  GET /api/novel?author=刘慈欣
• 按标签筛选：
  GET /api/novel?tag=sci-fi
• 关键词搜索：
  GET /api/novel?keyword=科幻
• 随机小说：
  GET /api/novel?random=1&size=10
• 按评分排行：
  GET /api/novel?sort=rating&order=desc
• 按字数排行：
  GET /api/novel?sort=word_count&order=desc
• 按发布日期排序：
  GET /api/novel?sort=date&date_type=发布&order=desc
• 年月筛选：
  GET /api/novel?year_month=202405&date_type=发布
• 获取年份列表：
  GET /api/novel?year_list=发布
• 按徽章筛选：
  GET /api/novel?badge_id=1
• 只返回指定字段：
  GET /api/novel?fields=id,title,pen_name
• 排除指定字段：
  GET /api/novel?exclude=summary
• 获取用户笔记：
  GET /api/novel?user_id=123&fields=note

注意事项

• 使用 id 或 title 参数时，返回单个小说的完整详情，包含标签和徽章信息。
• 未登录用户只能查看公开小说（is_public=true）。
• sort 参数支持多种排序方式，配合 order 控制升降序。
• year_month 格式为 YYYYMM，如 202405 表示2024年5月。
• guest 和 guest_title 用于推荐相似小说。
• 使用 fields 和 exclude 可以精确控制返回的字段。
• user_id 配合 fields=note 可以获取用户的读书笔记。

/api/info

获取网站基本信息，包括统计数据和首页标题信息。

请求参数

无需参数

返回字段

返回示例

GET /api/info

返回：
{
  "novel_count": 1234,
  "author_count": 567,
  "home_main_title": "网文数据库",
  "home_sub_title": "在Zuo，连接志同道合的读者"
}

说明

• 此接口无需认证，可公开访问。
• 统计数据实时从数据库获取，确保准确性。
• 标题信息来自系统设置，如果设置不存在则返回默认值。
• 适用于首页展示、统计面板等场景。

/api/coin

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

请求参数

返回字段

金币记录对象字段

排行榜对象字段

请求示例

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}
  ]
}

说明

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

/api/badges

获取徽章信息。支持获取所有徽章列表或按名称查询单个徽章。

请求参数

返回字段

获取所有徽章时返回数组，按名称查询时返回单个对象

示例

获取所有徽章：

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
  }
]

按名称查询单个徽章：

GET /api/badges?name=精品作品

返回：
{
  "id": 1,
  "name": "精品作品",
  "color": "#FFD700",
  "text_color": "#000000",
  "description": "获得精品作品称号的小说",
  "logo": "/static/img/badges/gold.png",
  "count": 12
}

注意事项

• 按名称查询时，先进行精确匹配，如果没有找到则进行模糊匹配
• 如果徽章不存在，返回404状态码和错误信息
• 所有徽章按获得该徽章的作品数量降序排列
• 需要API Token认证

/api/booklist

书单相关API，支持书单的增删改查、书单内小说的管理等操作。

主要路由

• GET /api/booklist　获取公开书单列表
• GET /api/booklist/{id}　获取单个书单详情及其小说
• POST /api/booklist　新建书单（需登录）
• PUT /api/booklist　编辑书单（需登录）
• DELETE /api/booklist　删除书单（需登录）
• POST /api/booklist/{id}/novel　向书单添加小说
• PUT /api/booklist/{id}/novel/{novel_id}　修改书单中小说评语
• DELETE /api/booklist/{id}/novel/{novel_id}　移除书单中的小说

GET /api/booklist

获取书单列表，支持三种场景：

• 全站公开书单： GET /api/booklist?page=1&page_size=10
• 当前用户所有书单： GET /api/booklist?user_id=me&page=1&page_size=10（需登录）
• 指定用户的所有公开书单： GET /api/booklist?user_id={id}&page=1&page_size=10

返回字段

示例

GET /api/booklist?user_id=me&page=1&page_size=5

返回：
{
  "list": [
    {
      "id": 1,
      "user_id": 2,
      "title": "我的科幻书单",
      "description": "收录喜欢的科幻小说",
      "is_public": true,
      "created_at": "2024-06-01T12:00:00Z",
      "updated_at": "2024-06-10T12:00:00Z",
      "username": "张三"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 5
}

注意事项

• 所有涉及创建、编辑、删除操作均需登录。
• 只有书单拥有者可编辑/删除书单及其小说。
• 添加小说时如已存在会报错。
• 移除小说需为书单拥有者。