kerryprops_bookmarks/项目/book/接口文档.md

书籍管理系统 API 设计

基于之前设计的 MySQL 表结构，以下是完整的 RESTful API 设计，包含调用示例和必填/非必填项说明。

1. 作者管理接口

1.1 创建作者

POST /api/authors

​​请求参数​​：

{
  "name": "鲁迅", // 必填
  "bio": "中国现代文学奠基人", // 非必填
  "birth_date": "1881-09-25", // 非必填
  "death_date": "1936-10-19", // 非必填
  "nationality": "中国" // 非必填
}

​​成功响应​​：

{
  "author_id": 1,
  "name": "鲁迅",
  "bio": "中国现代文学奠基人",
  "birth_date": "1881-09-25",
  "death_date": "1936-10-19",
  "nationality": "中国",
  "created_at": "2023-08-01T10:00:00Z"
}

1.2 获取作者列表

GET /api/authors?page=1&page_size=10&name=鲁迅

​​查询参数​​：

• page: 页码 (非必填，默认1)
• page_size: 每页数量 (非必填，默认10)
• name: 作者姓名模糊搜索 (非必填)

​​成功响应​​：

{
  "total": 1,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "author_id": 1,
      "name": "鲁迅",
      "bio": "中国现代文学奠基人",
      "birth_date": "1881-09-25",
      "death_date": "1936-10-19",
      "nationality": "中国"
    }
  ]
}

2. 书籍管理接口

2.1 创建书籍

POST /api/books

​​请求参数​​：

{
  "title": "呐喊", // 必填
  "author_id": 1, // 必填
  "type_id": 1, // 必填
  "cover_image_url": "https://example.com/nahan.jpg", // 非必填
  "description": "鲁迅的第一部小说集", // 非必填
  "isbn": "9787020090006", // 非必填
  "publish_date": "1923-08-01", // 非必填
  "publisher": "新潮社", // 非必填
  "page_count": 200, // 非必填
  "language": "中文", // 非必填
  "status": "published" // 非必填，默认draft
}

​​成功响应​​：

{
  "book_id": 1,
  "title": "呐喊",
  "author_id": 1,
  "type_id": 1,
  "cover_image_url": "https://example.com/nahan.jpg",
  "status": "published",
  "created_at": "2023-08-01T10:00:00Z"
}

2.2 更新书籍信息

PUT /api/books/{book_id}

​​请求参数​​：

{
  "title": "呐喊（修订版）", // 非必填
  "description": "鲁迅的第一部小说集，包含《狂人日记》等名篇", // 非必填
  "status": "published" // 非必填
}

​​成功响应​​：

{
  "book_id": 1,
  "title": "呐喊（修订版）",
  "description": "鲁迅的第一部小说集，包含《狂人日记》等名篇",
  "updated_at": "2023-08-01T11:00:00Z"
}

3. 章节管理接口

3.1 创建章节

POST /api/books/{book_id}/chapters

​​请求参数​​：

{
  "chapter_number": 1, // 必填
  "title": "狂人日记", // 必填
  "content": "今天晚上，很好的月光..." // 非必填
}

​​成功响应​​：

{
  "chapter_id": 1,
  "book_id": 1,
  "chapter_number": 1,
  "title": "狂人日记",
  "word_count": 0,
  "created_at": "2023-08-01T10:00:00Z"
}

3.2 更新章节内容

PUT /api/chapters/{chapter_id}/content

​​请求参数​​：

{
  "content": "今天晚上，很好的月光...我不见他，已是三十多年...", // 必填
  "change_reason": "修正错别字" // 非必填
}

​​成功响应​​：

{
  "content_id": 1,
  "chapter_id": 1,
  "version": 2,
  "word_count": 15,
  "updated_at": "2023-08-01T11:00:00Z"
}

4. 历史记录查询接口

4.1 获取书籍修改历史

GET /api/books/{book_id}/history?page=1&page_size=10

​​查询参数​​：

• page: 页码 (非必填，默认1)
• page_size: 每页数量 (非必填，默认10)

​​成功响应​​：

{
  "total": 2,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "history_id": 1,
      "title": "呐喊",
      "description": "鲁迅的第一部小说集",
      "changed_at": "2023-08-01T10:00:00Z"
    },
    {
      "history_id": 2,
      "title": "呐喊（修订版）",
      "description": "鲁迅的第一部小说集，包含《狂人日记》等名篇",
      "changed_at": "2023-08-01T11:00:00Z"
    }
  ]
}

4.2 获取章节内容历史

GET /api/chapters/{chapter_id}/content/history?page=1&page_size=10

​​成功响应​​：

{
  "total": 2,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "history_id": 1,
      "version": 1,
      "word_count": 0,
      "change_reason": "初始版本",
      "changed_at": "2023-08-01T10:00:00Z"
    },
    {
      "history_id": 2,
      "version": 2,
      "word_count": 15,
      "change_reason": "修正错别字",
      "changed_at": "2023-08-01T11:00:00Z"
    }
  ]
}

5. 错误响应

所有接口的错误响应格式统一：

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "作者ID不能为空",
    "details": {
      "author_id": "该字段为必填项"
    }
  }
}

常见错误码：

• INVALID_PARAMETER: 参数验证失败
• RESOURCE_NOT_FOUND: 资源不存在
• DUPLICATE_RESOURCE: 资源已存在
• PERMISSION_DENIED: 权限不足

接口设计说明

1. ​​必填项验证​​：所有创建接口的必填字段都会进行验证
2. ​​版本控制​​：章节内容修改会自动生成新版本
3. ​​分页查询​​：所有列表接口都支持分页
4. ​​历史追踪​​：书籍和章节的修改都会记录历史
5. ​​RESTful风格​​：资源路径清晰，HTTP方法语义明确

这个API设计覆盖了表结构中的所有核心功能，并考虑了实际应用场景中的需求。