1. 项目概述这套系统到底在解决什么问题仓库里的物资越堆越多采购单、领用单还靠Excel来回传盘点的时候拿着纸笔挨个数——这套物资综合管理系统最初就是冲着这些痛点来的。整个项目采用SpringBootVue3MyBatisMySQL的前后端分离方案把物资从入库、出库、调拨、盘点再到报废的生命周期全部收拢到同一个系统里管理。我接手这个项目的时候业务方提的核心诉求就三条第一每种物资在哪个库位、有多少、最近什么时候动过必须一眼能查到第二出入库操作要留痕谁在什么时间经手了什么物资追溯链不能断第三库存低于安全线的时候要能自动提醒别等到生产等着用料了才发现仓库空了。这套系统最终交付的形态就是一个标准的前后端分离Web应用后端暴露Restful接口前端通过HTTP请求完成全部交互数据库只存数据不掺和业务逻辑。技术栈上没有追新求奇SpringBoot负责把后端的配置和装配成本压到最低MyBatis让SQL写在XML里随时可以手动调优Vue3用组合式API把页面的逻辑组织得比Vue2时代清爽很多MySQL则稳稳托住关系型数据的落盘。如果你是正在学Java全栈的开发者或者公司需要一套内部物资管理工具但找不到合适的开源方案这个项目的拆解过程会很有参考价值。下面我会把系统的设计思路、核心表结构、前后端关键实现、部署步骤以及实际踩过的坑一条一条讲清楚。2. 为什么偏偏选这套技术组合很多初学者拿到一个项目先问“用什么框架”我建议反过来——先看业务要什么再选框架。物资管理系统的特点是典型的CRUD密集型业务记录多、查询条件多、报表多但并发量不大单表单据的修改频率也不高。这种场景下稳定、易维护、上手成本低比什么都重要。2.1 SpringBoot把繁琐的配置收进约定里早期用Spring MVC搭项目光是applicationContext.xml、springmvc-servlet.xml这些配置文件就能写一整天。SpringBoot最直接的贡献是“约定优于配置”——内嵌Tomcat一个main方法就能启动自动装配干掉了一大半模板代码。对物资管理这种需要快速迭代的系统来说SpringBoot意味着新同事入职当天就能把服务跑起来看接口文档写前端不用先啃一个月的框架配置文件。选SpringBoot还需要考虑版本。我这次用的是SpringBoot 2.7.x因为它的生态最成熟网上资料多遇到问题好排查。如果你的项目打算用SpringBoot 3.x要考虑JDK 17、jakarta命名空间迁移这些变化短期内踩坑概率会大一些。另外如果你要对接国产化数据库比如金仓SpringBoot 2.7.x做读写分离配置也相对好处理这一点后面部署章节会提到。2.2 Vue3组合式API让复杂页面不再难维护物资管理的前端页面不少但每个页面的复杂度其实可控。真正让我从Vue2切到Vue3的原因是组合式API带来的代码组织自由度。拿入库单页面举例Vue2时代你要在data、methods、computed、watch几个选项之间来回跳一个功能相关的逻辑被拆得七零八落Vue3里把这些逻辑收进setup函数按功能模块拆成独立的composition函数比如useStockIn就是一个自定义hook内部包含表单校验、提交、库存联动刷新、操作日志记录页面模板里只需要调用它。当然Vue3也有让人头疼的地方比如响应式代理的坑。深度监听对象的时候如果直接对reactive对象做解构响应性就丢了必须用toRefs或者toRef包一层。这种细节我放在后面的问题排查部分专门讲。前端UI组件库我选的是Element Plus主要是看中它对form校验和table操作封装得顺手。库存盘点、出入库台账这些页面用el-table el-form el-dialog组合几行代码就能拼出一个带弹窗编辑的完整页面。如果你喜欢Ant Design Vue这套系统的后端接口完全不受影响前端替换成本也不高。2.3 MyBatisSQL就该握在开发者手里为什么不用MyBatis-Plus或者Spring Data JPA不是说它们不好而是物资系统里动态SQL的场景太多了。查库存台账的时候“物资分类”“库位”“入库时间范围”“状态”这些筛选条件可能任意组合JPA的Specification虽然也能做动态查询但写起来远不如MyBatis的if标签直观。MyBatis的核心优势在于把SQL显式暴露在你面前。遇到慢查询直接把XML里的SQL抄出来放到MySQL里EXPLAIN一下索引建在哪、哪里走了全表扫描一目了然。JPA那种自动生成的SQL排查起来反而隔了一层。这个项目里我还自定义了几个TypeHandler处理特殊字段。比如物资状态用int存但前端展示时要变成“正常/停用/报废”这样的中文我写了一个StatusTypeHandler在查询时自动转换盘点记录里的差异明细用JSON字符串存储通过插入和查询的TypeHandler做对象和JSON字符串互转避免为了一个明细字段再拆好几张表。2.4 MySQL关系型数据的稳妥人选物资系统对事务的要求很明确一张入库单要同时更新主表、明细表、库存表任何一步失败都要整体回滚否则账实就对不上。MySQL配合InnoDB引擎的事务和行级锁完全扛得住。存储引擎我明确指定InnoDB禁用MyISAM因为MyISAM不支持事务一个误操作可能让整批库存数据出问题。数据库版本用8.x字符集utf8mb4。之所以不用utf8是因为物资名称里可能带生僻字、emoji或者特殊符号比如品牌名称里的圆圈R标志utf8mb4才能完整存下来。3. 数据库设计核心表结构是怎么拆出来的物资系统的表设计是整个项目的根基。表结构没设计好后面写多少代码都是在填坑。我按“主数据-单据-库存-日志”四个维度来拆这个思路可以沿用到绝大多数进销存类系统。3.1 物资分类与物资档案主数据的建模物资分类表material_category字段不多但做了父子级设计支持多级分类。核心字段如下字段类型说明idbigint主键自增parent_idbigint父分类ID顶级为0category_namevarchar(50)分类名称category_codevarchar(20)分类编码sort_orderint排序号statustinyint1启用 0停用这里有个容易犯的错误一个分类下的物资如果要统计总库存不能用JOIN反复查子分类正确做法是把编码设计成层级编码比如0101、010101然后用LIKE前缀匹配效率比递归查询高得多。物资档案表material_info是系统的核心主数据字段大概有物资编码、名称、规格型号、计量单位、分类ID、默认库位、安全库存、最高库存、状态正常/停用/报废。安全库存字段很重要它是后面预警功能的数据来源。物资编码建议用纯数字流水号或者“分类编码序号”的格式前端表单自动生成不允许手工输入避免重码。我当时还加了唯一索引在material_code上DB层面兜底防重。3.2 出入库与库存单据流和数据流分开出入库单我设计了主子表结构。主表stock_in_out_master记录单据号、单据类型1入库 2出库 3调拨入 4调拨出 5盘点调整、经手人、经办部门、业务时间、备注、审核状态子表stock_in_out_item记录每一条物资明细包括物资ID、数量、单价、金额、库位。为什么拆主表和子表因为一张入库单可能有几十个明细如果全部塞进一张表冗余严重而且查询和事务都不好维护。主子表用bill_no关联事务里先插主表再插子表任何一条失败整体回滚。库存表inventory_stock的设计要特别强调一下。它不按单据存而是按“物资库位”维度存当前实时数量。每次出入库审核通过后同时更新这张表。表结构如下字段类型说明idbigint主键material_idbigint物资IDwarehouse_idbigint仓库IDlocation_codevarchar(20)库位编码quantitydecimal(18,2)当前库存数量lock_quantitydecimal(18,2)锁定数量update_timedatetime最后更新时间locked_quantity这个字段容易忽略但在实际业务里非常关键。比如某个物资被领用单占用但还没出库库存不能先被下一次出库扣走。有锁定数量字段就能实现对库存的预占。3.3 盘点与操作日志保证账实一致盘点单stock_take记录盘点批次、盘点时间、参与人员、状态。盘点明细stock_take_item记录每一项物资的账面数量、实盘数量、差异数量、差异原因。盘点的核心逻辑是实盘数和账面数不一致时生成差异记录由负责人确认后做库存调整。这个过程不能自动执行必须有人工审核环节防止误操作。操作日志operation_log是我的加字段之一。它记录所有关键操作谁、什么时间、对哪张单、做了什么修改。因系统初始版本没设计日志表上线后出了笔糊涂账——有人误操作把出库单审核了查不到操作人靠数据库binlog才捞出来。加了日志表之后所有状态流转都能在界面上直接查省了无数扯皮。表设计到这里还有两个索引需要特别提一下。第一stock_in_out_master的bill_no要建唯一索引第二inventory_stock的material_id warehouse_id location_code要建联合唯一索引防止重复库存记录。4. 前后端核心实现一条入库单是怎么走完的数据库设计好之后功能开发其实就是沿着数据流往下走。我挑最典型的入库场景把前端到后端到数据库的完整链路拆开讲。4.1 项目目录结构与代码分层后端采用Maven多模块或者单模块分包的结构。单模块分包对我这个体量够用了按controller、service、mapper、entity、dto、common包拆开。通用返回体Result 统一code、message、data三个字段Controller层只做参数接收和结果封装不写业务逻辑Service层做事务和业务校验这是系统的关键Mapper层只写SQL和映射。前端目录用Vite初始化的标准Vue3项目核心是src/api、src/views、src/router、src/stores。api目录下每个模块对应一个JS文件比如stockIn.js里封装了所有入库单相关的接口请求函数views目录按页面功能分子文件夹stores目录里放Pinia的store用来保存当前登录用户的token和权限信息。4.2 后端入库接口的事务与校验逻辑后端入库接口核心逻辑分三步幂等校验、数据落库、库存更新。前两步用代码控制第三步用SQL原子操作控制。幂等校验是很多系统容易漏的环节。前端提交表单时如果网络抖动用户可能点两次“提交”如果没有幂等机制就会生成两张入库单。我的做法是前端生成一个uuid作为请求号后端在master表上对request_id做唯一索引插入时如果遇到重复request_id直接返回“请勿重复提交”。Service层关键代码片段如下Transactional(rollbackFor Exception.class) public StockInResult createStockIn(StockInMasterDTO dto) { // 1. 幂等校验requestId不能重复 if (stockInMapper.checkRequestId(dto.getRequestId()) 0) { return StockInResult.duplicated(); } // 2. 保存主表和明细表 StockInMaster master convertToMaster(dto); stockInMasterMapper.insert(master); for (StockInItemDTO itemDTO : dto.getItems()) { StockInItem item convertToItem(itemDTO); item.setBillNo(master.getBillNo()); stockInItemMapper.insert(item); } // 3. 更新库存利用SQL原子自增避免并发问题 for (StockInItemDTO itemDTO : dto.getItems()) { inventoryMapper.increaseStock( itemDTO.getMaterialId(), itemDTO.getWarehouseId(), itemDTO.getLocationCode(), itemDTO.getQuantity() ); } // 4. 记录操作日志 operationLogService.record(入库单, master.getBillNo(), 创建); return StockInResult.success(); }库存更新的SQL是UPDATE inventory_stock SET quantity quantity #{quantity} WHERE material_id #{materialId} AND warehouse_id #{warehouseId} AND location_code #{locationCode}用数据库层面的原子操作而不是先查询再加再更新这样才能避免并发时扣错库存。事务注解Transactional(rollbackFor Exception.class)也要注意rollbackFor必须加上否则遇到受检异常事务不会自动回滚这是Spring事务的经典坑之一。4.3 前端Vue3组合式API的组织方式前端的入库单页面我按三步走。第一步用reactive定义表单数据模型与校验规则第二步用onMounted加载下拉选项物资分类、仓库、库位、经办人第三步点击提交时调用api层封装的函数。代码逻辑尽量抽取到composition函数里// useStockIn.js import { reactive, ref } from vue; import { createStockIn, getMaterialList } from /api/stockIn; export function useStockIn() { const loading ref(false); const form reactive({ requestId: , supplierId: null, items: [] }); const addItem (material) { form.items.push({ materialId: material.id, materialName: material.name, quantity: null, price: null }); }; const submit async () { loading.value true; try { form.requestId generateUuid(); const res await createStockIn(form); if (res.code 0) { ElMessage.success(入库单提交成功); } else { ElMessage.warning(res.message); } } finally { loading.value false; } }; return { loading, form, addItem, submit }; }这里要注意一个问题loading.value false不能只写在try块里要放在finally中否则接口报错时loading永远卡在true用户会以为系统卡死了。模板层用Element Plus的el-table展示明细用户点击“添加物资”按钮弹出对话框里面用远程搜索组件选择物资选中后自动带入物资编码、名称、规格、单位。提交按钮上绑定 :loadingloading防止重复提交虽然后端有request_id兜底但前端交互体验上还是要先拦住一次。4.4 动态SQLMyBatis里最常用的一招查询库存台账页面时筛选条件非常灵活物资分类、库位、状态、库存数量区间、时间范围用户可能只用其中任意几个。MyBatis动态SQL在这里发挥了最大价值!-- 库存台账查询 -- select idlistInventories resultTypecom.example.vo.InventoryVO SELECT m.material_code, m.material_name, m.spec, i.warehouse_id, w.warehouse_name, i.location_code, i.quantity, i.lock_quantity, i.update_time FROM inventory_stock i LEFT JOIN material_info m ON i.material_id m.id LEFT JOIN warehouse w ON i.warehouse_id w.id where if testmaterialName ! null and materialName ! AND m.material_name LIKE CONCAT(%, #{materialName}, %) /if if testcategoryId ! null AND m.category_id IN ( SELECT id FROM material_category WHERE id #{categoryId} OR parent_id #{categoryId} ) /if if testwarehouseId ! null AND i.warehouse_id #{warehouseId} /if if testminQuantity ! null AND i.quantity gt; #{minQuantity} /if /where ORDER BY i.update_time DESC LIMIT #{offset}, #{pageSize} /selectwhere标签会自动处理首个条件前面的AND不用手工写“WHERE 11”这是很多新手容易忽略的细节。另外和在XML里必须用转义符gt;和lt;否则XML解析会报错。4.5 预警功能的实现思路库存预警是本系统比较有亮点的功能。实现不复杂在material_info表里有safety_stock字段查询台账时用一条SQL算出所有低于安全库存的物资然后在前端Dashboard展示并自动生成一条待办提醒通知给仓库管理员。查询SQL如下SELECT m.material_code, m.material_name, i.quantity, m.safety_stock, (m.safety_stock - i.quantity) AS shortage_qty FROM inventory_stock i LEFT JOIN material_info m ON i.material_id m.id WHERE i.quantity m.safety_stock AND m.status 1 ORDER BY shortage_qty DESC;这里的排序和下限字段都做了索引优化实际测试几万条数据秒开。要注意的是预警不能只在查询时算一次我加了一个定时任务Spring的Scheduled注解每天凌晨扫一遍库存低于安全线的物资自动生成一条预警消息推送到管理员的待办列表里。5. 环境准备与部署运行从零把这个系统跑起来这部分我按自己的实操记录来写。本地开发环境是Windows 11 JDK 8 Maven 3.8 Node.js 16 MySQL 8.0这套组合在绝大多数公司里都能直接复现。5.1 MySQL数据库初始化第一步创建数据库和账号CREATE DATABASE IF NOT EXISTS material_management DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER IF NOT EXISTS material_userlocalhost IDENTIFIED BY your_password; GRANT ALL PRIVILEGES ON material_management.* TO material_userlocalhost; FLUSH PRIVILEGES;然后把项目里resources/sql目录下的init.sql导入数据库。这里有个提示不同的MySQL客户端导入脚本时如果遇到“Unknown collation”之类的报错基本是SQL文件里指定了本地客户端不认识的排序规则直接改成utf8mb4_general_ci即可。5.2 后端配置与启动在application.yml里配置数据源、MyBatis和端口server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/material_management?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: material_user password: your_password mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.entity configuration: map-underscore-to-camel-case: trueJDBC URL里的allowPublicKeyRetrievaltrue是为了解决MySQL 8.x连接时报“Public Key Retrieval is not allowed”的问题这个不写经常会遇到。serverTimezoneAsia/Shanghai是为了时间类型的时区一致性漏了的话数据库存的明明是14点查询出来可能变成6点。启动方式不用IDE插件直接命令行mvn clean package -DskipTests java -jar target/material-manage-1.0.0.jar如果公司要求对接国产化数据库比如金仓SpringBoot 2.7.x下只需要替换数据库驱动和方言配置SQL基本兼容这里提一句供有需要的朋友参考。5.3 前端安装与启动前端用Vite作为构建工具。项目里package.json已经配置好依赖直接执行npm install如果npm install速度慢或者卡住换成淘宝镜像源npm config set registry https://registry.npmmirror.com启动开发服务npm run devVite默认端口是5173为了对接后端8080接口我在vite.config.js里配置了代理避免开发时天天处理跨域问题export default defineConfig({ plugins: [vue()], server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } })这样前端请求/api/stock/in/list时会被代理转发到http://localhost:8080/stock/in/listCookie和Session都不会有跨域问题。生产环境部署时我习惯在前端执行npm run build生成dist目录然后把dist目录丢到Nginx里Nginx再反代后端的8080端口。SpringBoot内嵌的Tomcat不带静态资源托管能力用它硬扛前端资源文件一来性能不够二来配置麻烦直接交给Nginx处理是业界主流做法。6. 常见问题与排查技巧实录本部分是我在敲代码和线上运维中反复踩过的坑单独整理出来每个问题都附上排查思路和正确答案。6.1 MySQL连接报错“Public Key Retrieval is not allowed”这是MySQL 8.x最常见的坑之一原因在于8.x默认使用caching_sha2_password认证插件客户端首次连接时需要从服务器获取公钥。解决方式就在JDBC URL里加allowPublicKeyRetrievaltrue或者用useSSLfalse配合降低安全校验级别。这两个参数我建议都加上不要问为什么照着写就行。6.2 前端请求跨域开发环境里跨域统一交给Vite的proxy处理不要在后端Controller上加CrossOrigin来临时解决。原因很简单CrossOrigin(*)会让生产环境的Cookie携带和权限控制全部失效你在开发时图省事生产环境就得返工。用代理不仅干净还能模拟生产环境的转发路径提前暴露问题。6.3 MyBatis查询结果全是null排查三步走第一步看实体类字段名和表字段名是否对应如果表字段是下划线命名、实体类是驼峰命名就必须开启map-underscore-to-camel-case: true这一步配置在application.yml里第二步看SQL的查询列是否加了别名多表JOIN时同名字段必须加别名区分第三步看TypeHandler是否正确匹配自定义TypeHandler没注册时框架会走默认处理器返回类型就可能错乱。90%的null问题都逃不出这三条。6.4 前后端时间字段差了8小时这个问题我遇到过好多次根因是时区不一致。数据库连接没指定serverTimezone时JDBC会取JVM默认时区而应用服务器和数据库服务器可能在不同时区。解决办法是在JDBC URL里明确指定serverTimezoneAsia/Shanghai同时MySQL的time_zone变量也改成08:00。如果JPA或MyBatis做时间转换还有偏差就在Jackson的序列化配置里加时间格式化Bean public Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() { return builder - builder .serializers(new LocalDateTimeSerializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))) .deserializers(new LocalDateTimeDeserializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); }6.5 事务不生效的排查清单事务不生效是SpringBoot开发里最坑的问题之一。我整理过一个排查清单确认ServiceImpl类是否被Spring管理有没有Service注解确认入口方法是否是public确认是不是在同类内部调用方法内部调用走的是this引用而不是代理对象Transactional会失效确认rollbackFor是否配置了异常类型默认只回滚RuntimeException确认数据源是不是配置了多数据源导致事务管理器未指定。这五条按顺序排查基本能覆盖所有场景。6.6 前端批量更新后列表不刷新的问题业务场景用户在页面上勾选多条记录执行“批量通过”操作成功后表格数据没有自动刷新。原因是操作完成之后只调了接口没有刷新查询。解决办法很简单在批量操作成功回调里调用一次fetchList()但要注意这个问题如果列表页挂在keep-alive里且使用了onActivated而不是onMounted刷新函数可能没被正确调用。Vue3里配合keep-alive时onActivated的触发时机和onMounted不同容易忽略这个细节。7. 上线后我还会做什么优化项目上线跑通之后我通常不会停在该版本。后续考虑的方向有几个一是把操作日志升级成独立的日志服务用AOP注解方式记录方法级日志省得每个Service里手工调用二是引入缓存物资分类这种几乎不变的字典数据可以放到Redis里不必每次都打MySQL三是在报表模块上加图形化展示出入库趋势、库存周转率这些指标用ECharts画出来管理层看起来更直观四是加上导入导出功能Excel模板导入物资信息、导出库存台账仓库老师傅用Excel的习惯很难改这个功能对他们来说最实用。8. 最后分享几个实在的小技巧聊点排错的题外话。实际做物资系统这类进销存项目时有几个习惯帮我节省了大量时间。第一所有查询接口的列表参数包里一定带上pageNum、pageSize分页查询能挡住绝大多数数据量膨胀的性能问题。第二删除操作一律用逻辑删除加一个deleted字段不要物理DELETE。出了事故还能还原这是数据管理的底线思维。写SQL的时候记得每个查询都带上AND deleted 0这个条件漏掉的话历史数据就会莫名其妙出现在列表里。第三接口数据返回模板固定所有接口返回ResultT的同一结构。前端拦截器里面做统一错误处理后端代码写起来一致不然每个接口的返回格式都不一样前端联调会疯掉的。我自己的体会是这类管理系统最大的敌人从来不是框架而是业务逻辑里的细节。物资管理看起来简单真跑起来之后库存精度、单据编号连续性、多人并发操作一致性每个点都能让系统崩给你看。所以我在做这套系统的时候特别强调事务边界和数据幂等前期多花一点心思上线之后就能少熬好几个夜。
