每年开学季和期末季学生公寓的报修需求都会集中爆发——水龙头漏水、空调不制冷、寝室灯管闪坏、柜门合不上各种报修单子从宿管、电话、微信群里涌进来靠人工登记和派单很容易漏单、错单、响应慢。我之前带团队做过一个基于SpringBoot的学生公寓报修平台从需求梳理、数据库设计到前后端联调、打包部署全部走了一遍过程中踩了不少坑也沉淀了一些比较实用的经验。这篇博文就把整个项目的设计思路、核心模块、数据库表结构、关键代码实现以及调试部署过程详细拆开讲希望对正在做类似管理系统、或者用SpringBoot做毕业设计的同学有帮助。这类平台本质上是一个典型的多角色业务管理系统核心价值就是把“学生报修—管理员派单—维修工处理—学生验收评价”这条链路搬到线上让每一步都有记录、可追踪、能统计。先说清楚它解决了什么问题以前报修靠纸质登记本或者微信群接龙信息分散、状态不透明学生不知道维修师傅什么时候来管理员也没法快速统计各楼栋的维修频率。有了平台之后学生在线提交工单系统自动按楼栋、报修类型分类管理员一键指派维修工手机端接单、填写维修结果学生确认后还能评价整套流程闭环数据也能沉淀下来做报表分析。适合谁来参考如果你正在做SpringBoot相关的课程设计、毕业设计或者想自己动手从零搭一个前后端分离的管理系统这个项目的完整度很合适如果你已经在写代码但不太清楚权限控制、工单状态流转这类业务怎么落地下面这些内容也能给你一些直接的参考。1.1 一个真实的学生公寓报修流程是什么样在设计系统之前我专门去学校后勤部门蹲了几天把线下流程摸了个清楚。真实场景大致是这样的学生发现宿舍设施损坏先找宿管登记宿管手写一张报修单然后电话联系维修工。维修工有空就上门没空就让宿管盯着修完在单子上签个字就算结束。这中间的痛点是楼栋一多报修单容易漏宿舍报修高峰期纸质单子堆积响应顺序全靠人工判断维修进度学生完全不知道。所以平台在还原线下流程的基础上做了数字化改造核心流程设计成四步学生提交工单 → 管理员分配维修工 → 维修工处理并填写结果 → 学生确认验收并评价。每一步都有对应的角色和状态约束不允许跨状态操作。比如维修工只能处理“待维修”状态的工单处理完必须填写维修耗时和材料消耗学生只能在状态为“已完成”时进行验收验收不通过可以退回返修。这样设计的好处是每个环节都有责任人出现纠纷时能直接通过系统日志定位。1.2 为什么选SpringBoot而不是其他框架很多人问做个报修平台用SpringBoot是不是杀鸡用牛刀其实不是。选SpringBoot有几个很实在的理由第一它生态成熟MyBatis-Plus、Redis、Shiro、MinIO这些常用组件都有非常完善的和SpringBoot的整合文档开发效率高第二它内置Tomcat打包成jar就能直接跑部署成本低对学生项目和中小型系统来说非常友好第三社区活跃面试和毕业答辩时也容易讲清楚。另外我对比过SSHStrutsSpringHibernate和SpringMVC单体架构SSH现在已经很少有人用了配置XML太繁琐纯SpringMVC虽然更轻量但要做大量的手动配置比如数据源、事务、json转换等。SpringBoot通过自动配置把这些全封装掉了我们只需要关注业务代码。当然SpringBoot也有弱点就是自动配置的黑盒机制出了问题排查起来比较费劲这个在后面“常见问题”部分我会专门讲。1.3 这个项目交付物里到底包含哪些东西标题里提到的“程序源码数据库调试部署开发环境”拆开来看其实是五个层次程序是打包好的可运行物源码是可读、可改的工程代码数据库是建库建表的SQL脚本和初始数据调试部署是详细的启动步骤和常见错误解决办法开发环境就是JDK、MySQL、IDEA、Maven这些工具的版本和配置要求。我建议拿到项目后先按顺序做先导入源码到IDEA再执行SQL脚本初始化数据库然后修改application.yml里的数据库连接信息最后启动检查控制台日志。不要一上来就想改功能先把系统跑通再动手改代码这样出问题的时候你才知道是环境问题还是业务代码问题。2. 整体架构与模块设计拆解整个平台采用的是经典的SSM微服务雏形不这里用的是SpringBoot单体架构。为什么不用微服务因为学生公寓报修平台的核心业务是工单流转和人员管理并发量不大单体架构部署简单、维护成本低、事务控制容易完全够用。如果硬拆成微服务反而会因为分布式事务、服务间调用等问题把项目复杂度拉高对学习和答辩都不利。这个选择我觉得是合理的在实际项目中能用单体解决的绝对不上微服务。2.1 三种角色一张图看懂权限边界系统里一共三类角色学生普通用户、维修工、管理员。权限边界用一句话概括学生管自己的报修单维修工管被分给自己的任务管理员管全局配置和数据统计。角色核心权限主要操作学生报修、查询、评价提交报修工单、查看处理进度、确认验收、评价评分、修改个人信息维修工任务处理查看我的工单、接单/退单、填写维修结果、上传维修后照片管理员全站管理工单派发/改派、用户管理、楼栋与报修类型维护、数据统计、公告发布三个角色共用一套登录认证逻辑登录成功后返回的角色码不同前端根据角色码渲染不同的菜单后端在接口层级做权限拦截。这里我建议权限校验放在后端做前端隐藏菜单只是体验优化不是安全手段。实际操作中有些同学只在前端做路由判断后端接口不拦结果有人直接调用接口绕过了权限这是很典型的安全漏洞。2.2 报修工单的生命周期设计工单是系统的核心实体我把它的状态设计成七个待派单、待接单、维修中、已完成、已验收、已驳回、已取消。状态的变迁不是随意的而是有严格的动作约束学生提交后工单进入“待派单”状态此时只有管理员能看到并派单。管理员派单给某个维修工后状态变为“待接单”维修工可以接单状态变为“维修中”也可以申请退单退回给管理员。维修工处理完成并填写结果后状态变为“已完成”此时学生端才会出现“验收”按钮。学生点击验收通过后状态变为“已验收”流程结束如果验收不通过可以填驳回意见工单重新回到“待派单”状态管理员可重新派单或催办。“已取消”状态主要用于学生提交后发现填错或自行解决了在没有被派单之前取消。一旦派单学生就不能自行取消了得联系管理员处理。这里有一个非常容易踩坑的地方状态字段如果用int存代码里每个数字代表什么含义很容易忘记特别容易改错。我建议用枚举统一管理代码里只允许通过枚举转换数据库里存字符串枚举名这样可读性和维护性都好很多。后面我贴了具体代码可以直接参考。2.3 功能模块划分与接口设计整个系统按业务域划分成六大模块用户模块、工单模块、报修类型模块、楼栋管理模块、公告模块、统计报表模块。每个模块的接口遵循RESTful风格返回统一格式的Result对象结构为code、message、data三件套。前端先判断code是否等于200再取data这样后端抛异常时也能统一返回code500前端弹一个错误提示不白屏。接口命名方面我按资源来设计比如POST /api/repair/order 提交工单GET /api/repair/order/list 查询工单列表支持分页和条件查询PUT /api/repair/order/assign 管理员派单PUT /api/repair/order/processing 维修工接单/处理PUT /api/repair/order/accept 学生验收这种以资源加动作为核心的命名方式前后端对接的时候非常直观也方便写接口文档。开发期间我把接口文档用Swagger生成写接口的时候就顺手加上注解省得后面还要单独维护文档。3. 数据库设计与核心表结构数据库设计是整个项目的地基地基没打好后面写接口的时候就会各种别扭。我在设计时遵循几个原则一是表名和字段名用清晰的英文命名二是所有业务表都要有id、create_time、update_time这三个字段三是金额、状态这类字段用int或decimal存不要用varchar存数字否则排序和统计都会出问题。3.1 核心表设计一览系统核心共八张表我把最关键的列和说明列出来表名说明关键字段t_user用户表id、username、password、real_name、role_id、phone、dormitory_idt_repair_order报修工单表id、order_no、student_id、dormitory_id、type_id、description、images、status、processor_id、process_time、apply_remarkt_repair_type报修类型表id、type_name、sortt_dormitory楼栋/宿舍表id、building_no、room_no、managert_repair_log工单操作日志表id、order_id、operator_id、action、remark、create_timet_announcement公告表id、title、content、publisher_id、create_timet_comment评价表id、order_id、student_id、score、content、create_timet_role角色表id、role_name、role_code3.2 工单表的设计细节t_repair_order是核心我把几个容易出问题的地方单独说一下。首先是order_no工单编号我用了“日期流水号”的生成规则格式是20250613001含义是2025年6月13日第1单。生成逻辑是查当天最大编号加1用Redis的incr做自增计数更稳但如果没有Redis用查询锁也能实现只是并发高时有可能会重复需要注意加数据库唯一索引兜底。其次是images字段存的是用户上传的故障照片URL多个用逗号分隔。有些同学会单独建一张图片表也可以但在照片数量不多的小系统里直接用分隔符存储更简单查询工单详情时切分一下就能渲染。我实际开发时是把图片传到MinIO返回的URL直接存到images字段里包工时再把URL取出拼接成json传给前端。第三是processor_id表示当前负责的维修工。一个工单在流转中可能被多次改派所以processor_id只存当前处理人历史流转记录全部记到t_repair_log里。这样的设计让工单表本身保持简洁同时日志表可以追溯整个处理过程审计也方便。3.3 逻辑删除与乐观锁的实践开发过程中我踩过一个很经典的坑删除用户时直接delete结果把历史工单里的学生关联搞没了导致工单统计的时候数据对不上。后来我给所有业务表都加了deleted字段用MyBatis-Plus的TableLogic做逻辑删除。查询时框架自动拼接deleted 0删除操作实际是update历史数据永远保留。这个习惯我在做其他系统时也沿用强烈建议大家从一开始就加上。乐观锁则用在工单状态的并发更新上。设想一个场景管理员在处理工单的同时维修工也点了接单两个请求同时读到状态是“待接单”都执行了update就可能出现状态覆盖。解决办法是给t_repair_order加version字段更新时带上WHERE version #{version}判断影响行数如果为零说明被别人改过了提示用户稍后重试。MyBatis-Plus自带Version插件开启乐观锁只是几行配置的事强烈推荐加上。4. 核心功能实现的几个关键点这一部分我讲一下开发过程中值得反复斟酌的几个技术点每个都涉及到系统的稳定性和用户体验也是答辩时老师容易追问的地方。4.1 工单状态机与流转控制状态机是整个业务最核心的部分。我建议不要在每个接口里都写一遍if判断而是把状态流转抽出来统一管理。实现方式有轻量和重量两种轻量方式是用枚举加一个变更校验方法重量方式是引入状态机框架比如Spring StateMachine。对报修平台这个规模用轻量方式就够了。我自己写了一个RepairOrderState枚举里面定义状态和允许的流转目标然后提供一个transition方法进入新状态前先校验当前状态是否允许流转到目标状态不允许就抛业务异常。这样所有状态更新都走同一个入口不会出现在A接口改了状态但没记录日志的情况。我把日志写入也放在transition方法里每流转一次就自动往t_repair_log插一条记录省得每个接口手动去写日志逻辑统一且不容易漏。4.2 前后端分离下的权限控制系统采用前后端分离架构后端接口用JWT做无状态认证。登录成功后签发token前端存到localStorage每次请求在header里带上Authorization。后端用一个拦截器统一解析token解析出userId和roleCode放到ThreadLocal里Controller直接取。权限校验我是在拦截器里根据角色码做简单判断哪些接口管理员才能访问哪些是维修工专属。比如/admin/**开头的接口只能管理员访问/worker/**只能维修工访问/student/**只能学生访问。如果接口放错路径权限就崩了所以不建议用URL前缀做粗粒度权限。更合理的做法是使用RequireRole这样的注解标注在Controller方法上拦截器通过反射读取注解做校验这样权限和接口写在了一起可读性也更高。4.3 图片上传与MinIO接入的方式报修必然要上传故障照片这是整个项目里最容易出问题的一环。一开始我用的是本地磁盘存储把上传的文件写到服务器的某个目录然后返回URL看起来简单但有两个坑一是服务器重启后目录丢失二是前端直接访问磁盘路径会有跨域和权限问题。后来我换成了MinIO一个开源的对象存储服务部署起来就一个docker命令的事本地开发也可以直接跑。SpringBoot整合MinIO其实不复杂。先在pom.xml引入io.minio:minio依赖然后在application.yml配endpoint、accessKey、secretKey、bucketName写一个MinioService里面封装上传、删除、获取访问地址这几个方法。上传时用UUID给文件重命名防止重名覆盖。有一点需要注意MinIO的bucket要提前创建并设置公共读策略否则前端拿到的URL预览会404。这个问题我当时排查了很久最后发现是bucket的访问权限没设置对。4.4 站内信与微信通知的取舍工单状态变了学生怎么第一时间知道最开始我只做了站内信就是工单列表里加个未读红点后来发现很多学生根本不会主动刷新网页于是加了WebSocket推送。实现方式是用Spring的WebSocket握手时从token里解析userId后端维护一个userId到Session的映射工单状态变更时主动推送一条消息给对应学生。这里有个细节WebSocket的Session不是线程安全的多线程并发推送前要加锁否则会出现消息丢失或异常。WebSocket推送只是“锦上添花”实际运行时如果学生关了网页推送还是收不到。所以最终方案是站内信保底WebSocket只做实时提醒。我建议做这类系统时不要过度依赖推送数据库里的消息表才是数据本体推送只是通知手段。很多同学做这类项目喜欢把推送放得很重结果一重启连接就全断反而把系统复杂度拉高了。5. 开发环境搭建与调试部署实录很多人在项目开发阶段很顺利一到部署就各种报错环境问题占了很大比重。我把自己实际搭建环境、调试、部署的过程完整记录下来包括版本选择、配置项和遇到的重点问题照着走基本能少踩一半坑。5.1 开发环境版本与安装说明我用的开发环境就是标题里说的“程序源码数据库调试部署开发环境”那一套具体版本如下工具推荐版本说明JDK1.8 或 11SpringBoot 2.7.x 对这两个版本支持最稳IDEA2023.x 及以上社区版完全够用不用买旗舰版Maven3.8.x不要用3.9.0之后的版本有些仓库兼容有问题MySQL5.7 或 8.0推荐8.0注意时区和驱动配置Redis6.x用于token缓存和工单号自增安装顺序我建议先装JDK再装Maven然后是MySQL最后是Redis。每次装完都验证一下环境变量JDK验证命令java -versionMaven验证mvn -vMySQL验证mysql --version。很多的坑往往发生在环境变量没配置好导致IDEA里编译的时候能过但命令行跑jar包就跑不起来。5.2 SpringBoot核心配置与关键参数application.yml是SpringBoot启动的核心我把关键的配置项解释一下特别标注几个容易出错的地方server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/repair_platform?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver redis: host: localhost port: 6379 database: 0 servlet: multipart: max-file-size: 10MB max-request-size: 20MB mybatis-plus: mapper-locations: classpath*:mapper/*.xml configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl有几个参数我要特别强调。第一是serverTimezone如果MySQL用的8.0url里必须带serverTimezoneAsia/Shanghai否则JDBC驱动会报“The server time zone value”的错这是新手最常见的问题。第二是map-underscore-to-camel-case这个开关默认是开的可以让数据库字段create_time自动映射到Java属性的createTime省去大量TableField注解。第三是multipart上传大小的限制如果照片原图比较大默认1MB的限制是不够的我配置成了10MB实际一张手机拍的照片通常在3-5MB左右。5.3 前端资源打包后放进SpringBoot的整合技巧实际部署时为了省一台服务器我把前端Vue项目打包后的dist目录直接放进SpringBoot的静态资源目录这样整个系统就是一个jar包java -jar启动后既能访问后端接口也能访问前端页面非常方便。具体步骤是这样先在前端项目根目录执行npm run build打包后生成一个dist目录。把dist目录里的全部文件复制到后端src/main/resources/static目录下。然后重新用Maven打包后端生成的jar就自带前端页面了。前端打包后默认的静态资源路径是/和后端接口的/api前缀不冲突。如果前端用了history路由模式记得要在后端加一个转发保证刷新页面时不会404不然单击刷新页面就报404非常影响体验。我是在SpringBoot里加了个WebMvcConfigurer把非/api的路径全部转发到index.html几行代码搞定。5.4 三种部署方式的对比与选择部署方式我试过三种本地IDEA直接启动、Linux服务器jar包部署、Docker容器化部署。本地IDEA启动适合开发调试按ShiftF10就能跑断点调试最方便。Linux服务器jar部署适合小规模正式使用把打包好的jar上传到服务器执行nohup java -jar xxx.jar app.log 21 日志输出到app.log方便排查。Docker部署适合环境统一写一个Dockerfile把JDK和jar打进镜像再用docker run启动换服务器的时候一条命令就能拉起环境。从稳定性角度我最推荐Linuxjar的方式原因很简单Docker虽然好但要额外运维镜像仓库对学生项目来说有点重。jar方式只需要一台能跑Java的服务器就够了出了问题看日志也比较直观。6. 常见问题与排查技巧实录这部分我把实际开发和部署过程中遇到的高频问题记录下来按照现象、原因、解决办法三个维度整理成速查表方便你遇到同样问题的时候直接对号入座。6.1 启动时报数据库连接错误报错信息一般是“Cannot connect to MySQL server”或“Access denied for user”。大多数原因是数据库没有启动、账号密码不对、或者url里的host端口写错。排查顺序建议先手动用命令行mysql -u root -p试试能不能连上确认数据库本身没问题再看SpringBoot配置文件的url、username、password是否一致。还有一个隐蔽原因如果你的MySQL跑在远程服务器上本地连不上可能是MySQL的bind-address默认绑定了127.0.0.1需要改成0.0.0.0然后授权远程访问。这个我在自己的项目里遇到过本地IDEA能连部署到服务器上就连不上最后发现是MySQL的安全配置问题不是SpringBoot代码的问题。6.2 端口被占用怎么办jar部署时最常遇到的报错是“Port 8080 was already in use”。先用netstat -tlnp | grep 8080找到占用端口的进程确认是不是自己之前启动的旧进程kill掉之后重新启动就好。如果你有多个项目要同时跑可以在application.yml里用server.port改成8081、8082等也可以启动时用--server.port8081覆盖配置文件里的端口灵活一些。如果服务器上已经有nginx或其他服务占用了80端口我一般会把SpringBoot服务跑在8080然后通过nginx反向代理到80对外提供服务。这样既不影响现有服务又不用改代码。6.3 Maven依赖冲突与下载失败SpringBoot项目依赖多时不时会遇到jar包下载失败或者依赖冲突。下载失败大概率是Maven仓库源的问题国内网络访问中央仓库经常超时我建议在settings.xml里把镜像源换成阿里云镜像基本一次解决。依赖冲突的表现是启动时报NoClassDefFoundError或者bean创建异常原因一般是同一个类有多个版本的jar被加载。排查依赖冲突的命令是mvn dependency:tree看依赖树里有没有重复的jar包。比如很多同学同时引入了spring-boot-starter-web和spring-boot-starter-actuator版本不一致时就会出现冲突。解决办法是使用Maven的依赖管理机制通过dependencyManagement统一版本号或者用exclusion把多余的传递依赖去掉。我自己的习惯是在pom.xml的properties里统一声明版本减少版本冲突的可能性。6.4 文件上传后无法预览或丢失图片上传后前端拿不到预览图这个问题的原因是多样的。如果是MinIO存储先确认bucket是否设置了公开读权限如果是本地存储检查上传文件路径是否真的有文件以及返回的URL是否能通过浏览器直接访问。还要注意一个细节SpringBoot默认对静态资源的映射不包括磁盘上的其他目录所以本地存储时我建议把上传目录放到resources/static下的uploads文件夹或者通过自定义资源映射把磁盘路径映射成/image/**,否则前端访问不了。文件丢失的问题通常是服务器重启后磁盘文件没了所以我一直推荐用MinIO或者OSS把文件数据和服务本身解耦服务器挂了也不怕。这一点在标题里虽然没有直接体现但“minio加入到springboot”这个点很多人在做报修平台时都会用到我也就顺便讲透。6.5 一个容易被忽略的bug事务失效在把多个写操作放在一起的时候如果方法没有加Transactional注解或者类没有被Spring管理就会出现事务失效的情况。报修工单创建、日志插入、通知写入这三个操作如果不在一个事务里日志插入失败时工单已经提交了数据就乱了。排查事务失效有个技巧加Transactional的方法不能是private的不能被this调用还要把异常抛出到事务边界之外否则异常被捕获了事务不会回滚。我实际开发时有一次工单创建成功后报错检查发现日志插入方法没有加Transactional导致创建和日志不一致加上注解并在Service入口统一管理事务后就好了。这个经验值得记下来很多反复出现的“灵异bug”其实都是事务边界的问题。7. 常用调试技巧与个人体会最后分享几个自己总结的调试技巧和心得。第一日志要善用但不滥用。开发时MyBatis-Plus控制台输出SQL日志可以看到每次执行的完整SQL排查问题直接看日志不要靠猜。线上部署时把日志级别调成INFO避免刷屏影响性能。第二前后端联调时先抓包看请求和响应体很多问题一看就是参数名不对或缺失字段不用急着改代码。第三接口测试用Postman或Apifox把常用的接口做成集合改完代码跑一遍回归测试比手工点前端页面高效很多。我个人在实际开发后最深的感受是这类多角色系统的难点不在CRUD而在业务的完整性和数据的准确性。状态流转约束、权限校验、事务边界、字段设计的规范性这些才是真正拉开代码质量差距的地方。另外给正在做毕业论文/毕设的同学一个建议不要只满足于“能跑”把状态机设计、权限方案、文件存储方案、事务控制这几个点讲明白答辩的时候这就是亮点。这个系统后续如果要扩展方向也挺明确的一是把微信小程序端补上学生更习惯用手机报修二是增加工单超时提醒用定时任务扫描超时未接单的工单自动提醒管理员三是数据统计做可视化大屏按楼栋、按类型展示维修频次和平均响应时长后勤部门会很需要。我这边也打算把小程序端和定时提醒做出来后面攒够经验再写一篇分享。如果你正在调这个项目遇到问题欢迎把报错信息发在交流区我看到都会回复。