Spring Cloud微服务实战：校园宿舍报修系统设计与实现

前阵子折腾了一套校园宿舍报修管理系统，技术栈是 SpringBoot + Vue + Spring Cloud + 微信小程序，整体走微服务分布式的路子。这套东西没多神秘，但胜在业务链路完整——学生小程序上报修、维修工接单、管理员派单、后勤统计，从用户端到管理端再到服务端，几乎把企业里常见的那套用户、权限、工单、消息、分布式事务问题都过了一遍。如果你正准备做类似的毕业设计，或者想找一个能写进简历的全栈微服务项目练手，这篇文章应该能帮你理解整个系统的骨架，也会把你实操时会踩的坑提前抖出来。

这类项目的核心价值不在“报修”两个字上，而在“微服务 + 多端 + 信单流转”的整体工程化能力。它既不像纯电商那样重支付，也不像纯后台管理系统那样缺用户端，而是围绕“一个工单生命周期”把业务模型、服务拆分、前后端联动、监控部署全部串起来，非常适合用来熟悉微服务落地的完整路径。下面我从需求拆解讲到部署避坑，按我做这个项目时实际推进的顺序来写。

1. 项目定位与需求拆解

1.1 校园报修业务的真实痛点

宿舍报修听起来简单，实际上比大多数人想的多两个层次。表层是“学生上报、维修工修好”的流程，里层则是“如何避免漏单、错单、档案丢失”的问题。

拿高校场景为例，报修物品集中在灯管、水龙头、门锁、空调、网络端口这些品类的耗材损坏，单量不小，但单张工单的维修时长通常只有十几分钟。这导致一个结果：如果不用系统管理，维修工手上的纸质单据或口头通知很容易在一天内堆积，漏掉一两单就要被学生投诉。管理者也想定期统计哪类报修最多、哪栋楼故障最频繁，没有数据支撑就只能靠猜。

这套系统要解决的，就是把“学生上报”和“后勤维修”之间的每一次状态变化都记录在案，并让相关角色实时可查。学生能看到自己的单子有没有被接、维修工是否已出发、是否完成；管理员能看到所有在途工单，按楼栋、类别筛选；维修工只看到被分配给自己或自己主动抢到的单。

1.2 角色与核心流程

系统最小的闭环包含四个角色：学生、维修工、楼栋管理员、系统管理员。

学生端通过小程序提交报修信息，选择楼栋、宿舍号、故障类型，填写文字描述并上传照片。维修工端可以是小程序也可以是管理后台的待办列表，看到新工单后接单，按预约时间上门，维修后回填处理方式和耗材。楼栋管理员负责审核和派单，也可以把单子转给特定维修工。系统管理员管理用户、角色、维修项字典、楼栋信息以及数据统计。

整个核心流程可以用一条链路概括：学生提交工单 -> 系统校验并落库 -> 楼栋管理员派单 -> 维修工接单 -> 上门维修 -> 回单 -> 学生确认 -> 工单归档。期间任何一个节点超时未处理，系统要能自动提醒对应角色，避免工单卡死。

1.3 为什么选微服务分布式架构

打开多数同类毕业设计，最常见的做法是单体 SpringBoot 加一个 Vue 后台，顶多再加个小程序端。那为什么我还要坚持用 Spring Cloud 微服务？

不是因为项目大，而是这套业务天然适合按“聚合根”切服务。报修工单的主流程涉及用户信息、宿舍信息、工单状态、通知记录，如果全塞进一个单体应用里，以后想单独扩展消息推送、单独做数据统计，全都得在同一个库里耦合改表。切成微服务后，用户服务管认证和人员信息，宿舍服务管楼栋和房间，工单服务管状态流转，通知服务只管站内信和订阅消息，每个服务内聚度高，接口边界也清晰。

哪怕你最后只需要部署在一台 2 核 4G 的服务器上，微服务架构带来的额外复杂度也可以通过合并部署来降低。这个选择更多是为了训练工程思维，不是盲目堆技术。做微服务最大的收益是可以让你把“服务边界”想清楚，这一点在面试和实际工作中都很值钱。

2. 总体架构设计与技术选型

2.1 服务拆分与模块划分

我最终把系统拆成了六个服务，不是越多越好，而是每个服务都有独立的数据表和明确的业务职责：

• gateway：统一入口，负责路由转发、鉴权过滤、跨域处理。
• system-service：用户、角色、权限、菜单管理，提供基于 JWT 的登录认证接口。
• dormitory-service：楼栋、宿舍、房间信息管理。
• repair-service：维修工单的创建、派单、接单、回单、评价全生命周期管理。
• message-service：站内信、微信订阅消息的发送记录和模板管理。
• statistics-service：按日、按月、按楼栋、按故障类别的报修统计报表。

每个服务独立连接自己的数据库。为了减少运维成本，我用的是 MySQL 8.0，每服务一个独立 schema，也就是逻辑隔离，并没有部署多套 MySQL 实例。注册中心和配置中心用 Nacos，服务间调用用 OpenFeign，网关路由用 Spring Cloud Gateway。整体保持主流但不过度，适合当前常见的微服务教程体系。

2.2 核心组件选型：Nacos、Gateway、负载均衡与远程调用

服务发现了以后，组件选型不是随便选的。

Nacos 同时承担注册中心和配置中心，我选择它是因为它对中文文档友好，且控制台自带服务列表、健康检查、配置上下线功能，排错时非常直观。Eureka 只能做注册中心，且已经停更维护，Spring Cloud Config 又是单独的配置中心，组合起来远不如 Nacos 一个中间件省事。

网关我用了 Spring Cloud Gateway，没有用 Zuul。Gateway 基于 WebFlux，性能更好，且遇到跨域、鉴权、限流都有成熟的 DSL 写法。关键点是网关层只做过滤和路由，不写具体业务逻辑，避免网关耦合业务导致重启频繁。

服务间同步调用用 OpenFeign，它自带声明式 HTTP 客户端和 Ribbon/Spring Cloud LoadBalancer 负载均衡，写起来像调用本地方法。异步消息通知则用 RabbitMQ，比如学生提交工单后，工单服务把“新工单事件”发到交换机，消息服务消费后给维修工推送通知，避免同步阻塞主流程。

2.3 前端 Vue 与小程序的双端设计

管理端和后端运维界面用 Vue 2 + Element-UI，这个组合胜在稳定，组件齐全，适合快速搭建表格、表单、弹窗类界面。如果你新开项目，也可以选 Vue 3 + Element Plus，但要注意生态差异。我的管理端只包含派单台、工单列表、用户管理、维修项配置、统计图表五个页面，所以用 Vue 2 完全够用。

小程序端不用原生，而是用 uni-app 编写后编译到微信小程序，好处是一套 Vue 语法同时管多端，以后要上支付宝小程序也能直接编译。但要注意 uni-app 对 Vuex 的集成和原生小程序的差异。实测下来，页面列表、登录态、表单提交、上传图片、获取手机号这些核心功能都能覆盖，只是有些原生组件如 map、video 在编译后略有差异，需要单独配置。

双端共用一套后端接口，但权限体系完全不同。小程序端只暴露学生和维修工的使用接口，管理端的敏感接口则必须通过网关校验管理员角色，这样即使接口路径被猜到，普通用户也无法访问。

2.4 为什么不用单体内嵌模块

有人会问：这几个服务加起来也没多复杂，为什么不干脆做一个单体模块划分，大不了拆包部署。我的回答是：单体拆包部署还是会共享数据库，一但某个表结构的变化影响多个模块，比如工单表改了字段，用户服务和消息服务都要跟着动，这就失去了独立演进的能力。

做这个项目的场景是学习和演示，微服务本身带来的多模块并行开发、独立测试、独立部署节奏，价值比“技术复杂度本身”更有意义。你才有机会在项目答辩或面试时讲清楚：服务如何注册发现、如何配置共享、如何统一鉴权，它们各自解决什么问题。如果全写在一个模块里，这些故事没法讲。

3. 关键模块实现与核心细节

3.1 报修工单的状态机设计

工单是这套系统的灵魂，所以状态流转我花了最多心思。

我设计了七个状态：待派单、待接单、维修中、待确认、已完成、已取消、已关闭。状态字段用 tinyint 存储，并在代码里用枚举类定义，绝不散落魔法数字。关键的流转规则如下：

• 待派单状态下，管理员才能执行派单；维修工不能自行抢单。
• 待接单状态下，维修工可以接单；如果设置了自动派单，则系统在派单后自动匹配维修工。
• 维修中状态下，只有维修工可以回单，回单必须填写维修结果和耗材。
• 待确认状态下，学生可以确认完成或发起二次报修。
• 已取消可以由学生主动取消，但限定时在待派单和待接单阶段；已关闭则由系统或管理员在超过72小时未处理后执行。

这里有一个值得注意的设计：状态流转不是光改字段，而是要写入操作记录表。也就是说，每当工单状态变化，repair_log表都插入一条记录，包括前状态、后状态、操作人 id、操作时间。这个表在后期做统计和追溯时非常关键，也能应对答辩时“如何保证历史问题可查”的提问。

3.2 分布式事务与数据一致性

微服务下最烧心的问题是分布式事务。先说结论：我最终没有引入 Seata，而是用“本地消息表 + 最大努力通知”来解决。

比如创建工单时，需要同时向 repair-service 插入工单主表，向 message-service 发一条站内信。如果强一致地同时写入两个库，就必须使用分布式事务方案，成本高且性能损失明显。对于报修场景，站内信晚几秒、甚至失败重试已经满足业务需求。所以我的做法是：

1. 在 repair-service 里创建工单，同时插入一条outbox_message本地消息表，状态为 pending。
2. 通过一个定时任务扫描 outbox 表中 pending 的记录，调用 message-service 的接口推送消息。
3. 推送成功后把 outbox 状态改为 done；推送失败则重试，超过重试次数则触发人工告警。

这样做的体验是：学生提交工单后，通知可能慢两三秒，但绝不会因为通知服务宕机导致工单创建失败。类似的思路可以覆盖大多数非资金、非库存类业务，是微服务中最实用的妥协方案。

如果一定要强一致，比如要求“派单时必须同时锁定维修工时间表”，那才需要 Seata 的 AT 模式。那种场景我只能说，要谨慎测试回滚逻辑，否则不如把两个操作合到同一个服务的一个事务里。

3.3 文件上传与消息通知

报修单里学生上传的照片是必要信息，维修工上门前至少能通过照片判断大概问题。我一开始把图片上传放在 repair-service 服务内部，后来发现不好：如果未来图片处理逻辑改了，或需要接入对象存储，动工单服务就会引发不必要的重启。所以我把上传能力独立成一个简单的文件操作接口，放在 system-service 里，实际存储改用了本机 MinIO。

MinIO 是兼容 S3 协议的对象存储，部署简单，学生上传图片后返回一个 URL，前端直接拼接域名展示。需要注意：上传接口必须做大小和格式限制，不能裸奔，否则攻击者会上传恶意文件。我的限制是单张 5MB，类型只允许 jpg、png、webp，并且文件名用 UUID 重命名，保留扩展名。回传图片时，后台会读取文件头再做一次校验，而不是只看文件扩展名。

消息通知这里，我用的是站内信 + 微信订阅消息双轨。站内信存库，小程序端通过轮询和 websocket 两种方式获取未读数量。微信订阅消息需要用户授权，而且有一次性模板的限制，只能用于“接单通知”“完成通知”这类关键节点，不能频繁发。实测下来，对用户体验最好的还是站内信列表 + 首屏未读铃铛角标，订阅消息作为补充。因为小程序端要申请订阅消息模板，审核较慢，而且模板关键词必须和官方库一致，这点要提前规划。

3.4 权限与登录态设计

权限这块用的是经典的 RBAC：用户 -> 角色 -> 菜单/权限点。后端没有在每个服务重复实现认证，而是把认证集中在 system-service，网关统一鉴权。

具体跑通的方案是：用户登录后，后端发放 JWT token，token 里带上 userId、角色列表、过期时间。前端每次请求把 token 放在 Authorization 头里。网关配置全局过滤器，先解析 token，再把用户信息放在请求头传给下游服务。下游服务从请求头拿用户 id，不重复解析 JWT。

这里有一个容易踩的坑：Spring Cloud Gateway 是基于 WebFlux 的，很多过滤器处理逻辑和传统 Spring MVC 不一样。比如你想在网关里读取请求体，就需要使用DataBuffer相关的 API，不能像 Servlet 里那样简单request.getInputStream()。我的建议是尽量别在网关层读请求体，只校验 header 和路径权限，把需要读体的操作放在业务服务内部完成。

小程序端的登录态又和 JWT 有一点区别。微信小程序需要先调用wx.login获取 code，后端拿着 code 再向微信接口换取 openid。我设计的是：openid 绑定到 user 表，首次登录时自动创建账号，后续直接返回自定义 JWT。这样学生打开小程序后无需输入账号密码，体验顺畅，也省去了复杂密码找回逻辑。

4. 从零搭建的实操过程与避坑记录

4.1 环境准备与项目骨架生成

整套东西我用的是 JDK 8、Maven 3.8、Spring Boot 2.7.x，Spring Cloud 用的是 2021.0.x 版本，Nacos 2.2.0。这个组合踩坑最少，网上的案例也最丰富。

如果你现在从零开始，建议按照这个顺序搭建：

1. 先创建父 Maven 工程，只放依赖管理和公共配置，不放业务代码。
2. 把 Nacos 跑起来，确认控制台能注册服务。
3. 创建第一个 system-service，先不做业务，只做健康检查和注册发现。
4. 依次创建 gateway、dormitory-service、repair-service、message-service、statistics-service，每次先把服务注册到 Nacos 成功再写业务。
5. 最后再搞前端和管理端页面。

这个顺序能避免“一堆服务同时出错没法定位”的局面。我第一次做的时候图快，一次性建了五个模块，结果启动后每个服务都报连接注册失败，排查了半天才意识到是 Nacos 地址写错了公共配置文件。有了基础骨架，再逐步加业务，心里会有底得多。

4.2 服务间调用与链路排错

服务间调用的报错日志往往很糊弄人，比如 OpenFeign 默认超时时间是 1 秒，一旦某个服务慢一点就报。实际排查的时候，我的经验是分三步：

先看 Nacos 控制台服务列表，确认调用方和被调方的实例是否都在线，如果某个服务下线了，报错就是java.net.UnknownHostException或connection refused。再看两端日志，重点看是否有序列化异常。Feign 默认用 Jackson 序列化，如果返回对象里有多级嵌套泛型或 LocalDateTime，非常容易出现反序列化错误。我遇到的经典问题是LocalDateTime反序列化报错，需要全局配置Jackson的 JavaTimeModule 和日期格式。最后再看超时配置，把连接超时设为 3 秒，读取超时设为 10 秒，基本能覆盖多数接口。

另外一定要给服务间调用加链路跟踪，我用了 Sleuth + Zipkin。因为微服务下跨服务的调用链拉长，没有 trace id 很难查一次完整请求到底在哪个循环里出了问题。Zipkin 的部署也不复杂，开一个 docker 容器，服务配置好地址就能自动上报。如果你项目里只有一个服务器，也可以不做 UI，只在日志里打印 traceId，再用 grep 串起链路，不过体验差很多。

4.3 小程序端对接的常见坑

小程序端最折磨人的是网络请求封装和本地缓存。

微信小程序原生wx.request不像浏览器那样会自动携带 Cookie，所以 token 必须手动放在Authorization头里。我写了一个 request 工具类，统一在 header 里注入 token，并在收到 401 响应时跳转到登录页。这里有一个细节：wx.request的success回调只要网络请求成功就会执行，并不代表业务成功，所以后端必须统一返回结构体{code, message, data}，前端根据 code 判断业务，否则很容易出现“请求成功但数据为空”的假象。

另一个坑是图片上传。wx.uploadFile的路径参数和wx.request不一样，它提交的是multipart/form-data，后端接口要处理好文件流。我测试时发现，如果前端header里手动设置了Content-Type，会导致上传失败，因为框架已经自动加了 boundary，正确做法是不要手动设置这个请求头。

小程序不同机型的顶部状态栏高度不一致，我做自定义导航栏时直接用wx.getSystemInfoSync()拿状态栏高度，再根据胶囊按钮位置计算导航栏高度。这个代码在网上有现成的实现，但要注意它可能拿到 0，需要做 fallback。我的做法是缓存到全局，避免每次页面加载都调用一次，因为实测某些安卓机型调用频繁会延迟。

4.4 部署时的资源与内存问题

微服务跑在一台 2 核 4G 的服务器上，最大的问题是内存不够。六个 Java 服务加 Nacos、MySQL、Redis、MinIO，随便启动一下就是 2G 多，毕业设计和演示场景往往没有多余机器。

我的部署策略是：基础中间件 MySQL、Redis、Nacos、MinIO 全都用 Docker 部署，Java 服务则打成 jar 包用 systemd 托管，不盲目上 k8s。每个 Java 服务的 JVM 参数我都限制了-Xms256m -Xmx512m，网关和 system-service 设置稍高一点。这样整套系统内存占用稳定在 3.2G 左右，4G 服务器勉强能跑，但要保持空闲内存至少 500M，否则 OOM 风险很高。

另一个重点是让前端打包产物直接由后端托管。Vue 管理端npm run build后把dist目录复制到 gateway 的静态资源目录下，这样管理端页面和接口同源，省去跨域配置。小程序端不需要托管，直接通过微信开发者工具上传即可。注意如果让 Vue 产物放在 gateway，那么网关的跨域配置就不用放开，否则反而容易被绕过，造成安全隐患。

4.5 高版本依赖冲突的调整

Spring Boot 版本和 Spring Cloud 版本必须严格对应。我用 2.7.x 配 2021.0.x 没有问题，后来试过升级到 Spring Boot 3.0 配 Spring Cloud 2022.0.x，结果一堆老依赖不兼容，尤其是javax.*包变成jakarta.*，很多第三方库没跟上，直接放弃升级。

如果你也遇到NoSuchMethodError或ClassNotFoundException，大概率是版本错配。解决办法是去 Spring Cloud 官网查版本对应表，Maven 里用父 BOM 统一管理版本，不要手动指定每个依赖的版本号。我用的是 Spring Cloud 的spring-cloud-dependencies引入方式，这样只改父 BOM 就能升级全部子组件。

5. 测试联调与性能优化

5.1 接口测试与并发模拟

写完核心接口后，最好先整理一份接口文档，我用的是 Swagger 自动生成。每个服务引入springfox或springdoc都行，但要注意如果网关做了统一路由，Swagger 的访问路径可能因为服务前缀对不上而扫不到，需要配置server.servlet.context-path一致。

并发模拟我用 JMeter 测试了 “学生提交工单” 这个核心接口，线程数 100，循环 5 次，也就是 500 个请求。实测下来，没有做优化时平均响应时间在 900ms，数据库连接池用了默认的 HikariCP 10 个连接，还算稳定。但如果把循环数加大到 200，就会出现少量连接池等待超时，这时候需要把maximum-pool-size调到 20，并合理设置connection-timeout。

这里的启示是：微服务项目如果要被人挑毛病，性能是最好下手的地方。你要能说清楚每个服务的数据库连接池数量、超时时间、缓存策略，而不是只说“能跑通”。这些细节决定了一个项目是演示品还是工程品。

5.2 数据库索引与慢查询

工单表的查询频率很高，各种状态查询、按时间和楼栋筛选，所以索引设计不能乱。我在 repair 表建了(status, create_time)联合索引，因为最常见的查询是“某个状态下的工单列表”，按时间倒序展示。另一个高频查询是“学生查看我的报修”，用(student_id, create_time)索引。维修工查看待接单列表则用(assignee_id, status)索引。

慢查询排查我用 MySQL 自带的慢查询日志。有个实际问题：当报修数据量到十几万条后，按楼栋统计报表的 SQL 用了GROUP BY导致文件排序，非常慢。解决办法是不直接查业务表，而是定时任务把统计结果写入报表表，每天更新一次。因为校园报修统计根本不需要实时秒级数据，日更就够了，这是典型的用空间换时间。

5.3 缓存与消息队列的取舍

工单列表接口一开始并发高时响应慢，我加入了 Redis 缓存“维修工待接单列表”和“楼栋字典数据”。缓存策略是：维修工待接单列表在每次派单、接单时删除缓存，下次查询重建；楼栋字典数据改动频率极低，可以设置 24 小时过期兜底。

消息队列我这里主要用于“提交工单后通知维修工”和“超时工单提醒”。这两个场景对实时性要求都不高，RabbitMQ 的延迟队列正好合适。我用了 TTL + 死信队列的方式实现“超过 30 分钟未派单提醒管理员”，比手动定时扫描数据库更优雅。注意死信队列的配置稍微绕一点，如果 RabbitMQ 版本较老，可能不支持 TTL 动态设置，需要提前确认。

6. 常见问题与服务治理心得

6.1 常见问题速查表

这里整理我实际踩过的问题，按出现频率排序：

这些问题的共同特征是：你只要在某一个环境跑通，就能避免。关键是不要到答辩或演示前一天才首次联调，一定要尽早把环境联调跑起来。

6.2 个人心得：微服务不是银弹，但值得认真做一次

做完整套系统，我最大的体会是，微服务架构的真正复杂度不在于写代码，而在于面对“服务边界”和“数据一致性”时的取舍。报修业务恰好给了你足够的空间去体验这种复杂度：有两个以上的服务要协作，工单状态需要跨服务流转，通知服务可能挂掉但核心流程不能挂。这些问题是单体项目里遇不到的。

如果只想快速交差，这套系统做成单体确实一天就能写完核心流程，但那就损失了“从架构层面思考问题”的机会。我的建议是，哪怕你最后答辩时老师问“为什么要拆这么多服务”，你也可以坦率地说：这个业务规模确实不需要，但拆服务是为了让团队并行开发更快，让独立的服务可以独立迭代。不盲目崇拜微服务，也能把每个组件的作用讲明白，反而是更成熟的表达。

这项目做完后，你可以继续扩展的方向不少：接一个管理 App、做维修耗材库存管理、叠加 IoT 传感器自动上报故障、把统计报表接入大屏。骨架和核心流程已经定死，后续只要在相应服务里加业务即可。微服务架构这时候的好处才真正显现——你不用在旧代码里挖地三尺，只要在新服务里写你的新逻辑。