SpringBoot+Vue宿舍管理系统开发实战：需求、设计到部署全攻略

1. 项目概述与核心需求解析

每年到了毕业设计季和期末课程设计节点，总有一批同学被同一个问题卡住——宿舍管理系统到底怎么做才能既满足评审要求，又不会把自己卷进无底洞一样的前端调试里。我见过太多人拿着网上那种几十块钱打包的“古董项目”硬改，结果要么是SpringMVC堆XML堆到怀疑人生，要么是前端用着十年前的老JQuery，页面丑得连自己都不忍直视。

这次要拆解的，是一套基于SpringBoot + Vue + MyBatis + MySQL的宿舍管理系统。从项目标题里的“2025最新”定位来看，它的技术栈选型非常贴近当前主流就业市场的实际需求：后端用SpringBoot 2.x摆脱XML配置地狱，前端用Vue 2.x/3.x做组件化开发，数据库用MySQL存宿舍分配、学生入住、水电费、报修这些核心业务数据，中间用MyBatis做ORM映射。这套组合在JavaWeb开发里属于“万金油”级别的搭配，既能撑起毕设答辩的技术亮点，又能直接对标中小型公司内部管理系统的真实开发范式。

很多同学第一次看到“源码”两个字，第一反应是“直接拿来交差”。但我的建议是：源码只是起点，不是终点。你拿到这套项目后真正该做的，是搞清楚它抽了哪些表、Mapper层怎么写的、前端路由怎么跟后端API对上的，然后才有能力在答辩现场回答“为什么这么设计”这种问题。这篇文章会从需求拆解讲到环境搭建，再到功能实现、排查坑点，把整套系统的五脏六腑翻出来给你看。

2. 功能模块拆解与表结构设计思路

2.1 角色权限体系的三层划分

宿舍管理系统不是一个单用户工具，它天然就有三种身份：学生、宿管员、系统管理员。这直接决定了系统的权限设计绝对不能搞成“登录进去一个页面走天下”的简陋版。

• 学生端：核心动作是查看自己的入住信息、提交报修申请、查看水电费账单、在线请假或出入登记。
• 宿管端：权限比学生大一级，能看到自己管辖楼栋的所有房间状态，办理入住、退宿、换寝，处理学生提交的报修单。
• 管理员端：全局视角，管楼栋、管房间、管用户账号、管公告发布、管所有数据统计。

这套系统采用的做法很常规但非常有效：后端加一个Spring Security拦截器（或者自己写一个HandlerInterceptor），每次请求都校验Token里携带的角色标识，前端再配合Vue Router的路由守卫做页面级控制。两层校验的意义在于防止有人绕过前端直接调用API——前端路由隐藏只是“看不见”，后端拦截才是“进不来”。

2.2 数据库表的四大核心分组

如果让我只看数据库设计就能判断一个宿舍管理系统靠不靠谱，我会重点看它有没有把这几张表分清楚：

第一组：基础信息表

• building：楼栋表，字段包括楼栋编号、楼栋名称、楼层数、宿舍类型（男生/女生/混合）。
• room：宿舍房间表，关联楼栋ID，包含房间号、可住人数、已住人数、房间状态（空闲/部分入住/已满/维修中）。

注意：房间表的“已住人数”字段理论上是冗余字段，因为它可以通过关联学生表count出来。但在实际项目中保留这个字段、由Service层在办理入住的同时更新，性能收益非常明显。查询宿舍列表时不需要写联表Count，单表查询直接显示剩余床位，这就是空间换时间的典型取舍。

第二组：人员与业务表

• student：学生表，字段是学号、姓名、性别、院系、班级、联系方式、入住状态、楼栋ID、房间ID、床位号。
• dormitory_manager：宿管员表，关联负责的楼栋ID。

设计学生表的时候有个细节需要注意：床位号字段不能只存一个String，比如"03"，而是要在逻辑上保证同一个房间内床位号唯一。最简单的做法是在Service层做校验：查询该房间内是否已存在相同床位号。偷懒的做法是直接在student表加唯一索引(room_id, bed_number)，双保险。

第三组：流程业务表

• repair：报修表，字段有报修事由、详细描述、报修人ID、报修房间ID、状态（待处理/处理中/已完成）、报修时间、处理时间、处理人。
• water_electricity：水电费表，按月份记录房间号、冷水用量、电用量、金额、缴费状态。

水电费表设计上我不推荐一张表同时存“本月读数”和“上月读数”然后自己算差值，更推荐直接存“本月应缴金额”，读数计算放在业务层处理，数据库只负责结果存储。这样SQL会简单很多，报表查询也不需要在SQL里搞自连接减差值。

第四组：系统支撑表

• user：系统用户表（账号、密码、角色）。注意密码必须加密存储，至少用MD5加盐或者BCrypt。
• notice：公告表。

表关系上：user表与student表、manager表通过业务字段关联，而不是建立物理外键。很多新手喜欢在Navicat里画物理外键线，看起来ER图挺漂亮，但真正上线运维时你会发现，物理外键约束在数据量大、需要分库分表的情况下是个累赘。首选逻辑外键，由程序保证一致性。

2.3 为什么用MyBatis而不是MyBatis-Plus

这个项目标题里写的是“MyBatis”而非“MyBatis-Plus”，我猜作者是为了展示原生Mapper编写能力，这其实是好事。MyBatis-Plus确实能在单表CRUD上省大量时间，但毕设答辩时老师几乎必问一句“MyBatis中#{}和${}的区别”，你要是全程用Wrapper写查询，反而答不出底层原理。

这套系统的Mapper层可以采用XML方式编写SQL，这样可以主动控制复杂查询。比如“搜索学生”接口通常要支持按姓名、学号、院系三个条件动态拼SQL，用<if>标签写动态SQL就是MyBatis的核心加分项：

<select id="searchStudents" resultType="com.example.entity.Student"> SELECT * FROM student <where> <if test="name != null and name != ''"> AND name LIKE CONCAT('%', #{name}, '%') </if> <if test="stuNo != null and stuNo != ''"> AND stu_no = #{stuNo} </if> <if test="dept != null and dept != ''"> AND dept = #{dept} </if> </where> ORDER BY create_time DESC </select>

<where>标签会在第一个条件为真时自动补WHERE关键字，并且自动去掉第一个AND，这比手动拼where 1=1干净多了，也是面试时被问频率极高的知识点。

3. 项目搭建与核心配置详解

3.1 后端工程结构规划

如果你拿到这套源码，第一件事不要急着跑起来，先看它的包结构是否规范。一个合格的SpringBoot+MyBatis项目，分包应该长这样：

com.dormitory ├── config // 配置类：跨域、拦截器、自定义异常 ├── controller // 控制层：接收请求、返回JSON ├── service // 业务层：接口+Impl实现 ├── mapper // 数据访问层：接口 ├── entity // 实体类：对应数据库表 ├── common // 通用类：Result封装、枚举、常量 └── utils // 工具类：JWT生成解析、日期工具

特别提醒：controller里严禁写业务逻辑。我见过很多毕设把“查询学生列表并判断房间是否已满”这种逻辑直接堆在Controller里，四十行代码糊在一个方法里。老师一眼就能看出来你写代码没有分层意识。这套系统的正确处理方式是Controller只做三件事：接收参数、调用Service、返回封装好的Result对象。

3.2 配置文件里的坑与优化

先看application.yml。连接数据库时，有几处设置决定了项目能不能在别人的电脑上顺畅跑起来：

spring: datasource: url: jdbc:mysql://localhost:3306/dormitory_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver

这里最少有三个知识点：

• useSSL=false必加，否则新版MySQL驱动连本地库时会报SSL警告，甚至直接握手失败。
• serverTimezone=Asia/Shanghai必加，否则如果MySQL服务器时区设置不对，操作结果集里的日期时间字段会比实际慢8小时或者直接报错。
• MySQL 8.x驱动类名是com.mysql.cj.jdbc.Driver，MySQL 5.x还是com.mysql.jdbc.Driver。如果你本地装的是MySQL 8.0，pom里驱动版本又引的是5.x，这个地方就会ClassNotFoundException。

再有一个很容易翻车的地方就是MyBatis的驼峰映射配置。数据库字段习惯用stu_no这种下划线风格，Java实体类喜欢写stuNo，两者之间必须靠映射规则桥接。在application.yml里配备MyBatis设置：

mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.dormitory.entity configuration: map-underscore-to-camel-case: true

map-underscore-to-camel-case: true就是自动将stu_no映射为stuNo，不开的话，你会发现查询结果是null。

3.3 前端Vue项目初始化与安装指导

前端部分如果是Vue CLI创建的项目，标准结构是src/api存放接口请求模块、src/router存放路由配置、src/views存放页面组件、src/components存放公共组件。

跑前端之前你必须确认三样东西有：Node.js（版本不低于14，推荐16+）、npm或yarn、后端服务已启动。然后执行：

npm install npm run serve

npm install慢是老生常谈的问题，十分钟崩溃在node-sass上的人我见过太多。2025年这个时间点，npm源直接换成淘宝镜像再装：

npm config set registry https://registry.npmmirror.com npm install

装依赖的过程中如果某个包一直报ERR，优先怀疑版本冲突。一个非常常见的坑：vue-cli 4项目默认安装的是webpack 4，如果你手动把node-sass升级到了最新版，编译时必然报Module build failed。处理方式就是锁定node-sass版本为4.14.1，或者直接换dart-sass。

4. 核心功能实操：从登录鉴权到业务闭环

4.1 登录鉴权：JWT的完整流程落地

这套系统的登录流程用JWT做无状态鉴权，对比传统的Session方案，它更适合前后端分离架构。具体执行链路如下：

1. 前端登录页提交账号密码到后端/api/login接口。
2. 后端Service查询user表，用MD5或BCrypt校验密码。
3. 校验通过后生成Token字符串，把用户ID与角色塞进Token的载荷里。
4. Token返回给前端，前端存在localStorage里。
5. 前端每次请求在Header加Authorization: Bearer <token>字段。
6. 后端配置拦截器统一校验Token，签名正确且未过期才放行。

JWT的工具类核心就三个方法：生成Token、解析Token、校验过期。其中签名密钥建议写死在配置文件中：

@Component public class JwtUtils { // 密钥。注意：实际项目不能明文写在这里！最好放环境变量或配置中心 @Value("${jwt.secret}") private String secret; public String generateToken(Integer userId, String role) { return Jwts.builder() .setSubject(String.valueOf(userId)) .claim("role", role) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 24)) .signWith(SignatureAlgorithm.HS256, secret) .compact(); } }

为什么要在Token里放角色？因为后端拦截器拿到Token后就能直接判断当前请求人能不能访问这个接口，比如学生角色的Token调不了/admin/dashboard，省了一次数据库查询权限的开销。

4.2 学生入住办理：事务控制的典型场景

办理入住是整个系统里逻辑最重的操作：要改学生表的入住状态、改房间的已住人数、记录一条入住历史、可能还要给学生的账号做状态标记。任何一个环节报错，数据库就会处于半完成状态——学生显示在房间，但房间人数没加，那数据就错乱了。

SpringBoot里处理这个场景只需要给Service方法加一个@Transactional注解。但我希望你理解背后的东西：默认情况下RuntimeException会触发回滚，但受检异常（checked exception）不会回滚，这一点资深开发考实习生必问。所以办理入住时，如果你写的是throws Exception，注解不加rollbackFor = Exception.class，那你的事务就是失灵的。

拟代码逻辑如下：

@Transactional(rollbackFor = Exception.class) public Result assignRoom(AssignRoomDTO dto) { Student student = studentMapper.selectById(dto.getStudentId()); if (student == null) { return Result.error("学生不存在"); } if (student.getStatus() == 1) { return Result.error("该学生已入住"); } Room room = roomMapper.selectById(dto.getRoomId()); if (room == null) { return Result.error("房间不存在"); } if (room.getUsedCount() >= room.getCapacity()) { return Result.error("房间已满"); } // 修改学生入住状态 student.setRoomId(dto.getRoomId()); student.setBedNumber(dto.getBedNumber()); student.setStatus(1); studentMapper.updateById(student); // 房间人数+1 room.setUsedCount(room.getUsedCount() + 1); roomMapper.updateById(room); // 记录入住日志（省略） return Result.success(); }

这段代码里有三个防御性校验，每一个背后都是真实线上会出现的问题：学生重复入住、房间满员仍分配、床位号越界。做管理系统，永远记得一句话：接口要对脏数据说不。

4.3 前端路由守卫与页面权限

Vue路由守卫做权限拦截，是对后端鉴权的第一层体验优化。

router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (!token && to.path !== '/login') { next('/login') return } const role = localStorage.getItem('role') if (to.meta.roles && !to.meta.roles.includes(role)) { next('/403') return } next() })

to.meta.roles数组在路由定义时指定，比如管理员页面是roles: ['ADMIN']，学生个人中心是roles: ['STUDENT']。这样做的好处是页面不至于404，而是跳转到403无权限页，体验好很多。

4.4 数据统计与可视化展示

宿舍管理系统的新手常犯的错误是只做CRUD，不做统计。但实际上，楼栋入住率、各院系住宿人数、本月水电费用度排行，这些统计才是答辩时相对容易展示的亮点。

实现统计不必纠结用什么高贵的技术，最简单的方案就是SQL聚合查询。以“各楼栋入住率”为例：

SELECT b.id, b.name, COUNT(r.id) AS total_rooms, SUM(CASE WHEN r.status = '入住' THEN 1 ELSE 0 END) AS occupied_rooms, CONCAT(CAST(SUM(CASE WHEN r.status = '入住' THEN 1 ELSE 0 END) * 100.0 / COUNT(r.id) AS DECIMAL(5,2)), '%') AS occupancy_rate FROM building b LEFT JOIN room r ON r.building_id = b.id GROUP BY b.id, b.name;

如果前端要图表展示，Vue生态里最常用的方案是ECharts。安装过程很简单：

npm install echarts

然后按需引入柱状图、饼图组件渲染入住率。注意不要import * as echarts from 'echarts'整包引入，构建产物会大几十K，按需引入才是正经做法。

5. 常见问题与线上排查技巧实录

5.1 数据库连接失败的三种典型场景

“Access denied for user ‘root’@‘localhost’”：这个报错九成是密码不对。但经常出现“我明明密码没错”的情况，原因是MySQL 8默认使用了caching_sha2_password认证插件，而项目里引入的数据库驱动版本太老不支持。解决方式是在pom里将mysql-connector-java版本锁到8.0.x以上，或者执行SQL把账号认证插件改回mysql_native_password：

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '123456';

在本地毕设项目里两种方式都行，但如果你以后对接云数据库，推荐升级驱动而不是改插件，因为云厂商数据库普遍只支持新插件。

“Unknown database ‘dormitory_db’”：这种低级错误最好排查。用Navicat连接MySQL后新建数据库，注意字符集选utf8mb4，然后右键数据库选择“运行SQL文件”，把项目里自带的dormitory_db.sql导进去。导入的时候一定要先确认SQL文件里没有CREATE DATABASE语句的开头注释，否则容易重复建库或建到错误的实例上。

端口被占用：SpringBoot默认跑在8080，如果你机器上已经开了别的服务，直接java -jar启动会报Port 8080 was already in use。最快的解决办法是在配置文件里改端口：

server: port: 8081

5.2 前端接口404：跨域和代理配置

前后端分离项目最恶心的问题就是跨域。你在浏览器里访问localhost:8080的前端页面，但发起的请求目标是localhost:8081/api/xxx，浏览器就会因为跨域策略直接拦截响应。

最省事的方案是前端配Vue CLI的devServer代理，让浏览器以为自己只访问了8080端口：

// vue.config.js module.exports = { devServer: { proxy: { '/api': { target: 'http://localhost:8081', changeOrigin: true } } } }

后端也同时配上全局跨域配置类，双保险：

@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true); } }

注意：如果使用了Spring Security或自定义拦截器，OPTIONS预检请求必须在拦截器层面直接放行，否则你会被“跨域失败”折磨到怀疑人生。

5.3 报修状态流转与并发小问题

报修流程在并发表面上看起来很简单：学生创建工单→宿管员接单→完成维修。但实际运行时有一个大家都忽略的问题：如果同一个报修单被两个宿管员同时点击“接单”，状态就可能被覆盖或产生冲突。

对于毕设级别的并发量，加一个乐观锁就够了。在repair表加version字段，每次更新时在SQL里带条件：

UPDATE repair SET status = 2, handler = #{handlerId}, version = version + 1 WHERE id = #{repairId} AND version = #{version};

如果更新影响行数为0，说明有人抢先处理了，提示“该工单已被其他管理员接单”。这道题我在很多面试题里见过，如实说你用乐观锁解决过并发抢单，面试官一般会点头。

5.4 密码安全问题

很多学生宿舍系统的源码里，密码直接明文存在数据库里，这要是让答辩老师看到，印象分直接扣光。别说“内部系统无所谓”，这是最基本的安全素养。

项目里至少要提供一种密码加密方式。如果是基于SpringSecurity，可以直接注入BCryptPasswordEncoder，比MD5安全性高出一个档次。如果项目没有引入SpringSecurity，只用了拦截器做鉴权，我建议在注册/初始化用户时用加盐MD5：

public static String md5Salt(String password, String salt) { String raw = password + salt; for (int i = 0; i < 3; i++) { raw = DigestUtils.md5DigestAsHex(raw.getBytes()); } return raw; }

做三次MD5并不是从数学上增加安全性，但它让彩虹表攻击的代价大幅提升。你不需要跟老师纠结理论细节，能解释清楚“加盐是为了防彩虹表，多次哈希是为了增加破解成本”就完全够用了。

6. 项目扩展方向与个人实操心得

这套系统跑通了只是一个起点，真正让它变成简历上有含金量的项目，需要做几个针对性扩展。

第一个方向是引入Redis缓存。宿舍列表和楼栋信息这种读多写少的数据，完全适合缓存起来。具体做法：在Service层的查询方法前先查Redis，没有数据再查MySQL，回填缓存时设置过期时间，比如10分钟。这一句话，就能在答辩时从“会用框架”升级为“理解性能优化”。

第二个方向是增加数据导出功能。宿舍管理系统的报表需求非常多：每月水电费账单、学期末住宿名单、各楼栋入住统计。用Java后端配合EasyExcel或POI实现Excel导出，工作量不大，但实用度极高。前端页面上放一个“导出Excel”按钮，调用后端接口下载文件，几十行代码就能搞定。

第三个方向是前端引入Pinia或Vuex做状态管理。当你的项目里有“当前登录用户信息”“当前选中的楼栋”这类全局状态，再用组件props一层层传递就太痛苦了。把用户信息存在store里，任意页面都能直接读取，代码会清爽非常多。

关于这套“SpringBoot+Vue宿舍管理系统”，说句心里话：它看起来简单，但五脏俱全，覆盖了权限校验、复杂CRUD、事务处理、动态SQL、前后端联调、跨域解决这些真实开发中的高频场景。我见过不少同学，刚拿到代码时觉得“就这”，但真到动手改需求、加功能、回答老师提问的时候才发现，很多细节自己根本没吃透。

我个人在实际调试中还有一个最深的体会：这类项目第一遍跑通不要追求完美，按默认配置把前后端都拉起来，看到登录页面能进去，哪怕显示有点丑也别急着改样式。先把整条主流程走通，建立信心，再一个个模块去优化，比一开始就抠细节效率高得多。

最后再分享一个小技巧：如果前端页面有报错但控制台信息看不懂，优先打开浏览器开发者工具的Network面板，看具体请求的状态码。404就去查路由和Controller映射，500就把后端控制台报错贴到搜索引擎里。200但数据不对，那就是SQL或参数映射问题。大多数时候，报错信息已经告诉了你答案，只是新手容易被一长串英文吓到。冷静读一遍，基本就能定位到问题在哪一行。