做物资捐赠和分配系统这个选题本身就是在啃一块硬骨头。业务逻辑不复杂但牵扯的角色多、状态多、线下场景杂稍不注意就会做成一个“能跑但没人愿意用”的演示品。我用SpringBoot从零搭了一版把捐赠登记、库存管理、分配出库、物资追踪这几条主线全部串通源码和设计文档都整理好了。这篇文章把我整个设计思路、核心实现和踩过的坑一次性讲清楚给准备做类似管理系统的朋友一个可以直接参考的底子。1. 项目整体设计与思路拆解1.1 业务本质这不是一个CRUD系统而是一个协同管理平台很多人拿到“物资捐赠和分配系统”这个需求第一反应就是做几个表物资表、捐赠记录表、分配记录表然后套上SpringBoot的增删改查就完事了。这种做法做完以后大概率会被打回重做因为真实场景下的物资管理核心痛点根本不在“登记”上而在供需匹配和流向透明这两个地方。我设计的这套系统从一开始就明确了四个核心角色捐赠方个人或企业、受赠方需求单位、仓库管理员物资进出、系统管理员全局配置与监督。四类角色看到的界面、操作的流程、关注的数据完全不同这就决定了不能用一个简单的权限标记打天下而是要在业务模块划分上就拉开层次。整个系统我拆成了六大模块捐赠管理、物资库存、分配管理、运输跟踪、统计报表、系统管理。其中统计报表看似是附属功能实际在真实使用中是使用频率最高的模块各级管理者都需要通过数据来了解物资是否真的流向了最需要的地方。1.2 设计取舍为什么选择单系统整合而非微服务技术选型时有不少人建议我拆成微服务把捐赠、库存、物流分开部署。我的判断是这个场景不需要。物资捐赠系统的并发量、数据量都远未达到需要分布式架构的程度而微服务带来的事务一致性、服务间调用、部署复杂度对这个体量的项目完全是负担。我选择的是单体应用模块化代码结构。对外是一个SpringBoot应用对内用清晰的包结构把捐赠、库存、分配、统计等模块隔离好未来如果某个模块真的要独立部署代码层面已经具备了拆分的基础但现阶段不需要额外付出运维成本。举一个具体例子分配物资时需要同时扣减库存、生成分配单、记录物资流向明细。这三件事在单体应用里就是一个事务Transactional注解就能保证原子性。如果拆成三个微服务就需要分布式事务方案引入消息队列或Seata对一个小团队来说运维成本和复杂度都是成倍上升的。1.3 权限模型RBAC的精细化落地这套系统的权限设计我采用了RBAC基于角色的访问控制模型但在标准RBAC基础上做了两处针对业务场景的定制。第一处是数据范围的控制。普通的RBAC只控制“能不能访问这个接口”但物资系统还需要控制“能看哪些数据”。比如仓管员只能看到自己仓库的库存而不能看到其他区域的库存受赠单位只能看到分配给自己的物资及状态不应该看到全局的物资储备信息。我在查询层统一封装了数据权限过滤器根据当前登录用户的角色和所属机构自动追加查询条件避免了在每一个Service方法里手动拼接权限逻辑的繁琐。第二处是审批流的嵌入。物资分配不是仓库管理员一个人说了算的。我设计了“申请-审批-出库-确认”的四步流程受赠方提交物资申请管理员审核申请的合理性和库存余量审批通过后生成出库任务仓管员执行出库受赠方最终确认收货。这个流程用一张状态机表来控制每个节点都有对应的状态码和操作权限校验保证了每一步操作都有据可查。2. 核心技术实现与数据库设计2.1 数据库设计六张核心表如何支撑业务闭环数据库是整个系统的地基我前前后后改了四版设计最终沉淀下来的核心表结构有六张。这里我把关键字段和设计意图直接列出来你可以对照着自己建表。第一张是物资表material。基础字段包括物资名称、类别、单位件/箱/吨、规格型号但真正关键的是三个扩展字段库存总量、可用库存、锁定库存。这三个字段的设计值得细说。库存总量就是实际仓库里的数量锁定库存是已经被分配单占用但还没实际出库的数量可用库存就是总量减去锁定。为什么要拆这么细因为分配单生成之后到仓管员实际出库之间有一个时间差如果不做锁定两个审批员可能同时把最后一批物资分配给不同单位超卖问题就出现了。第二张是捐赠单表donation_order。每个捐赠单有单号、捐赠方信息、捐赠物资明细通过子表实现一对多、状态待入库/已入库/已上架。捐赠物资到达仓库后仓管员要做入库确认此时系统会自动为对应物资增加库存同时生成一条入库流水。这里有一个细节捐赠单上必须记录有效期尤其是食品、药品类物资我加了临期预警功能效期不足30天的物资在分配时会被优先匹配避免物资过期浪费。第三张是分配单表allocation_order。这是业务流转的核心单据包含申请单位、申请物资及数量、审批状态、出库状态、收货确认状态。每次分配操作会联动产生两条流水一条是物资出库流水减少可用库存一条是分配明细流水记录给了谁、给了多少。第四张是单位表organization统一维护捐赠方和受赠方的信息。这里我把企业和个人都抽象成“单位”来处理个人捐赠者可以视为一个特殊的单位主体字段上做兼容就行。受赠单位需要维护联系人和联系电话方便物流环节的对接。第五张是系统用户表sys_user。关联单位表和角色表实现“用户-角色-权限”的标准RBAC链路。用户表里我预留了机构ID字段用于数据权限的过滤。最后是操作日志表operation_log。这个表容易被忽略但实际运行中非常重要。所有关键操作入库、出库、审批、修改库存都写入日志配合Spring的AOP机制实现不侵入业务代码。审计追踪在物资管理场景里不是可选项而是刚需。出了问题通过日志能准确还原每一步操作的操作人、时间和内容。2.2 库存扣减的并发安全方案库存操作是这个系统里最需要严谨对待的地方。一开始我直接用UPDATE material SET available available - #{num} WHERE available #{num}这样的条件更新语句来扣减库存依靠数据库的行锁机制保证并发安全。后来在高并发测试中发现一个隐患如果同一时刻大量分配单都在操作同一个物资数据库的行锁竞争会造成部分请求等待超时。最终我采用的方案是乐观锁事务重试的组合策略。在物资表上增加一个version字段每次扣减库存时先查出当前版本号更新时带上WHERE version #{oldVersion}如果更新影响行数为0说明数据被其他事务修改了就重新查询并重试最多重试三次。这个方案的好处是读操作完全无锁写操作的冲突概率在物资管理场景下很低重试三次基本不会出现失败。还有一个容易踩坑的点库存扣减和分配单生成必须是同一个事务。否则就会出现分配单生成了但库存没扣减成功实际库存和系统数据对不上的情况。我在AllocationService的createAllocation方法上加了一个事务注解方法内部先检查库存、再生成分配单、最后扣减库存任何一步异常都会整体回滚。2.3 报表模块用聚合查询替代跑批任务统计报表如果按传统的“每天凌晨跑批生成数据表”来做会面临一个时效性问题管理者下午想看的报表数据却是早上8点的体验很差。我调研了使用场景后发现物资系统的数据量完全撑得起实时统计没必要定时跑批。我直接在SQL层面写聚合查询用GROUP BY加时间维度来统计日报、周报、月报数据。比如要统计“过去30天各类物资的入库/出库趋势”一条SQL就能解决查询耗时才几十毫秒。配合SpringBoot的Cacheable缓存机制把高频查询的结果缓存起来设置5分钟的过期时间既保证了时效性又减轻了数据库压力。报表模块我觉得最有价值的是供需匹配分析。通过对比同类别物资的入库总量和分配出库总量计算出供需缺口在首页仪表盘上直观展示哪些物资紧缺、哪些物资积压。这个功能在真实救灾场景里非常实用帮助管理者动态调整物资募集方向避免出现“帐篷堆成山棉被却不够发”的尴尬局面。3. 实操过程与核心环节实现3.1 项目搭建与依赖配置整个项目基于SpringBoot 2.7.x版本JDK选用1.8数据库使用MySQL 8.0ORM框架选择了MyBatis-Plus而不是原生MyBatis。理由很简单MyBatis-Plus提供的基础CRUD方法能省掉大量重复的XML编写工作而业务需要的复杂动态查询它也支持用QueryWrapper以Java代码的方式构建配置同样灵活。前端我没有采用前后端分离架构而是用Thymeleaf模板引擎做服务端渲染这对于中小型管理系统来说开发效率最高不需要额外搭建前端工程和联调接口。核心依赖在pom.xml里就是几个关键组件我贴一下主要配置dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependenciesSpring Security的引入可能有人觉得重了但对于管理系统来说安全框架是标配。我用它实现了登录认证、密码加密BCrypt、会话管理。配置上做了一些自定义登录接口放行其余接口全部要求认证静态资源放行自定义UserDetailsService从用户表加载用户信息和角色权限。3.2 核心业务流程的前后端衔接我挑两个核心场景讲一下完整的数据流转过程这部分是理解和二次开发这个系统的钥匙。场景一捐赠物资入库捐赠方在前端页面填写捐赠登记表提交后生成一张待入库状态的捐赠单。仓管员登录系统后在待入库列表中看到这张单子点击“入库确认”进入入库操作页面。页面展示捐赠单的物资明细仓管员核对实物无误后填写实收数量有可能捐赠100箱实际到货只有98箱提交入库。后端的逻辑是这样的入库确认接口首先校验捐赠单状态必须是“待入库”防止重复入库。然后遍历物资明细对每项物资执行库存增加操作同时写一条入库流水记录。全部处理成功后把捐赠单状态置为“已入库”并调用AOP记录操作日志。整个方法被Transactional包裹处理过程中任何一项物资失败了所有操作都会回滚不会出现“入库单状态更新了但库存没加”的情况。场景二物资分配与出库受赠单位在系统里提交物资申请单填写需要的物资种类、数量和用途说明。管理员在审批列表中看到申请点击查看详情系统会实时显示当前库存余量供管理员参考。审批通过后系统自动生成分配单并将对应数量的物资锁定。仓管员在出库任务列表中看到待出库的分配单执行出库操作。出库成功后系统将锁定库存转为实际扣减更新分配单状态为“已出库”。受赠方在系统里做“收货确认”整个分配流程闭环状态更新为“已完成”。每个状态变更的节点系统都会尝试推送通知给相关方包括站内消息和邮件通知。3.3 代码实现要点Service层的职责划分与事务边界代码层面的架构我保持了经典的Controller-Service-Mapper三层结构。在Service层严格遵守一个核心原则事务从Service方法开始不在Controller层做业务操作。举例来说生成分配单的方法内部包含查库存、验权限、生成单号、插入分配单、扣库存、记录日志六个步骤。这些步骤必须在一个事务里完成所以它们都在同一个createAllocation方法内。在Service层内部我还做了一个领域对象的划分。DonationDomainService负责捐赠领域逻辑AllocationDomainService负责分配领域逻辑InventoryDomainService负责库存的增减和冻结解冻操作。这样做的好处是当分配逻辑里需要扣库存时调用的是InventoryDomainService的公开方法而不是直接操作Mapper。领域服务之间的调用边界清晰未来调整库存规则时不需要去改分配模块的代码。我分享一个我觉得整套设计里比较巧妙的地方分配单号的生成。单号格式是“AP 年月日 四位随机数”例如AP202501150032。为什么不直接用数据库自增ID因为分配单号会出现在物流单据和对外沟通中自增ID既容易暴露业务量又不好记忆和核对。我在代码里写了一个单号生成器使用Redis的INCR命令保证同一天内的序列号不重复即使未来部署多实例也不会撞号。3.4 前端页面的实用化设计前端部分我没有做过多的花哨效果主要精力花在了操作效率上。三个页面我花的时间最多。第一个是物资入库操作页。这个页面要支持一次处理多个物资条目每行有物资选择器、数量输入框、有效期输入框。如果用原生HTML写表单校验和动态增删行会非常繁琐我用了少量的JavaScript封装实现了新增行、删除行、数量联动校验实收数量不能大于申报数量。第二个是库存总览页。这个页面默认展示所有物资的库存列表支持按类别筛选、按名称搜索、按库存余量排序。每一行都配了独立的操作按钮入库、分配、查看流水。因为这个页面是仓管员和高频使用者每天打开次数最多的页面我把所有常用操作的入口都聚合到了一起尽量让用户在一个页面内完成大部分工作。第三个是分配审批页。审批页不仅要展示申请单的基本信息和物资明细还要并排显示库存余量参考。我特意做成双栏布局左边是申请信息右边是当前库存快照。审批人不需要离开当前页面就能完成库存核对审批效率明显提升。这里我用了Thymeleaf的模板片段功能把库存信息列表做成一个独立片段在审批页通过th:replace引入同时这个片段也能被其他页面复用。4. 常见问题与排查技巧实录4.1 环境与部署阶段的经典报错先说你一上来就可能遇到的坑。用java -jar方式部署后很多新手会发现上传的文件或者生成的日志不知道存到哪里了于是习惯在代码里写绝对路径比如/root/upload/或者D:\upload\。这个做法我强烈建议戒掉。我把上传路径和日志路径统一配置在application.yml里用${upload.path}这样的占位符引用。部署时通过--spring.config.additional-location外部指定配置文件这样代码和环境就完全解耦了。环境阶段比较常见的一个问题是Spring版本与JDK版本不兼容。SpringBoot 2.7.x默认依赖的Spring Framework 5.3.x在JDK 8到JDK 17上都能跑但如果你用了JDK 17以上还要注意一些反射相关的警告。很多人遇到“项目启动直接失败日志一堆ClassNotFound”的情况十有八九是明明项目指定了JDK 8IDEA里Project SDK和Module SDK没同步改编译用的还是高版本JDK。我的排查习惯是先看maven-compiler-plugin的source和target配置再核对IDEA的Project Structure不要一上来就怀疑依赖冲突。还有一个高发问题是MySQL连接报Public Key Retrieval is not allowed。这是MySQL 8.0以上的连接安全机制导致的解决方案是在JDBC连接串上增加allowPublicKeyRetrievaltrueuseSSLfalse。这类配置小坑属于“网上答案很多但当时就是找不到”你看到了就顺手记一下。4.2 并发场景下库存数据不一致的实战排查库存数据不一致是我遇到的最棘手问题之一。具体表现是分配单明明生成了但过了几分钟库存数量“回弹”了好像扣减没生效。这个现象在低并发测试时不会出现一旦用JMeter并发跑库存扣减接口复现率就会显著提高。排查过程我是这样走的。第一步查看MySQL的隔离级别确认是不是默认的REPEATABLE READ。第二步查看事务日志确认分配接口的事务确实提交了。第三步给库存扣减的SQL加上FOR UPDATE行锁重新压测发现问题仍然偶发。第四步我把事务日志和SQL日志联合起来看终于发现问题所在虽然扣库存的UPDATE语句执行了但事务并没有立即提交另一个事务在这个间隙读取到了旧库存生成了超卖分配单。最终修复方案就是我前面说的乐观锁加重试。我在扣减SQL里加上了version判断条件执行UPDATE时返回影响行数如果返回值是0就抛出冲突异常由上层捕获后重新执行整个分配流程。这个方法改动量不大但对并发安全性的提升是决定性的。实测压测1000并发分配请求库存超卖数为0成功率99.9%。4.3 让系统真正稳定运行的几个习惯这套系统正式上线运行后我复盘了一些做得对的和本可以避免的习惯。给大家几个我认为价值最高的建议。日志规范这件事值得从第一天就做好。很多项目上线后出了问题排查困难是因为日志里没有任何关键业务节点的记录。我在Service层的核心方法里都加了日志输出包括入参、关键判断、操作结果日志级别统一格式里带上操作人ID和单号。遇到问题一条链路从头看到尾定位一台服务器、一个操作、一个时间点逻辑非常顺畅。数据库连接池参数值得单独调一下。SpringBoot默认的HikariCP配置偏保守默认最大连接数是10。在物资管理系统这种“用户不多但操作频繁”的场景10个连接很可能会成为瓶颈。我调成了最大连接数20最小空闲5连接超时30秒。这个调整非常见效压测时数据库连接等待的情况几乎消失。最后一点任何库存相关的操作一定要做库存流水的对账机制。我写了一个对账定时任务每天凌晨检查库存表的数据是否等于初始库存加所有入库流水减所有出库流水。不一致时自动告警定位到具体的差异物资和对应的出入库记录。这套对账机制挽救过我一次因为手动改数据库导致的数据错乱强烈推荐你也在系统里做一个。4.4 二次开发和扩展的三个方向如果你拿到这套系统想继续扩展我根据实际使用经验提供三个我认为最有价值的方向。第一个是引入消息通知渠道。当前系统的消息通知只有站内信实际使用中发现物资到达、审批通过这类信息如果通过短信或微信模板消息触达效率会高得多。SpringBoot整合阿里云短信或者微信公众平台的模板消息都很成熟建议在通知模块上做扩展。第二个是条形码/二维码的应用。每一批物资入库后可以生成唯一的二维码标签仓管员出库时用扫码枪直接扫描物资二维码系统自动匹配物资和数量替代手动录入。这能大幅降低出入库的操作时间也能减少人为录入错误。市面上的安卓扫码枪本质上就是一个蓝牙扫码枪加一个接收程序和后端对接的方式是暴露一个HTTP接口。第三个是数据分析维度的深化。当前系统已经有供需匹配分析未来可以接入地理信息在MAP上展示各区域物资储备量和分配流向管理人员一屏掌握全局。这个扩展需要引入地图组件后端接口只需要提供经纬度、区域内物资汇总数据。我个人在带这个项目的过程中最深的体会是物资系统的技术难点不在某个单独的技术点上而在如何把库存、单据、权限、流程这些零散的东西拼成一个严丝合缝的整体。每加一个功能都要想清楚它会不会影响库存数据的准确性、会不会绕过审批流程。代码写得稳妥一点、日志打得完善一点、事务边界划得清晰一点这个系统就能稳定地为一线人员提供支撑。这一版源码和文档我已经整理好了需要的可以直接拿去作为基础结合自己的业务场景做二次开发。