一、接口概述

本接口文档用于描述图书管理系统中的一系列 Restful 接口，涵盖图书的查询、添加、更新与删除操作，以及用户的登录注册等功能，方便客户端与服务器之间进行数据交互。

二、接口基础信息

• 接口地址：https://book-management-api.example.com/api

• 请求方式：支持 GET、POST、PUT、DELETE

• 请求数据格式：JSON

• 响应数据格式：JSON

三、接口详情

（一）用户注册接口

• 接口名称：/users/register

• 接口描述：新用户注册账号，提交用户名、密码、邮箱等信息创建新用户记录。

• 请求方式：POST

• 请求参数：

{"username": "string","password": "string","email": "string"
}

• 响应状态码及说明

  • 201 Created：用户注册成功，响应示例：

{"message": "用户注册成功","user_id": 123
}

• 400 Bad Request：请求数据格式错误或用户名已存在等情况，示例：

{"error": "用户名已存在，请更换用户名"
}

（二）用户登录接口

• 接口名称：/users/login

• 接口描述：用户提交用户名和密码进行登录验证，成功后返回认证令牌。

• 请求方式：POST

• 请求参数：

{"username": "string","password": "string"
}

• 响应状态码及说明

  • 200 OK：登录成功，返回令牌，示例：

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

• 401 Unauthorized：用户名或密码错误，示例：

{"error": "用户名或密码错误"
}

（三）获取所有图书接口

• 接口名称：/books

• 接口描述：获取图书管理系统中所有图书的信息列表。

• 请求方式：GET

• 请求参数：无

• 响应状态码及说明

  • 200 OK：成功获取图书列表，响应示例：

[{"book_id": 1,"title": "百年孤独","author": "加西亚·马尔克斯","publication_year": 1967,"isbn": "9787544253994"},{"book_id": 2,"title": "平凡的世界","author": "路遥","publication_year": 1986,"isbn": "9787530212004"}
]

（四）获取单本图书接口

• 接口名称：/books/{book_id}

• 接口描述：根据图书 ID 获取特定图书的详细信息。

• 请求方式：GET

• 请求参数

  • book_id：路径参数，整数类型，必填，指定要查询的图书 ID。

• 响应状态码及说明

  • 200 OK：成功获取图书信息，响应示例：

{"book_id": 1,"title": "百年孤独","author": "加西亚·马尔克斯","publication_year": 1967,"isbn": "9787544253994"
}

• 404 Not Found：未找到指定 ID 的图书，示例：

{"error": "未找到指定图书"
}

（五）添加图书接口

• 接口名称：/books

• 接口描述：添加一本新图书到图书管理系统，需提供图书的相关信息。

• 请求方式：POST

• 请求参数：

{"title": "string","author": "string","publication_year": "number","isbn": "string"
}

• 响应状态码及说明

  • 201 Created：图书添加成功，响应示例：

{"message": "图书添加成功","book_id": 3
}

• 400 Bad Request：请求数据格式错误或缺少必填项，示例：

{"error": "缺少必填项：publication_year"
}

（六）更新图书接口

• 接口名称：/books/{book_id}

• 接口描述：根据图书 ID 更新特定图书的信息，可部分更新。

• 请求方式：PUT

• 请求参数

  • book_id：路径参数，整数类型，必填，指定要更新的图书 ID。

  • 请求体：包含要更新的图书信息，示例：

{"title": "百年孤独（新版）","publication_year": "2018"
}

• 响应状态码及说明

  • 200 OK：图书信息更新成功，响应示例：

{"message": "图书信息更新成功"
}

• 404 Not Found：未找到指定 ID 的图书，示例：

{"error": "未找到指定图书"
}

• 400 Bad Request：请求数据格式错误或更新数据与数据库约束冲突等情况，示例：

{"error": "更新数据不符合数据库约束"
}

（七）删除图书接口

• 接口名称：/books/{book_id}

• 接口描述：根据图书 ID 删除特定图书记录。

• 请求方式：DELETE

• 请求参数

  • book_id：路径参数，整数类型，必填，指定要删除的图书 ID。

• 响应状态码及说明

  • 204 No Content：图书删除成功，无响应体内容。

  • 404 Not Found：未找到指定 ID 的图书，示例：

{"error": "未找到指定图书"
}

四、接口安全

• 认证方式：基于 Token 的认证方式。客户端在每次请求时，需在请求头中添加 Authorization 字段，格式为 Bearer <token>。

• 权限控制：普通用户仅能查询图书信息；管理员用户具有添加、更新、删除图书以及管理用户账号的权限。

五、错误处理

• 除上述接口特定错误情况外，对于其他网络错误、服务器内部错误等，统一返回以下状态码及说明：

  • 500 Internal Server Error：服务器内部错误，示例：

{"error": "服务器内部错误，请稍后重试"
}

• 503 Service Unavailable：服务器暂时不可用，示例：

{"error": "服务器暂时不可用，正在维护中"
}

六、版本控制

• 本接口文档遵循语义化版本控制，当前版本为 v1.0。如有接口更新或修改，将按照语义化版本规则进行版本升级，并及时更新文档。