上个月我帮学弟整理一套基于SpringBoot的农产品销售小程序项目从源码结构到部署文档再到代码讲解全程走了一遍。看着挺标准的一个选题实际动手才发现真正需要花精力的地方根本不在于CRUD本身而是功能边界怎么划、订单状态怎么流转、小程序端和后端之间怎么配合以及最后部署上线时那些文档里不会明说的坑。这篇博文就按我实际梳理项目时的顺序来讲把设计思路、源码目录、核心代码逻辑和部署关键步骤全部拆开给正在做同类毕设或者想用SpringBoot整一个小程序实战项目的朋友一个能直接照着走的参考。1. 需求分析农产品销售小程序要解决的不只是“卖东西”农产品销售小程序听起来就是“商品列表购物车下单”但真做起来需求拆分比想象中复杂。我拿到项目的第一件事不是看代码而是把角色、业务流程和功能边界画清楚。很多毕设项目之所以后期改来改去就是因为一开始没把这三个问题想透代码写一半发现缺角色、缺状态、缺接口。1.1 角色拆解买家、商家、管理员各需要什么在农产品销售场景里至少有三类角色。普通用户通过小程序浏览农产品、加购物车、下单支付商家负责发布农产品、管理库存、处理订单管理员负责审核商家资质、管理首页推荐位、查看整体销售数据。这里有一个经典的设计取舍小程序端到底要不要做商家管理功能我见过的很多项目为了“功能多”在小程序里硬塞一个商家工作台结果页面臃肿、接口耦合最后答辩演示时手忙脚乱。真正合理的做法是商家端独立成后台管理页面Web端小程序只面向C端买家。管理员和商家的操作都放到后台小程序保持轻量这样后端接口职责也更清晰。角色定义清楚之后权限模型就顺理成章了。用户表里可以设计一个role字段0代表普通用户1代表商家2代表管理员。后端接口通过JWT拦截器校验角色而不是把所有角色判断塞到前端否则别人直接调接口就能绕过页面操作非常危险。1.2 核心业务流程从浏览到履约的闭环农产品销售小程序的核心流程很直接用户打开小程序看到首页推荐和分类列表选择商品后加入购物车从购物车生成订单支付成功后商家发货用户确认收货。如果要支持团购、预售这种农产品常见的玩法那还要在订单类型上单独设计但第一版不建议加太多扩展逻辑先把主链路跑通。我把主链路拆成四个状态节点待支付、待发货、待收货、已完成。另外再加一个已取消状态用于用户超时未支付或者主动取消。订单状态在后端统一维护小程序端只是展示状态文案和按钮千万不要让前端传状态来更新订单否则很容易被恶意请求刷状态。农产品还有一个特殊点季节性明显库存波动大。所以商品表里必须有库存字段下单时要校验库存并扣减支付超时后回滚库存。如果忽略库存一致性会出现商品显示有货但下单失败的情况这在真实运营里是硬伤。2. 技术选型与项目环境为什么是SpringBoot而不是其他方案项目名里明晃晃写着SpringBoot但选型理由不能一句“因为它流行”就带过。我在梳理项目时把技术选型也当作一个模块来讲这样无论是答辩还是二次开发都能说清楚“为什么”。2.1 后端框架的取舍SpringBoot、JPA还是MyBatis PlusSpringBoot最大的优势是自动配置和生态成熟JDK 8配合SpringBoot 2.7.x是当前稳定且资料最多的组合。现在网上很多教程直接让装SpringBoot 3.x但SpringBoot 3要求JDK 17很多毕设环境还在用JDK 8而且部分依赖如MyBatis Plus的旧版本在新框架下会出兼容性问题。我这次选的是SpringBoot 2.7.18 JDK 8 MyBatis Plus 3.5.3这个组合经过大量项目验证坑最少。ORM层面我推荐MyBatis Plus而不是Spring Data JPA。原因很简单JPA适合实体关系非常规整的内部管理系统但农产品销售这类小程序接口要写不少动态查询比如按价格区间、按销量排序MyBatis Plus的LambdaQueryWrapper能直接拼条件排查SQL也更直观配合分页插件一行代码就能搞定分页。2.2 小程序端与后端交互RESTful接口加统一响应体小程序端选微信官方原生框架不整uni-app那套复杂流程。原生框架对新手友好调试工具成熟页面跳转、组件生命周期都有文档。后端接口全部设计成RESTful风格GET /api/goods查列表POST /api/order提交订单PUT /api/order/{id}/cancel取消订单。小程序端需要做一次请求封装统一处理baseUrl、请求头里的token、HTTP状态码和业务状态码。很多项目失败就败在每写一个页面都重新wx.request一遍导致后端改了接口名前端四处报错。封装之后就一个request.js文件后端返回格式固定为{code, msg, data}小程序端拦截code非200统一弹错误提示这样后续排错会轻松很多。2.3 开发环境版本匹配明细环境问题虽然不是技术深度问题但往往是项目跑不起来的头号原因。我梳理项目时专门整理了一份版本清单JDK1.864位Maven3.8.xMySQL5.7或8.0均可驱动用8.xSpringBoot2.7.18MyBatis Plus3.5.3微信开发者工具最新稳定版Node环境小程序原生开发不需要Node但如果要用npm包则需要这里尤其要强调MySQL 8和MySQL 5.7的驱动区别。SpringBoot 2.7默认的mysql驱动是8.x但连接串如果忘了加serverTimezoneAsia/Shanghai本地往往能通部署到服务器上就报时区错误。文档里直接写死这个配置能省很多麻烦。3. 源码结构与核心代码讲解从启动类到业务实现很多同学拿到源码包后第一反应是打开Application.java直接点运行结果报错一堆依赖找不到。源码结构的意义在于让你知道每个包该放什么、接口调用链是怎么串起来的。我按实际项目的完整目录结构来讲方便大家对照自己的代码。3.1 SpringBoot项目分层Controller、Service、Mapper、Entity农产品销售小程序的后端我习惯按标准三层结构拆包controller接收前端参数调用service返回统一响应体service业务逻辑层处理订单状态流转、库存校验这些复杂操作mapperMyBatis Plus的数据访问层只写数据库操作entity数据库实体类字段与表结构对应config配置类包括拦截器、跨域、文件上传配置common通用类如统一返回体Result、自定义异常、常量类实体类不要直接用Map接收数据库查询结果虽然速度快但可读性差。我在项目里会为每个核心表建对应的entity比如Goods、Cart、Order、OrderItem。MyBatis Plus的TableName注解可以保证实体和表名严格对应避免数据库表改名后还到处找SQL。另外控制器层要尽量瘦不要堆业务代码。正确写法是controller里只做参数校验和结果返回业务逻辑全部下沉到service。比如“下单”这个操作service里可能调用了checkStock、createOrder、createOrderItem、deductStock好几个方法任何一个方法出问题都应该抛业务异常而不是在controller里try catch吞掉。3.2 用户登录与JWT鉴权微信登录接口怎么接微信小程序登录的核心流程是前端调用wx.login()拿到临时code后端用这个code加上小程序的appid和secret请求微信的code2Session接口得到openid。这个openid就是用户在小程序里的唯一标识。项目里我在application.yml中配置好appid、secret后端的AuthService中发起HTTP请求换openid然后查数据库。如果用户不存在就自动注册最后用JWT生成一个token返回给前端。JWT的好处是后端不用存session小程序每个请求在请求头里带上Authorization: token后端拦截器解析token并放行。拦截器配置有几个细节容易踩坑登录接口和商品列表接口必须放行否则用户没登录连商品都看不了但下单、购物车、订单列表接口必须拦截。放行路径和拦截路径不要写错我见过一个项目把/api/user/**全部放行了结果用户信息接口可以直接匿名访问问题相当严重。下面是一个简单的JWT拦截器核心方法片段关键点在于从请求头取token然后解析并校验用户是否存在Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { if (OPTIONS.equalsIgnoreCase(request.getMethod())) { return true; } String token request.getHeader(Authorization); if (StringUtils.isBlank(token) || !jwtUtil.validateToken(token)) { throw new BusinessException(未登录或登录已过期); } Long userId jwtUtil.getUserId(token); request.setAttribute(currentUserId, userId); return true; }这里要注意token过期时间的设置。农产品销售小程序不像OA系统需要长会话我建议token有效期设7天既避免频繁重新登录又能保证基本安全。刷新token机制第一版可以不做降低复杂度。3.3 农产品列表与加载更多分页接口的经典写法小程序端“加载更多”是很多热搜词里反复出现的需求农产品列表页同样需要。后端分页接口不能每次把全表数据返回肯定要分页。MyBatis Plus的分页插件配置好之后service层代码非常简洁public PageGoodsVO getGoodsPage(int page, int size, String category, String keyword) { LambdaQueryWrapperGoods wrapper new LambdaQueryWrapper(); wrapper.eq(StringUtils.isNotBlank(category), Goods::getCategory, category) .like(StringUtils.isNotBlank(keyword), Goods::getName, keyword) .eq(Goods::getStatus, 1) .orderByDesc(Goods::getSales); PageGoods goodsPage goodsMapper.selectPage(new Page(page, size), wrapper); // 转换为VO并填充图片、销量等字段 return convertToVO(goodsPage); }分页插件需要配置MybatisPlusInterceptor这一点是MyBatis Plus最容易漏的步骤不配置分页插件的话selectPage会把所有数据查出来再在内存里分页数据量一大就直接卡死。小程序端触底加载的实现也比较常规。在页面的onReachBottom里判断hasMore当前页码加一然后调用封装好的分页接口把新数据追加到列表数组尾部。注意请求期间要加一个loading变量防止用户快速下滑导致重复请求同一页。这个loading锁是很多人会漏掉的接口慢的时候会出现列表重复数据实测非常影响体验。3.4 购物车与订单模块库存、金额、状态的联动购物车的核心是一张cart表包含用户ID、商品ID、数量、选中状态。加购接口要做两次校验一是商品状态必须为上架二是数量不能超过库存。很多项目只在提交订单时校验库存其实加购时就应该提示用户否则购物车里有货结算时却提示无货用户很难接受。订单模块是整个项目里最容易写出问题的部分。我建议在service层用一个事务方法处理下单先校验库存再创建主订单接着批量创建订单明细最后扣减库存。任何一个环节失败整个事务回滚避免出现订单生成了但库存没扣的情况。Transactional(rollbackFor Exception.class) public Long createOrder(OrderCreateDTO dto, Long userId) { // 1. 从购物车或前端传参获取商品列表 // 2. 计算总金额、校验商品上下架状态 // 3. 插入orders表状态为待支付 // 4. 插入order_item表 // 5. 扣减库存 // 6. 清空已购买的购物车记录 return orderId; }订单编号不要用自增ID直接展示给用户最好生成一个yyyyMMddHHmmss 随机数的订单号方便查询和售后。用户下单后有一个待支付状态支付成功通过微信支付回调来通知回调里更新订单状态并触发库存的最终确认。这部分逻辑比较复杂我在部署文档里会特别强调回调地址必须是公网HTTPS地址否则微信服务器无法回调。4. 数据库设计一张订单表怎么支撑完整业务流转数据库是设计题里最值得花时间推敲的部分。很多刚开始做项目的同学直接把所有信息堆进一张大表比如商品和订单混在一个表里最后统计报表根本没法写。合理的库表设计能让后续代码量减少一半。我按项目实际的表来拆解。4.1 核心表结构用户、商品、购物车、订单、订单明细农产品销售小程序最核心的表有六张我用表格列一下关键字段表名关键字段说明userid, openid, nickname, avatar, role, statusopenid唯一role区分买家商家管理员goodsid, name, category, price, stock, sales, image, statusstatus控制上下架cartid, user_id, goods_id, quantity, checked一对多每个用户多条购物车记录ordersid, order_no, user_id, total_amount, status, pay_status, create_time主订单一个用户对应一个订单order_itemid, order_id, goods_id, goods_name, price, quantity订单明细快照商品信息bannerid, image, url, sort首页轮播图可动态管理order_item表一定要存商品名称、商品图片和单价快照而不是直接关联goods表。原因是商品之后可能改价或者删除但历史订单里的信息和价格必须保持不变。等再过几个月回头看你就能感受到这个决策有多重要。另外user表的角色权限需要配合前面的JWT拦截器使用。管理员和商家的账号可以在后台初始化也可以在小程序第一次登录时默认普通用户再通过一个单独的引导流程申请成为商家。这个流程在毕设里可以用固定接口演示不需要真正做审核流但表结构要预留status字段。4.2 订单状态字段与状态机设计订单状态我用status字段表示取值范围是0待支付、1已支付待发货、2已发货、3已完成、4已取消。状态流转在后端用常量类约束比如只有状态为0的订单才能取消只有状态为1的订单才能发货。用int而不是string的好处是存储小、索引快、判等简单。对应的状态文案小程序端映射即可不必存中文。如果真要做到生产级还要加一个pay_status字段因为可能存在“支付回调成功但数据库更新失败”的极端情况两个字段分开可以方便对账。再有就是下单时间字段建议用datetime类型不要用timestamp因为timestamp有2038年问题虽然目前不是问题但习惯了不推荐用。MyBatis Plus在实体类上配合TableField(fill FieldFill.INSERT)可以自动填充创建时间减少重复代码。如果后面要加“订单超时自动关闭”可以给orders表加一个expire_time字段通过定时任务扫描待支付订单超过30分钟自动取消并回滚库存。这是一个加分项但第一版可以先不做等主流程通了再加。5. 部署文档实操从本地跑起来到服务器上线说起部署我见过太多项目源代码写得不错一部署就崩。主要原因就是文档只写了三分环境对不上、路径不明白、端口没放开。下面这部分就是我在整理部署文档时写的完整实操步骤尽量覆盖主流环境。5.1 本地开发环境启动步骤本地启动前后端一般按三条线走。第一步准备数据库在MySQL里创建farm_db然后导入项目提供的farm_db.sql。第二步配置后端打开application.yml把数据库用户名密码改成自己的把小程序appid和secret改成自己申请的。第三步启动后端入口类看到Tomcat started on port 8080就说明后端起来了。接着是小程序端。用微信开发者工具导入项目中的miniapp目录在app.js里把baseUrl改成http://localhost:8080/api。因为微信开发者工具本地请求合法域名的校验默认是开启的本地调试时需要在右上角“详情-本地设置”里勾选“不校验合法域名、web-view业务域名、TLS版本以及HTTPS证书”。这个开关只用于开发环境上线前务必关闭。启动之后先测试登录接口。如果点击登录后拿不到用户信息大概率是appid/secret配置错误或者code2Session接口被安全风控拦截。排查时先在开发者工具里看console输出再看后端日志两端日志一对照就能定位问题。5.2 服务器部署Maven打包、systemd、Nginx配置服务器部署比本地多几个步骤。首先准备好一台Linux服务器装好JDK8、MySQL和Nginx。然后把后端项目用Maven打包成jar包命令是mvn clean package -DskipTests生成的jar在target目录下。项目直接用java -jar有点脆弱我建议用systemd配置一个守护进程让后端应用开机自启、异常重启都有人管。先建一个配置文件/etc/systemd/system/farm.service内容大致是[Unit] DescriptionFarm MiniProgram Backend Afternetwork.target [Service] Userroot WorkingDirectory/opt/farm ExecStart/usr/bin/java -jar /opt/farm/farm-backend.jar Restarton-failure RestartSec10 [Install] WantedBymulti-user.target配置好以后执行systemctl daemon-reload systemctl start farm。后端服务跑起来之后前端小程序要上线必须用HTTPS域名访问。Nginx配置一个server块把/api反向代理到本地的8080端口静态资源由Nginx直接托管证书建议用免费DV证书现在申请流程已经非常方便了。关键点Nginx的反向代理要显式加上proxy_set_header Host $host;否则后端取不到真实请求头微信支付回调验签时会出问题。同时需要把上传目录映射好比如图片上传到/opt/farm/upload通过/upload/访问这个路径在Nginx里要单独配置alias或者root。5.3 微信小程序合法域名与上线准备微信小程序在生产环境有一个硬性约束所有请求域名必须在小程序后台配置为合法域名必须HTTPSICP备案不能少。在微信公众平台的“开发管理-服务器域名”里配置request合法域名也就是后端接口域名还要配置uploadFile合法域名供图片上传功能使用。如果小程序里加载了别域名的图片也得一并加到downloadFile合法域名里。很多项目部署后能请求接口但图片全部裂掉多半就是因为图片域名没配进去。上线前还要在开发者工具里把“不校验合法域名”的开关关掉再走一遍完整流程谁也不想等审核通过了才发现首页图片加载不出来。部署完成之后不要急着提交审核先在开发者工具中切换成“正式版”环境填写真实域名用手机上预览一下。重点测登录、下单、支付、查看订单这四个核心链路任何一个环节卡住都要先看控制台和服务器日志。这一步虽然占时间却是最值得的。6. 真实踩坑记录配置、代码、环境三方面的教训最后这部分全部来自实际调试中遇到的问题每条都对应一次真实的报错过程。我会把现象、原因、解决方案一起写出来方便你遇到类似问题时直接对照。6.1 本地图片上传显示404后端日志没有异常第一次跑通完整流程后我发现商品新增时图片上传成功但页面回显却是404。排查下来原因是SpringBoot默认不会把本地文件目录作为静态资源映射出来。上传接口确实把文件写到了服务器本地路径但访问的时候URL匹配不到对应的静态目录。解决方案有两种。一种是在后端配置WebMvcConfigurer把本地目录映射为/upload/**另一种是把上传目录交给Nginx单独管理前端访问的地址直接指向Nginx。我在项目里推荐第二种因为后端服务重启不会影响静态资源而且Nginx处理静态文件的性能更好。核心配置是这样的location /upload/ { alias /opt/farm/upload/; }6.2 订单接口出现重复提交库存被扣成负数购物车页快速点两次“提交订单”按钮后端生成了两笔一模一样订单库存也被扣了两次。这个问题在小程序端用loading锁并不能根治因为恶意用户可以绕过前端直接调接口。后端的兜底方案是给订单表加一个order_no唯一索引同时在创建订单之前先查一下相同用户、相同商品组合是否已有待支付订单。但订单表加唯一索引并不是万能方案因为用户可能同时买好几样商品。更稳妥的办法是在下单接口上做幂等控制用用户的请求唯一标识idempotent_key作为唯一索引同一标识重复请求直接提示“请勿重复提交”。毕设项目做到这一步已经能应对绝大多数情况。6.3 微信支付回调回调地址无法访问本地开发时微信支付的回调地址填的是http://localhost:8080/api/pay/notify结果一直收不到回调通知。原因很简单微信服务器不可能访问到我们自己电脑上的localhost。解决方案是使用内网穿透工具把本地端口映射成公网可访问地址或者直接把后端部署到有公网IP的服务器上测试。支付回调还有另一个坑回调地址必须是公网可访问的HTTPS域名普通IP地址在某些情况下会被微信拦截证书不合法也不会回调。调试阶段可以用开发者工具里的“真机调试”配合内网穿透看日志但生产环境一定要把正式域名配好。6.4 后端时间格式不对前端显示成一串数字数据库是datetime类型但前端拿到的时间却是一串1680000000000这样的数字这是因为SpringBoot默认使用Jackson序列化LocalDateTime时输出的是时间戳。处理办法是在application.yml里配置全局时间格式spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: Asia/Shanghai如果还是不行就在实体类的LocalDateTime字段上加上JsonFormat(pattern yyyy-MM-dd HH:mm:ss)。这个问题不影响业务正确性但很影响演示效果用户端看到一串时间戳你也不好解释。踩完这些坑之后我对这类项目的理解更深了一层农产品销售小程序真正的难点从来不是“不会写代码”而是需求边界、状态设计和部署链路串不到位。源码结构怎么组织、数据库怎么落表、接口怎么分层、部署文档怎么补全这些才是让项目真正像一个完整交付物的关键。如果你正在折腾同类型项目建议先从主链路跑通再逐步加功能遇到部署问题多对比前后端日志问题总能定位到具体那一层。