# library-manage-backend **Repository Path**: it4/library-manage-backend ## Basic Information - **Project Name**: library-manage-backend - **Description**: 本系统是基于 Spring Boot 3.x、JDK 17 和 MyBatis-Plus 开发的现代化、企业级图书管理系统后端服务。系统基于经典的三层架构（Controller-Service-Mapper），内置了轻量级 JWT 鉴权引擎、基于 AOP 的极简声明式权限控制系统、乐观锁高并发库存扣减机制以及严谨的全局异常拦截器，能够完美支撑起高颜值前端的数据交互与业务逻辑流转。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-27 - **Last Updated**: 2026-05-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: SpringBoot ## README # 📚 云端悦读 - 图书管理系统（后端） [![JDK](https://img.shields.io/badge/JDK-17-orange?style=flat-square&logo=oracle)](https://www.oracle.com/java/technologies/downloads/) [![Spring Boot](https://img.shields.io/badge/Spring_Boot-3.2.4-6DB33F?style=flat-square&logo=springboot)](https://spring.io/projects/spring-boot) [![MyBatis-Plus](https://img.shields.io/badge/MyBatis--Plus-3.5.5-blue?style=flat-square)](https://baomidou.com/) [![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?style=flat-square&logo=mysql)](https://www.mysql.com/) [![Maven](https://img.shields.io/badge/Maven-3.6+-c71a36?style=flat-square&logo=apachemaven)](https://maven.apache.org/) 本系统是基于 **Spring Boot 3.x**、**JDK 17** 和 **MyBatis-Plus** 开发的现代化、企业级图书管理系统后端服务。系统基于经典的三层架构（Controller-Service-Mapper），内置了轻量级 JWT 鉴权引擎、基于 AOP 的极简声明式权限控制系统、乐观锁高并发库存扣减机制以及严谨的全局异常拦截器，能够完美支撑起高颜值前端的数据交互与业务逻辑流转。 --- ## 🛠️ 后端技术栈与亮点特性 ### 1. 核心技术栈 * **基础运行环境**：`JDK 17` (具备高度优化的新一代长生命周期 LTS 版本)。 * **核心框架**：`Spring Boot 3.2.4` (基于 Spring Framework 6.x 开发的全新微服务/单体脚手架，具备更快的冷启动速度与一流的生态集成度)。 * **持久层框架**：`MyBatis-Plus 3.5.5` (针对 Spring Boot 3 优化的版本，完美省去了大量的通用 CRUD XML 编写，提供极具表现力的 Lambda 链式查询与自动化物理分页功能)。 * **数据库**：`MySQL 8.0` (利用 JSON 支持、优化的索引机制与高性能读写承载核心数据)。 * **安全与加密**： * `JJWT 0.11.5`：无状态 JSON Web Token 库，用于安全生成、解析与校验用户登录 Token。 * `Spring Security Crypto`：采用业界高强度的 **BCrypt 强哈希算法**，对用户密码进行单向加盐加密存储。 * **其他组件**：`Lombok` (消除臃肿的 Getter/Setter/Constructor)、`Spring Boot Starter Validation` (基于 JSR-380 的标准声明式入参校验)、`Spring AOP` (实现非侵入式权限拦截)。 ### 2. 核心架构设计亮点 * **轻量级无状态鉴权**：系统使用 JWT 进行鉴权，无 Session 状态维护，非常适合分布式或多端部署。 * **声明式权限拦截拦截控制**：通过自定义注解 `@LoginRequired`（需要登录）与 `@AdminOnly`（管理员专属）配合 **Spring AOP 切面**，在 Controller 层轻松实现粒度细致的方法级接口访问控制。 * **线程隔离的安全上下文**：封装了基于 `ThreadLocal` 的 `UserContext` 线程绑定容器。JWT 过滤器校验成功后，将用户信息存入当前请求线程的 `UserContext` 中，业务代码与 Mapper 层可随时随地、线程安全地获取当前操作人身份，且在请求结束后由过滤器统一自动释放，杜绝内存泄露隐患。 * **乐观锁安全扣减库存**：借书业务中针对图书库存的扣减，采用了基于 CAS 的乐观锁 SQL 机制更新数据更新：`UPDATE book_info SET stock = stock - 1 WHERE id = ? AND stock > 0`。通过原子更新在数据库层防范并发超卖，无需笨重的分布式锁，依然保障高并发借阅场景下的库存准确性。 --- ## 📂 项目结构指南 以下是后端工程的详细目录结构说明： ```text backend/ ├── .idea/ # IntelliJ IDEA 项目配置文件目录 ├── db/ # 数据库脚本目录 │ └── init.sql # MySQL 数据库建表与初始测试数据脚本 (包含管理员与读者账号) ├── src/ # 核心源代码目录 │ ├── main/ │ │ ├── java/ │ │ │ └── com/library/ │ │ │ ├── annotation/ # 自定义权限控制注解目录 │ │ │ │ ├── AdminOnly.java # 标记该接口仅限管理员访问 │ │ │ │ └── LoginRequired.java # 标记该接口需要登录后访问 │ │ │ ├── aspect/ # AOP 切面逻辑目录 │ │ │ │ └── AuthAspect.java # 核心拦截器：拦截注解并获取 UserContext 进行角色校验 │ │ │ ├── common/ # 统一公共组件 │ │ │ │ ├── Result.java # 统一规范的接口返回数据结构 Result { code, message, data } │ │ │ │ └── exception/ # 全局业务异常定义及处理器 GlobalExceptionHandler │ │ │ ├── config/ # 全局配置类目录 │ │ │ │ ├── CorsConfig.java # 跨域配置类 (允许前端开发端口 5263 跨域访问) │ │ │ │ └── MybatisPlusConfig.java # MyBatis-Plus 拦截器配置 (装配物理分页插件) │ │ │ ├── controller/ # API 控制器层 (对外发布 restful 接口) │ │ │ │ ├── AuthController.java # 登录、注册、个人信息修改接口 │ │ │ │ ├── BookController.java # 图书信息获取、新增、更新、删除接口 │ │ │ │ └── BorrowController.java # 图书借阅、归还、借阅记录分页查询接口 │ │ │ ├── dto/ # DTO (Data Transfer Object) 入参数据传输对象 │ │ │ │ ├── BookAddDTO.java # 新增图书入参结构 │ │ │ │ └── BookUpdateDTO.java # 修改图书入参结构 │ │ │ ├── entity/ # 实体层 (映射数据库表结构) │ │ │ │ ├── BookInfo.java # 图书详情表实体 │ │ │ │ ├── BorrowRecord.java # 借阅记录表实体 │ │ │ │ └── SysUser.java # 系统用户表实体 │ │ │ ├── filter/ # 过滤器层 │ │ │ │ └── JwtAuthFilter.java # JWT 核心身份校验过滤器 (提取 Token 并组装至 UserContext) │ │ │ ├── mapper/ # MyBatis Mapper 接口层 (持久层交互) │ │ │ │ ├── BookMapper.java │ │ │ │ ├── BorrowMapper.java │ │ │ │ └── SysUserMapper.java │ │ │ ├── service/ # 业务逻辑接口及其实现层 (Service / ServiceImpl) │ │ │ ├── util/ # 系统通用核心工具类 │ │ │ │ ├── JwtUtil.java # 封装 JWT 生成、解析及过期检查算法 │ │ │ │ └── UserContext.java # 基于 ThreadLocal 封装的线程隔离安全用户上下文 │ │ │ ├── vo/ # VO (View Object) 出参视图数据对象 │ │ │ │ ├── BookInfoVO.java # 连表拼接分类名称后的图书出参对象 │ │ │ │ └── BorrowRecordVO.java # 连表拼接图书名称、作者后的借阅记录出参对象 │ │ │ └── LibraryApplication.java # Spring Boot 启动类 │ │ └── resources/ │ │ ├── mapper/ # 复杂的 MyBatis 多表联合查询 XML 文件存放目录 │ │ └── application.yml # 全局主配置文件 (核心环境配置) │ └── test/ # 后端单元测试目录 ├── target/ # Maven 编译与打包产物输出目录 ├── uploads/ # 运行时动态存储上传的图书封面图片的本地目录 ├── pom.xml # Maven 核心依赖及插件配置文件 ├── 后端结构图.png # 后端结构及技术逻辑脉络图 └── README.md # 后端项目说明文档 ``` --- ## 🚀 启动与运行说明 ### 1. 开发环境准备 * **JDK 运行环境**：确保安装了 **JDK 17**，配置好系统的 `JAVA_HOME`。 * **开发工具**：推荐使用 **IntelliJ IDEA** 或 **Eclipse**。 * **构建工具**：建议安装 **Maven 3.6+** (也可直接使用 IDEA 内置的 Maven)。 * **数据库**：安装并启动 **MySQL 8.0+** 服务。 ### 2. 数据库配置与初始化 1. **创建数据库与导入数据**： * 在 MySQL 终端或可视化连接工具（如 Navicat, DataGrip）中，创建一个名为 `library_db` 的数据库： ```sql CREATE DATABASE library_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` * 运行项目根目录下 `/db/init.sql`（或 `backend/db` 下的 SQL 文件）来创建表结构、索引并导入初始测试数据。 2. **配置数据库连接**： * 打开 `backend/src/main/resources/application.yml` 文件。 * 根据您的本地或远程 MySQL 真实连接信息，修改数据库的 `url`、`username` 与 `password` 字段： ```yaml spring: datasource: url: jdbc:mysql://YOUR_IP:3306/library_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai username: YOUR_USERNAME password: YOUR_PASSWORD ``` ### 3. 项目运行启动 * **方式一（推荐，在 IDE 中运行）**： 1. 使用 IntelliJ IDEA 选择 `File -> Open`，打开 `backend` 目录。 2. 等待 Maven 自动下载并加载所有相关的依赖包（右下角进度条跑完）。 3. 找到并打开文件 `backend/src/main/java/com/library/LibraryApplication.java`。 4. 点击文件内的绿色三角形启动按钮运行项目。 * **方式二（Maven 命令行运行）**： 在 `backend` 项目根目录下打开终端，执行以下 Maven 启动指令： ```bash mvn clean spring-boot:run ``` ### 4. 服务验证与默认账户 启动成功后，控制台会打印出 Spring Boot 启动成功的日志，默认运行端口为 `8781`。 * **基本接口地址**：`http://localhost:8781` * **默认初始化体验账号**： * **管理员（拥有全部增删改及看板权限）**：用户名 `admin` / 密码 `123456` * **普通读者（拥有借阅、归还、图书检索权限）**：用户名 `reader` / 密码 `123456` *(说明：系统中的密码均已通过 BCryptPasswordEncoder 加密后落库存储，默认登录密码明文为 `123456`)* --- ## 🎨 后端架构与包依赖结构图 以下是后端工程的核心依赖层级与类文件分包脉络： ![后端结构图](后端结构图.png) --- ## ⚙️ 核心配置说明 * **图片上传与虚拟路径映射**： 系统支持图书封面及用户头像的本地文件上传（默认存储在 `backend/uploads/` 目录中）。Spring Boot 自动配置了文件静态映射，外部可通过 `http://localhost:8781/uploads/图片名` 直接下载或在前台页面渲染显示。 * **跨域控制**： 系统通过 `config/CorsConfig.java` 实现了跨域资源共享（CORS），特别针对前端默认运行地址 `http://localhost:5263` 放行了所有跨域预检与数据包请求，保障了前后端通信顺畅。