前后端分离的学生宿舍信息系统，光是听到这个技术栈组合——SpringBoot + Vue + MyBatis + MySQL，很多开发者第一反应就是"又是毕设项目"。但我认真折腾完这套源码之后想说，这类系统恰恰是检验全栈基本功的试金石：业务上覆盖了宿舍管理、学生管理、报修流程、公告发布、权限控制这些典型场景，技术上把后端接口设计、数据库关系建模、前端组件化、跨域联调、生产部署全部串起来了。这篇文章我不打算只贴代码，而是把这套系统从架构设计到部署上线的整个过程重新走一遍，把关键取舍和踩过的坑一起讲清楚，适合正准备做类似管理系统、想上手前后端分离项目，或者想找一套完整可运行源码做二次开发的开发者参考。

1. 项目定位与整体架构解析

1.1 宿舍系统的业务边界

学生宿舍系统听起来只是"管理房间"这么简单，但真正落地的时候业务边界比想象中宽得多。最基本的诉求是宿舍楼栋和宿舍房间的维护，包括楼栋名称、楼层数量、房间床位数、宿舍类型；其次是学生信息管理，学生入住哪栋楼哪个房间哪个床位，当前是在住状态还是已退宿；然后是报修管理，学生提交宿舍设备报修工单，宿管员接单处理并记录结果；还要有公告通知模块，管理员发布停水停电、维修安排、假期留宿之类的通知；再叠加角色权限，区分管理员、宿管员、学生三类身份，每个身份能做的事情完全不同。

这套源码在这几个模块上都覆盖到了，整体设计没有追求花哨，而是把后台管理系统的常规需求做得完整扎实。实际做这类项目的时候最容易犯的错误就是一上来先写代码，结果做到一半发现表结构设计不合理，比如宿舍床位和学生的关系没理清楚，报修工单状态流转没考虑闭环，最后返工成本很高。所以拿到一个管理系统需求，第一步永远是先把业务流程图和表结构设计搞定，代码反而是水到渠成的事。

1.2 前后端分离的架构取舍

前后端分离这个词这些年被说得太多，但真正深入理解它解决什么问题的人并不多。传统单体结构下，前端页面和后端逻辑揉在一个工程里，模板引擎渲染页面，改个交互可能要动后端代码，两边耦合得很紧。这种模式做小项目没问题，但一旦系统功能多起来，前端要改样式、后端要调接口，所有人挤在同一套代码里，版本管理、调试、部署都是麻烦事。

前后端分离的核心变化是把页面渲染和数据处理彻底拆开，前端只负责展示和交互，通过HTTP请求向后端要数据，后端只负责业务逻辑和数据库操作，通过标准接口把数据返回给前端。这样带来的好处很直接，前端开发者和后端开发者可以并行推进，后端定义了接口文档后，前端用Mock数据就能先把页面写出来，后端把接口实现完再一联调就完事。另外部署上也灵活，前端打包成静态文件交给Nginx托管，后端打包成Jar包独立运行，哪边要更新就单独重新部署哪边，不用整包替换。

这套系统采用的正是这种分离架构，后端跑在8080端口提供RESTful接口，前端用Vue开发跑在5173或者打包成dist目录静态文件。带来的一个必然问题就是跨域，浏览器安全策略会拦截不同源的Ajax请求，这是前后端分离绕不开的坎。实际项目中有两种主流解决方案，开发阶段用Vite或者Webpack的Proxy把接口请求代理到后端地址，生产阶段用Nginx反向代理把/api前缀转发到后端服务。这套源码里把这两种方式都配好了，我在下面的实操部分会详细拆解。

1.3 技术选型的底层逻辑

技术栈选型不是越新越好，也不是越热门越好，关键要看项目规模和团队的熟悉程度。宿舍管理系统属于典型的中小型业务系统，QPS压力不大，并发要求不高，但业务逻辑相对完整，需要快速开发、稳定运行、方便维护。基于这个前提来看这套技术栈的合理性就很清楚了。

SpringBoot在后端用的是Java生态最成熟的方案，内置Tomcat容器，不用额外配置外部服务器，自动配置机制省掉了大量XML配置，配合SpringMVC的注解开发，一个Controller就能把接口写得很干净。MyBatis作为持久层框架，优势在于SQL由开发者自己掌控，复杂的关联查询、报表统计直接写SQL更直观，而且SQL调优空间大，相比Hibernate这类全自动ORM框架，在中小型系统中MyBatis的学习成本和可控性都更均衡。MySQL作为数据库不用多说，开源免费，性能完全够用，配合Navicat或者DBeaver这类可视化工具做数据管理很方便。

前端选择Vue，在目前的主流框架里它是上手门槛最低的，组件化开发模式让页面复用非常方便，直接使用Element UI或者Element Plus组件库，表格、表单、弹窗、分页这些后台管理系统的高频组件都是现成的，几天时间就能把管理端界面搭出一个雏形。这样的组合对于毕业设计或者中小规模真实项目来说，性价比很高，团队成员只要会Java、懂得基本的SQL、了解Vue的基础语法就可以上手干活，不至于在框架本身耗费太多精力。

2. 数据库设计与核心接口拆解

2.1 表结构设计要点

数据库设计是一个管理系统最根本的骨架，表关系理不顺，后面所有接口和前端页面都会跟着别扭。这套源码在表结构设计上做得比较规范，我把核心表梳理一下：

• 用户表（user）：存储系统登录账号，字段有主键id、用户名username、密码password、角色role、关联学号或工号、创建时间。这里要注意密码不能存明文，源码中使用的是MD5加盐或者BCrypt加密存储，登录时比对摘要值而不是原文。
• 学生表（student）：存储学生基础信息，包括主键、学号studentNo、姓名name、性别gender、电话phone、所属楼栋ID、所属宿舍ID、床位号、入住状态。学号要加唯一约束，因为学号是学生的自然业务标识。
• 楼栋表（building）：楼栋名称、楼层数、楼栋描述等。
• 宿舍表（dormitory）：所属楼栋ID、房间号roomNo、床位数capacity、当前已住人数、宿舍类型（男生宿舍/女生宿舍）。
• 报修表（repair）：报修宿舍ID、报修学生ID、报修标题、问题描述、报修状态（待处理/处理中/已完成）、报修时间、完成时间。
• 公告表（notice）：标题、内容、发布人ID、发布时间、置顶标记。

重点说一下宿舍和学生之间的关系，宿舍和学生是典型的一对多关系，一个宿舍可以住多个学生，一个学生同时只属于一个宿舍。但设计时不能在student表里简单只存一个dormitoryId，还要存床位号bedNo和入住状态，这样才能精确到"3栋501宿舍2号床住的是谁"。同时dormitory表的capacity和已住人数要维护好，每次学生入住时事务里要同时做两件事：把student表的状态改为在住并写入宿舍ID和床位，把dormitory表的已住人数加一。如果这两步不是原子操作，就会出现数据不一致的情况，人数统计错误。

这部分实际设计的时候还涉及一个常见选择：要不要建一个独立的"入住记录表"来记录学生从入住到退宿的完整历史？如果只是做毕业设计，业务深度要求不高，不建也能跑通。但如果想让系统更有说服力，加一张move_record入住记录表会加分很多，退宿的时候不是把学生状态标记为已离校就完事，而是留一条历史记录。这套源码选择的是简化方式，学生表里直接管理当前入住状态，逻辑更清晰，也更好向答辩评委解释，取舍上没有什么问题。

2.2 模块接口清单与权限控制

后端接口围绕业务模块展开，核心接口大致分类如下：

• 认证模块：POST /api/auth/login 登录接口、POST /api/auth/logout 退出接口。登录成功后后端签发一个JWT token返回给前端，前端存储后每次请求放在请求头里。
• 学生管理：GET /api/student/list 分页查询学生列表、POST /api/student 新增学生、PUT /api/student/{id} 修改学生信息、DELETE /api/student/{id} 删除学生、POST /api/student/assign 分配宿舍。
• 宿舍管理：GET /api/dormitory/list 分页查询宿舍列表、POST /api/dormitory 新增宿舍、PUT /api/dormitory/{id} 修改宿舍、GET /api/dormitory/building/{buildingId} 按楼栋查宿舍。
• 报修管理：POST /api/repair 提交报修、GET /api/repair/list 分页查询报修列表（管理员和宿管员看全部，学生只看自己的）、PUT /api/repair/{id}/status 更新报修状态。
• 公告管理：GET /api/notice/list 公告列表、POST /api/notice 发布公告、DELETE /api/notice/{id} 删除公告。
• 统计接口：GET /api/dashboard/stats 获取首页统计数据，包括总学生数、总宿舍数、待处理报修数、当前入住率等。

权限控制使用SpringBoot拦截器加上JWT实现。逻辑不复杂：登录成功生成token，拦截器对所有受保护的接口请求校验请求头里的Authorization字段，解析token是否合法，如果token无效直接返回401状态码。角色控制则在接口层用注解或代码判断，比如发布公告接口只允许管理员角色调用，更新报修状态接口只允许宿管员和管理员调用。这种基于拦截器的权限模型对于中小型系统完全够用，不需要引入Spring Security那么重的框架。

2.3 密码存储与数据安全细节

很多拿来即用的管理系统源码在密码这块处理很随意，直接明文存数据库，这是非常不好的习惯，哪怕只是学习项目也应该建立安全意识。这套源码的做法是用户注册或初始化的时候对密码做加密处理，常见的做法是使用BCrypt，同一个密码每次加密得到的字符串都不同，因为内部引入了随机盐，验证的时候用BCrypt的matches方法做比对。

另外一个值得注意的细节是数据库连接配置。application.yml文件里的数据源配置要确保数据库名、用户名、密码和本机MySQL实际情况一致。MySQL 8.x版本的驱动类名是com.mysql.cj.jdbc.Driver，连接URL要带上serverTimezone参数指定时区，否则容易报错。字符编码也要设置成UTF-8，避免中文乱码问题。这些配置虽然琐碎，但恰恰是初学者最容易被卡住的地方。

3. 本地运行与全流程实操

3.1 开发环境准备清单

在开始跑源码之前，我先把需要准备的环境列出来，这样你可以对照检查，避免中途翻车：

• JDK 1.8 或 11
• Maven 3.6以上
• Node.js 14以上
• MySQL 8.0及以上
• 后端开发工具推荐 IDEA（社区版即可）
• 前端开发工具推荐 VSCode

MySQL安装完成后要手动创建一个数据库，字符集选择utf8mb4。这里有个细节，我建议直接用命令行或者Navicat执行源码中提供的sql脚本，不要在可视化工具里手工建表，因为sql文件里通常还包括了初始化数据，比如默认管理员账号和基础楼栋宿舍数据，手工建表很容易漏掉。

3.2 后端从配置到启动

后端工程导入IDEA之后，首先需要确认Maven配置正确。项目导入时IDEA会自动开始下载依赖，如果你发现依赖下载慢或者一直失败，需要检查Maven的settings.xml文件是否配置了阿里云镜像仓库，这个问题在国内开发环境下太常见了，我在后面的排查章节会专门讲。

打开src/main/resources/application.yml文件，核心配置大概长这样：

server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/dormitory_db? useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: 你的数据库密码 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.entity jwt: secret: 你的签名密钥 expire: 86400000

把数据库密码改成你自己的，确认MySQL服务已经启动，然后运行启动类里的main方法，看到控制台输出Tomcat started on port 8080就说明后端启动成功了。这时候可以用Postman或者浏览器直接访问登录接口做验证，比如POST请求往/api/auth/login发送一个JSON格式的登录请求，返回结果里有token字段就说明接口链路是通着的。

3.3 前端从依赖到运行

前端工程使用Vue开发，启动流程相对简单。打开终端进入前端项目目录，先执行npm install安装依赖，这个步骤耗时取决于网络情况。安装完成后执行npm run dev，Vite或者Webpack会启动一个开发服务器，默认端口一般是5173或者8080。

这里有一个非常关键的配置要提前检查，就是前端开发环境访问后端接口的代理设置。如果用的Vite，请看vite.config.js文件里的server.proxy配置，如果用的Vue CLI，则是vue.config.js里的devServer.proxy配置。代理的作用是把前端请求的/api前缀请求转发到后端的8080端口，从而绕开浏览器跨域限制。配置大致这样：

server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }

配置好之后，前端页面里的axios请求就可以直接写/api/auth/login，Vite开发服务器会把这个请求转发到http://localhost:8080/api/auth/login。如果你打开浏览器F12发现请求返回的是404，大概率是代理配置里target地址写错，或者后端没有启动。

前端登录页面输入默认管理员账号密码，登录成功后会跳转到系统首页。首页布局一般是左侧菜单栏加右侧内容区的后台管理框架，左侧菜单根据角色动态显示不同模块。到这里，本地完整运行就跑通了。

3.4 前后端联调与生产部署

本地开发模式跑通只是第一步，真正要把系统部署到服务器上还需要走生产构建流程。后端的处理比较直接，在项目根目录执行mvn clean package -Dmaven.test.skip=true，等待打包完成后，target目录下会生成一个可执行的Jar包，在服务器上执行java -jar xxx.jar就能启动后端服务。生产环境建议使用nohup命令后台运行，并且配合错误日志输出，方便排查问题。

前端的生产构建是在项目目录执行npm run build，构建完成后生成dist目录。dist目录就是纯静态文件，里面包含html、js、css和各种静态资源，把这个目录上传到服务器上，配置Nginx作为静态文件服务器，同时设置反向代理把/api请求转发到后端服务。Nginx配置核心部分如下：

server { listen 80; server_name 你的域名或IP; root /var/www/dist; index index.html; location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { try_files $uri $uri/ /index.html; } }

这里最关键的是最后这个try_files配置，它的意思是前端路由匹配不到具体文件时，统一返回index.html，让Vue Router接手处理页面路由。如果没有这一行，刷新非首页路由时会出现404页面，这是SPA应用部署最常见的坑之一。

4. 常见问题与排查技巧实录

4.1 跨域问题怎么彻底解决

前后端分离项目第一个遇到的基本都是跨域问题。现象很典型，前端页面能打开，控制台网络请求里报错Failed to load resource或者Access to XMLHttpRequest has been blocked by CORS policy，接口数据拿不到。

跨域的本质是浏览器同源策略在拦截，协议、域名、端口任何一个不同都属于跨域。本地开发时前端5173端口和后端8080端口本身就是跨域关系，但因为有代理转发，实际上浏览器看到的请求是同源的，代理把接口请求在服务端转发出去了。所以开发阶段跨域问题的排查重点不是后端的CORS配置，而是前端代理配置对不对。检查代理配置后记得重启前端开发服务器，vite.config.js或vue.config.js的修改必须重启才生效。

生产环境则依赖Nginx反向代理解决跨域，浏览器访问的是Nginx的80端口，请求/api前缀时Nginx服务端转发到后端8080端口，浏览器依然认为所有请求是同源的，也就不存在跨域问题。

4.2 数据库连接与时间配置问题

后端启动时报数据库相关错误，最常见的两种：一种是Communications link failure，说明MySQL服务没启动或者配置的地址端口不对；另一种是Access denied for user，说明用户名密码错误或者该用户没有远程访问权限。

MySQL 8.x还需要特别注意驱动类和时区参数。驱动类必须写成com.mysql.cj.jdbc.Driver，这是MySQL 8的驱动路径，如果写成老的com.mysql.jdbc.Driver虽然有些版本也能跑，但会提示驱动已过时。时区参数serverTimezone=Asia/Shanghai是必要的，不写的话启动时可能报The server time zone value 'China Standard Time'这样的错误，因为MySQL驱动的时区推断规则变了。另外我建议连接URL里把useUnicode和characterEncoding也带上，这个参数能避免从数据库查出来的中文显示乱码。

4.3 Maven依赖下载失败与端口冲突

后端导入IDEA后一直报红，或者pom.xml里dependency标红，基本都是Maven依赖下载问题。我遇到过很多次，项目本身没毛病，就是settings.xml里没有配置镜像或者配置的镜像不可用。在settings.xml的mirrors节点里加上阿里云公共仓库地址：

<mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

配置完成后重新导入项目，IDEA会自动重新拉取依赖。

端口冲突是另一个高频问题，启动后端时控制台报Port 8080 was already in use，说明8080端口被占用。Windows下用netstat -ano | findstr 8080查看占用PID，打开任务管理器找到对应进程结束掉，或者直接在application.yml里改成其他端口，比如8081。前端Vite开发服务器端口被占用同理，可以在vite.config.js里修改port参数。

4.4 前端部署后404与打包体积优化

本地开发环境一切正常，部署到服务器后刷新页面就404，这个问题前面提到过，是SPA路由模式导致的。Vue Router默认使用history模式来实现干净的URL，但生产环境Nginx没有配置try_files指令时，浏览器访问某个子路由路径，比如/admin/dormitory，Nginx会去磁盘上找这个路径对应的文件，找不到自然就返回404了。解决方式就是配置try_files $uri $uri/ /index.html，让所有路径都回退到前端入口文件。

打包体积优化这块，如果npm run build产出的dist目录有几十兆，说明没有做代码分割和按需加载。可以检查一下main.js里是不是把整个Element Plus组件库全部import了，正确做法是使用按需加载插件，或者至少在全局引入前考虑清楚哪些组件是真正高频使用的。还有一个基础优化是把路由组件改成懒加载，用const xxx = () => import('@/views/xxx.vue')的方式引入，这样首屏只加载当前路由对应的组件代码，打包体积能瘦身不少。

4.5 学生分配宿舍与数据统计的业务校验

业务层面的坑往往比技术层面的更隐蔽。给学生分配宿舍时，接口如果不判断宿舍当前已住人数是否已经达到容量上限，就会出现超员分配的情况，显示已经住了4个人的4人间还能分配新学生进去。源码的逻辑是在分配宿舍的事务里先查dormitory表的currentCount和capacity做比对，超过容量直接抛出业务异常返回提示信息。这个校验如果只在Vue前端做是不够的，因为前端校验只拦截了正常操作路径，用API工具绕过前端直接调用后端接口时，后端必须自己做数据合法性验证。

首页的统计图表数据也值得一说，入住率、楼栋人数分布、报修分类占比这些数据，通常通过SQL的聚合查询直接完成。比如统计各楼栋人数可以这样写：SELECT building_id, COUNT(*) FROM student WHERE status = 1 GROUP BY building_id。要注意COUNT函数统计的是学生表在住记录数，而不是宿舍表的容量字段，两个概念别搞混。

写在最后

把这套系统从头到尾跑通之后，我最深的感受是：管理系统项目从来不缺技术点，缺的是把技术点串起来的能力。宿舍管理系统从业务上看就是"管人、管房间、管工单"三件事，但从工程角度看，表结构设计、接口权限建模、前后端数据流转、跨域联调、生产部署，每一环都有足够多值得琢磨的细节。我自己在做这个项目时踩过最大的坑反而是最简单的数据库配置问题，浪费了整整一个晚上才反应过来是时区参数没配，所以说，越是看似基础的地方，越要养成配置前先确认环境参数的习惯。

如果你是拿这套源码做课程设计或者毕设，我的建议是在把基础功能完全跑通之后，挑一两个方向做二次开发，比如给报修模块加一个Excel导出功能、给统计模块接入一个ECharts柱状图、把登录改成JWT加Redis的会话管理。这些扩展点虽然不大，但每一次动手都会逼着你把某个环节理解得更深一层。系统的完整源码和部署教程都在本地目录里，编译启动过程花不了多长时间，真正值得花时间的，是在这个过程中把每一行配置和每一个接口设计吃透。