SpringBoot+Vue社区平台实战：RBAC权限与JWT认证

做社区居民服务平台这个选题，很多做毕设或者练手项目的人第一反应都是：功能又多又杂，技术上似乎没什么“新东西”。但真正动手之后你会发现，它其实是一个特别完整的架构练习。SpringBoot负责后端接口和业务闭环，Vue负责前端页面和状态流转，两者拼起来，刚好把一套前后端分离的完整流程走了一遍。我这次用实际做这个项目的全过程，把整体设计、核心实现、部署上线以及踩过的坑整理出来，给正在做同类系统或者想练手社区类平台的朋友一个能直接参考的样板。

这个项目适合谁？一是正在准备毕设、需要完整可演示系统的学生，二是想练手前后端分离开发、想弄明白权限控制和多角色业务的初学者，三是想在自己小区做试点运营的小团队。读完你至少能搞清楚：社区类平台的功能模块应该怎么切，RBAC权限模型怎么落到代码里，JWT和Redis怎么配合管理登录态，以及一个SpringBoot+Vue项目从本机跑通到服务器部署要经历哪些过程。

1. 项目定位与整体方案设计思路

1.1 为什么选SpringBoot+Vue这套前后端分离架构

先说选型。社区居民服务平台本质上是典型的信息管理系统，核心是数据流转：居民提交请求，物业处理请求，管理员配置系统。这类系统其实用传统单体JSP方案也能做，但维护起来很痛苦。前两年我也试过用SpringBoot+Thymeleaf服务端渲染来做，页面、接口、数据全是耦合在一起的，改个样式还得重启服务，热更新配半天，后来果断切到前后端分离。

选SpringBoot的原因很直接：内嵌Tomcat，不用单独部署Web容器；一堆Starter依赖让配置量大幅减少；生态成熟，主流的问题基本都有官方或社区方案。你不需要完全吃透自动装配原理也能用起来，但建议多少了解一下，因为后面排查依赖冲突、版本升级问题会用到。

选Vue则是看中它的渐进式特性：可以从简单的页面组件开始写，逐步用到Vue Router做路由、Pinia/Vuex做状态管理。对中型项目来说，Vue的组件化开发效率比直接操作DOM写页面高太多，而且Element UI组件库让后台管理界面做起来像搭积木一样。

再往后想一层：前后端分离不只是技术偏好，它带来的最大好处是接口复用。这次做的是Web端，等哪天想加个居民微信小程序或者物业App，后端接口完全可以直接复用，前端重新做一层就行。这一点在答辩或者跟团队介绍方案时非常加分。

1.2 核心功能模块的划分：三类角色三种视角

社区居民服务平台面向的对象很清晰：居民、物业人员、系统管理员。功能模块我按角色的“日常动作”来切，而不是按技术习惯来切。

做的时候我给功能排了优先级。必修闭环是“报修工单流”：居民提交、物业接单、状态流转、居民确认完成。这个流程几乎覆盖了权限校验、状态机设计、文件上传、消息通知，做完它整个项目的核心技术点就全打通了。活动报名和访客预约属于功能性加分项，时间紧的话可以简化成“信息登记+列表展示”。公告和费用属于低难度高展示度的模块，一定要做，因为演示效果好。

这里给一个建议：不要一上来就全部功能铺开做，先把数据库设计好，再按“报修-公告-费用-活动”这个顺序逐个实现。我做的时候贪快，先做了简单的公告模块练手，再啃报修模块，后面再补费用模块，这样心理压力和踩坑成本都小很多。

1.3 数据库设计的几个关键决策

数据库设计是社区服务平台最体现功底的地方。我用了MySQL 8.0，表虽然不是特别多，大概二十张左右，但关系比较复杂，这里讲几个关键决策。

第一，用户和角色的关系必须用关联表。社区平台里一个人可能既是居民，又是某个活动的发起人，或者同时是物业人员值班表里的管理端账号，如果用给用户表加一个role_id字段的方式，一条用户数据只能对应一个角色，后面想扩展多角色就要改表结构，麻烦。所以标准做法是user、role、user_role三张表，用户通过关联表挂多个角色。

第二，楼栋房屋关系是社区业务的基础数据。我建了building（楼栋表）、room（房屋表）、user_room（住户房屋绑定关系表）三张表。为什么要单独建关联表？因为居民可能搬家，房屋可能换主人，直接往room表里加owner_id字段，历史数据就丢了。绑定关系表还能记录入住时间、搬离时间，后面做人口统计和缴费账单都靠它。

第三，业务表必须有状态字段和逻辑删除标记。比如报修工单表设一个status字段，字典值缓存到Redis里，页面标签用的也是这套字典。逻辑删除用deleted字段配合MyBatis-Plus的@TableLogic注解，这样误删数据还能“留底”，答辩的时候解释这个设计也能加分。

第四，公共字段自动填充。每张表都带create_by、create_time、update_by、update_time，用MyBatis-Plus的MetaObjectHandler统一填充，省去在每个Service里手动set的重复劳动。顺便说一句，时间字段MySQL端默认用datetime，Java端用LocalDateTime，JSON序列化要额外配一下，这个后面踩坑部分会细说。

2. 核心难点拆解：权限、认证与接口规范

2.1 基于RBAC的三级权限模型怎么落地

权限设计是这个项目里最值得讲清楚的部分。我采用的是标准的RBAC模型，分三层：用户关联角色，角色关联菜单权限，菜单权限精确到按钮。

具体到表结构，除了刚才说的user和role，还要有menu（菜单权限表）和role_menu（角色菜单关联表）。menu表字段大概是：id、parent_id（父级菜单，0表示顶级）、menu_name（菜单名）、path（路由路径）、component（前端组件路径）、perms（权限标识字符串，比如community:repair:process）、menu_type（目录/菜单/按钮）、icon、sort、visible。

这里想提醒一点：做动态菜单的时候，很多人会把菜单管理和权限标识混在一起，导致一个角色的菜单和它能操作的按钮对不上。我建议菜单权限和按钮权限用同一套perms标识，后端每次请求都校验，前端用v-permission指令控制按钮显隐。例如物业角色有community:repair:process权限，那么维修单详情的“接单”按钮才显示，没有这个权限的后端接口也会返回403，双重保险。

后端拦截器逻辑也很简单：请求进来，先解析JWT拿到userId，再从Redis查用户权限列表，判断这个用户是否拥有接口要求的权限标识。管理员角色直接放行，普通角色逐个匹配权限字符串。这里有个性能小优化：权限列表每次登录时一次性加载到Redis，不用每次请求都查数据库。

2.2 JWT认证与登录态管理的正确姿势

登录认证用的JWT，但在社区平台里光靠JWT还不够。JWT本身是无状态的，签发之后在过期之前服务器端没法主动让它失效，用户改密码、被管理员禁号、退出登录，这些问题都处理不了。所以我用的是JWT+Redis的方案。

具体做法是：登录成功以后，生成一个token返回给前端，同时把token存到Redis里，key是login_token:{userId}，value是token字符串，过期时间跟token一致。后端拦截器每次拿token去Redis里查一下，查不到就判定未登录。这样管理员禁号的时候，直接删掉Redis里的key，这个用户立马失效，不需要等JWT自然过期，效果跟“踢下线”一样。

JWT的生成要注意几个配置：签名密钥要单独放配置里，不要写到代码里；过期时间我设成了2小时；payload里只放userId和roleCode，不放手机号、密码之类的敏感信息。密码存储用BCrypt加密，Spring Security的BCryptPasswordEncoder就能干这个事，千万别用MD5——社区平台涉及居民隐私，密码明文存储这种事答辩时会非常尴尬。

再补充一个多端登录的小细节：如果允许同一账号手机端Web端同时在线，Redis的key可以设计成login_token:{userId}:{clientType}，推广的时候讲出来，评委通常会多给几分印象分。

2.3 前后端联调的接口规范与拦截器设计

前后端分离以后，接口联调是最耗时的环节。我提前把一套规范定死了，后面几乎没在沟通上浪费过时间。所有后端接口统一返回Result对象，结构是code、message、data三个字段。分页接口固定返回PageResult，里面是total（总条数）、records（当前页数据）、currentPage、pageSize。

错误码也做了约定：200成功，401未登录或token过期，403没有权限，404资源不存在，500业务异常。全局异常处理器用@RestControllerAdvice统一捕获，业务异常手动抛出，未知异常自动包装成“系统繁忙，请稍后重试”返回给前端，避免把堆栈信息直接暴露到页面上。

前端这边，Axios做了两层拦截：请求拦截器从Pinia里读token，加到Authorization请求头；响应拦截器统一处理code，401跳登录页面并清空登录态，其他错误码弹提示。这里有个血泪教训：响应拦截器里处理401跳转时，要判断当前页面是不是已经在登录页，不然登录页本身的登录请求也拿不到token，会形成死循环。

接口命名规范也建议一开始就定好：资源名复数，动作路径化。比如GET /api/resident/repairs表示分页查我的报修单，PUT /api/property/repairs/{id}/process表示物业处理工单。路径里带上角色前缀，后面做权限匹配会非常方便。

3. 从零到一搭建项目的完整实操记录

3.1 后端工程初始化与依赖版本选择

我先说版本问题，这是最容易入坑的地方。SpringBoot版本我强烈建议：求稳就用SpringBoot 2.7.x配JDK8，尤其你是做毕设、参考了很多旧教程的情况下。SpringBoot 3.x确实新，但坑不少——包名从javax迁到jakarta，一些老版本的MyBatis-Plus、Druid、Knife4j不兼容，你光处理依赖冲突就能耗掉一整天。等把2.x方案跑通、原理也理解了，想尝鲜再升3.x不迟。

用IDEA新建SpringBoot工程，依赖选这些：

application.yml里重点配三块：数据源（地址、账号、密码、连接池）、Redis（地址、端口、密码）、MyBatis-Plus（驼峰映射、日志输出、逻辑删除配置）。分页插件要单独加一个MybatisPlusInterceptor配置类，不然分页查询会查出全部数据，这是MyBatis-Plus最典型的坑。

工程目录按职责分包：controller、service、mapper、entity、dto、vo、config、common、utils。实体类对应数据库表，DTO负责接收前端参数，VO负责返回前端数据，避免把数据库实体直接裸露给前端。这样分层以后，改字段不会到处炸。

3.2 前端工程初始化与核心依赖安装

前端用Vue，版本上如果你是新手，我建议直接跟着Vue3生态来：Vue 3.2以上、Vue Router 4、Pinia、Element Plus。Vue2现在老项目里还很多，但新项目再用它有点逆潮流了。

Node版本管理建议装nvm，Node 16或18都行，别直接用最新的Node 21、22，容易出现依赖编译问题。工程创建我用的Vite，对比Vue CLI它启动速度快太多了，改代码热更新基本秒级。如果是为了和网上SpringBoot+Vue教程保持一致性，用Vue CLI创建也不是不行，只是如果遇到node-sass编译失败，八成是Node版本和node-sass不兼容，换成sass或dart-sass能解决，这也是群里的高频掉坑点。

装的依赖大致是：axios（HTTP请求）、element-plus（UI组件库）、@element-plus/icons-vue（图标）、pinia（状态管理）、vue-router、sass。目录结构按api、assets、components、router、store、utils、views来分。api目录下按业务模块拆文件，比如repair.js放报修相关接口，每条接口注释写明用途和参数，后面联调省心。

路由配置用Router，两个重点：一是在路由meta里标记需要哪些角色访问，二是配合后端返回的动态菜单用router.addRoute动态加业务路由。基础路由（登录页、404页）写死在路由表里，业务路由登录后动态挂载，这样刷新页面时不会白屏。

3.3 核心业务闭环的实现过程：以报修工单为例

报修工单模块是整个项目的心脏，因为它串起了居民、物业、管理员三类角色，每一步状态变化都牵动权限和页面展示。从设计到实现我完整走了一遍，这里把关键过程拆开讲。

数据库层面，repair_order表字段包括：id（雪花ID）、order_no（工单号）、resident_id（报修人）、room_id（房屋ID）、repair_type（维修类型：水/电/暖/其他）、description（问题描述）、image_urls（图片地址，支持多张）、status（状态）、property_id（处理人）、handle_remark（处理备注）、evaluate_score（评价分）、create_time、update_time、deleted。

状态流转我设计成严格单向：待接单 -> 已接单/处理中 -> 已完成（待评价） -> 已评价。用枚举类OrderStatus把每个状态和对应的操作权限锁起来。比如待接单状态只允许物业角色的“接单”操作，居民不可操作；处理中状态允许物业提交完成，也允许居民取消（取消是考虑到居民报错修的兜底，但也只能在这个状态做）。

后端实现上，提交报修用@Transactional事务，因为要同时写工单表和一条通知记录（通知物业有新工单）。查询接口按角色区分：居民只能看到自己的工单，物业只能看到自己负责的小区的工单，这是数据权限的实现，不能只靠前端隐藏菜单，后端查询条件必须拼上小区ID或者用户ID。状态汇总接口用SQL的group by status做一张仪表盘，物业首页显示待接单数量、处理中数量、本月完成数，演示效果非常直观。

前端页面交互：报修表单做三块校验——维修类型必选、描述必填且长度不小于10个字、图片最多上传6张。提交成功后跳转到“我的报修”列表页。列表页按状态切换Tab展示，用表格加标签渲染状态。详情页用抽屉组件showDrawer实现，里面放时间轴显示状态流转历史，底部根据当前状态显示不同操作按钮，比如“接单”“完成维修”“评价”。这套交互做完，整个平台的操作流程感就出来了。

4. 打包上线：本地跑通只是第一步

4.1 环境配置分离与打包

本地跑通只算完成了60%，真正把项目部署到云服务器上才是完整交付。首先把配置按环境拆开：application-dev.yml给本地开发，application-prod.yml给生产，application.yml里只用spring.profiles.active切换，不再写具体配置。

生产环境的配置要特别注意：数据库密码不要硬编码写在配置文件里，改成从环境变量读取，比如password: ${DB_PASSWORD}。部署的时候在docker-compose里注入环境变量，这样即使配置文件被人看到也不会泄露密码。敏感字段一律环境变量化，这是基本的职业素养。

后端打包：mvn clean package -DskipTests，跳过测试是为了避免测试环境连不上数据库导致打包失败。打出来的jar在target目录下。前端打包：项目根目录建.env.development和.env.production两个文件，分别定义VITE_API_BASE_URL，开发环境指向本机后端，生产环境指相对路径/api，这样打包后的dist部署到哪里接口路径都能用。

4.2 Docker编排：MySQL、Redis、后端、前端一次拉起

部署我用的Docker Compose，一次把MySQL、Redis、后端jar、前端Nginx全部编排起来。给一套可直接用的方案：写docker-compose.yml，定义四个服务：mysql8、redis7、community-backend、community-frontend。

后端Dockerfile用多阶段构建：第一阶段用maven镜像把jar构建出来，第二阶段jre镜像直接跑jar。这样最终镜像体积小很多。前端Dockerfile更简单：从一个nginx镜像开始，把dist目录复制到/usr/share/nginx/html，再把自定义的nginx.conf覆盖进去。

这里有一个新手必踩的坑：容器里的后端要连数据库时，数据库地址不能写localhost，要写docker-compose里MySQL的服务名，比如jdbc:mysql://mysql:3306/community。因为容器之间通过服务名互相通信，localhost指向的是容器自己。还有时区问题，MySQL和Redis容器启动参数加上TZ=Asia/Shanghai，不然服务器时间显示和本地时间差8小时，前端时间显示会莫名其妙多8个小时或者少8个小时。

4.3 Nginx反向代理、history路由和静态文件映射

前端Nginx配置是部署的关键。Vue Router如果是history模式（地址栏没有#号），服务器端必须配合配置，否则用户刷新页面就404。解决方式是Nginx里加上try_files配置，所有路径回退到index.html。

location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; }

后端接口走反向代理：前端请求统一带/api前缀，Nginx把/api开头的请求转发到后端容器的8080端口。这样生产环境前后端同域，不存在跨域问题，前端也不需要在Axios里配跨域相关的东西。

location /api/ { proxy_pass http://community-backend:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /uploads/ { alias /data/uploads/; }

最后这个uploads映射值得说一说。上传的图片（维修照片、活动海报）默认存在后端服务器某个目录，必须给Nginx配置一个静态路径映射，否则图片URL返回404。把这个配置写进Nginx之后，上传的图片就能直接通过http://域名/uploads/xxx.jpg访问了。当然，如果项目再大一点，文件就不应该存在本地磁盘了，可以用MinIO或者云OSS，思路一样，只是把uploads映射换成对应的对象存储地址。

5. 踩坑实录：线上真实问题与排查思路

5.1 高频问题速查表

5.2 一个典型排查过程：报修提交流程突然失败

我印象最深的一次排查，是物业反映某小区报修工单提交后页面一直报系统繁忙。我把过程完整理了一遍，这其实是排查问题的一个标准模板。

第一步，打开浏览器F12看Network面板，找到对应的提交请求，查看响应内容。返回体里是统一的错误码500，但没有具体报错信息。第二步，去看后端控制台日志，日志里打了一行SQL异常：Column 'repair_type' cannot be null。第三步，回到前端代码检查提交参数，发现页面上有维修类型下拉框，但用户没有选择时默认值是空字符串，而空字符串传过去并没有被后端校验拦截。第四步，修复：后端DTO把repair_type字段加上@NotNull注解，前端表单把维修类型设为必选项，双重保证。第五步，重新测试，问题解决。

这个案例看起来简单，但揭示了前后端联调的正确姿势：永远先看请求和响应报文，再看后端日志，不要上来就猜代码。日志级别我建议开发环境SQL输出打开，MyBatis-Plus里有配置可以直接看到SQL语句；生产环境关闭SQL输出，保持日志干净，同时把业务异常和系统异常分开打印，用logback把error日志单独输出到文件，排查问题效率高很多。

5.3 容易忽略的安全与细节问题

社区平台涉及居民真实信息，安全问题不能只顾功能。这里有几个我实测后认为必须有意识处理的点。

越权访问是最容易出事的。我给后端每个查询接口都做了数据权限校验：居民查询工单自动带上自己的userId，物业查询工单强制带自家小区ID，管理员操作日志里记录每次关键操作的userId和操作内容。测试的时候我故意用普通物业账号去调管理员接口，返回403才算是真的安全。

文件上传校验务必做严。我限制只允许jpg、png、jpeg、webp四种图片格式，上传前校验文件后缀，再校验文件头Magic Number，大小限制5MB，文件名直接重命名成UUID不带原始名。为什么？因为如果允许任意文件上传又不加校验，恶意上传一个jsp或php文件到服务器，配合静态目录映射，那就等于把服务器大门打开了。Web容器默认有安全规则，但自己项目里做防御才是负责任的做法。

再一个是富文本内容处理。管理员发布公告的时候如果用了富文本编辑器，前端提交上来的HTML字符串要做过滤，里面可能藏了script标签。后端统一用HtmlUtils把尖括号转义，或者只允许白名单标签，别直接把HTML原样存库又原样渲染回页面。另外，公告发布时间做定时任务时，注意服务器时区和任务的触发时间对齐，别出现“定时发送结果隔了8小时才发出去”的尴尬。

最后再分享一点实际的经验

整个项目从设计到部署，我大概花了三周半的时间，中间还推倒重来了一次数据库设计。复盘下来，最重要的经验不是某个技术细节，而是“先想清楚角色和状态，再动手写代码”。社区服务平台看着功能多，核心其实就是各角色的日常动作加状态流转，把这两个定扎实了，后面按部就班写代码是很快的。

面试或者答辩的时候，大家最爱问的问题也集中在这些点上：为什么用关联表做多角色、JWT过期怎么办、前端刷新404怎么解决、分页查询怎么实现。这些恰好都是项目里踩过坑又修好的地方，做过一遍的人，和被背题八股的人，说出来的深度完全不一样。后面如果你想扩展，可以试着把二手的闲置交易往里加，或者接腾讯地图做便民服务定位，也可以把消息推送换成WebSocket让物业实时接单，这些都是在这个骨架上长出来的新业务，技术路径我已经帮你趟通了大半。