做这个基于SpringBoot+Vue的综合小区管理系统，前后花了差不多两个月。选题阶段目标就很明确：这类系统要覆盖业主信息、物业费、报修、车位这些高频业务，后端用SpringBoot整合MyBatis操作MySQL，前端用Vue做界面，既能把全栈开发思路走通，又不会为了炫技把架构搞复杂。项目做完之后再回头看，技术栈的选择、表结构的设计、前后端联调的细节，踩了不少坑也攒了不少经验。这篇文章就把整个设计和实现过程完整拆一遍，对正在做毕业设计、或者刚接触前后端分离项目的同学，应该能省下不少摸索时间。
1. 整体设计与技术选型思路拆解
1.1 为什么用前后端分离而不是传统单体
小区管理系统本质上是一个典型的CRUD密集型业务系统：管理人员要维护业主档案，财务要处理物业费账单，维修人员要接报修单，业主端要看公告、查账单。这种交互密集、页面多的系统，传统JSP+Servlet单体模式虽然也能做，但到后期改一个页面要重新编译重启，联调效率非常低。
前后端分离的核心价值在于职责边界清晰：后端只用SpringBoot提供RESTful接口，处理业务逻辑和数据库交互；前端用Vue负责渲染和数据展示。两边通过JSON格式的数据做交互，互不干扰。具体到这个项目里，我前后端是同步开发的，后端用Postman测接口，前端用mock数据先画页面，到最后联调阶段对接起来几乎没有返工。如果按传统模式，前端页面必须等后端模板渲染出来才能动工，开发周期至少多出一半。
另外一点，前后端分离对部署也自由。开发环境下前后端各跑各的端口，生产环境把前端build出来的静态文件交给Nginx托管，后端接口单独跑一个端口，哪边出了问题都好排查。
1.2 SpringBoot + MyBatis + MySQL的组合逻辑
选SpringBoot没什么好纠结的，现在Java后端开发的绝对主流，约定大于配置，内嵌Tomcat打成jar包就能跑，非常适合做管理系统这类单体应用。
数据库选MySQL也是常规操作，免费、成熟、文档多，小区管理系统的数据量撑死几十万条记录，MySQL完全够用。
真正值得聊的是持久层框架为什么选MyBatis而不是MyBatis-Plus或者Spring Data JPA。我的理由有三个：
第一，MyBatis的SQL是自己写的，Control感强。物业费按月份、按楼栋统计这种复杂查询，直接手写SQL，关联查询、分组统计、子查询都明明白白，出问题能定位到具体SQL，而不像JPA那样要反推生成的SQL。
第二，MyBatis对动态SQL的支持是一绝。小区管理系统的查询条件变化多端——按状态、按时间段、按关键字模糊搜索，用<where>、<if>标签组合条件非常灵活，比JPA的Specification少写很多样板代码。
第三，MyBatis入门成本低。实体类、Mapper接口、XML映射文件三者对应关系清晰，Java基础不深的同学也能很快上手。
至于MyBatis-Plus，它确实能省掉大量单表CRUD的XML配置，但做这个项目我是有意用原生MyBatis，把SQL基础打牢。实际开发中很多公司还在大量使用原生MyBatis，这一点工作经验也会更认可。
1.3 系统核心模块切分
小区管理系统的业务域并不复杂，关键在于覆盖全面。我最终拆成六大模块：
- 系统管理：用户、角色、菜单权限
- 业主管理：业主档案、房屋信息、家庭成员
- 物业收费：物业费单价设置、账单生成、缴费记录
- 报修管理：业主申报、人员派单、维修结果反馈
- 车位管理：车位分配、车位费用
- 公告管理：通知发布、业主可见
模块划分的原则是"低耦合、高内聚"。比如报修和缴费是两条独立链路，就不要混在一起；但是报修单和业主、房屋之间又有强关联，需要通过外键关联查询。把模块边界定清楚，后面的表结构设计和接口分工才能顺理成章。
2. 数据库设计实操：表结构、权限与核心业务逻辑
2.1 核心数据表建模过程
数据库设计是整个项目的地基。我第一版设计图省事，把业主和房屋信息放一张表里，结果后面发现一个人名下多套房的情况根本没法处理，又推倒重来。最终的结构是房屋表独立出来，跟业主表分开，通过owner_id关联。
核心表大概长这样：
| 表名 | 作用 | 关键字段 |
|---|---|---|
| sys_user | 系统登录用户 | id, username, password, role_id |
| sys_role | 角色表 | id, role_code, role_name |
| sys_menu | 菜单权限表 | id, parent_id, menu_name, path, perms |
| sys_user_role | 用户角色关联 | user_id, role_id |
| house | 房屋档案 | id, building_no, unit_no, room_no, area, owner_id |
| owner | 业主档案 | id, name, id_card, phone, gender |
| property_fee | 物业账单 | id, owner_id, house_id, period, amount, status, paid_time |
| repair_order | 报修单 | id, owner_id, description, assignee, status, create_time |
| parking_space | 车位 | id, space_no, type, holder_id, monthly_fee, status |
| notice | 小区公告 | id, title, content, publish_time, publisher |
有几个设计细节值得提出来。第一，业主和房屋是1对多的关系，也就是一个业主名下可以有多个房产，这在实际小区场景里非常常见。第二，物业费和房屋强绑定，账单生成时要记录house_id，这样就能支持按房屋维度查账、催费。第三，所有表都保留一个status字段，用来做逻辑删除或者业务状态流转，不要直接物理删除数据，后面查账查历史记录都靠它。
2.2 角色权限模型怎么落地：RBAC方案
小区管理系统里有管理员、物业人员、业主三种角色，权限控制必须做，但不能做得太重。我采用经典的RBAC模型，五张表搞定：用户表、角色表、用户角色关联表、菜单表、角色菜单关联表。
一个用户所属角色决定了他能访问哪些菜单、操作哪些功能。后端在登录成功时返回属于这个用户的菜单列表和权限标识，前端根据权限标识控制按钮是否显示，比如业主没有"生成物业费账单"这个按钮，物业人员看不到系统管理菜单。
后端权限拦截我是用Spring的HandlerInterceptor实现的，写一个Interceptor注册进去，针对/api/admin/**这类管理接口做校验。实际项目比这复杂，会引入Spring Security或者Shiro，但我这里刻意控制复杂度，把核心权限逻辑放在前端路由控制和后端拦截器两层，够用且容易看懂。
2.3 物业费生成逻辑的设计与实现
物业费是系统里最核心的业务逻辑，也是面试时最容易聊的点。收费规则其实不复杂：单价的平方数乘以房屋面积，得到一个月的物业费，一次性生成一个季度或者一年的账单。但实现上一定要考虑几个边界情况：
- 房屋空置怎么办？一般是按空置标准打折，需要一个空置起止时间记录
- 业主中途入住怎么算？按入住月份开始计费，不是从年初算
- 逾期缴费要不要收违约金？要，每天按应缴金额的万分之五加收
生成账单的代码我放在Service层，核心逻辑是查出所有状态为"正常"的房屋列表，遍历生成账单记录。批量生成时一定要控制事务，要么全部生成成功，要么全部回滚。用一个@Transactional注解解决问题。
生成逻辑的关键SQL大概是这样：
INSERT INTO property_fee (owner_id, house_id, period, amount, status, create_time) SELECT h.owner_id, h.id, CONCAT('2025-01'), ROUND(h.area * #{unitPrice}, 2), 'UNPAID', NOW() FROM house h WHERE h.status = 'NORMAL'这条SQL一次完成批量生成，比在Java里循环insert高效得多，也是MyBatis少写代码的典型场景。账单状态用枚举值：UNPAID、PAID、OVERDUE，方便前端做状态色彩区分。
3. 后端SpringBoot核心实现：从接口到持久层
3.1 项目分层与代码结构
后端工程我严格按照Controller、Service、Mapper三层来写。Controller只做参数接收和结果包装，Service层写业务逻辑，Mapper层只做SQL交互。分层清晰的好处后面会体现得很明显：加需求的时候只管Service一层，改SQL只管Mapper一层，不会到处翻代码。
我的包结构是这样的：
com.community.system ├── controller // 接收请求，返回结果 ├── service // 业务逻辑层 │ └── impl ├── mapper // MyBatis Mapper接口 ├── model │ ├── entity // 实体类 │ ├── dto // 请求参数对象 │ └── vo // 返回结果对象 ├── config // 配置类，如跨域、拦截器 ├── common // 通用类，统一返回结果Result └── utils // 工具类，如JWT工具统一返回结果是必做的第一步。每个接口都返回一个Result对象，包含code、message、data三个字段，前端axios根据code判断请求是否成功。这个类一定要先写，不然几十个接口返回格式不一致，前端联调起来会想骂人。
3.2 核心接口设计与编写思路
接口设计遵循RESTful风格，资源名词用复数，操作通过HTTP方法区分。以业主接口为例：
| 接口 | 方法 | 说明 |
|---|---|---|
| /api/owner/page | GET | 分页查询业主列表 |
| /api/owner/{id} | GET | 查询单个业主 |
| /api/owner | POST | 新增业主 |
| /api/owner/{id} | PUT | 修改业主信息 |
| /api/owner/{id} | DELETE | 删除业主 |
分页查询用MyBatis的PageHelper插件还是自己写limit？我选了PageHelper，一行代码搞定分页，不用每写一个查询就手动算offset。唯一要注意的是PageHelper的线程安全问题，它用的是ThreadLocal存分页参数，所以startPage方法必须紧跟查询语句，中间不能夹别的SQL。
登录接口我重点说一下。用户登录成功后生成一个JWT令牌返回给前端，前端后续请求都带着这个token，后端用拦截器解析token获取用户身份。JWT的好处是服务端无状态，不用把session存在内存里，分布式部署也不受影响。
@Service public class AuthServiceImpl implements AuthService { @Override public Result login(LoginDTO loginDTO) { SysUser user = userMapper.findByUsername(loginDTO.getUsername()); if (user == null || !MD5Utils.encrypt(loginDTO.getPassword()).equals(user.getPassword())) { return Result.error("用户名或密码错误"); } String token = JwtUtils.generateToken(user.getId(), user.getRoleId()); return Result.success(token); } }密码必须加密存储，我用的MD5加盐。真实项目建议用BCrypt这种可调节强度的算法，MD5现在跑字典库已经太容易破解了。
3.3 MyBatis实战：三个必须注意的细节
第一，#{}和${}的区别一定要刻在脑子里。#{}是预编译，会生成占位符防止SQL注入；${}是字符串拼接，直接替换。排序字段、表名这种动态SQL场景会用到${}，但凡是用户输入的参数值，一律用#{}。
第二，动态查询用<where>标签而不是手动写WHERE 1=1。<where>标签会在条件成立时自动拼接WHERE，并且会去掉第一个多余的AND，避免出现SQL语法错误。我一开始图省事，直接在XML里写WHERE 1=1 AND name = #{name}，后面被同事指出来可读性和性能都有问题，现在全改成<where>。
第三，批量操作一定要考虑SQL大小。一次性插入几百条账单没问题，如果一次插入几万条，单个SQL可能超过MySQL的max_allowed_packet限制。稳妥的做法是分批插入，或者用MyBatis的<foreach>标签配合批处理Executor。小区管理系统一个季度的账单也就几千条，单条插入也能跑完，但性能上批量插入快非常多。
4. Vue前端实操：从环境配置到权限路由
4.1 开发环境与项目初始化
前端我用的Vue 2 + Element UI，组件生态最成熟。Vue 3的Composition API确实香，但Element UI对Vue 2支持更稳定，做管理后台这类中后台项目，Vue 2 + Element UI可以说是最省心的组合。如果你已经上手Vue 3，也可以用Element Plus，思路一样。
初始化项目直接用官方脚手架：
npm install -g @vue/cli vue create community-frontend npm install element-ui axios vue-routerNode版本这个坑要提前说一句。Vue CLI对Node版本有要求，太新的Node可能因为OpenSSL版本问题和Webpack不兼容。如果安装依赖或者运行dev服务时报错，多半是Node版本问题，建议用Node 16左右的LTS版本，省心很多。
项目目录结构我按功能模块组织，每个模块有一个独立的文件夹：
src ├── api // 每个模块的请求接口封装 ├── assets // 静态资源 ├── components // 公共组件 ├── router // 路由配置 ├── store // Vuex状态管理 ├── views // 页面组件 │ ├── owner // 业主管理页面 │ ├── fee // 物业费页面 │ ├── repair // 报修管理页面 │ └── login // 登录页面 └── utils // axios实例、工具函数4.2 axios封装与请求拦截器
前端开发里最容易出问题的是axios请求的统一管理。我封装了一个axios实例，配置了baseURL、超时时间和请求/响应拦截器。请求拦截器统一从localStorage里拿token，加到请求头的Authorization字段；响应拦截器统一判断code，登录过期自动跳转登录页。
const service = axios.create({ baseURL: '/api', timeout: 10000 }) service.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers['Authorization'] = token } return config }) service.interceptors.response.use( response => { if (response.data.code === 401) { router.push('/login') } return response.data }, error => { Message.error(error.message) return Promise.reject(error) } )这样做的好处是每个页面里调用接口只需要写一句ownerApi.page(params)，重复的header处理、错误提示都被拦截器兜住了。联调阶段少了一大半重复劳动。
4.3 动态路由与按钮级权限控制
这是前端最有分量的一个模块。不同角色登录后，看到的路由菜单不一样。管理员进系统管理页面，业主登录后只能看到查账单、提交报修的入口。我没用静态路由表，而是让后端登录接口返回可访问的菜单列表，前端在登录成功后用router.addRoutes动态添加路由。
思路是基准路由只保留登录页和404页面，其他业务路由全部动态注册。后端返回的菜单数据里包含了路由的path、name、component字段，前端根据path映射到具体的组件文件，然后用router.addRoute逐个注册。
路由守卫在每次跳转前检查token和用户信息，没有token一律踢回登录页。配置了权限的页面再检查角色是否有权限，没有权限跳403页面。这套组合拳做完，登录用户看不到自己没权限的功能模块，界面上按钮的v-if再根据权限标识做一次控制，前后端双重校验都闭环了。
4.4 Vue项目打包后如何部署到SpringBoot
开发环境下前端跑8080端口，后端跑8081端口，通过proxy代理把/api开头的请求转发到后端解决跨域。但上线部署是另一个问题。
这里有两个方案。方案一是前端打包后部署到Nginx，配置反向代理转发接口请求，也是生产环境的推荐姿势。方案二是个快速路子，把前端npm run build生成的dist目录直接复制到SpringBoot的src/main/resources/static目录，打包进同一个jar。这种方式适合个人项目或者演示环境，不用单独装Nginx，一个jar全部搞定。
第二个方案有个坑必须处理：Vue Router默认是history模式，部署后刷新页面会404，因为后端没有对应的路由映射。两种处理办法：要么改vue-router为hash模式，URL里会多一个#号，不美观但零配置；要么在后端加一个WebMvcConfigurer配置，把非接口的GET请求都转发到index.html。我个人推荐hash模式，省心稳定，管理系统不追求SEO，URL好不好看不重要。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
把项目过程中遇到的高频Bug整理成了一张表，都是你开发时大概率会碰到的。
| 问题现象 | 根因分析 | 解决方案 |
|---|---|---|
| 启动报Communications link failure | MySQL和SpringBoot时区不匹配 | JDBC URL加serverTimezone=Asia/Shanghai |
| 前端POST请求报CORS跨域错误 | 前后端不同端口没做处理 | 后端加CorsFilter，或前端配置proxy代理 |
| 中文数据乱码 | 数据库字符集不是utf8mb4 | 建库时指定utf8mb4，连接串加characterEncoding=utf8 |
| 动态查询条件不生效 | XML里写错where拼接 | 用<where>标签包住所有<if> |
| 返回的JSON里时间格式不对 | Jackson默认序列化格式导致 | 配置全局jackson格式化yyyy-MM-dd HH:mm:ss |
| history模式刷新404 | 前端路由与后端资源映射不一致 | 切换hash模式或配置转发 |
| 端口被占用启动失败 | 开发环境端口冲突 | 改端口，或kill占用进程 |
5.2 印象最深的三个坑
第一个坑是MySQL 8.0的时区问题。本地MySQL是8.x版本，SpringBoot项目启动连接数据库直接报错，排查半天发现是JDBC URL少了serverTimezone=Asia/Shanghai参数。这个错误如果你用云数据库或者低版本MySQL可能遇不到，但本地新装MySQL 8.0几乎是必踩的坑。所有新手的通病是报错只看最后一行，实际上要往上看Caused by那一串，真正的原因藏在Exception链的最深处。
第二个坑是Vue前端打包后接口400错误。开发环境一切正常，打包部署后用不了。最后发现问题是axios的baseURL写死了http://localhost:8081/api，打包后浏览器访问的是服务器IP，跨域又被拦截了。处理办法是把baseURL改成相对路径/api，通过Nginx或者后端统一转发。教训就是baseURL一定不要写死IP。
第三个坑是MyBatis的一对多映射。查询业主信息时，一个业主名下有多套房屋，需要用到collection标签。一开始没写对，导致同一个业主的信息被查重了多条记录，列表里一个业主出现好几行。用resultMap明确主表数据和子表的映射关系后才能正确合并。
6. 实操过程中的效率建议与经验总结
做一个这种规模的项目，我的体会有几点。第一，一定要先画数据库表结构图再动手写代码。我在这个项目里两次返回改表，一次是因为业主要支持多套房，一次是因为要加逻辑删除字段。每次改表都牵动实体类、Mapper、Service、前端页面一整条链路，代价非常大。哪怕只花半天时间把表关系理清楚，都比后期改来改去划算得多。
第二，接口文档和开发同步维护。我用的是Apifox这样的工具，接口一写完文档也自动生成了，前端照着文档调接口，省去大量口头沟通成本。如果是单兵作战，也要保持接口定义有固定的写法规范，参数名、返回结构都要统一。
第三，日志一定要打关键节点。加日志不是为了好看，是为了问题排查。登录、生成账单、支付回调这几个关键流程都要打日志，并且把业务ID带进日志里，方便出问题时通过ID定位整个链路。我在排查一个小区公告发布后用户端看不到的问题时，就是靠日志发现是缓存没有清理。
最后再说一个部署技巧：生产环境的数据库账号不要用root，单独建立一个只拥有该项目所有表权限的账号。这既是安全习惯，也能防止误操作drop掉别的库。这个项目做完之后，把它往自己的简历、作品集里写的时候，最值钱的部分不是代码量，而是对每个环节为什么这么做的理解，这些才是下次遇到类似项目真正能迁移的经验。
