开头部分
一个完整的图书管理系统，是Java程序员成长路上绕不开的经典项目。这次我打算把 SpringBoot + Vue3 + MyBatis + MySQL 这套前后端分离的“智慧图书管理系统”源码，从技术选型到落地部署，全部拆开讲清楚。不管你是准备做毕业设计、课程设计，还是想系统梳理一下全栈开发的核心技能点，这篇文章都能给你一条可以直接照抄的路径。项目本身不复杂，但涉及的知识面很广：后端有 SpringBoot 的分层架构、MyBatis 的映射与分页、JWT 的登录鉴权，前端有 Vue3 的组件化、路由守卫、Axios 封装，再加上 MySQL 的表设计与 SQL 优化。把它们串起来的过程，其实就是一次很完整的全栈实战训练。
1. 整体架构设计与技术选型思路
1.1 为什么选前后端分离架构
技术选型这块，我在设计之初就确定要走前后端分离。传统 JSP + Servlet 那套页面和后端代码揉在一起，改个按钮样式都得重启服务，维护成本太高了。前后端分离之后，后端只负责提供 JSON 数据接口，前端只管渲染页面和交互，两边可以并行开发——前端不用等后端写完接口，后端也不用等前端画完页面，各干各的，最后联调对接即可。
这个项目里，我把前端放在 8080 端口跑 Vite 开发服务器，后端在 8081 端口跑 SpringBoot，开发阶段通过 Vite 的代理配置把/api开头的请求转发到后端，生产环境则用 Nginx 托管前端静态文件并做反向代理。这样既解决了开发时的跨域问题，也模拟了真实的生产部署形态。
1.2 技术栈选型的理由与取舍
后端选 SpringBoot 2.7.x 而不是 SSM 手写配置，核心原因只有四个字：开发效率。SpringBoot 的自动配置机制省掉了一大堆 XML 配置，内嵌 Tomcat 也让部署变成一条java -jar命令。Spring Boot 不是把 SSM 抛弃了，而是把 SSM 从“需要你手动拼装”变成了“开箱即用”的组合。而 MyBatis 作为持久层框架，我特意选了它而不是 JPA，原因是图书管理系统这种场景里有大量多表关联查询和动态条件查询，MyBatis 的 SQL 完全可控，调优起来心里有数。JPA 那种自动生成 SQL 的方式确实快，但碰到复杂查询时 SQL 往往不是你想要的，还得去拼接 Specification，反而绕远路。
前端这块，Vue3 + Vite + Pinia + Vue Router 是当前 Vue 生态的标准组合。Vue3 的组合式 API 比 Vue2 的选项式 API 在逻辑复用上强太多，一个 useBookList 函数就能把图书列表的加载、搜索、分页逻辑全部封装起来，多个组件共用起来非常舒服。Vite 的开发服务器冷启动快到飞起，热更新也是毫秒级的，比 Vue CLI 时代的 Webpack 体验好太多。
MySQL 作为数据库是顺理成章的选择，图书管理系统这种读多写少的业务场景，MySQL 的 InnoDB 引擎在并发读性能和事务支持之间取得了一个很不错的平衡。配合 MyBatis 的二级缓存，热点数据查询的性能还能再上一个台阶。
2. 数据库设计与MyBatis核心实践
2.1 图书管理系统的表结构设计
数据库设计是一切的根基，表结构没设计好，后面写多少代码都是白搭。图书管理系统最核心的表有四张：用户表（sys_user）、图书表（book）、图书分类表（book_category）和借阅记录表（borrow_record）。
用户表里我特意加了一个role字段，区分管理员和普通读者。这里有个小建议：角色字段用 int 类型存储，0 表示管理员，1 表示普通用户，不要直接存字符串。一方面省存储空间，另一方面程序里判断逻辑也更直观，而且后续如果要扩展角色，加数字枚举值就行，不用动表结构。
图书表是系统的主角，字段设计要放长远看。除了常规的book_name、author、publisher、isbn、publish_date之外，我还加了total_count和borrowed_count两个字段。很多人会把“可借数量”直接在页面上用total_count - borrowed_count计算，这个做法在数据量小的时候没问题，但一旦借阅记录多了，每次查询都要 COUNT 一遍 borrow_record 表，性能就会下降。我一开始就是这么设计的，后来压测发现全表扫描太慢，才改成了用冗余字段实时维护两个计数，在借阅和归还的事务里同时更新，查询时直接读字段，性能问题就消失了。
借阅记录表 borrow_record 是核心业务表，包含user_id、book_id、borrow_time、due_time、return_time、status几个字段。status 字段用 0 表示借阅中，1 表示已归还，2 表示逾期未还。逾期状态我用了定时任务每天扫描一次：当due_time小于当前时间且return_time为空时，自动把 status 更新为 2。
外键约束我在建表时没有加物理外键，只在逻辑层用索引来保证查询效率。原因很实际：物理外键在删除和插入时需要额外校验，影响写入性能，而且在分库分表的场景下物理外键基本就是摆设。生产级别的系统更倾向于用应用层逻辑保证数据一致性，而不是把压力推给数据库。
2.2 MyBatis映射文件与动态SQL实战
MyBatis 的强大之处在于写 SQL 的灵活性。这个项目里，图书列表查询是最典型的动态 SQL 场景——搜索条件可能有书名模糊查询、分类筛选、出版社精确匹配，用户不会每次都填全所有筛选条件，所以不能写死 SQL。
<select id="selectBookPage" resultType="com.example.entity.Book"> SELECT b.*, c.category_name FROM book b LEFT JOIN book_category c ON b.category_id = c.id <where> <if test="bookName != null and bookName != ''"> AND b.book_name LIKE CONCAT('%', #{bookName}, '%') </if> <if test="categoryId != null"> AND b.category_id = #{categoryId} </if> <if test="publisher != null and publisher != ''"> AND b.publisher = #{publisher} </if> </where> ORDER BY b.create_time DESC </select><where>标签的好处是它自动处理了第一个条件前的 AND 关键字——如果你第一个条件没传，它不会在 WHERE 后面留下一个裸奔的 AND。很多人第一次写动态 SQL 会踩这个坑，直接写WHERE 1=1再加条件，性能上虽然影响不大，但看着实在不够优雅。
项目里我把所有 SQL 都写在 XML 映射文件里，而不是用注解。注解写 SQL 确实快，但一旦 SQL 长了，字符串拼接在 Java 代码里既难看又难调优，XML 里可以有注释、有格式化的缩进，还能在测试工具里直接捞出来执行排查问题。
2.3 MyBatis分页插件与缓存实战
分页这个功能，我要重点讲一下 MyBatis 里 PageHelper 的用法，因为这是面试八股文里必然会出现的知识点。PageHelper 是一个基于 MyBatis 拦截器机制实现的分页插件，原理是在 Executor 执行 SQL 前拦截，自动把原始 SQL 改写成带 LIMIT 的分页 SQL，然后再查询一条 COUNT 语句统计总条数。
使用方式非常简单，在查询前调用一行代码：
PageHelper.startPage(pageNum, pageSize); Page<Book> page = bookMapper.selectBookPage(bookQuery); long total = page.getTotal(); List<Book> books = page.getResult();这里有个致命细节我必须强调：PageHelper.startPage()只对紧接着的下一条 SQL 生效。如果你在 startPage 和 mapper 调用之间插入了其他业务逻辑，或者其他查询语句，分页就会作用到错误的 SQL 上。我早期就犯过这个错，在 startPage 之后调了一个统计方法获取某个数据，结果分页跑到统计 SQL 上去了，查出来的数据完全错乱。排查了好久才定位到原因。
另外还要提醒一点：PageHelper 返回的 Page 对象本身继承自 ArrayList，所以你不要手动再去 new 一个 ArrayList 来接收结果，否则total就丢失了。
MyBatis 的缓存机制也是面试高频考点。一级缓存是 SqlSession 级别的，默认开启，同一个 SqlSession 中执行两次完全相同的 SQL，第二次会直接走缓存。但注意，如果你在同一个 SqlSession 中先查询再做了更新操作，一级缓存会被清空。二级缓存是 namespace 级别的，默认关闭，需要手动开启。图书列表这种热点数据非常适合开二级缓存——多个用户查询同一份图书数据时，第二次起就不再查数据库了，直接命中缓存。
不过二级缓存有个使用禁忌：如果同一个 namespace 下有更新操作，缓存会全部失效。所以我把图书分类这类几乎不变的数据单独放在一个 mapper 里开启二级缓存，借阅记录这类高频写的数据坚决不开。
3. 后端核心模块实现
3.1 SpringBoot分层架构与控制层设计
后端代码组织上，我严格遵循 Controller -> Service -> Mapper 三层架构。Controller 只负责接收参数和返回结果，不写业务逻辑；Service 层处理业务规则，比如借书时要判断库存是否充足、用户是否已有逾期未还的书；Mapper 层只做数据库交互，不掺业务判断。
这样分层最大的好处是测试和排查问题方便。举个实际场景：用户反馈“借书接口报错”，如果是传统写成一坨的代码，你得从头到尾捋一遍；分层之后，你可以先看 Controller 是否正常接收参数，再看 Service 层的业务规则哪个校验没通过，最后才轮到排查 SQL 问题，定位效率高出一大截。
Controller 层我全部返回统一响应体Result<T>，结构是 code、message、data 三个字段。code 为 0 表示成功，非 0 表示各种异常码。这样前端 Axios 拦截器统一判断 code 是否为 0 即可决定走成功还是失败回调，避免每写一个接口都重复做异常判断。
@PostMapping("/borrow") public Result<Void> borrowBook(@RequestBody BorrowRequest request) { borrowService.borrowBook(request.getUserId(), request.getBookId()); return Result.success(); }3.2 JWT登录鉴权与密码安全
登录鉴权这块，我选了 JWT（JSON Web Token）方案。JWT 本质上是一个经过签名的 JSON 字符串，服务端无需存储 session，用户拿着 token 来请求，服务端验签通过即信任该用户身份。这在前后端分离架构下天然的友好——不需要处理跨域情况下的 Cookie 传递问题，也方便后续做移动端接入。
JWT 的 header 里存放签名算法，payload 里存放用户的 id、用户名、角色，最后用密钥做 HMACSHA256 签名。我生成 token 时设置了 24 小时的过期时间，前端在 Axios 请求拦截器里自动从 localStorage 取出 token 放到 Authorization 请求头，后端用拦截器统一校验。
密码存储必须强调：一定不要用明文，也不要用简单的 MD5。MD5 虽然不可逆，但彩虹表攻击太容易破解。我用了 BCrypt 加密，它内部自带随机盐，每次加密同一个密码得到的结果都不一样，安全性比 MD5 高一个量级。用户注册时用BCrypt.hashpw()加密存储，登录校验时用BCrypt.checkpw()比对，Spring Security 里自带这个工具类，单独抽出来用也很方便。
拦截器里放行白名单也值得说下：登录接口、注册接口、静态资源路径需要放行，其余请求全都要校验 token。校验逻辑很简单——判断请求头里有没有 Authorization、token 能否解析成功、解析出的用户是否存在于数据库。注意要捕获 JWT 解析时的异常，防止伪造 token 直接穿透拦截器。
4. Vue3前端构建与前后端联调
4.1 Vite项目搭建与Axios请求封装
前端部分，我用 Vite 脚手架初始化了 Vue3 项目。这里要说个经验：Vite 很挑 Node 版本，建议用 Node 16 以上的 LTS 版本，否则启动时会报一堆莫名其妙的错误。项目装好之后，第一件事就是配置路径别名，把@指向src目录，这样组件里引用文件路径就不用一长串相对路径了。
Axios 封装是前端工程化的关键一步。我单独写了一个request.js工具文件，创建 Axios 实例时统一配置 baseURL 和超时时间，然后在请求拦截器里加上 token，在响应拦截器里统一处理错误码。响应的 code 如果非 0，直接弹出提示；HTTP 401 状态码则清除本地 token 并跳回登录页。这样一来，业务组件里只需要关心成功数据，异常处理全部集中收敛。
const request = axios.create({ baseURL: '/api', timeout: 10000 }) request.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers.Authorization = `Bearer ${token}` } return config })4.2 Vue3组件化设计与路由守卫
图书列表页是前端最核心的页面。我用组合式 API 把逻辑抽成了一个useBookList函数，里面封装了列表加载、分页切换、搜索条件重置等逻辑。组件模板只负责展示，数据逻辑全在 composable 里，其他页面如果也要展示图书数据，直接复用这个函数就行。这就是组合式 API 对比选项式 API 最大优势的实际体验。
页面结构上，图书列表用了 Element Plus 的表格组件，配合分页组件 Pagination。搜索区域是三个条件：书名输入框、分类下拉框、出版社输入框，点击搜索按钮重新从第一页加载数据，点击重置按钮清空条件并重新加载。
路由守卫是 Vue3 前端安全的第一道防线。全局前置守卫里判断目标路由是否需要登录权限，如果用户没登录，直接重定向到登录页，并带上 redirect 参数方便登录后跳回原页面。管理员专属页面还要额外校验用户的角色字段，角色不对直接跳到 403 页面。
router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (to.meta.requiresAuth && !token) { next({ path: '/login', query: { redirect: to.fullPath } }) } else { next() } })4.3 开发环境下联调的代理配置与跨域处理
前后端联调是必经之路。开发环境下，前端在 8080 端口，后端在 8081 端口，想让前端请求直接打到后端，跨域问题必须先解决。Vite 的server.proxy配置就能优雅地处理：
server: { port: 8080, proxy: { '/api': { target: 'http://localhost:8081', changeOrigin: true } } }配置好之后，前端请求/api/user/login会被 Vite 转发到http://localhost:8081/api/user/login，浏览器层面没有跨域这回事了。这里要强调一下：changeOrigin必须设为 true，否则后端接收到的 Host 头还是前端地址，部分严格校验的框架会拒绝请求。
生产环境就不靠 Vite 了，用 Nginx 做反向代理。前端构建产物dist目录丢到 Nginx 的 html 目录，location 块里配置/api/前缀的请求转发到后端服务地址。Nginx 的配置我觉得是每个全栈开发者都应该掌握的技能，它不复杂，但能解决部署落地的大问题。
5. 常见问题与排查技巧
5.1 MyBatis常见报错与分页失效场景
我建这个项目时踩了无数坑，挑几个典型的说一下。
第一个是Invalid bound statement (not found)错误。这个报错几乎每个用 MyBatis 的人都会碰到，原因通常是 Mapper 接口和 XML 映射文件没有正确关联。排查顺序可以这样来：先确认 XML 文件在resources/mapper目录下，再确认 XML 文件的 namespace 和接口全限定名完全一致，最后确认 application.yml 里配了mapper-locations: classpath:mapper/*.xml。我最早犯的错误就是把 XML 文件放到了 Java 源码目录里，编译时没被复制到 classpath，Mapper 接口根本找不到对应语句。
第二个是分页失效问题。PageHelper 分页不生效的高频原因是不满足“startPage 紧接着是查询语句”这个前提。另外还有个隐蔽情况，就是查询时 Mapper 方法内部做了多表关联查询，返回结果嵌了一个集合属性，PageHelper 对这种情况的分页统计不准确。我的做法是分页查询的 SQL 单独写一个，不做嵌套集合映射，需要详情时再按主键查一次。
第三个是数据库连接相关的报错。项目启动时如果报Access denied for user 'root'@'localhost'，先检查用户名密码配没配错，再检查数据库有没有建出来。如果报Public Key Retrieval is not allowed，在 JDBC URL 后面加上allowPublicKeyRetrieval=true&useSSL=false，这个问题尤其常见于 MySQL 8.0 以上版本。
5.2 MySQL 8.0的时区与连接参数问题
MySQL 8.0 和 5.7 有几个明显的坑。第一个就是时区问题——你连接的 JDBC URL 会看到这样一长串参数：
jdbc:mysql://localhost:3306/library?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/ShanghaiserverTimezone不配的话，高版本 MySQL 驱动会直接报The server time zone value 'Öйú±ê׼ʱ¼ä' is unrecognized。这个报错第一次见到确实容易慌，实际原因就是 JDBC 驱动和数据库服务器的时区信息不匹配，指定成Asia/Shanghai就解决了。
第二个坑是 MySQL 8.0 默认字符集是 utf8mb4，但很多老项目建库时依然用 utf8。utf8 在 MySQL 里最多存 3 字节，而 emoji 表情是 4 字节，一旦用户昵称里带个 emoji，插库直接报Incorrect string value错误。我的处理方式是建库时直接指定：
CREATE DATABASE library DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;写作时这里特别提醒：utf8mb4_unicode_ci和utf8mb4_general_ci的区别在于排序和比较规则精度。中文场景推荐utf8mb4_general_ci就行，排序更快，除非你有德语、法语这类特殊字符需求才需要unicode_ci。
5.3 配置文件和依赖冲突排查
SpringBoot 项目明明启动成功，但访问接口 404，这种问题也让人头大。优先查 Controller 类有没有被 Spring 容器扫描到——如果你的启动类在com.example包，而 Controller 在com.example.api包，它会被扫描到；但如果你把 Controller 放到了com.other包，那 SpringBoot 默认的包扫描机制就扫不到它。解决方案通常是把启动类移动到项目包的根路径，或者用@ComponentScan显式指定扫描范围。
依赖冲突这块，我用 Maven 的mvn dependency:tree命令检查过多次。最典型的是多个 MyBatis 相关依赖版本不一致导致启动报NoSuchMethodError。比如mybatis-spring-boot-starter的版本和pagehelper-spring-boot-starter的版本不兼容，运行时后者的拦截器调用前者的某个类方法，方法不存在就崩了。遇到这种情况不要瞎猜，先把依赖树拉出来看版本号，再去官方文档查兼容对照表。
5.4 前端控制台常见问题的排查思路
前端项目启动时报error:0308010C:digital envelope routines::unsupported这个错，通常是因为 Node 版本太高和 Webpack 4 的哈希算法不兼容。但 Vite 项目一般不受影响，如果真碰到了，用 Node 16 LTS 版本基本能解决。
前端页面空白且控制台报路由相关错误，大概率是路由模式问题。Vue Router 的 history 模式在生产环境下没有做 Nginx 配置的话，刷新非首页会 404。因为 Nginx 默认只找真实文件路径，你直接访问/books这个前端路由，服务器去找 books 这个文件肯定找不到。解决方法是 Nginx 里配置 try_files：
location / { try_files $uri $uri/ /index.html; }所有前端路由全部回退到 index.html，由 Vue Router 接管后续路由渲染。
5.5 数据库查询性能排查清单
图书管理系统的数据量虽然不算大，但性能优化的习惯要从一开始就养成。排查慢查询的第一件事是打开 MySQL 慢查询日志。在 my.ini 配置文件里加上两行：
slow_query_log = ON long_query_time = 1这样执行时间超过 1 秒的 SQL 都会被记录到日志里，定位问题就有依据了。我依此发现过borrow_record表在user_id上没有加索引，导致用户查询借阅记录时走了全表扫描。
加索引时也要有度。不是越多越好，索引会占磁盘空间，还会拖慢写入速度。优先给 WHERE 条件里高频使用的字段加索引，比如sys_user表的username字段、book表的isbn字段、borrow_record表的user_id和book_id字段。组合索引体验也很明显——比如查询条件是“状态 + 到期时间”，建立(status, due_time)联合索引后，逾期任务的扫描效率能提高很多。
最后分享一个我总结的排查顺序：先看代码里有没有循环查询数据库，再看索引有没有命中，最后才考虑要不要引入缓存。很多时候性能瓶颈不是数据库不够快，而是代码写法有问题——比如在循环里一条条查数据，这种问题加再多索引都救不回来，改成批量查询就好了。
