# library-system3.0-java

**Repository Path**: luming-02/library-system3.0-java

## Basic Information

- **Project Name**: library-system3.0-java
- **Description**: library-system3.0后端
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Library

## README

# 图书馆管理系统 3.0

基于 Spring Boot 3 + MyBatis + JWT 的图书馆借阅管理系统

## 📋 项目简介

这是一个功能完善的图书馆管理系统，支持用户管理、图书管理、分类管理、借阅管理等功能。系统采用前后端分离架构，提供 RESTful API 接口，并实现了基于 JWT 的身份认证和基于角色的权限控制（RBAC）。

## ✨ 核心功能

### 🔐 用户认证与权限
- ✅ **JWT 标准登录**：使用 JSON Web Token 进行身份认证
- ✅ **Token 刷新机制**：支持 Token 宽限期刷新，避免频繁重新登录
- ✅ **基于角色的访问控制（RBAC）**：
  - **管理员（role=1）**：可以访问所有接口，包括用户管理、图书管理、借阅管理等
  - **普通用户（role=2）**：只能使用登录、登出功能以及图书借阅功能

### 👥 用户管理（仅管理员）
- 查询所有用户列表
- 根据 ID 查询用户详情
- 添加新用户
- 更新用户信息
- 删除用户

### 📚 图书管理（所有用户可访问）
- 查询所有图书列表
- 根据 ID 查询图书详情
- 根据 ISBN 查询图书
- 添加新图书
- 更新图书信息
- 删除图书
- 分页搜索图书（支持书名、作者、ISBN 等多条件）
- 动态条件查询图书（支持自定义排序和分页）
- 按分类查询图书

### 📖 借阅管理（所有用户可访问）
- 借书操作
- 还书操作
- 续借操作
- 查询借阅记录列表
- 根据 ID 查询借阅记录详情
- 添加借阅记录
- 更新借阅记录
- 删除借阅记录
- 检查图书是否可借
- 获取用户借阅记录
- 获取图书借阅记录
- 逾期未还记录查询
- 分页搜索借阅记录

### 🏷️ 分类管理
- 查询所有分类
- 添加分类
- 更新分类
- 删除分类

## 🛠️ 技术栈

### 后端框架
- **Spring Boot 3.2.2** - 核心框架
- **MyBatis 3.0.3** - ORM 框架
- **MySQL** - 关系型数据库
- **HikariCP** - 数据库连接池

### 安全认证
- **JJWT 0.12.5** - JWT 标准实现
- **自定义拦截器** - 权限验证

### 接口文档
- **SpringDoc OpenAPI 3.2.5** - Swagger UI 接口文档

### 开发工具
- **Lombok** - 简化代码
- **Spring Boot DevTools** - 热部署
- **Maven** - 构建工具

### 其他
- **Hibernate Validator** - 参数校验
- **全局异常处理** - 统一错误响应

## 🚀 快速开始

### 环境要求
- JDK 17+
- MySQL 8.0+
- Maven 3.6+

### 安装步骤

#### 1. 克隆项目
```bash
git clone <repository-url>
cd library-system3.0
```

#### 2. 数据库初始化
```bash
# 登录 MySQL
mysql -u root -p

# 创建数据库并执行建表脚本
source src/main/resources/sql/schema.sql

# 执行测试数据脚本
source src/main/resources/sql/data.sql
```

#### 3. 修改数据库配置
编辑 `src/main/resources/application.yml`，修改数据库连接信息：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/book_management_system?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&transformedBitIsBoolean=true&allowMultiQueries=true&useSSL=false&allowPublicKeyRetrieval=true
    username: root
    password: your_password
```

#### 4. 编译项目
```bash
mvn clean install
```

#### 5. 运行项目
```bash
mvn spring-boot:run
```

或者打包后运行：
```bash
mvn clean package
java -jar target/library-system-0.0.1-SNAPSHOT.jar
```

#### 6. 访问接口文档
启动成功后，访问 Swagger UI：
```
http://localhost:8080/swagger-ui.html
```

## 📖 API 接口说明

### 认证相关

#### 1. 用户登录
```http
POST /api/user/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userId": 1,
    "username": "admin",
    "realName": "系统管理员",
    "role": 1,
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 7200000
  }
}
```

#### 2. 刷新 Token
```http
POST /api/user/refresh
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiJ9..."
}
```

**说明：** 
- Token 有效期为 2 小时
- 过期后 30 分钟宽限期内可以刷新
- 超出宽限期需要重新登录

#### 3. 用户登出
```http
POST /api/user/logout
Authorization: Bearer <token>
```

### 用户管理（仅管理员）

#### 1. 获取所有用户
```http
GET /api/user/list
Authorization: Bearer <token>
```

#### 2. 根据 ID 获取用户
```http
GET /api/user/{id}
Authorization: Bearer <token>
```

#### 3. 添加用户
```http
POST /api/user/add
Authorization: Bearer <token>
Content-Type: application/json

{
  "username": "newuser",
  "password": "123456",
  "realName": "新用户",
  "phone": "13800138000",
  "email": "newuser@book.com",
  "role": 2,
  "status": 1
}
```

#### 4. 更新用户
```http
PUT /api/user/update
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": 5,
  "username": "newuser",
  "realName": "更新后的名字",
  "phone": "13900139000",
  "email": "update@book.com",
  "role": 2,
  "status": 1
}
```

#### 5. 删除用户
```http
DELETE /api/user/delete/{id}
Authorization: Bearer <token>
```

#### 6. 更新用户状态（启用/禁用）
```http
PUT /api/user/{id}/status?status=1
Authorization: Bearer <token>
```

#### 7. 修改密码
```http
POST /api/user/chpw
Content-Type: application/json

{
  "userId": 1,
  "oldPassword": "123456",
  "newPassword": "654321"
}
```

#### 8. 更新个人信息
```http
PUT /api/user/updateProfile
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": 1,
  "email": "newemail@book.com",
  "phone": "13900139000"
}
```

### 图书管理（所有用户可访问）

#### 1. 获取所有图书
```http
GET /api/book/list
```

#### 2. 根据 ID 获取图书
```http
GET /api/book/{id}
```

#### 3. 添加图书
```http
POST /api/book/add
Content-Type: application/json

{
  "bookName": "新书名",
  "isbn": "9787111111111",
  "author": "作者",
  "publisher": "出版社",
  "publishDate": "2024-01-01",
  "categoryId": 1,
  "price": 58.00,
  "stock": 100,
  "description": "图书描述",
  "coverUrl": "https://example.com/cover.jpg",
  "status": 1
}
```

#### 4. 更新图书
```http
PUT /api/book/update
Content-Type: application/json

{
  "id": 1,
  "bookName": "更新后的书名",
  "stock": 50
}
```

#### 5. 删除图书
```http
DELETE /api/book/delete/{id}
```

#### 6. 分页搜索图书
```http
POST /api/book/search
Content-Type: application/json

{
  "pageNum": 1,
  "pageSize": 10,
  "bookName": "Java",
  "author": null,
  "isbn": null
}
```

#### 7. 动态条件查询图书
```http
POST /api/book/query
Content-Type: application/json

{
  "pageNum": 1,
  "pageSize": 10,
  "orderBy": "createTime",
  "order": "desc",
  "bookName": null,
  "author": null,
  "isbn": null,
  "categoryId": null
}
```

#### 8. 根据 ISBN 获取图书
```http
GET /api/book/isbn/{isbn}
```

#### 9. 根据分类获取图书
```http
GET /api/book/category/{categoryId}
```


### 借阅管理（所有用户可访问）

#### 1. 获取所有借阅记录
```http
GET /api/borrow/list
```

#### 2. 根据 ID 获取借阅记录
```http
GET /api/borrow/{id}
```

#### 3. 添加借阅记录
```http
POST /api/borrow/add
Content-Type: application/json

{
  "userId": 2,
  "bookId": 1,
  "borrowTime": "2024-01-15",
  "expectedReturnTime": "2024-02-15",
  "status": 1,
  "remark": "正常借阅"
}
```

#### 4. 更新借阅记录
```http
PUT /api/borrow/update
Content-Type: application/json

{
  "id": 1,
  "borrowTime": "2024-01-15",
  "expectedReturnTime": "2024-02-15",
  "returnTime": "2024-02-10",
  "status": 2,
  "remark": "提前归还"
}
```

#### 5. 删除借阅记录
```http
DELETE /api/borrow/delete/{id}
```

#### 6. 借书
```http
POST /api/borrow/borrow
Content-Type: application/json

{
  "userId": 2,
  "bookId": 1,
  "expectedReturnTime": "2024-02-01"
}
```

#### 7. 还书
```http
POST /api/borrow/return
Content-Type: application/json

{
  "borrowId": 1,
  "remark": "正常归还"
}
```

#### 8. 续借
```http
POST /api/borrow/renew/{borrowId}
```

#### 9. 检查图书可借状态
```http
GET /api/borrow/available/{bookId}
```

#### 10. 获取用户借阅记录
```http
GET /api/borrow/user/{userId}
```

#### 11. 获取图书借阅记录
```http
GET /api/borrow/book/{bookId}
```

#### 12. 获取逾期未还记录
```http
GET /api/borrow/overdue
```

#### 13. 分页搜索借阅记录
```http
POST /api/borrow/search
Content-Type: application/json

{
  "pageNum": 1,
  "pageSize": 10,
  "userId": null,
  "bookId": null,
  "status": null
}
```

### 分类管理（所有用户可访问）

#### 1. 获取所有分类
```http
GET /api/category/list
```

#### 2. 根据 ID 获取分类
```http
GET /api/category/{id}
```

#### 3. 获取分类下的图书
```http
GET /api/category/{id}/books
```

#### 4. 添加分类
```http
POST /api/category/add
Content-Type: application/json

{
  "categoryName": "新的分类"
}
```

#### 5. 更新分类
```http
PUT /api/category/update
Content-Type: application/json

{
  "id": 1,
  "categoryName": "更新后的分类名"
}
```

#### 6. 删除分类
```http
DELETE /api/category/delete/{id}
```

### 使用 Token
需要在请求头中携带 Token：
```http
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
```

## 👤 默认用户

| 用户名 | 密码 | 角色 | 说明 |
|--------|------|------|------|
| admin | 123456 | 管理员 | 可以访问所有接口 |
| zhangsan | 123456 | 普通用户 | 只能登录/登出 |
| lisi | 123456 | 普通用户 | 只能登录/登出 |
| wangwu | 123456 | 普通用户（已禁用） | 无法登录 |

## 📁 项目结构

```
library-system3.0/
├── src/
│   ├── main/
│   │   ├── java/com/luming/librarysystem/
│   │   │   ├── annotation/          # 自定义注解
│   │   │   │   └── RequireAdmin.java
│   │   │   ├── config/              # 配置类
│   │   │   │   ├── CorsConfig.java
│   │   │   │   ├── MyBatisConfig.java
│   │   │   │   └── SwaggerConfig.java
│   │   │   ├── controller/          # 控制器
│   │   │   │   ├── BookController.java
│   │   │   │   ├── BorrowController.java
│   │   │   │   ├── CategoryController.java
│   │   │   │   ├── ExceptionTestController.java
│   │   │   │   └── UserController.java
│   │   │   ├── dto/                 # 数据传输对象
│   │   │   │   ├── BookConditionRequest.java
│   │   │   │   ├── BookSearchRequest.java
│   │   │   │   ├── BookStatistics.java
│   │   │   │   ├── BorrowBookRequest.java
│   │   │   │   ├── BorrowSearchRequest.java
│   │   │   │   ├── BorrowStatistics.java
│   │   │   │   ├── ChangePasswordRequest.java
│   │   │   │   ├── LoginRequest.java
│   │   │   │   ├── LoginResponse.java
│   │   │   │   ├── PageRequest.java
│   │   │   │   ├── PageResult.java
│   │   │   │   ├── RefreshTokenRequest.java
│   │   │   │   ├── RefreshTokenResponse.java
│   │   │   │   ├── ResponseResult.java
│   │   │   │   ├── ReturnBookRequest.java
│   │   │   │   └── TokenUser.java
│   │   │   ├── entity/              # 实体类
│   │   │   │   ├── Book.java
│   │   │   │   ├── Borrow.java
│   │   │   │   ├── Category.java
│   │   │   │   ├── User.java
│   │   │   │   └── UserRole.java
│   │   │   ├── enums/               # 枚举
│   │   │   │   ├── BookStatusEnum.java
│   │   │   │   ├── BorrowStatusEnum.java
│   │   │   │   └── ResponseCodeEnum.java
│   │   │   ├── exception/           # 异常处理
│   │   │   │   ├── BusinessException.java
│   │   │   │   ├── GlobalExceptionHandler.java
│   │   │   │   └── ValidationException.java
│   │   │   ├── interceptor/         # 拦截器
│   │   │   │   ├── AuthInterceptor.java
│   │   │   │   └── ResponseWrapperInterceptor.java
│   │   │   ├── mapper/              # MyBatis Mapper
│   │   │   │   ├── BookMapper.java
│   │   │   │   ├── BorrowCountByBook.java
│   │   │   │   ├── BorrowCountByUser.java
│   │   │   │   ├── BorrowMapper.java
│   │   │   │   ├── BorrowTrend.java
│   │   │   │   ├── CategoryMapper.java
│   │   │   │   └── UserMapper.java
│   │   │   ├── service/             # 服务层
│   │   │   │   ├── impl/
│   │   │   │   │   ├── BookServiceImpl.java
│   │   │   │   │   ├── BorrowServiceImpl.java
│   │   │   │   │   ├── CategoryServiceImpl.java
│   │   │   │   │   └── UserServiceImpl.java
│   │   │   │   ├── BookService.java
│   │   │   │   ├── BorrowService.java
│   │   │   │   ├── CategoryService.java
│   │   │   │   └── UserService.java
│   │   │   └── util/                # 工具类
│   │   │       └── JwtUtil.java
│   │   └── resources/
│   │       ├── mapper/              # MyBatis XML
│   │       │   ├── BookMapper.xml
│   │       │   ├── BorrowMapper.xml
│   │       │   ├── CategoryMapper.xml
│   │       │   └── UserMapper.xml
│   │       ├── sql/                 # SQL 脚本
│   │       │   ├── data.sql
│   │       │   └── schema.sql
│   │       └── application.yml      # 配置文件
│   └── test/
│       └── java/com/luming/librarysystem/
│           └── ApplicationTests.java
├── pom.xml
└── README.md
```

## 🔧 配置说明

### JWT 配置（application.yml）
```yaml
jwt:
  secret: library-system-secret-key-2024-this-is-a-very-long-secret-key-for-jwt
  expiration: 7200000  # Token 有效期：2 小时
  refresh-window: 1800000  # 刷新窗口期：30 分钟
```

### 数据库配置
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/book_management_system?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&transformedBitIsBoolean=true&allowMultiQueries=true&useSSL=false&allowPublicKeyRetrieval=true
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
    type: com.zaxxer.hikari.HikariDataSource
```

### MyBatis 配置
```yaml
mybatis:
  mapper-locations: classpath:mapper/*.xml
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
```

### Swagger 配置
```yaml
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    try-it-out-enabled: true
```

## 🔒 安全说明

1. **密码加密**：当前版本使用明文密码存储，生产环境建议使用 BCrypt 等加密算法
2. **密钥管理**：生产环境应该使用环境变量或配置中心管理 JWT 密钥（当前配置中的 secret 仅为示例）
3. **HTTPS**：建议在生产环境使用 HTTPS 传输
4. **Token 存储**：客户端应该安全存储 Token（推荐使用 HttpOnly Cookie）
5. **权限控制**：系统实现了基于角色的访问控制（RBAC），管理员（role=1）可访问所有接口，普通用户（role=2）只能访问部分接口

## 📝 接口测试

### 使用 Swagger UI
访问 `http://localhost:8080/swagger-ui.html` 可以直接在浏览器中测试所有接口。Swagger UI 支持：
- 查看所有 API 接口的详细说明
- 在线调试接口，查看请求和响应
- 直接点击"Try it out"按钮进行测试

### 使用 cURL 示例
```bash
# 登录
curl -X POST http://localhost:8080/api/user/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# 获取用户列表（需要管理员权限）
curl -X GET http://localhost:8080/api/user/list \
  -H "Authorization: Bearer <your-token>"

# 获取所有图书
curl -X GET http://localhost:8080/api/book/list

# 借书操作
curl -X POST http://localhost:8080/api/borrow/borrow \
  -H "Content-Type: application/json" \
  -d '{"userId":2,"bookId":1,"expectedReturnTime":"2024-02-01"}'

# 分页搜索图书
curl -X POST http://localhost:8080/api/book/search \
  -H "Content-Type: application/json" \
  -d '{"pageNum":1,"pageSize":10,"bookName":"Java"}'
```

## 🐛 常见问题

### 1. 启动时报数据库连接失败
检查 MySQL 是否启动，以及 `application.yml` 中的数据库连接配置是否正确。确保数据库 `book_management_system` 已经创建。

### 2. Token 无效或已过期
请重新登录获取新的 Token，或者使用刷新接口刷新 Token。注意 Token 有效期为 2 小时，过期后 30 分钟内可以刷新。

### 3. 权限不足（403）
确保使用的是管理员账号（admin）进行登录。普通用户（如 zhangsan、lisi）只能访问部分接口。

### 4. SQL 脚本执行失败
确保按照正确的顺序执行 SQL 脚本：先执行 `schema.sql` 创建表和数据库，再执行 `data.sql` 插入测试数据。

### 5. Swagger UI 无法访问
检查项目是否正常启动，确认端口是否为 8080。如果使用了其他端口，请相应调整访问地址。

## 📄 License

MIT License

## 👨‍💻 开发信息

- **项目名称**：图书馆管理系统 3.0
- **开发语言**：Java 17
- **框架版本**：Spring Boot 3.2.2
- **数据库**：MySQL 8.0+
- **ORM 框架**：MyBatis 3.0.3
- **接口文档**：SpringDoc OpenAPI 3.2.5
- **认证方式**：JWT (JJWT 0.12.5)
- **构建工具**：Maven 3.6+

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

---

**注意**：本项目仅供学习交流使用，生产环境请根据实际情况进行调整。