做社区类管理系统这几年我最大的感受是业务复杂度往往不在技术本身而在于你把多少真实场景的“脏活”想清楚了。以“基于SpringBoot的社区智能垃圾管理系统”为例很多人第一眼觉得这就是个CRUD项目但其实里面藏了智能设备对接、积分规则、清运调度、数据统计、权限控制这些硬骨头。这篇文章我会从项目拆解、数据建模、核心模块实现、常见坑位排查几个方向完整走一遍用的就是SpringBoot这个主力框架。如果你是做毕设、课设或者想在公司内部快速搭一套社区管理后台这篇文章可以直接当参考蓝本。1. 整体设计与业务模型拆解1.1 智能垃圾管理到底在管什么先想清楚一个核心问题这个系统服务的对象是谁不是居民个人而是社区物业、街道环卫和再生资源回收企业。那“智能”体现在哪里我归纳下来主要是三件事识别谁投的、称重计了多少、违规有没有证据。再往后推演就有了积分激励、清运车调度、垃圾满溢预警、分类正确率分析这些衍生功能。我见很多新手一上来就画六个大模块用户管理、垃圾分类、积分管理、清运管理、统计报表、系统管理。没问题但这只是菜单层面。真正的业务闭环是居民刷脸或扫码开箱 - 设备称重并识别垃圾类型 - 系统记录投放明细 - 按规则发积分或扣信用分 - 积分去兑换商品或抵扣物业费 - 设备满溢后自动生成清运工单 - 清运人员接单处理并回传照片 - 后台生成分类质量报表。这个闭环里每一个箭头都对应一条或一组接口。如果不先把链路画出来直接建表写接口后期一定会返工。我自己习惯用一页纸把角色、动作、数据流画出来然后再动手。1.2 为什么选SpringBoot这一套组合技术选型上SpringBoot几乎是这类项目的标准答案。本身内嵌Tomcat、自动装配、生态成熟配合MyBatis-Plus操作数据库效率很高Spring Security做登录鉴权Redis缓存热点数据MinIO做图片存储WebSocket推实时消息Spring Task做定时汇总。这套组合既不炫技又能保证快速交付。有人纠结要不要上微服务、要不要用消息队列。我的建议是这个规模完全不需要。一个社区几百户到几千户就算高峰期全员投放QPS也到不了几百。单体应用加合理缓存完全扛得住。强行拆微服务反而引入分布式事务、服务间调用这些额外复杂度得不偿失。关于版本我强烈建议用SpringBoot 2.7.x或3.x稳定版。网上有些教程直接给3.0.0之后javax包名改成jakarta很多老代码直接编译不过。如果你用的是3.x注意javax.servlet要替换成jakarta.servletMyBatis-Plus也要用适配3.x的版本。这一步是很多人移植项目时踩的第一个坑。1.3 数据库表设计的关键取舍表设计是整个项目的地基。我按业务域拆成六组用户域、设备域、投放域、积分域、清运域、配置域。下面是我最终落地的核心表结构已经去掉了冗余字段表名核心字段说明community_userid, openid, phone, real_name, address, point_balance居民用户openid对应小程序登录device_infoid, device_no, community_id, lng, lat, type, status智能垃圾箱type区分可回收/厨余/其他device_recordid, device_no, user_id, category, weight, images, video_url, create_time投放记录一张表记录每次投放明细point_accountid, user_id, point, balance, direction, remark积分流水只增不改便于追溯penalty_recordid, user_id, violation_type, device_no, evidence_url, status违规投放记录混投、未分类等clean_taskid, device_no, task_type, assignee, status, before_photo, after_photo, finish_time清运工单含前后对比照片category_rateid, community_id, category, rate, update_time分类标准不同小区可配置不同费率sys_role / sys_user / sys_menu常规RBAC三件套后台账号权限控制几个关键设计点要重点说。第一金额和积分一律用decimal不用float。称重数据涉及重量和积分计算浮点误差在累计场景下会被放大我遇到过重量90.1公斤在报表里显示90.099999的情况排查半天。所有数值字段用decimal(10,2)起步。第二每张业务主表都带上create_time、update_time、deleted逻辑删除字段。MyBatis-Plus配置好自动填充后非常省事。逻辑删除项目必备物理删除一旦误操作数据找不回来有些社区还要做季度审计物理删除是绝对不接受的。第三投放记录表要建联合索引。实际项目里查询最多的场景是“某用户在某个时间段的所有投放记录”和“某台设备最近N条投放”所以索引建议(user_id, create_time)和(device_no, create_time)。这条索引上线前后查询速度差异非常大数据量到十万级别后尤其明显。2. 核心功能模块设计与实现要点2.1 登录鉴权Spring Security JWT的落地配置后台管理系统和居民小程序端的鉴权方式要分开。管理端我用的Spring Security JWT小程序端用的是openid 自签token两者共用一套Redis存储登录态但不共用过滤器链。很多项目把所有接口放在同一个过滤器链里导致小程序端也要走Security的权限校验写起来很别扭。Spring Security的配置要注意几个点。一是放行白名单登录接口、验证码接口、设备回调接口必须放行否则设备端上报数据会被拦在外面。二是JWT过滤器要放在UsernamePasswordAuthenticationFilter之前核心代码大致是这样Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http.csrf().disable() .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() .authorizeRequests() .antMatchers(/api/auth/login, /api/auth/captcha, /api/device/callback/**).permitAll() .antMatchers(/api/admin/**).hasRole(ADMIN) .anyRequest().authenticated() .and() .addFilterBefore(new JwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class); return http.build(); }JWT密钥一定要放到配置文件里用环境变量注入别硬编码在代码里。之前有同事把密钥写到application.yml还提交到了Git仓库结果公司安全扫描直接报了高危漏洞。我现在的做法是本地application-local.yml写默认值生产环境通过JWT_SECRET环境变量覆盖即使代码泄露也不会直接影响线上。2.2 智能设备对接称重数据和图像上报的处理思路设备对接是这类系统里最容易出问题的环节。市面上智能垃圾箱的通信协议五花八门有走MQTT的有走HTTP回调的有设备端SDK直接上报的。我在这个项目里采用的是HTTP回调加设备签名校验的方式原因很简单MQTT需要自己维护BrokerHTTP回调部署简单社区设备数量不大完全够用。设备上报的数据结构大致如下{ deviceNo: DEV-001, userId: u10001, category: recyclable, weight: 1.25, images: [http://minio:9000/bucket/xxx.jpg], timestamp: 1690000000, sign: md5(deviceNotimestampsecretKey) }服务端要做三件事验签防伪造、幂等处理防重复提交、数据落库。验签用设备密钥生成MD5签名对比幂等用deviceNo timestamp userId做唯一索引重复上报直接忽略。这块代码不复杂但必须写否则设备网络抖动重试一次居民积分就多发一次后续对账会非常痛苦。设备端图像上传我推荐走MinIO预签名URL。设备端先调用一个接口申请预签名URL然后把图片直接PUT到MinIO不经过应用服务器转发。这样可以避免大图占用应用带宽也方便后续做违投图片识别时直接读取桶里的文件。预签名URL生成代码很简单String url minioClient.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.PUT) .bucket(community-device) .object(upload/ fileName) .expiry(60 * 10) .build());2.3 积分规则引擎不写死在代码里的配置方案积分规则是业务方改得最频繁的地方。今天说可回收垃圾每公斤积5分明天说厨余垃圾正确投放每次奖励2分后天说连续7天投放额外奖励20分。如果这些规则写死在Java代码里每次改动都要发版时间一长程序员会被业务方追着改。我设计了一套可配置的规则表核心结构是规则编码、适用垃圾类型、计算方式、奖励分值、生效时间、状态。计算时用策略模式按垃圾类型分发到不同的积分计算器。比如按重量计分的规则public class RecyclablePointStrategy implements PointStrategy { Override public PointResult calc(DeviceRecord record) { // 可回收垃圾积分 重量 * 单价 * 正确投放系数 return PointResult.of(record.getWeight().multiply(rate).multiply(coefficient)); } }这里有个细节正确投放系数。系统会结合居民的分类正确率动态调整积分倍率分类正确率高的居民投放可回收垃圾时会有额外加成。这个机制落地后社区里正确分类的用户明显增多因为大家能看到积分流水明细知道“分对了有奖励分错了有惩罚”。积分流水的balance字段一定要做乐观锁控制防止并发扣减时出现负数。我用的方案是UPDATE point_account SET balance balance - ? WHERE user_id ? AND balance ?通过受影响行数判断是否扣减成功。2.4 清运工单闭环从满溢预警到任务完结垃圾满溢不能只靠居民电话投诉系统要有自动感知。方案是在设备上报投放记录时同时上报当前满载率。后台有定时任务每5分钟扫描一次设备状态凡是满载率超过80%的设备自动生成清运工单。清运工单的状态机我定义为待接单 - 已接单 - 清运中 - 已完成 - 已取消。每个状态变更都要求记录操作人和时间清运人员完成时必须上传清运前后的对比照片这样可以倒逼清运人员真的到现场处理而不是在后台点个完成按钮就结束了。工单分配的策略我踩过坑。最开始按设备编号轮流分配结果某位清运员被派到距离很远的设备来回路程一小时效率极低。后来改成“根据清运员当前定位与设备距离最近优先分配”配合百度地图API计算实际道路距离整体响应时间从平均45分钟降到了18分钟。如果你也想做类似功能注意别直接用经纬度直线距离排名社区周边的河流、围墙都会导致直线距离近但实际走很远。3. 关键机制的落地细节3.1 Spring Task定时的任务与动态开关垃圾数据分析报表、设备离线巡检、工单超时提醒这些都依赖定时任务。SpringBoot自带的Scheduled完全够用。我在配置里会加一个开关控制task: report: enabled: true任务类上用ConditionalOnProperty控制是否加载这样临时要停某个任务时改配置重启即可不用改代码再发版。定时任务建议给每个任务起独立的名字并在执行入口和出口打印日志。定时报表任务一旦失败日志里至少要能看出是数据源问题还是计算方法问题。用Scheduled时有一个5分钟就能踩到的坑默认线程池只有一个线程。如果项目里有多个定时任务其中一个任务因为数据量大跑得久其他任务全部阻塞等待。解决办法是配置线程池Bean(name taskScheduler) public TaskScheduler taskScheduler() { ThreadPoolTaskScheduler scheduler new ThreadPoolTaskScheduler(); scheduler.setPoolSize(10); scheduler.setThreadNamePrefix(scheduled-); return scheduler; }3.2 WebSocket实时推送投放确认与工单提醒居民投放垃圾后小程序端要立刻收到投放结果和积分变动通知这个场景用WebSocket比轮询体验好得多。我在项目里用ServerEndpoint实现了一个简易推送服务用户登录后建立连接按userId维度的session保存在一个ConcurrentHashMap里。投放记录落库后通过用户ID找到对应的WebSocket session推送消息public void pushToUser(String userId, String message) { Session session sessionMap.get(userId); if (session ! null session.isOpen()) { session.getBasicRemote().sendText(message); } }注意WebSocket session不是线程安全的多线程并发发送时要加锁或使用CopyOnWriteArraySet来管理。另外部署时如果用了Nginx代理必须配置WebSocket升级支持加上proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection upgrade;否则前端连不上这一条排查起来相当隐蔽。3.3 MinIO接入后的权限隔离方案MinIO做文件存储后最容易被忽略的是桶的权限配置。我把桶按业务拆分device-image存放设备上报图片、user-avatar存放居民头像、report-export存放后台导出的报表。每个桶的访问策略不同设备上报图片用私有读写报表导出文件用临时下载链接这样既安全又灵活。下载导出文件时用预签名URL设定5分钟有效期即可不要直接暴露桶的对外公开读权限。之前有个项目把MinIO桶设成public结果所有居民头像和垃圾投放照片都能通过链接直接访问这已经算隐私泄露事故了。MinIO虽然轻量但该做的访问控制一步不能少。3.4 高并发场景下的数据一致性处理积分发放和重量记录这类写操作并发峰值集中在早晚投放高峰期。这个规模下不会真的把数据库打崩但会出现两类典型问题重复积分和积分竞态。重复积分已经在设备回调幂等里解决积分竞态用数据库乐观锁解决。加工单状态时要注意“状态校验更新”必须是一个原子操作。我有一次写代码时先查工单状态判断是待接单再更新为已接单结果两个清运员同时点击接单两个人都显示接单成功实际工单状态只变了一次。后来改成一条SQL完成状态流转UPDATE clean_task SET status 已接单, assignee #{userId}, accept_time NOW() WHERE id #{taskId} AND status 待接单受影响行数为0说明工单已经被别人抢走了直接提示用户即可。这种“条件更新”的思路在处理所有状态机流转时都适用。4. 前端联动与接口设计4.1 管理后台用Vue还是直接用模板引擎我见过很多SpringBoot毕设项目用Thymeleaf直接渲染后台页面开发确实快但做到图表报表、复杂交互时会很痛苦。我推荐分离式开发SpringBoot只做纯接口前端用Vue3 Element Plus。两个项目分开部署接口通过Nginx反向代理。前后端分离模式对接口设计的要求更高。统一返回结构非常关键我用的格式是{ code, message, data }。通常一段简单的Axios拦截器就能处理所有基础异常service.interceptors.response.use( response response.data, error { if (error.response.status 401) { router.push(/login); } return Promise.reject(error); } );对于毕设来说这样做的好处是答辩时可以清晰展示前后端分层代码结构也更规范。后端接口文档可以直接集成SpringDoc基于OpenAPI 3自动生成Swagger页面前端照着调效率很高。4.2 接口设计规范路由命名、参数校验与分页接口路由我按资源命名比如/api/device-records、/api/clean-tasks、/api/points不用/api/getAllRecord这种动词式命名。REST风格的好处是前后端沟通成本低看到路径就能猜到大概含义。参数校验是很多人忽略的部分。后端接口入参一定要做校验不能完全信任前端。我用Validated加NotNull、Min、Pattern这些注解在校验失败时统一抛出参数异常返回友好错误信息。JSR-303校验在SpringBoot里配置非常简单顺手写一下能省掉后面大量字段为空导致的空指针问题。分页统一用MyBatis-Plus的Page对象。前端传current和size后端返回total和records。需要特别提醒排序字段不要直接拼接用户传入的内容搞一个白名单映射防止SQL注入和恶意排序拖垮数据库。4.3 小程序端的数据加载策略小程序端主打轻量。首页加载时一次请求聚合接口把设备列表、用户积分、待办事项合并返回减少请求次数。下拉刷新时重新拉取聚合接口投放记录和积分流水用分页懒加载。图片列表用懒加载加缩略图参数设备上报的原图可能2MB一张直接拉原图在小程序端既卡又费流量。还有一个很实用的做法小程序端进入投放页前先请求设备状态接口如果设备离线或满载率100%直接置灰不可投放按钮减少用户到现场发现不能用的挫败感。这个功能上线后物业接到的咨询电话少了很多。5. 部署调试与常见问题排查5.1 从本地到云端的构建部署全流程这个项目部署我推荐用Docker Compose编排把SpringBoot应用、MySQL、Redis、MinIO放到同一台服务器上各容器通过内部网络通信。应用镜像基于eclipse-temurin:17-jdk构建时用Maven打包mvn clean package -DskipTests docker build -t community-garbage:1.0.0 . docker-compose up -d需要注意的点是MySQL初始化脚本和MinIO初始化权限要在容器启动时完成。生产服务器上数据卷一定要挂载出来不然容器一删数据全没。我第一次部署时就因为没挂载MySQL数据卷升级镜像后数据直接丢失好在当时还是测试环境教训惨痛。5.2 前端项目打包放进SpringBoot的静态资源目录有一步很多教程没讲明白Vue前端打包后可以直接把dist目录里的文件复制到SpringBoot的src/main/resources/static下这样前端后端合并在一个SpringBoot应用里。但这样做有一个前提前端路由要改成history模式并且后端要配置一个路由兜底把非API路径的请求转发到index.html否则刷新页面就是404。我的习惯是不合并前后端分开部署。前端静态文件丢Nginx接口请求反代到SpringBoot这样重前端和重接口的场景都能灵活扩缩容。直接合并的方式适合部署环境极其有限的场景比如学校机房只有一台服务器。5.3 常见问题速查表与避坑思路问题现象排查思路解决建议设备数据上报失败看接口白名单是否放行验签逻辑是否一致本地用Postman模拟设备请求先用跳过签名模式调试积分出现负数扣减SQL缺少余额条件判断使用条件更新SET balance balance - ? WHERE balance ?WebSocket连不上检查Nginx代理配置、反向代理是否开启升级头添加Upgrade和Connection请求头定时任务所有任务都不执行SpringBoot默认调度线程池只有1个线程且被阻塞配置ThreadPoolTaskScheduler设置池大小JWT登录后接口报403Security过滤器链顺序错误确认JwtAuthenticationFilter在用户密码过滤器之前注册Vue打包后接口404没配置代理或地址拼写错误检查BaseURL使用环境变量区分环境这些坑都是我实际踩过的。尤其是Spring Security过滤器链顺序那个当时卡了一整个下午后来把过滤器执行日志打开才看到JWT过滤器根本没被调用因为过滤器链的注册顺序错了。5.4 性能优化与压测经验系统上线前我做了简单的JMeter压测模拟300个用户同时投放垃圾。当天就暴露了两个问题一是登录接口没有限流导致同一账号疯狂请求二是积分流水表在大量插入时出现了锁等待。对策分别是对登录接口加Redis计数器限流以及将积分流水插入改为批量提交。压测的意义不一定是要测出系统能扛多少QPS而是要找到最容易崩溃的薄弱点提前加固。查询性能上给查询频率高、数据量大的表加索引是最直接的手段。有一个配置文件表每天加载很多次我把热数据放到了Redis里设置60秒过期数据库压力一下就降下来了。这种优化其实非常朴素但对单体应用来说足够有效。6. 总结与个人实操体会做这个系统的过程中我最大的体会是“功能写完只是开始”。设备对接、积分规则、工单闭环、推送时机每一个节点都要站在真实使用者的角度去想。居民不会关心你用了什么设计模式他只在乎投放后积分有没有到账清运员不会关心你的表结构设计得多优雅他只在乎工单派发合不合理、到现场有没有活可干。很多毕设项目做完就扔了但如果真的要去社区试点这些细节才决定系统的成败。最后分享一个小技巧。如果你用的是SpringBoot 3.x遇到依赖冲突问题先不要急着改代码用Maven的依赖树命令查一下mvn dependency:tree -Dverbose然后观察spring-boot-starter-parent版本和子模块版本是否一致。很多ClassNotFoundException、NoSuchMethodError都不是代码问题而是依赖版本被其他模块改写了。搞清这一条能少走很多弯路。个人建议如果你准备做同类项目可以先从设备上报接口和积分流水这两条主线入手跑通以后再补管理后台和报表功能。主干一旦通了后面的模块只是规则的堆叠。技术栈SpringBoot Vue MySQL MinIO Redis已经是这类项目的斤两剩下的就看你怎么把业务设计得足够有说服力了。 做社区类管理系统这几年我最大的感受是业务复杂度往往不在技术本身而在于你把多少真实场景的“脏活”想清楚了。以“基于SpringBoot的社区智能垃圾管理系统”为例很多人第一眼觉得这就是个CRUD项目但其实里面藏了智能设备对接、积分规则、清运调度、数据统计、权限控制这些硬骨头。这篇文章我会从项目拆解、数据建模、核心模块实现、常见坑位排查几个方向完整走一遍用的就是SpringBoot这个主力框架。如果你是做毕设、课设或者想在公司内部快速搭一套社区管理后台这篇文章可以直接当参考蓝本。1. 整体设计与业务模型拆解1.1 智能垃圾管理到底在管什么先想清楚一个核心问题这个系统服务的对象是谁不是居民个人而是社区物业、街道环卫和再生资源回收企业。那“智能”体现在哪里我归纳下来主要是三件事识别谁投的、称重计了多少、违规有没有证据。再往后推演就有了积分激励、清运车调度、垃圾满溢预警、分类正确率分析这些衍生功能。我见很多新手一上来就画六个大模块用户管理、垃圾分类、积分管理、清运管理、统计报表、系统管理。没问题但这只是菜单层面。真正的业务闭环是居民刷脸或扫码开箱 - 设备称重并识别垃圾类型 - 系统记录投放明细 - 按规则发积分或扣信用分 - 积分去兑换商品或抵扣物业费 - 设备满溢后自动生成清运工单 - 清运人员接单处理并回传照片 - 后台生成分类质量报表。这个闭环里每一个箭头都对应一条或一组接口。如果不先把链路画出来直接建表写接口后期一定会返工。我自己习惯用一页纸把角色、动作、数据流画出来然后再动手。1.2 为什么选SpringBoot这一套组合技术选型上SpringBoot几乎是这类项目的标准答案。本身内嵌Tomcat、自动装配、生态成熟配合MyBatis-Plus操作数据库效率很高Spring Security做登录鉴权Redis缓存热点数据MinIO做图片存储WebSocket推实时消息Spring Task做定时汇总。这套组合既不炫技又能保证快速交付。有人纠结要不要上微服务、要不要用消息队列。我的建议是这个规模完全不需要。一个社区几百户到几千户就算高峰期全员投放QPS也到不了几百。单体应用加合理缓存完全扛得住。强行拆微服务反而引入分布式事务、服务间调用这些额外复杂度得不偿失。关于版本我强烈建议用SpringBoot 2.7.x或3.x稳定版。网上有些教程直接给3.0.0之后javax包名改成jakarta很多老代码直接编译不过。如果你用的是3.x注意javax.servlet要替换成jakarta.servletMyBatis-Plus也要用适配3.x的版本。这一步是很多人移植项目时踩的第一个坑。1.3 数据库表设计的关键取舍表设计是整个项目的地基。我按业务域拆成六组用户域、设备域、投放域、积分域、清运域、配置域。下面是我最终落地的核心表结构已经去掉了冗余字段表名核心字段说明community_userid, openid, phone, real_name, address, point_balance居民用户openid对应小程序登录device_infoid, device_no, community_id, lng, lat, type, status智能垃圾箱type区分可回收/厨余/其他device_recordid, device_no, user_id, category, weight, images, video_url, create_time投放记录一张表记录每次投放明细point_accountid, user_id, point, balance, direction, remark积分流水只增不改便于追溯penalty_recordid, user_id, violation_type, device_no, evidence_url, status违规投放记录混投、未分类等clean_taskid, device_no, task_type, assignee, status, before_photo, after_photo, finish_time清运工单含前后对比照片category_rateid, community_id, category, rate, update_time分类标准不同小区可配置不同费率sys_role / sys_user / sys_menu常规RBAC三件套后台账号权限控制几个关键设计点要重点说。第一金额和积分一律用decimal不用float。称重数据涉及重量和积分计算浮点误差在累计场景下会被放大我遇到过重量90.1公斤在报表里显示90.099999的情况排查半天。所有数值字段用decimal(10,2)起步。第二每张业务主表都带上create_time、update_time、deleted逻辑删除字段。MyBatis-Plus配置好自动填充后非常省事。逻辑删除项目必备物理删除一旦误操作数据找不回来有些社区还要做季度审计物理删除是绝对不接受的。第三投放记录表要建联合索引。实际项目里查询最多的场景是“某用户在某个时间段的所有投放记录”和“某台设备最近N条投放”所以索引建议(user_id, create_time)和(device_no, create_time)。这条索引上线前后查询速度差异非常大数据量到十万级别后尤其明显。2. 核心功能模块设计与实现要点2.1 登录鉴权Spring Security JWT的落地配置后台管理系统和居民小程序端的鉴权方式要分开。管理端我用的Spring Security JWT小程序端用的是openid 自签token两者共用一套Redis存储登录态但不共用过滤器链。很多项目把所有接口放在同一个过滤器链里导致小程序端也要走Security的权限校验写起来很别扭。Spring Security的配置要注意几个点。一是放行白名单登录接口、验证码接口、设备回调接口必须放行否则设备端上报数据会被拦在外面。二是JWT过滤器要放在UsernamePasswordAuthenticationFilter之前核心代码大致是这样Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http.csrf().disable() .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() .authorizeRequests() .antMatchers(/api/auth/login, /api/auth/captcha, /api/device/callback/**).permitAll() .antMatchers(/api/admin/**).hasRole(ADMIN) .anyRequest().authenticated() .and() .addFilterBefore(new JwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class); return http.build(); }JWT密钥一定要放到配置文件里用环境变量注入别硬编码在代码里。之前有同事把密钥写到application.yml还提交到了Git仓库结果公司安全扫描直接报了高危漏洞。我现在的做法是本地application-local.yml写默认值生产环境通过JWT_SECRET环境变量覆盖即使代码泄露也不会直接影响线上。2.2 智能设备对接称重数据和图像上报的处理思路设备对接是这类系统里最容易出问题的环节。市面上智能垃圾箱的通信协议五花八门有走MQTT的有走HTTP回调的有设备端SDK直接上报的。我在这个项目里采用的是HTTP回调加设备签名校验的方式原因很简单MQTT需要自己维护BrokerHTTP回调部署简单社区设备数量不大完全够用。设备上报的数据结构大致如下{ deviceNo: DEV-001, userId: u10001, category: recyclable, weight: 1.25, images: [http://minio:9000/bucket/xxx.jpg], timestamp: 1690000000, sign: md5(deviceNotimestampsecretKey) }服务端要做三件事验签防伪造、幂等处理防重复提交、数据落库。验签用设备密钥生成MD5签名对比幂等用deviceNo timestamp userId做唯一索引重复上报直接忽略。这块代码不复杂但必须写否则设备网络抖动重试一次居民积分就多发一次后续对账会非常痛苦。设备端图像上传我推荐走MinIO预签名URL。设备端先调用一个接口申请预签名URL然后把图片直接PUT到MinIO不经过应用服务器转发。这样可以避免大图占用应用带宽也方便后续做违投图片识别时直接读取桶里的文件。预签名URL生成代码很简单String url minioClient.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.PUT) .bucket(community-device) .object(upload/ fileName) .expiry(60 * 10) .build());2.3 积分规则引擎不写死在代码里的配置方案积分规则是业务方改得最频繁的地方。今天说可回收垃圾每公斤积5分明天说厨余垃圾正确投放每次奖励2分后天说连续7天投放额外奖励20分。如果这些规则写死在Java代码里每次改动都要发版时间一长程序员会被业务方追着改。我设计了一套可配置的规则表核心结构是规则编码、适用垃圾类型、计算方式、奖励分值、生效时间、状态。计算时用策略模式按垃圾类型分发到不同的积分计算器。比如按重量计分的规则public class RecyclablePointStrategy implements PointStrategy { Override public PointResult calc(DeviceRecord record) { // 可回收垃圾积分 重量 * 单价 * 正确投放系数 return PointResult.of(record.getWeight().multiply(rate).multiply(coefficient)); } }这里有个细节正确投放系数。系统会结合居民的分类正确率动态调整积分倍率分类正确率高的居民投放可回收垃圾时会有额外加成。这个机制落地后社区里正确分类的用户明显增多因为大家能看到积分流水明细知道“分对了有奖励分错了有惩罚”。积分流水的balance字段一定要做乐观锁控制防止并发扣减时出现负数。我用的方案是UPDATE point_account SET balance balance - ? WHERE user_id ? AND balance ?通过受影响行数判断是否扣减成功。2.4 清运工单闭环从满溢预警到任务完结垃圾满溢不能只靠居民电话投诉系统要有自动感知。方案是在设备上报投放记录时同时上报当前满载率。后台有定时任务每5分钟扫描一次设备状态凡是满载率超过80%的设备自动生成清运工单。清运工单的状态机我定义为待接单 - 已接单 - 清运中 - 已完成 - 已取消。每个状态变更都要求记录操作人和时间清运人员完成时必须上传清运前后的对比照片这样可以倒逼清运人员真的到现场处理而不是在后台点个完成按钮就结束了。工单分配的策略我踩过坑。最开始按设备编号轮流分配结果某位清运员被派到距离很远的设备来回路程一小时效率极低。后来改成“根据清运员当前定位与设备距离最近优先分配”配合百度地图API计算实际道路距离整体响应时间从平均45分钟降到了18分钟。如果你也想做类似功能注意别直接用经纬度直线距离排名社区周边的河流、围墙都会导致直线距离近但实际走很远。3. 关键机制的落地细节3.1 Spring Task定时的任务与动态开关垃圾数据分析报表、设备离线巡检、工单超时提醒这些都依赖定时任务。SpringBoot自带的Scheduled完全够用。我在配置里会加一个开关控制task: report: enabled: true任务类上用ConditionalOnProperty控制是否加载这样临时要停某个任务时改配置重启即可不用改代码再发版。定时任务建议给每个任务起独立的名字并在执行入口和出口打印日志。定时报表任务一旦失败日志里至少要能看出是数据源问题还是计算方法问题。用Scheduled时有一个5分钟就能踩到的坑默认线程池只有一个线程。如果项目里有多个定时任务其中一个任务因为数据量大跑得久其他任务全部阻塞等待。解决办法是配置线程池Bean(name taskScheduler) public TaskScheduler taskScheduler() { ThreadPoolTaskScheduler scheduler new ThreadPoolTaskScheduler(); scheduler.setPoolSize(10); scheduler.setThreadNamePrefix(scheduled-); return scheduler; }3.2 WebSocket实时推送投放确认与工单提醒居民投放垃圾后小程序端要立刻收到投放结果和积分变动通知这个场景用WebSocket比轮询体验好得多。我在项目里用ServerEndpoint实现了一个简易推送服务用户登录后建立连接按userId维度的session保存在一个ConcurrentHashMap里。投放记录落库后通过用户ID找到对应的WebSocket session推送消息public void pushToUser(String userId, String message) { Session session sessionMap.get(userId); if (session ! null session.isOpen()) { session.getBasicRemote().sendText(message); } }注意WebSocket session不是线程安全的多线程并发发送时要加锁或使用CopyOnWriteArraySet来管理。另外部署时如果用了Nginx代理必须配置WebSocket升级支持加上proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection upgrade;否则前端连不上这一条排查起来相当隐蔽。3.3 MinIO接入后的权限隔离方案MinIO做文件存储后最容易被忽略的是桶的权限配置。我把桶按业务拆分device-image存放设备上报图片、user-avatar存放居民头像、report-export存放后台导出的报表。每个桶的访问策略不同设备上报图片用私有读写报表导出文件用临时下载链接这样既安全又灵活。下载导出文件时用预签名URL设定5分钟有效期即可不要直接暴露桶的对外公开读权限。之前有个项目把MinIO桶设成public结果所有居民头像和垃圾投放照片都能通过链接直接访问这已经算隐私泄露事故了。MinIO虽然轻量但该做的访问控制一步不能少。3.4 高并发场景下的数据一致性处理积分发放和重量记录这类写操作并发峰值集中在早晚投放高峰期。这个规模下不会真的把数据库打崩但会出现两类典型问题重复积分和积分竞态。重复积分已经在设备回调幂等里解决积分竞态用数据库乐观锁解决。加工单状态时要注意“状态校验更新”必须是一个原子操作。我有一次写代码时先查工单状态判断是待接单再更新为已接单结果两个清运员同时点击接单两个人都显示接单成功实际工单状态只变了一次。后来改成一条SQL完成状态流转UPDATE clean_task SET status 已接单, assignee #{userId}, accept_time NOW() WHERE id #{taskId} AND status 待接单受影响行数为0说明工单已经被别人抢走了直接提示用户即可。这种“条件更新”的思路在处理所有状态机流转时都适用。4. 前端联动与接口设计4.1 管理后台用Vue还是直接用模板引擎我见过很多SpringBoot毕设项目用Thymeleaf直接渲染后台页面开发确实快但做到图表报表、复杂交互时会很痛苦。我推荐分离式开发SpringBoot只做纯接口前端用Vue3 Element Plus。两个项目分开部署接口通过Nginx反向代理。前后端分离模式对接口设计的要求更高。统一返回结构非常关键我用的格式是{ code, message, data }。通常一段简单的Axios拦截器就能处理所有基础异常service.interceptors.response.use( response response.data, error { if (error.response.status 401) { router.push(/login); } return Promise.reject(error); } );对于毕设来说这样做的好处是答辩时可以清晰展示前后端分层代码结构也更规范。后端接口文档可以直接集成SpringDoc基于OpenAPI 3自动生成Swagger页面前端照着调效率很高。4.2 接口设计规范路由命名、参数校验与分页接口路由我按资源命名比如/api/device-records、/api/clean-tasks、/api/points不用/api/getAllRecord这种动词式命名。REST风格的好处是前后端沟通成本低看到路径就能猜到大概含义。参数校验是很多人忽略的部分。后端接口入参一定要做校验不能完全信任前端。我用Validated加NotNull、Min、Pattern这些注解在校验失败时统一抛出参数异常返回友好错误信息。JSR-303校验在SpringBoot里配置非常简单顺手写一下能省掉后面大量字段为空导致的空指针问题。分页统一用MyBatis-Plus的Page对象。前端传current和size后端返回total和records。需要特别提醒排序字段不要直接拼接用户传入的内容搞一个白名单映射防止SQL注入和恶意排序拖垮数据库。4.3 小程序端的数据加载策略小程序端主打轻量。首页加载时一次请求聚合接口把设备列表、用户积分、待办事项合并返回减少请求次数。下拉刷新时重新拉取聚合接口投放记录和积分流水用分页懒加载。图片列表用懒加载加缩略图参数设备上报的原图可能2MB一张直接拉原图在小程序端既卡又费流量。还有一个很实用的做法小程序端进入投放页前先请求设备状态接口如果设备离线或满载率100%直接置灰不可投放按钮减少用户到现场发现不能用的挫败感。这个功能上线后物业接到的咨询电话少了很多。5. 部署调试与常见问题排查5.1 从本地到云端的构建部署全流程这个项目部署我推荐用Docker Compose编排把SpringBoot应用、MySQL、Redis、MinIO放到同一台服务器上各容器通过内部网络通信。应用镜像基于eclipse-temurin:17-jdk构建时用Maven打包mvn clean package -DskipTests docker build -t community-garbage:1.0.0 . docker-compose up -d需要注意的点是MySQL初始化脚本和MinIO初始化权限要在容器启动时完成。生产服务器上数据卷一定要挂载出来不然容器一删数据全没。我第一次部署时就因为没挂载MySQL数据卷升级镜像后数据直接丢失好在当时还是测试环境教训惨痛。5.2 前端项目打包放进SpringBoot的静态资源目录有一步很多教程没讲明白Vue前端打包后可以直接把dist目录里的文件复制到SpringBoot的src/main/resources/static下这样前端后端合并在一个SpringBoot应用里。但这样做有一个前提前端路由要改成history模式并且后端要配置一个路由兜底把非API路径的请求转发到index.html否则刷新页面就是404。我的习惯是不合并前后端分开部署。前端静态文件丢Nginx接口请求反代到SpringBoot这样重前端和重接口的场景都能灵活扩缩容。直接合并的方式适合部署环境极其有限的场景比如学校机房只有一台服务器。5.3 常见问题速查表与避坑思路问题现象排查思路解决建议设备数据上报失败看接口白名单是否放行验签逻辑是否一致本地用Postman模拟设备请求先用跳过签名模式调试积分出现负数扣减SQL缺少余额条件判断使用条件更新SET balance balance - ? WHERE balance ?WebSocket连不上检查Nginx代理配置、反向代理是否开启升级头添加Upgrade和Connection请求头定时任务所有任务都不执行SpringBoot默认调度线程池只有1个线程且被阻塞配置ThreadPoolTaskScheduler设置池大小JWT登录后接口报403Security过滤器链顺序错误确认JwtAuthenticationFilter在用户密码过滤器之前注册Vue打包后接口404没配置代理或地址拼写错误检查BaseURL使用环境变量区分环境这些坑都是我实际踩过的。尤其是Spring Security过滤器链顺序那个当时卡了一整个下午后来把过滤器执行日志打开才看到JWT过滤器根本没被调用因为过滤器链的注册顺序错了。5.4 性能优化与压测经验系统上线前我做了简单的JMeter压测模拟300个用户同时投放垃圾。当天就暴露了两个问题一是登录接口没有限流导致同一账号疯狂请求二是积分流水表在大量插入时出现了锁等待。对策分别是对登录接口加Redis计数器限流以及将积分流水插入改为批量提交。压测的意义不一定是要测出系统能扛多少QPS而是要找到最容易崩溃的薄弱点提前加固。查询性能上给查询频率高、数据量大的表加索引是最直接的手段。有一个配置文件表每天加载很多次我把热数据放到了Redis里设置60秒过期数据库压力一下就降下来了。这种优化其实非常朴素但对单体应用来说足够有效。6. 总结与个人实操体会做这个系统的过程中我最大的体会是“功能写完只是开始”。设备对接、积分规则、工单闭环、推送时机每一个节点都要站在真实使用者的角度去想。居民不会关心你用了什么设计模式他只在乎投放后积分有没有到账清运员不会关心你的表结构设计得多优雅他只在乎工单派发合不合理、到现场有没有活可干。很多毕设项目做完就扔了但如果真的要去社区试点这些细节才决定系统的成败。最后分享一个小技巧。如果你用的是SpringBoot 3.x遇到依赖冲突问题先不要急着改代码用Maven的依赖树命令查一下mvn dependency:tree -Dverbose然后观察spring-boot-starter-parent版本和子模块版本是否一致。很多ClassNotFoundException、NoSuchMethodError都不是代码问题而是依赖版本被其他模块改写了。搞清这一条能少走很多弯路。个人建议如果你准备做同类项目可以先从设备上报接口和积分流水这两条主线入手跑通以后再补管理后台和报表功能。主干一旦通了后面的模块只是规则的堆叠。技术栈SpringBoot Vue MySQL MinIO Redis已经是这类项目的斤两剩下的就看你怎么把业务设计得足够有说服力了。