学生宿舍管理系统在毕设和课程设计里属于经久不衰的题目,网上“基于Spring Boot”的成品源码也很多,但如果你只是下载一个压缩包,解压之后直接点运行,大概率会卡在环境问题或者业务理解上。我自己接手过好几个这类项目,也帮人排查过“明明源码完整却跑不起来”的尴尬情况,反而觉得这类系统真正考验人的不是代码量,而是几件事:宿舍业务的状态怎么梳理、数据库表怎么设计、换宿退宿这些容易乱的流程如何保证不把数据搞脏。这篇就围绕一个基于Spring Boot的学生宿舍管理系统,从业务建模、技术选型、数据库设计、核心功能实现,一直到项目交付的源码、数据库脚本和文档整理,把整体思路和实操细节一次讲清楚。适合正在用Spring Boot做毕设或练手项目的人参考,也适合拿到的源码后不知道怎么改、不知道怎么看的同学对照着读。
1. 写代码之前,先把宿舍管理的业务边界理清楚
很多宿舍管理项目看起来功能差不多,无非就是学生信息管理、宿舍分配、楼栋管理,但真正落到自己手上要重做或二次开发时,最先要明确的不是“写哪些接口”,而是“这个系统到底给谁用、业务要覆盖到哪个程度”。
1.1 宿管场景不是简单的增删改查
我最初做这个系统时也以为,只要能对“学生表”做增删改查,再把宿舍字段加进去就结束了。后来跟实际管宿舍的师傅聊了几次才发现,真实场景里存在很多被忽略的细节:新生入学时要批量安排宿舍,入住后可能因为生活习惯问题换宿舍,中途有人休学或者当兵要暂时退宿,宿舍里的灯坏了或者床板坏了要报修,毕业时要按规定流程完成退宿并检查宿舍,楼栋的到访人员也要登记。这些都不是在学生表上改一个字段能解决的。
所以设计之前,我习惯先画出简单的角色清单:
- 系统管理员:负责账号维护、楼栋信息设置、宿舍资源初始化和数据查看。
- 宿管或辅导员:负责分配宿舍、登记报修、处理换宿和退宿。
- 学生:可以查看自己的入住信息、提交报修申请或在线申请换宿。
这些角色决定了后端接口会分成管理端接口和学生端接口,登录认证也要能区分身份。如果一开始只做一套不分角色的接口,后面改权限会非常痛苦。
1.2 最怕“看起来能跑,实际上逻辑不闭合”
在我看过的宿舍管理源码里,最典型的问题就是业务不闭合。比如“退宿”功能只是把学生记录删掉了,但宿舍的空床位没有加回来;又比如“换宿”功能直接改了宿舍ID,但原来的宿舍可用床位没有恢复,新旧住宿记录也没有形成可以追踪的历史。到写数据库表和接口的时候,这些问题就会集中暴露。
所以在正式设计表结构之前,我建议先把状态流程列出来:入住创建一条住宿记录,状态为“在住”;换宿时旧住宿记录状态改成“已退宿”,新宿舍重新建一条“在住”记录;退宿时住宿记录结束,宿舍余位加一;宿舍维修时生成报修单,状态从“待处理”到“维修中”再到“已完成”。系统里很多模块其实都是围绕状态流转做的,状态定义清楚了,代码怎么写都顺。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术选型:Spring Boot 版本、ORM 框架和项目分层
学生宿舍管理系统如果只从技术角度说,并不复杂,但选型时也要考虑一个核心问题:代码是要交出去给别人运行和二次开发的。版本太新反而会带来一堆兼容性麻烦。
2.1 为什么我建议用 Spring Boot 2.7.x + JDK 1.8
现在不少人在用 Spring Boot 3,但对这类以毕业设计和教学为主要场景的系统来说,Spring Boot 3 要求 JDK 17,相关的 javax 包也换成了 jakarta,很多老资料和视频里的配置已经对不上了。一旦“版本太高”,刚导入项目就报一堆编译错误,把本该用在学习业务代码上的时间全耗在环境上,性价比很低。
我自己做这套系统时,最终锁定的是 Spring Boot 2.7.18 + JDK 1.8 + MySQL 8.0。这套组合适合绝大多数开发环境:JDK 1.8 依然是很多学校电脑里的默认版本,Spring Boot 2.7 既支持传统配置也有相对成熟稳定的社区资料。MySQL 8 时驱动用 com.mysql.cj.jdbc.Driver,也不需要额外处理认证插件问题,整体兼容性很好。
如果你已经有 JDK 17 环境又不想重新装,也可以用 Spring Boot 3 来做,但要注意把导入包从 javax.servlet 改成 jakarta.servlet,连数据库的驱动坐标也得确认版本。这个问题后面排查启动错误时还会再遇到。
2.2 技术栈和分层结构
这个系统的后端主要包含这些组件:
- Spring Boot:负责 Web 接口、依赖注入和自动配置。
- MyBatis 或 MyBatis-Plus:操作数据库。如果项目里有多表联查和自定义 SQL,我建议用原生 MyBatis 写 XML,掌握底层也能清楚地看懂每一条 SQL。
- MySQL:存储学生、宿舍、住宿记录、报修单等数据。
- Maven:管理依赖和打包。
- 前端部分可以有两种形态,一种是用 Vue 或者 React 做成前后端分离,另一种直接用 Thymeleaf 模板加 Bootstrap 做后台页面。对“源码+数据库+文档”这种交付形式来说,分离式项目要同时跑后端和前端,对运行环境要求更高,文档也就必须写清楚前端启动命令。
推荐的后端分层结构如下:
text复制springboot-dormitory/
├── src/main/java/com/example/dormitory/
│ ├── common/ // 统一返回结果、异常处理
│ ├── config/ // 拦截器、跨域等配置
│ ├── controller/ // 接收前端请求
│ ├── service/ // 业务逻辑层
│ ├── mapper/ // 数据库操作接口
│ ├── entity/ // 实体类
│ ├── vo/ // 视图对象,例如查询结果封装
│ └── DormitoryApplication.java
├── src/main/resources/
│ ├── mapper/ // MyBatis XML 文件
│ ├── application.yml
│ └── sql/dormitory.sql
├── pom.xml
└── README.md
Controller 层别写复杂业务,Controller 只做接收参数和返回结果,真正的宿舍分配判断、换宿逻辑和报修状态流转都放进 Service,这样一方面代码好测,另一方面别人看源码时也能快速理解业务线索。
3. 数据库模型:每个表和关键字段都要经得起业务追问
数据库是整个宿舍管理系统的核心,个人认为它比接口代码更能决定项目成败。表设计得不好,后面做换宿历史、统计宿舍入住率时才发现缺字段,返工成本很高。
3.1 这套系统需要哪些核心表
一个典型的 Spring Boot 学生宿舍管理系统,单从业务角度出发,核心表可以分成以下几张:
| 表名 | 作用 | 核心字段说明 |
|---|---|---|
| sys_user | 登录账号和统一身份 | user_id, username, password, real_name, role, status |
| student_info | 学生基础资料 | student_id, user_id, student_no, name, gender, college, major, phone |
| building | 宿舍楼栋 | building_id, building_name, address, floors, manager_name |
| dormitory | 具体宿舍房间 | dormitory_id, building_id, room_no, gender_limit, bed_num, spare_num |
| occupancy | 住宿记录 | record_id, student_id, dormitory_id, bed_no, checkin_date, checkout_date, status |
| repair_order | 报修单 | order_id, student_id, dormitory_id, description, status, create_time, finish_time |
| visit_record | 来访登记 | visit_id, dormitory_id, visitor_name, visit_time, leave_time, reason |
这套表结构是我按照“尽量保持职责单一”的思路整理的。有些项目会把用户名和密码直接放在 student_info 里,这样也能用,但会造成同一个学生如果既想用系统登录,又想维护基础资料,两处很容易不一致。拆出 sys_user 统一管账号,student_info 只存档案,后面要扩展宿管账号也会方便很多。
3.2 住宿记录单独建表,而不是直接改学生表的宿舍字段
学生表里加一个 dorm_id 在设计上最省事,查询“某个学生在哪个宿舍”一条 SQL 就能搞定。但实际问题在于:一个学生只要上学期间出现过一次换宿,原来的住宿信息就彻底丢了;等系统需要统计某栋楼历年的入住人数时,你会发现没有历史数据可以查。
所以整套逻辑里最核心的应该是 occupancy 住宿记录表。学生在宿舍的当前状态,实际上就是这张表里一条 status=1 的记录。查询时用“学生表 关联 在住状态住宿记录”的方式,得到的才是当前宿舍;换宿时把旧记录状态改为 0,再插入一条新记录。相比直接改学生表,这样最大好处是每次住宿安排都有迹可循。费用结算、入住率统计、退宿检查都能基于这张表继续扩展。
3.3 宿舍余位是用“查出来的”还是“冗余字段”
dormitory 表里的 spare_num 字段是一个冗余设计。如果宿舍房间本身存了总床位数,理论上每次查询都能通过计算已入住人数得到剩余床位,但页面频繁展示宿舍列表时,每次都去关联入住记录统计会很啰嗦。所以绝大多数宿舍管理项目都会直接在 dormitory 表中存一个 spare_num,用来表示当前可用空床位数,分配和退宿时同步维护。
这个冗余字段带来的唯一问题是数据可能不一致。比如程序写完没测试好,学生已经新增住宿记录,却没执行宿舍余位减一,页面展示就会出问题。我解决的办法是:所有修改宿舍余位的代码都集中放在 Service 层,不在 Controller 里直接 update;而且关键业务方法上用事务控制,保证住宿记录和余位变化要么同时成功,要么同时回滚。能不能加锁这个问题,面试时经常被问到,简单的单机项目用事务加乐观锁就够了,签名里带上版本号或者 update 条件里写 WHERE spare_num > 0,不让超卖发生,这也是一种思路。
4. 核心功能实现:登录鉴权、宿舍分配和报修状态流转
选定表结构后,后端代码的骨架基本就定了。下面我挑几个典型模块,讲一下具体实现思路,这些模块也能体现一个宿舍管理系统是否“好用”。
4.1 用户登录和角色权限控制
登录接口是所有管理系统的入口,实现上要明确几件事:密码不能明文存放,至少用 MD5 加盐或 BCrypt 处理;登录成功后的会话要保持状态,这里我用 JWT 生成一个 token 返回给前端;后端拦截器统一校验 token,再通过 token 里的用户 ID 确定当前用户是谁。
一个简单的 token 校验拦截器类似这样:
java复制@Component
public class AuthInterceptor implements HandlerInterceptor {
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) throws Exception {
// 放行登录请求
if (request.getRequestURI().contains("/login")) {
return true;
}
String token = request.getHeader("token");
if (token == null || !JwtUtil.verify(token)) {
response.setStatus(401);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{\"code\":401,\"msg\":\"未登录或登录已过期\"}");
return false;
}
Integer userId = JwtUtil.getUserId(token);
request.setAttribute("loginUserId", userId);
return true;
}
}
同时,在 config 里注册拦截器,把不需要登录就能访问的路径排除掉,一般是 /api/login、静态资源和错误页。在需要限制管理端接口时,可以再根据角色判断接口权限,比如 /admin/register 只允许管理员调用。注意这层校验只解决“对方是不是登录用户”的问题,具体能不能执行某个操作,还需要 Service 层继续判断角色和资源归属。
4.2 学生信息管理接口怎么写
学生信息管理模块一般是这套系统的门面,第一个演示功能通常是“新增学生”。做这类接口时有一个比较容易忽略的点:学生账号和学生档案是不是同时创建。正确的做法是在一个事务里完成两件事:先生成 sys_user 账号,默认密码可以设置为学号后六位,然后再插入 student_info 档案。这样既能保证登录可用,也避免出现一条学生档案没有对应登录账号的情况。
查询功能建议提供组合查询接口,比如按姓名、学号、学院、当前宿舍楼栋筛选。项目源码里一定会有类似这样的接口方法:
java复制public PageResult<StudentDormVO> queryStudent(int page, int size,
String studentNo, String name, Integer dormitoryId) {
Page<StudentDormVO> pageData = new Page<>(page, size);
List<StudentDormVO> list = studentMapper.selectStudentPage(
pageData, studentNo, name, dormitoryId);
return new PageResult<>(pageData.getTotal(), list);
}
上面这种写法里出现了一个 StudentDormVO,它用于把学生表相关字段和住宿表相关字段组装成一个前端好用的结构,而不是直接返回多层嵌套的对象。实际 XML 里大致是这样:
xml复制<select id="selectStudentPage" resultType="com.example.dormitory.vo.StudentDormVO">
SELECT
s.student_id,
s.student_no,
s.name,
s.major,
s.phone,
d.dormitory_id,
d.room_no,
d.building_id
FROM student_info s
LEFT JOIN occupancy o ON o.student_id = s.student_id AND o.status = 1
LEFT JOIN dormitory d ON o.dormitory_id = d.dormitory_id
<where>
<if test="studentNo != null and studentNo != ''">
AND s.student_no LIKE CONCAT('%', #{studentNo}, '%')
</if>
<if test="name != null and name != ''">
AND s.name LIKE CONCAT('%', #{name}, '%')
</if>
</where>
ORDER BY s.student_no
</select>
这里用 LEFT JOIN 而不是 INNER JOIN,是因为存在尚未分配宿舍的学生,记录不能丢。诸如此类的小细节,都会在改源码时体会尤其明显。
4.3 宿舍分布和空床位查询
宿舍分布页面要把“哪个楼里有哪些房间、每间住了多少人、还剩几个空位”展示出来。查询接口可以返回楼栋列表,再根据楼栋 ID 查询它的房间列表。也就是所谓的“一对多”查询。可以在 Mapper 接口里定义:
java复制List<BuildingVO> selectBuildingWithRoomList();
对应的 XML 可以用 collection 标签把房间列表嵌套进楼栋对象中,也可以分开查两次后组装。对于宿舍房间较少的管理系统,分开查询然后内存中组装,代码反而更好读。这里我推荐优先使用两三次简单查询,而不是写一条非常复杂的一对多嵌套 SQL,项目可读性更强,维护成本更低。
空床位查询需要注意查询条件里的性别限制和楼栋限制,避免把某栋女生楼的宿舍分配给男生,这类约束要在 SQL 里带条件过滤,并且 Service 层也做一次判断。
4.4 宿舍分配与换宿的代码逻辑
分配宿舍是本系统最重要的环节。项目代码中出现最频繁的业务方法通常是:
java复制@Transactional(rollbackFor = Exception.class)
public Result assignDormitory(AssignRequest req) {
StudentInfo student = studentInfoMapper.selectById(req.getStudentId());
if (student == null) {
return Result.error("学生不存在");
}
// 1. 检查当前是否已有在住记录
Integer validCount = occupancyMapper.countValidByStudentId(req.getStudentId());
if (validCount > 0) {
return Result.error("该学生当前已有住宿记录,请先退宿再分配");
}
// 2. 检查宿舍是否存在且有空位,这句更新本身带有条件
Dormitory dorm = dormitoryMapper.selectById(req.getDormitoryId());
if (dorm == null || dorm.getSpareNum() <= 0) {
return Result.error("宿舍不存在或已满");
}
// 3. 新增住宿记录
Occupancy record = new Occupancy();
record.setStudentId(req.getStudentId());
record.setDormitoryId(req.getDormitoryId());
record.setBedNo(req.getBedNo());
record.setStatus(1);
record.setCheckinDate(LocalDate.now());
occupancyMapper.insert(record);
// 4. 宿舍余位减一
int row = dormitoryMapper.reduceSpareNum(req.getDormitoryId());
if (row == 0) {
throw new RuntimeException("余位更新失败,宿舍可能已满");
}
return Result.success();
}
这里有两个关键点。第一点是查询空位后到执行更新之间,可能出现两个请求同时给同一间宿舍分配学生的情况,所以“余位减一”的 update 语句要带上条件,例如 UPDATE dormitory SET spare_num = spare_num - 1 WHERE dormitory_id = ? AND spare_num > 0,通过受影响行数判断是否分配成功。第二点是 @Transactional 不可或缺,一旦余位更新失败,住宿记录也要一起回滚,否则会出现学生有了住宿记录但宿舍余位没变的脏数据。
换宿逻辑本质上也是两段子逻辑:先把旧住宿记录状态置为“已退宿”,同时旧宿舍余位加一;再在新宿舍执行一次分配逻辑。注意换宿如果写成“先生成新记录再退旧记录”,中间临时会多出一段“同时在住”的中间状态,虽然用户基本感知不到,但逻辑清晰的项目通常会把顺序设计成先退旧再入新,并且在业务里判断学生当前确实存在在住记录。
关于床位号,很多系统用 bed_no 来表示“1号床、2号床”,但具体哪些床位已经有人,可能需要一张床位表来管理。简单方案下,如果一房间里所有床铺都只是通过 bed_no 和 occupancy 关联,分配时就要检查这个床位是否已经被在住的住宿记录占用:
sql复制SELECT COUNT(*) FROM occupancy
WHERE dormitory_id = #{dormitoryId}
AND bed_no = #{bedNo}
AND status = 1
若结果大于 0,则提示该床位已入住。用这种方式,即使只有 dormitory 里的总床位数,也不至于出现同一张床住两个人的问题。
4.5 退宿与报修单状态流转
退宿一般发生在毕业离校或中途休学时,核心操作是把在住记录状态改为已离校、设置退宿时间,并让宿舍余位加一。同时有些系统会连学生档案里的当前状态也一起改成“已离校”,方便首页统计在校人数。
报修单模块是最容易展示状态流的地方。报修单字段可以这样定义:创建时状态为 待受理;宿管看到后把状态改成 维修中;维修完成后改成 已完成。整个流程就是状态机的一次次迁移,Controller 里可以直接写两个方法:acceptOrder 和 finishOrder。实现并不复杂,但要注意不能允许状态从“待受理”直接跳到“已完成”,所以每次修改状态时都应当校验当前状态,比如只有 待受理 才能改成 维修中。用一张表、一个状态字段,配合几条有效的 update 语句,就能避免大多数误操作。
5. 把源码跑起来的常见问题与排查链路
拿到一份“源码+数据库+文档”的宿舍管理项目,如果在自己电脑上第一次启动,通常不会一帆风顺。这里我把自己排查过的高频问题整理一遍,你可以按照这个顺序自查。
5.1 数据库连不上的问题
绝大多数项目跑不起来,都出在 application.yml 配置和 MySQL 版本不一致。如果是 MySQL 8,数据库连接配置里建议写成这样:
yaml复制spring:
datasource:
url: jdbc:mysql://localhost:3306/dormitory?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
username: root
password: 你自己的密码
driver-class-name: com.mysql.cj.jdbc.Driver
serverTimezone=Asia/Shanghai 解决时区问题,useSSL=false 避免本机没有证书时报 SSL 警告,allowPublicKeyRetrieval=true 则解决 MySQL 8 在某些客户端工具下认证插件报错的问题。如果项目用的 MySQL 5.7,驱动改成 com.mysql.jdbc.Driver 通常也能跑,但建议优先保持和数据库版本匹配。
5.2 启动时端口被占用
Spring Boot 默认端口是 8080。如果启动日志显示端口被占用,第一件事不是改端口,而是先看哪个进程占用了 8080。Windows 下可以用:
bash复制netstat -ano | findstr 8080
taskkill /F /PID 进程号
Linux 或 Mac 下可以用:
bash复制lsof -i:8080
kill -9 进程ID
有时候前端工程也就跑在 8080,后端反而需要换到 8081,这时可以直接在 application.yml 里改 server.port。如果改完端口却出现跨域问题,就得在后端单独配置 CORS,让后端允许来自前端地址的请求。
5.3 编译错误、依赖冲突和 Java 环境版本不匹配
如果你是 Spring Boot 3 的源码,但机器上配的是 JDK 1.8,Maven 导入后一定会编译报错。遇到报错别急着删文件,先打开 pom.xml 看 Spring Boot 的父版本,再执行 java -version 对比。Spring Boot 2.7 及以下用 JDK 8/11 即可,Spring Boot 3 必须 JDK 17 以上。若源码里大量 import 的是 javax.* 包,实际又跑在 Spring Boot 3 上,需要转换成 jakarta.*,这个批量改动要仔细,不要手动改一半漏一半。
依赖下载不下来也是常见问题。最好在 Maven 的 settings.xml 里配置阿里云镜像仓库,重新执行 mvn clean package -DskipTests,看是否能够顺利打包。如果执行命令时报“程序包不存在”,多半是子模块没有正确引入,检查各个模块的依赖关系是关键。
5.4 SQL 脚本执行报错
拿到数据库脚本后,如果直接全选执行报错,常见原因有三种:第一,脚本开头没有 CREATE DATABASE,而你当前连接的库名和源码配置不一致;第二,脚本要求 utf8mb4,但客户端连接编码不对;第三,表之间存在外键依赖,删除或创建顺序不对。稳妥做法是先用命令行登录 MySQL:
bash复制mysql -uroot -p
然后在 MySQL 中执行:
sql复制source D:/dormitory.sql
这样能完整看到每一步执行是否报错。也可以用 Navicat 等工具,但要注意选择 UTF-8 编码模式再执行。
6. 交付一个“别人一次跑通”的源码包如何整理
最后聊聊交付。下载到一个源码包,对照它的目录结构,你可以看到合格的交付至少有源码、SQL 脚本和文档三段内容。如果你是自己要交毕设,更要按这个标准整理,毕竟“能运行”和“别人照着操作也能运行”是两回事。
6.1 README 文件应该写什么
一份好的 README 至少包含以下内容:
- 项目简介:这个宿舍管理系统解决什么问题,有哪些角色。
- 技术栈:Spring Boot 版本、JDK 版本、MySQL 版本、前端技术。
- 运行步骤:创建数据库并导入 SQL、修改配置文件、启动后端、启动前端。
- 默认账号:管理员账号、密码,以及学生测试账号。
- 项目结构:简单画出目录,让读者知道核心代码在哪里。
- 常见问题:比如端口占用、MySQL 8 驱动报错怎么解决。
写默认账号时一定要谨慎,不要只写“admin / 123456”就完事,还要说明该账号对应的角色和权限范围。如果项目里写了数据库初始化脚本,默认管理员就是脚本里 insert 进去的那条数据,使用前要提醒用户修改初始密码。
6.2 数据库脚本的自我描述能力
数据库脚本不只是建表语句,还要做到开箱即用。SQL 文件开头应该包含数据库创建与选择:
sql复制CREATE DATABASE IF NOT EXISTS dormitory DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
USE dormitory;
接着是删除旧表和建表语句,然后再插入可演示的初始化数据。学生、宿舍、管理员账号都要提前造好,不然登录后一片空白,不知道功能是不是有问题。建表语句里的关键枚举状态建议用注释说明,例如 status 字段值为 1 表示在住,0 表示已退宿,这样后来维护数据库的人不会靠猜。
6.3 文档怎么组织不算凑数
网上很多文档模板写得很厚,但放到具体项目上就水土不服。编写数据库设计文档时,建议包括 ER 关系说明、每张表的字段注释、枚举值含义和核心业务表的关联关系。使用说明书则应该用“角色+场景”的方式写作:学生进系统能干什么,管理员进系统怎么给新生批量分配宿舍,宿舍报修之后状态怎么流转。
一开始文档可能写不厚,但这都不是大问题。真正让评审或同事觉得舒服的,是文档和实际代码保持一致。有些人为了凑篇幅,把网上其他项目的表结构直接复制过来,结果和脚本里的字段对不上,不仅没加分,反而容易暴露问题。
最后再分享一点做宿舍系统的体会
这套系统做了几轮之后,我最大的体会是:如果把“学生宿舍管理系统”拆解得足够细,完全可以当一个小型业务系统的样板。你在这里练会了登录鉴权、权限控制、状态流转、一对多查询装配和事务数据一致性,以后再去做库存管理、楼宇管理、物业报修,会发现思路几乎是一模一样。实际做项目时,拿到源码先别急着跑,先花半天把它的 ER 图和状态流转图理顺,比直接改代码要高效得多。这个性价比极高的小习惯,我到现在做任何新项目还都在用。
