SpringBoot+Vue+MyBatis物业管理系统前后端分离实战

我前阵子给一个小区的物业公司做管理系统白天跑现场调研晚上回来写代码。当时他们还在用纸质台账登记业主信息和报修单查个记录翻半天催费基本靠打电话。做完这套前后端分离物业管理系统之后最直观的感受是很多所谓的“复杂业务”其实用经典技术栈就能解决得很好难点全在前后端如何顺畅协作、代码如何组织得让人半年后还能看懂。这套项目我完整跑通了从0到1的全过程包括编码、打包、部署到云服务器今天就把整个思路和技术细节掏出来给准备做前后端分离项目实战的朋友们一个直接能用的参考。这个项目用到的技术栈很主流SpringBoot Vue MyBatis MySQL后端负责业务逻辑和接口输出前端用Vue做页面交互通过RESTful API通信数据库用MySQL存业务数据。它适合的人群很广——刚学完框架想找个完整项目练手的初学者、正在冲刺毕业设计的在校生、或者公司需要一套轻量级管理后台做内部工具的开发人员都能从这套源码和部署流程里拿到东西。1. 小区物业管理系统的功能蓝图与整体架构设计做这类系统第一步绝不是急着写代码而是先把业务边界划清楚。物业管理系统听起来是个大概念但落到实际使用场景核心就几块业主信息管理、房屋档案管理、报修工单处理、物业费收缴记录、公告通知发布、停车位管理。我调研时发现绝大多数中小型物业公司的痛点集中在两个点一是业主信息散乱难以维护二是报修和催费流程靠人工很容易扯皮。所以设计时我花了大量时间在这两条主线上。1.1 角色权限模型系统的用户分三类超级管理员、物业工作人员、业主。权限控制上我用了经典的RBAC基于角色的访问控制模型后端通过JWT令牌识别用户身份前端配合Vue Router的路由守卫做页面级别的权限拦截。角色边界定义如下超级管理员拥有全部菜单权限包括用户管理、角色权限分配、系统日志查看物业工作人员可以处理报修工单、录入业主信息、发布公告、登记收费记录业主只能查看自己的房屋信息、提交报修申请、缴纳物业费、查看公告这里面有个经验权限模型千万别一开始就设计得太复杂。我见过不少项目上来就搞数据权限、字段级权限结果业务还没跑起来光权限就把自己绕晕了。先做菜单级和按钮级的控制等真有需求再加粒度够用就好。1.2 前后端分离的部署逻辑前后端分离最大的优势用一句话说清楚前端只管界面渲染和用户交互后端只管业务逻辑和数据存取两边互不干扰各自可以独立演进。这在整个项目开发过程中感知特别深。在实际部署时后端SpringBoot打包成jar包运行在服务器上提供RESTful API。前端Vue项目执行npm run build打包出静态资源文件放在Nginx的html目录下。后端接口统一以/api开头前端通过Nginx配置代理转发请求这样避开了跨域问题。整体结构如下浏览器 → Nginx接收静态资源请求 代理/api路径 → SpringBoot后端服务:8080 ↓ MySQL:3306这里有个新手经常掉坑的点直接用Vue项目开发时启用proxy代理但生产环境部署时忘了配置Nginx转发结果接口全挂在不同端口上一调用就报CORS错误。正确的做法就是上线时把接口请求集中到一个域名下由Nginx完成转发不要让浏览器直接去访问后端端口。2. 环境搭建与工程初始化版本冲突和配置陷阱写这个项目的时候环境问题其实占了我不少时间。很多初学者动不动就跑不起项目八成以上不是代码问题而是版本匹配问题。SpringBoot和Vue的生态更新很快版本割裂严重一个版本对不上就能折腾一晚上。2.1 版本选型与对应关系我这个项目最终确定下来的版本组合是被验证过稳定可跑的组件版本说明JDK1.8SpringBoot 2.7.x的兼容性最好SpringBoot2.7.14稳定版社区资料最多MyBatis3.5.x配合mybatis-spring-boot-starter 2.xMyBatis-Plus3.5.3.1分页插件和代码生成器很好用MySQL8.0.x生产环境推荐8.0性能更好Vue2.6.14配合Element UI 2.15.x最稳定Node.js16.20.x太新版本对老依赖兼容性差为什么要用MyBatis-Plus而不是纯MyBatis因为这套项目里有大量单表CRUD操作MyBatis-Plus的BaseMapper接口直接内置了selectPage、insert、updateById这些方法开发效率提升非常明显。分页时只要配置一个PaginationInnerInterceptor连SQL都不用手写它会自动帮我在SQL后面拼接LIMIT语句。2.2 后端工程结构初始化后端我用Maven搭建父子模块结构实际开发按业务模块分包更清晰property-system ├── src/main/java/com/property │ ├── controller # 控制层接收前端请求 │ ├── service # 业务层核心业务逻辑 │ ├── mapper # 数据访问层MyBatis接口 │ ├── entity # 实体类对应数据表 │ ├── common # 通用类Result封装、异常处理、工具类 │ └── config # 配置类拦截器、CORS、分页插件 ├── src/main/resources │ ├── mapper # MyBatis XML映射文件 │ ├── application.yml │ └── sql # 数据库初始化脚本 └── pom.xmlapplication.yml里最值得注意的配置是脱敏连接串和时区问题MySQL 8.0的驱动要求指定时区否则连接报错。我当时的配置如下server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/property?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8 mybatis-plus: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.property.entity configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImplmap-underscore-to-camel-case: true是我觉得最香的一个配置它让数据库里的下划线字段比如owner_name自动映射到Java实体类的驼峰属性ownerName少写大量映射代码。2.3 Vue前端项目的初始化前端用Vue CLI脚手架创建项目这里我踩过最深的坑是npm安装依赖时版本兼容问题。如果用最新版Node.js直接创建Vue 2项目一跑npm run serve就报错digital envelope routines::unsupported。这是Node 17以上版本OpenSSL的变化导致的解决办法是在package.json里加一行启动参数scripts: { serve: set NODE_OPTIONS--openssl-legacy-provider vue-cli-service serve, build: set NODE_OPTIONS--openssl-legacy-provider vue-cli-service build }Mac或Linux系统把set换成export。这个问题很典型但网上搜到的答案往往很零散我就栽过一次。前端结构里我按功能模块划分了views并且用Vue Router路由懒加载的方式配置{ path: /owner, name: Owner, component: () import(../views/property/OwnerList.vue), meta: { title: 业主管理, roles: [ADMIN, STAFF] } }同时封装了一个axios实例统一处理请求头里带token对响应做统一拦截处理。这一步非常重要不然每个页面都要重复写token注入和错误状态处理代码项目一大会乱成一锅粥。3. 后端核心业务实现从JWT认证到报修工单闭环后端是整个系统的中枢业务逻辑占了主体。我按用户认证、核心CRUD、复杂业务三个层面逐步实现每块都积累了不少实战经验。3.1 JWT认证机制与拦截器设计物业系统虽然不算高安全等级要求但也不能裸奔。我选用了JWT做无状态认证逻辑链路是用户提交用户名密码后端校验通过后生成tokentoken里封装用户id和角色信息前端拿到token后存储在localStorage每次请求在请求头加Authorization: Bearer token后端定义JwtInterceptor拦截器对所有/api/**请求进行token校验核心代码如下这段代码当时反复优化了几次Component public class JwtInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 放行登录接口和静态资源 if (request.getRequestURI().contains(/api/auth/login)) { return true; } String token request.getHeader(Authorization); if (token null || !token.startsWith(Bearer )) { throw new BusinessException(未登录或token已过期); } // 解析token并存入request域方便后续获取当前用户 Claims claims JwtUtil.parseToken(token.replace(Bearer , )); request.setAttribute(userId, claims.get(userId)); request.setAttribute(role, claims.get(role)); return true; } }有一点要提醒开发调试时一定要记得在WebMvcConfig里注册拦截器并配置排除路径。我一开始只写了拦截器类忘了注册结果所有请求都放行了token校验形同虚设排查了半天才发现。3.2 业主信息管理与条件查询业主管理模块是典型的CRUD但实际做的时候有几个细节值得注意模糊查询姓名、手机号支持关键字模糊搜索用MyBatis的if标签动态拼接SQL关联查询业主和房屋是一对多的关系列表页需要连表查出房产信息分页调用MyBatis-Plus的分页插件统一用PageT对象接收这里贴一段实际使用的Mapper XML动态SQL部分很有代表性select idselectOwnerPage resultTypecom.property.entity.OwnerVO SELECT o.*, h.building_no, h.unit_no, h.room_no FROM owner o LEFT JOIN house h ON o.house_id h.id where if testkeyword ! null and keyword ! AND (o.owner_name LIKE CONCAT(%, #{keyword}, %) OR o.phone LIKE CONCAT(%, #{keyword}, %)) /if if testbuildingNo ! null and buildingNo ! AND h.building_no #{buildingNo} /if /where ORDER BY o.create_time DESC /select动态SQL的where标签会自动处理多余的AND写的时候不用太担心条件的拼接这是MyBatis非常实用的特性。3.3 报修工单状态机与事务处理报修流程是我在整个系统里比较得意的一块设计它模拟了一个简单的状态机业主提交报修申请状态变为待受理物业人员接单状态变为处理中维修完成物业人员上传处理结果状态变为已完成业主确认无误状态变为已确认这个流程不复杂但状态流转的校验要注意。比如只允许业主在“待受理”状态取消报修物业人员只能在“待受理”和“处理中”状态修改处理结果。我在Service层写了一个状态校验方法private void checkStatus(RepairOrder order, String expectedStatus) { if (!expectedStatus.equals(order.getStatus())) { throw new BusinessException(当前状态不允许执行该操作); } }在维修人员确认完成时我同时要更新维修记录表和工单表这时候加Transactional事务注解就很有必要。我曾经因为没有加事务测试时模拟了一次中途异常情况维修记录写进库了但工单状态没更新数据当场就不一致了。这个小问题如果没发现正式上线后会产生很严重的用户反馈问题维修师傅干完活系统显示还是待处理得亏是测试阶段暴露出来的。4. Vue前端业务开发与接口联调从页面到交互前端工作量其实占比不小尤其是表单交互、表格展示、状态提示这些看似简单但非常消耗时间的部分。4.1 页面路由与主框架布局主框架我用经典的左右布局左侧菜单栏放系统功能右侧是内容区域顶部是用户信息和面包屑导航。这套布局用Element UI的Container布局组件就能快速实现。菜单项根据用户角色动态渲染这里用到了路由表里配置的meta.roles字段。Vue Router的beforeEach守卫做了这样的处理router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (!token to.path ! /login) { next(/login) return } const userInfo JSON.parse(localStorage.getItem(userInfo)) if (to.meta.roles userInfo !to.meta.roles.includes(userInfo.role)) { next(/403) return } next() })做法通俗易懂而且对不熟悉前端权限控制的人来说这个方案最好理解。4.2 核心页面实现报修工单的列表与弹窗报修工单页面是整个前端最复杂的页面之一它包含表格展示、筛选条件、状态交互、弹窗表单可以说麻雀虽小五脏俱全。列表页我直接用了Element UI的el-table配合el-dialog实现。表格部分关键点el-table :datatableData v-loadingloading el-table-column proprepairNo label工单编号 width180 / el-table-column propownerName label报修人 width100 / el-table-column proptitle label报修标题 min-width150 / el-table-column propstatus label状态 width120 template slot-scopescope el-tag :typestatusTypeMap[scope.row.status] {{ statusTextMap[scope.row.status] }} /el-tag /template /el-table-column el-table-column label操作 width220 fixedright template slot-scopescope el-button typetext clickhandleDetail(scope.row)详情/el-button el-button v-ifcanOperate(scope.row) typetext clickhandleProcess(scope.row)处理/el-button /template /el-table-column /el-table状态标签用映射对象控制避免在模板里写大量判断后续维护只需要改映射表。4.3 Axios统一封装与状态码处理前端所有接口都走封装好的request.js统一做了三件事注入token、统一处理业务状态码、统一弹出错误提示。这样接口层异常逻辑不用每个页面都重复写。import axios from axios import { Message } from element-ui const service axios.create({ baseURL: /api, timeout: 10000 }) service.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers[Authorization] Bearer token } return config }) service.interceptors.response.use( response { const res response.data if (res.code ! 200) { Message.error(res.msg || 请求失败) if (res.code 401) { localStorage.removeItem(token) location.href /login } return Promise.reject(new Error(res.msg)) } return res }, error { Message.error(error.message || 网络异常) return Promise.reject(error) } )这里有个前端开发的小经验后端返回的统一Result结构一定要用JSON对象包业务数据让code、msg、data三层结构固定好前后端联调时不需要看接口文档也能猜到数据格式。我见过很多项目后端直接返回一堆零散字段前端拿到后还要猜含义沟通成本特别高。5. 打包部署全流程从本地开发到服务器上线开发完的代码如果不能顺利部署到服务器跑起来这个项目在实战意义上就是不完整的。这一节我把从打包到上线的完整链路走一遍顺便讲讲我在真实部署过程中遇到的各种问题。5.1 后端打包与jar运行后端打包很简单在Maven面板执行clean和package命令生成target/property-system-0.0.1-SNAPSHOT.jar。部署到服务器上直接运行java -jar property-system.jar --spring.profiles.activeprod但真正跑生产环境光用裸java命令跑jar包是不够的进程管理、日志收集都需要处理。我用了Linux的systemd服务管理配置一个property.service文件[Unit] DescriptionProperty System Service Afternetwork.target [Service] Typesimple Userroot ExecStart/usr/local/java/jdk1.8.0_202/bin/java -Xms256m -Xmx512m -jar /opt/property/property-system.jar SuccessExitStatus143 [Install] WantedBymulti-user.target配置好后执行systemctl start property和systemctl enable property这样开机自启、崩了自动重启都不用管。不要小看这一步用systemd管理进程可比nohup重定向日志优雅太多日志直接journalctl就能看。5.2 前端打包与Nginx配置前端执行npm run build后dist目录下就是打包好的静态文件。把这些文件上传到服务器的/usr/share/nginx/html/property目录下然后修改Nginx配置server { listen 80; server_name property.example.com; location / { root /usr/share/nginx/html/property; index index.html; # 关键配置前端路由history模式需要所有路径都指向index.html try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }try_files $uri $uri/ /index.html这一行是我当年踩过的重点坑之一。如果不写这行前端用了Vue Router的history模式用户刷新页面比如刷新/owner/list这个路由Nginx会尝试去找对应的静态路径结果返回404而实际上这个路径是前端路由而已。这段配置的注释值得保留。proxy_pass http://127.0.0.1:8080/;末尾的/也很有讲究它表示把URL中的/api前缀去掉后再转发给后端这样后端接口定义就不用担心会被代理加一层前缀了。5.3 MySQL初始化与数据备份数据库方面我准备了初始化SQL脚本包含建库、建表、初始数据导入。首次部署在服务器上执行mysql -u root -p init.sql脚本里包含所有表的建表语句、默认管理员账号密码用BCrypt加密过的、基础数据字典。项目运行前先跑通这部分往往能省不少排查时间。生产环境数据备份我写了一个简单的cron定时任务每天凌晨自动mysqldump备份0 2 * * * mysqldump -u root -p123456 property /backup/property_$(date \%Y\%m\%d).sql对于物业系统这种数据量不太大的系统这个方案简单可靠低成本的保障比花大价钱引入复杂中间件可靠得多。6. 实际开发中的高频问题与排查思路最后这部分把我在整个开发部署过程中遇到的高频问题单独拿出来聊。之所以单独写一节是因为这类问题的解决思路很有代表性在别的项目中也很容易复用。6.1 MyBatis分页失效的问题MyBatis-Plus的分页插件如果配置不当会出现分页不生效的情况。我当时遇到的情况是Page参数传了但SQL执行出来还是全量数据。排查后发现问题出在拦截器没有加载到MyBatis-Plus的配置类中这是我的疏漏。正确的做法是单独在配置类里创建MybatisPlusInterceptor并加分页插件Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }还有一个细节自己手写了连表查询的selectPage时返回类型必须是IPageT而不是ListT不然MyBatis-Plus的分页语义会乱。这个坑需要认真检查SQL才找得到因为编译和运行都不会报错就是返回结果不符合预期。6.2 跨域调试与线上跨域配置本地联调阶段前端跑在localhost:8081后端跑在localhost:8080跨域是家常便饭。解决方式有两种开发环境用Vue CLI的proxy代理生产环境用Nginx转发。我强烈建议不要用后端开启CORS全局配置的方式来解决因为一旦上线后有了真实域名CORS配置会变成安全隐患。开发环境的vue.config.js配置如下module.exports { devServer: { port: 8081, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }这样开发时前端请求/api/owner/list代理会自动转发到localhost:8080且浏览器看到的请求是同源的完全不会有跨域报错。6.3 慢SQL与性能优化物业系统在数据量小的时候性能问题不明显但碰到小区有几千户业主再加上维修记录、缴费记录增长慢SQL问题就出来了。我用两种手段做了优化一是为高频查询字段添加索引。业主表里phone字段和房屋表的building_no/unit_no/room_no组合字段报修表的status字段都加了索引。加完索引后查询性能明显提升。二是开启MyBatis-Plus的SQL日志定位慢查询。在application.yml配置里加log-impl: org.apache.ibatis.logging.stdout.StdOutImpl控制台会打印每条SQL的执行时间。我曾经找到一个耗时1.2秒的查询加个LEFT JOIN条件后直接降到30毫秒。经验是在表的数据量还没上来的时候就应该把索引设计好别等到数据量大了再补。不过也不要一开始堆大量索引每个索引都有写入成本优先覆盖最主要的两三个查询场景就够了。6.4 前后端联调时接口字段名不一致前后端联调最容易出现的问题是我这里返回ownerName前端却拿owner_name取值结果列表一列全是空。为了避免这种问题我采用了一种简单有效的方式后端定义清晰统一的VO对象所有返回数据在前端直接用驼峰命名取数据库字段转驼峰统一由MyBatis的配置来处理。这样前后端协同时只依赖VO对象的字段定义而不依赖数据库表结构沟通效率高很多。如果两个团队配合开发更规范的做法是后端用Swagger或apifox自动生成接口文档前端直接看文档联调。我这次是一个人全栈开发所以省掉了这步但换来的是对每一步的深刻掌握。7. 部署上线后的体会与扩展方向系统交付之后物业公司实际用了两周反馈比我预期的要好。报修工单流转确实解决了他们之前电话记录丢失、处理进度不透明的问题物业费模块也让他们月底对账的工作量小了不少。从个人收获来说这套项目最大的价值在于帮我把SpringBoot、Vue、MyBatis这些知识点真正串了起来。以前写Demo每个框架都是零散地学真正做一个完整的全栈项目才发现知识点的串联和融会贯通才是有难度的环节。比如前端传参格式如何匹配后端RequestBody的实体类后端返回数据如何适配前端表格渲染这些细节如果不做完整项目永远想不到。如果后续要在这个系统上继续扩展我建议可以往这几个方向走一是引入Redis缓存业主信息和热点公告提升接口响应速度二是增加小区车辆通行记录和门禁联动逻辑打通智能硬件的API三是把缴费模块和微信支付对接减少业主跑物业办公室的次数。这些都是现在市面上商业物业软件在做的功能技术上也都是基于这套基础架构做延伸并不难实现。但核心还是先跑通一套基础可用、结构清晰的系统再做增量演进。希望这份完整的实战记录能让打算做前后端分离项目的朋友少走几个弯路。