📖 小说管理 API

响应：200 OK，返回小说数组

[
  {
    "id": "1738368000000abc123",
    "resourceType": "novel",
    "name": "三体",
    "description": "地球往事三部曲第一部，讲述了地球文明和三体文明的信息交流、生死搏杀以及两个文明在宇宙中的兴衰历程。",
    "author": "刘慈欣",
    "genre": "科幻",
    "tags": ["科幻", "硬科幻", "雨果奖"],
    "resourcePath": "E:\\Books\\三体.epub",
    "coverPath": "E:\\Books\\Covers\\三体.jpg",
    "publishYear": "2008",
    "visitedSessions": [
      "2025-12-01T10:30:00.000Z",
      "2025-12-15T14:20:00.000Z"
    ],
    "addedDate": "2025-11-20T08:00:00.000Z",
    "rating": 5,
    "comment": "非常精彩的硬科幻作品",
    "isFavorite": true
  }
]

JavaScript

// 获取所有小说
fetch('http://localhost:3000/api/novels')
  .then(response => response.json())
  .then(novels => console.log(novels))
  .catch(error => console.error('Error:', error));

Python

import requests

# 获取所有小说
response = requests.get('http://localhost:3000/api/novels')
novels = response.json()
print(novels)

参数：id - 小说ID

响应：200 OK 返回小说对象，不存在则 404

{
  "id": "1738368000000abc123",
  "resourceType": "novel",
  "name": "三体",
  "description": "地球往事三部曲第一部，讲述了地球文明和三体文明的信息交流、生死搏杀以及两个文明在宇宙中的兴衰历程。",
  "author": "刘慈欣",
  "genre": "科幻",
  "tags": ["科幻", "硬科幻", "雨果奖"],
  "resourcePath": "E:\\Books\\三体.epub",
  "coverPath": "E:\\Books\\Covers\\三体.jpg",
  "publishYear": "2008",
  "visitedSessions": [
    "2025-12-01T10:30:00.000Z",
    "2025-12-15T14:20:00.000Z"
  ],
  "addedDate": "2025-11-20T08:00:00.000Z",
  "rating": 5,
  "comment": "非常精彩的硬科幻作品",
  "isFavorite": true
}

JavaScript

// 获取单个小说
const novelId = '1738368000000abc123';
fetch(`http://localhost:3000/api/novels/${novelId}`)
  .then(response => response.json())
  .then(novel => console.log(novel))
  .catch(error => console.error('Error:', error));

Python

import requests

# 获取单个小说
novel_id = '1738368000000abc123'
response = requests.get(f'http://localhost:3000/api/novels/{novel_id}')
novel = response.json()
print(novel)

请求体：

{
  "name": "三体",
  "description": "地球往事三部曲第一部",
  "author": "刘慈欣",
  "genre": "科幻",
  "tags": ["科幻", "硬科幻", "雨果奖"],
  "resourcePath": "E:\\Books\\三体.epub",
  "coverPath": "E:\\Books\\Covers\\三体.jpg",
  "publishYear": "2008",
  "rating": 5,
  "comment": "非常精彩的硬科幻作品",
  "isFavorite": true
}

响应：201 Created，返回创建的小说对象

注意：ID 和 addedDate 会自动生成

JavaScript

// 创建小说
fetch('http://localhost:3000/api/novels', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: '三体',
    description: '地球往事三部曲第一部',
    author: '刘慈欣',
    genre: '科幻',
    tags: ['科幻', '硬科幻', '雨果奖'],
    resourcePath: 'E:\\Books\\三体.epub',
    rating: 5
  })
})
  .then(response => response.json())
  .then(novel => console.log('Created:', novel))
  .catch(error => console.error('Error:', error));

Python

import requests

# 创建小说
novel_data = {
    'name': '三体',
    'description': '地球往事三部曲第一部',
    'author': '刘慈欣',
    'genre': '科幻',
    'tags': ['科幻', '硬科幻', '雨果奖'],
    'resourcePath': 'E:\\Books\\三体.epub',
    'rating': 5
}

response = requests.post('http://localhost:3000/api/novels', json=novel_data)
novel = response.json()
print('Created:', novel)

参数：id - 小说ID

请求体：要更新的字段（JSON 对象，只需传要修改的字段）

{
  "rating": 5,
  "comment": "重读后更加喜欢了",
  "isFavorite": true
}

响应：200 OK，返回更新后的小说对象

注意：ID 和 addedDate 字段不允许修改

JavaScript

// 更新小说
const novelId = '1738368000000abc123';
fetch(`http://localhost:3000/api/novels/${novelId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    rating: 5,
    comment: '重读后更加喜欢了'
  })
})
  .then(response => response.json())
  .then(novel => console.log('Updated:', novel))
  .catch(error => console.error('Error:', error));

Python

import requests

# 更新小说
novel_id = '1738368000000abc123'
update_data = {
    'rating': 5,
    'comment': '重读后更加喜欢了'
}

response = requests.put(f'http://localhost:3000/api/novels/{novel_id}', json=update_data)
novel = response.json()
print('Updated:', novel)

参数：id - 小说ID

响应：204 No Content（成功）或 404 Not Found（不存在）

注意：删除操作不会删除本地小说文件，仅移除管理器中的引用

JavaScript

// 删除小说
const novelId = '1738368000000abc123';
fetch(`http://localhost:3000/api/novels/${novelId}`, {
  method: 'DELETE'
})
  .then(response => {
    if (response.status === 204) {
      console.log('Novel deleted successfully');
    }
  })
  .catch(error => console.error('Error:', error));

Python

import requests

# 删除小说
novel_id = '1738368000000abc123'
response = requests.delete(f'http://localhost:3000/api/novels/{novel_id}')

if response.status_code == 204:
    print('Novel deleted successfully')

小说对象包含以下字段：

• id - 小说唯一标识符（自动生成，不可修改）
• resourceType - 资源类型，固定为 "novel"
• name - 小说名称（必需）
• description - 小说简介
• author - 作者
• genre - 类型（如：科幻、奇幻、言情等）
• tags - 标签数组
• resourcePath - 小说文件路径
• coverPath - 封面图片路径
• publishYear - 出版年份
• visitedSessions - 访问会话时间数组（ISO 字符串数组，记录每次阅读时间）
• addedDate - 添加日期（自动生成，不可修改）
• rating - 评分（1-5 或 0）
• comment - 备注
• isFavorite - 是否收藏

API 使用标准的 HTTP 状态码：

• 200 OK - 请求成功
• 201 Created - 资源创建成功
• 204 No Content - 删除成功
• 400 Bad Request - 请求参数错误（如缺少必需字段）
• 404 Not Found - 资源不存在
• 500 Internal Server Error - 服务器内部错误

错误响应格式：

{
  "error": "小说名称不能为空"
}