做Java后端这行，Spring Boot的练习项目谁都绕不开，但很多人练到“图书管理”“用户管理”这类单端CRUD就停了，简历上拿不出手。去年我完整做了一遍“基于Java Spring Boot的果蔬种植销售服务平台”，从数据库表设计到订单状态机，从种植户端到买家端，踩了一圈坑之后最大的感受是：这种带“种植端+销售端”双链条的业务，才是真正能锻炼工程思维的练手项目。
这篇文章不是讲课，就是一次项目复盘。我尽量把业务建模、技术选型、关键实现、环境坑位都讲透，适合三类人看：准备做Spring Boot实战项目但不知道选什么题的开发者，需要一套课程设计方案做参考的同学，以及想了解果蔬电商这类垂直业务和普通商城到底差在哪的从业者。
1. 果蔬种植销售平台的业务本质：它和普通电商系统的差异
1.1 普通电商的商品模型，放到果蔬行业直接失灵
如果你照着淘宝、京东那套思路去设计果蔬平台，第一版就会卡在商品表上。普通电商卖的是标准化工业品：一台手机有固定的SKU、固定的库存、固定的包装规格，上架之后半年不动价格都正常。果蔬完全不是这样。
果蔬商品的第一个特点是“按批次而不是按SKU管理”。同一块地上种出来的西红柿，今天采摘的和三天前采摘的，虽然品种一样、规格一样，但新鲜度不同、剩余可售天数不同，价格也可能不同。更麻烦的是，批发场景下买家是按“斤”或者“箱”来交易的，规格本身会随行就市调整，昨天是五斤装，今天可能就改成十斤装。你没法用一个静态的“商品编码”把这一切锁死。
第二个特点是库存会自然损耗。工业品库存只有卖出才减少，果蔬框架里，库存会随着时间推移“蒸发”——库里还有一千斤，但三天后可能只剩九百斤能卖了。我一直觉得，果蔬平台的库存表设计得不好，线上显示的数量和冷库里的实际数量对不上，那这个系统做出来就是个摆设。
所以我当时把业务基础打成了三件事：批次（Batch）、规格（Spec）、随行就市（动态价格）。核心不是“商品”，而是“今天这一批货能卖什么价、还剩多少、还能放几天”。
1.2 平台的三类角色与信息断点
这个平台里至少有三类人：种植户、平台运营方、买家。种植户负责把果蔬登记上架，平台方负责审核、定价、结算和流量，买家负责浏览、下单、收货、售后。听着和普通B2B2C平台很像，但真正的痛点在于信息断裂。
常见场景是这样的：种植户把一批黄瓜采下来，拍了张照片填了个价格，但平台不知道这批货是什么时候采的、有没有打过药、还剩几天保质期，只能靠电话来回问。买家下单之后，又不知道这批货从哪里发出、什么时候到。整个链条上没有一个人能看到“从地块到餐桌”的完整信息。
我做这个系统的想法很简单：把种植端的批次信息登记清楚，把平台端的审核与价格管理做灵活，把买家端的订单状态做牢靠，再把这三段串成一条完整的数据流。这个定位和普通商城有本质区别，所有表结构都是围绕“批次+订单+库存”三条主线展开的。
1.3 为什么选Spring Boot做底座
这种中型业务系统，用Spring Boot做底座太合适了。它默认帮我把内嵌Tomcat、自动配置、依赖管理都处理好了，起步就是几个注解的事；生态又全，MyBatis-Plus接MySQL、Thymeleaf做服务端页面、JWT做登录态，全是现成组件；最关键的是社区资料多，踩坑成本低，做课程设计或者求职项目，面试官对这个技术栈的认可度也高。
我见过不少项目非要用微服务硬拆，一个果蔬平台拆成订单服务、用户服务、库存服务三个工程，结果部署的时候自己都调不通。这类项目的合理上限就是单体+模块化分包，Spring Boot在中间这个复杂度区间里，几乎是性价比最高的选择。
2. 技术选型复盘：为什么是Spring Boot + MyBatis-Plus + MySQL
2.1 版本组合与JDK对应关系，第一坑就埋在这儿
先说结论：JDK 8 + Spring Boot 2.7.x + MyBatis-Plus 3.5.x + MySQL 5.7/8.0，这是目前最稳的组合。Spring Boot 3.x虽然已经成熟，但它要求JDK 17，而且包名从javax换成了jakarta，很多老教程和老代码直接复制过来会编译失败。如果你的开发机是JDK 8，就别看Spring Boot 3的教程硬上，版本对不上，光是导入依赖就能卡你一下午。
如果你机器上已经装了JDK 17，用Spring Boot 3.x也没问题，但要注意两点：一是数据库驱动要跟着升级，MySQL驱动得用8.0.33以上版本；二是网上大部分博客里的import语句都是javax开头的，得手动改成jakarta。我见过太多人在“明明代码一样为什么报错”上浪费时间，九成是版本体系不一致。
2.2 MyBatis-Plus：单表CRUD省事，复杂查询不啰嗦
我没有用原生的MyBatis，也没有用Spring Data JPA，选了MyBatis-Plus。原因很直接：这个项目里有大量的单表CRUD操作，比如用户管理、果蔬分类、收货地址、操作日志，用MyBatis-Plus的BaseMapper自带方法就能解决，不需要为每个表写一遍XML；而到了订单统计、库存联动这类稍微复杂的逻辑，它有LambdaQueryWrapper和分页插件，写起来也不别扭。
它的乐观锁插件我也用上了，后面会讲库存扣减，这个功能就是靠它实现的。给个实用建议：每次启动项目之前，先确认MyBatis-Plus版本是否和Spring Boot版本兼容，3.5.1配2.7.x是最稳的，再新的版本有时会有兼容性问题。
2.3 前端与服务端渲染：Thymeleaf不是落后，是够用
很多人在犹豫前端到底用Vue还是Thymeleaf。我个人的建议是：如果这是你的课程设计或第一个完整后端项目，老老实实用Thymeleaf + Bootstrap/Layui这套服务端渲染方案。理由也简单：一是你不用再单独启动一个前端工程，不需要处理跨域，部署的时候打一个Jar包就能跑；二是考核和答辩时，老师更关心你的后端逻辑，而不是前端动画。
Vue分离式当然更现代，但在单机演示、学习成本、部署复杂度这些维度上，对以业务逻辑为主的项目来说是额外负担。我见过太多人把时间耗在Vue构建配置上，最后后端没时间写。项目先跑起来，比什么都重要。
3. 核心模块拆解：种植户端、平台端、买家端各自管什么
3.1 种植户端：不是“上架商品”，而是“登记批次”
种植户端是这类平台和普通商城最大的区别所在。普通商城卖家上架商品，填的是标题、主图、库存、价格；这里的种植户上架行为，本质是登记一个“生产批次”。我设计了这样一套登记字段：果蔬名称、品种、产地、采摘日期、保质期天数、单位（斤/箱）、入库数量、建议售价、农事记录（可选填，比如施了什么肥、打了什么药）。
多说一句农事记录，这是一个很加分的功能点。果蔬消费者最关心安不安全，把农事记录和批次绑定，买家端展示出来，你的项目就有了“源头可溯”的概念。我当时还做了一个简单的二维码按钮：后台根据批次号生成一个包含该批次全部信息的链接，买家扫码就能看到这批菜的来龙去脉。虽然实现不复杂，但答辩的时候讲解效果非常好。
种植户端的库存管理也简单直接：入库就是登记批次，出库就是订单发货时扣减对应批次库存，再加上一个“报损”入口，让种植户手动冲减变质损耗的数量。有这三个操作，库存就能对得上冷库了。
3.2 平台端：审核、价格、结算三件事
平台运营方承担三个核心职责。审核是第一步，种植户登记的批次信息和价格不是直接上架的，平台要确认品种没错、产地没错、参考价合理。没有审核环节，平台上就会冒出各种乱七八糟的价格和描述，买家体验直接崩。
价格管理是果蔬平台最灵活的地方。我设计了一个独立的“价格表”，每个批次每天可以调一次价，修改不直接覆盖原价，而是插入一条新纪录，保留历史价格。这样做有个实际好处：结算对账的时候能查到“这批西红柿上架第一天卖了50单，当时单价是2.8元，第二天降到2.5元后又卖了30单”，每一笔订单的价格都说得清。
结算功能也不能缺。平台每个周期（我设置了每周）给种植户生成结算单，里面有已发货订单金额、平台服务费、退款扣减，种植户确认后走线下打款。这个模块看起来不起眼，但它是平台能活下去的商业闭环，写文档和画原型时一定要画进去。
3.3 买家端：下单容易，状态难缠
买家端的功能是标准电商那一套：分类浏览、搜索、商品详情、购物车、下单、支付（演示用模拟支付）、订单跟踪、确认收货、售后申请。看似简单，但这里最容易翻车的是订单状态的流转逻辑，我后面单独用一整节聊。
有一个电商项目普遍会忽略、但果蔬平台必须有的功能：下单时的批次状态提示。比如某批西红柿显示“距保质期还有2天”，买家会自己判断是否购买；一旦超过保质期，商品自动下架。这个规则不复杂，在商品查询时用当前日期和保质期天数做个计算就行，但能体现出你是认真理解了果蔬业务的。
4. 数据库设计：五张核心表的字段取舍与快照策略
4.1 果蔬批次表：从源头建立数据基础
设计这张表时我反复推翻过几次，最后沉淀下来的核心字段大致是这样：
| 字段 | 说明 | 设计理由 |
|---|---|---|
| id | 主键 | 常规 |
| batch_no | 批次号，如20240621-XHSJ-001 | 线下冷库按批次管理，线上要能对应 |
| vegetable_name | 果蔬名称 | 冗余，方便列表展示 |
| origin | 产地 | 溯源信息 |
| harvest_date | 采摘日期 | 计算剩余保质期的起点 |
| shelf_life_days | 保质期天数 | 过期自动下架 |
| unit | 单位：斤/箱 | 规整交易 |
| total_quantity | 入库总量 | 初始库存 |
| remaining_quantity | 剩余可售数量 | 每次扣减后更新 |
| price | 建议售价 | 平台可调整 |
| status | 待审核/在售/已下架/已售罄 | 状态驱动展示 |
注意我用了remaining_quantity而不是每次用总量减订单来计算剩余，原因很简单：报损、退货、过期都会影响库存，如果靠计算得出，结果永远是错的。干脆在业务操作发生时及时更新余量字段，查询时直接读，简单准确。
4.2 订单主表和订单明细表：为什么必须做快照
订单主表存储订单号、买家ID、总金额、下单时间、收货信息、订单状态这些通用字段。订单明细表则不一样，它不仅要存商品ID和数量，更要存“商品名称快照”和“单价快照”。
这就是快照策略。假设买家下单时西红柿单价是2.8元，第二天平台调价到3.2元，你如果只建立订单关联商品ID，再去查商品表的当前价格，历史订单金额就会全乱套。我在第一版就吃过这个亏，结算对账时价格怎么都对不上，最后才发现是关联查价的问题。后来统一改成：订单产生那一刻，就把商品名称、规格、单价、单位全部拷贝一份到订单明细表里，之后不管商品怎么改，订单永远以快照为准。这是做交易系统的基本功，但很多新课设项目都不会注意。
4.3 库存的并发安全：为什么必须加版本号
果蔬平台最怕超卖。同一批货剩100斤，三个买家同时下单各买50斤，如果不做控制，三单都会成功，库存就成了负数。这在实际业务里是事故。
我处理的方法很简单：库存表单独设计，带上一个version字段，更新时用乐观锁。对应SQL长这样：
UPDATE stock SET remaining_quantity = remaining_quantity - #{quantity}, version = version + 1 WHERE batch_id = #{batchId} AND remaining_quantity >= #{quantity} AND version = #{version};更新影响行数为0，说明库存不够或者版本变了，那这笔下单请求就要回滚并提示买家库存不足。这个方案不会锁表，并发压力不大时效率很高，也符合当前项目的体量。如果硬要用悲观锁SELECT ... FOR UPDATE，小项目里反而容易因为长事务把连接池占满。
5. 最容易翻车的三处代码实现：状态机、库存扣减、权限控制
5.1 订单状态机：不用一堆if，用Map约束流转
订单状态这块我见过太多人用if-else层层判断：先if是待付款，再if是已付款……十个状态能写出五十层嵌套，改一个状态就得追着改全部分支。我的做法是定义一个状态枚举和一个流转Map，把“从哪到哪合法”显式声明出来。
public enum OrderStatus { PENDING_PAYMENT, // 待付款 PAID, // 已付款 SHIPPED, // 已发货 COMPLETED, // 已完成 CANCELED, // 已取消 REFUNDING; // 售后中 private static final Map<OrderStatus, Set<OrderStatus>> TRANSITIONS = new HashMap<>(); static { TRANSITIONS.put(PENDING_PAYMENT, EnumSet.of(PAID, CANCELED)); TRANSITIONS.put(PAID, EnumSet.of(SHIPPED, REFUNDING)); TRANSITIONS.put(SHIPPED, EnumSet.of(COMPLETED, REFUNDING)); TRANSITIONS.put(REFUNDING, EnumSet.of(CANCELED, COMPLETED)); } public boolean canTransitTo(OrderStatus target) { Set<OrderStatus> allowed = TRANSITIONS.get(this); return allowed != null && allowed.contains(target); } }每次状态变更前先调canTransitTo校验，非法流转直接抛业务异常。这样做的好处是，状态规则集中在一个类里，加新状态时只改一处，不会散落各个Service方法里，排查问题也快。
5.2 库存扣减：先查再改必出问题，必须用条件更新
这一节已经被无数人讲烂了，但每次做项目还是会有人踩。核心教训一句话：永远不要先查库存、在Java里判断够不够、再执行更新。两个请求同时查到还有100斤，各自判断都够，各自执行扣减，最后库存变成负数。
正确做法就是我在4.3里写的那条SQL，把“库存是否充足”作为一个更新条件写进WHERE，数据库自己保证判断和更新的原子性。MyBatis-Plus的乐观锁插件其实就是帮你自动拼上version字段的更新条件，如果没有用插件，手动在XML里写这条SQL也完全可行。
这个方案有一个小坑要提醒：更新影响行数为0时，不一定是超卖，也可能是version冲突，但业务上你可以统一当作“库存紧张，请重试”来处理。演示系统这么处理没问题，生产系统则要考虑失败后的重试机制。
5.3 登录与角色权限：JWT + 拦截器，为什么不上Spring Security
权限控制这个项目我选择的是JWT + HandlerInterceptor，而不是Spring Security。理由很务实：Spring Security的学习曲线陡，对课程设计项目来说，配置一套Security的过滤器链和权限注解体系，比写业务本身还费时间；而且大多数演示场景只需要区分管理员、种植户、买家三种角色，一个拦截器完全够用。
实现思路是：登录成功以后生成一个JWT令牌，把用户ID和角色塞进自定义claims里，前端每次请求在Header里带上Authorization: Bearer <token>。拦截器里写三段逻辑：白名单放行登录接口和公开的商品查询；解析Token失败统一返回401；然后根据路径前缀做角色校验，比如/admin/**只允许管理员访问。
这里有一个很多人忽略的点：拦截器只做身份识别和粗粒度角色校验，订单归属之类的细粒度校验必须放在Service层做。比如买家A不能查看买家B的订单，这种校验不是“登录了就行”的拦截器能解决的，你必须在查询订单的Service方法里用当前用户ID做条件过滤。这个分层思想想明白了，权限这一关基本就通了。
6. 本地跑通项目的完整步骤和环境坑位
6.1 从源码到运行：四步就能把系统跑起来
这套项目的交付形式一般是“源码+数据库脚本+文档+运行视频”，拿到手之后不要急着用IDE打开，按这个顺序来：
- 用Navicat或命令行创建一个数据库，字符集选utf8mb4，然后执行项目附带的
sql脚本。脚本里一般会建表并插入初始数据，包括管理员账号、分类、示例批次和测试买家。 - 修改
application.yml里的数据库连接配置。重点看三个参数：URL里的数据库名、用户名、密码。如果MySQL是8.0以上，URL里记得带serverTimezone=Asia/Shanghai，不然时间字段会差八个小时。 - 检查JDK版本和Maven配置，确认和项目要求一致后，在项目根目录执行
mvn spring-boot:run，或者用IDE里的Spring Boot启动类直接跑。 - 启动日志里看到
Started Application in xxx seconds后，浏览器访问http://localhost:8080。
整个过程熟练的话十分钟以内。第一次跑不通多半不是代码问题，而是环境问题，看下面这三个坑。
6.2 启动失败的三个高频原因，按出现频率排
端口冲突是最常见的，8080被占用时启动日志会报Port already in use，解决方式有两种：关掉占用进程，或者在配置里换个端口，比如server.port=8081。
数据库连接失败是第二个高频原因，报错通常是Access denied for user或Communications link failure。前者是用户名密码不对，后者八成是URL写错了数据库名，或者MySQL服务没启动。我建议配置文件里连接参数用最简单的写法，能连上再考虑时区、SSL这些附加参数。
JDK版本不匹配排在第三。如果你用的是JDK 17却跑Spring Boot 2.x，启动时会报UnsupportedClassVersionError；反过来JDK 8跑Spring Boot 3更不行。确认好版本再去处理其他问题，不要看着一堆异常到处乱试。
6.3 演示数据和测试账号：跑通之后第一步做什么
系统起来以后，先别急着注册新用户，用项目自带的测试账号登录是最快的验证方式。一般会提供三个账号：管理员、种植户、买家。分别登录一遍，把每个角色的核心页面都点一遍，确认页面渲染正常、数据能查出来，再开始看代码。
看代码的顺序我也建议按“配置类→实体类→Mapper→Service→Controller→前端页面”来。先看懂配置怎么连库的，再顺着一次完整的“下单”请求把所有层串一遍，你对整个项目的理解会快很多。不要从Controller第一行开始一行行读，那样容易迷失在细枝末节里。
7. 复盘与扩展：这套系统还能往哪些方向改
做完这个项目我最大的体会是，技术上的难点其实不在某个框架的API，而在把果蔬行业这块业务读懂。水果蔬菜的高损耗、短保质期、价格波动，这些特性决定了库存、订单、批次的设计逻辑和普通商城完全不一样。这些业务理解才是这个项目真正的含金量，也是面试时最能讲出东西的地方。
如果还想继续扩展，我建议从三个方向考虑。第一是溯源能力，现在每个批次已经有了采摘日期和产地信息，再加一个农事记录表和批次二维码，买家扫码就能看生产全程，这块在展示和答辩时非常抢眼。第二是数据报表，平台端可以加一套简单的统计图表：按天/周统计订单量、销售额、果蔬销量排行，技术不复杂，但对决策有价值。第三是小程序端，后端接口都用Restful风格写好的话，适配小程序只是换个前端壳，能极大提升项目的完整度。
数据量扩大之后，单库单表的方案就不太够看了。到时候可以先把热门商品列表和首页数据用Redis缓存，再把订单和用户表拆开读写分离，最后才是考虑消息队列做订单超时关闭之类的异步任务。但对大多数课程设计和求职作品来说，把现有项目吃透、把状态机和库存扣减讲清楚，已经比写一个空壳微服务系统强太多。
最后再分享一个小技巧：把所有角色密码设置得简单统一，演示的时候少输几遍；把测试数据准备得逼真一点，价格、产地、保质期都贴近真实行情。一个细节饱满的Demo，比一份冗长的PPT更容易让听的人记住。
