这套基于Spring Boot和微信小程序的扶贫助农系统，是我最近从需求梳理、数据库建表、后端接口开发再到小程序前端联调完整跑下来的一套全栈项目。它面向的是农产品帮扶销售这个场景，整体并不复杂，但胜在链路完整：用户通过小程序浏览商品、加购物车、下单，后端负责登录鉴权、业务处理和订单流转。如果你想找一个能打通“小程序端 + Java接口 + 数据库 + 管理后台”全部环节的参考项目，这篇总结应该能帮你省不少时间。无论你是准备做类似方向的毕业设计，还是刚接触Spring Boot小程序开发想找个完整例子拆解，这个项目都非常适合从零过一遍。
1. 项目整体设计与思路拆解
1.1 需求场景与角色划分
扶贫助农系统这个名字听起来比较“政府项目”，但落到实际产品形态上，它就是一套垂直领域的农产品电商小程序。核心痛点有三个：农产品信息传播渠道分散、农户没有直接触达消费者的线上入口、中间环节多导致优质产品卖不出好价。
系统的用户角色我最终划分成了三类：
- 普通用户：在小程序端浏览农产品、查看助农资讯、收藏商品、加入购物车、下单、查看订单。
- 农户/商家：管理自己发布的农产品，处理订单发货，查看自己商品的销量统计。
- 平台管理员：审核农户入驻、管理商品上下架、管理首页轮播图和资讯公告、查看全平台订单数据。
这里有一个容易被忽略的点：农产品和普通电商商品不同，它受季节性影响大，而且很多农户没有运营能力，所以系统里我特意加了“助农资讯”和“推荐专栏”这两个内容模块，用来做产品背书和引导流量。不是所有页面都硬邦邦地卖货，有内容引导，转化会更自然。
1.2 技术选型背后的取舍
后端选择Spring Boot，几乎是这类项目的默认答案。生态成熟、资料多、招人容易找，而且内嵌Tomcat让部署变得非常简单。但这里我要特别提醒一句：如果你只是做毕设或者个人项目，千万不要追新用Spring Boot 3.x。它要求JDK 17以上，而且很多老版本的依赖和配置都不兼容，踩坑成本很高。我这次用的是Spring Boot 2.7.x配合JDK 8，稳定且网上能搜到的问题解法最多。
持久层我选了MyBatis-Plus而不是原生MyBatis，理由是这类业务系统的单表CRUD太模式化了，用Plus可以省掉大量重复的Mapper XML，分页插件也是现成的。复杂查询依然可以用注解写SQL，并不冲突。
小程序端我坚持用原生开发，没有上uni-app或者Taro。原因很简单：这个项目只需要覆盖微信平台，原生的性能和调试体验最好，而且微信开发者工具对原生项目的支持是最完整的。上一轮交付的2048-小程序.zip就是原生小程序工程，里面pages、utils、components的结构非常清晰，比跨平台框架生成的一堆混编代码更容易让初学者看明白。
支付环节我用的是模拟支付。因为个人主体的小程序无法开通微信支付，而且真实支付涉及商户号、证书、回调通知这些复杂配置，对课程设计和演示场景来说负担太重。模拟支付的核心逻辑和真实支付是一致的，把“支付动作”抽象成一个接口调用，后面想升级真实支付时只需要替换支付实现类。
1.3 功能模块与整体分层
后端从功能上划分为六大模块：用户认证、商品中心、购物车、订单交易、内容管理、数据统计。每个模块都遵循Controller-Service-Mapper三层结构，Controller只做参数接收和结果封装，Service层放业务逻辑，Mapper层管数据库交互。
这里有个设计原则我必须强调：前端页面可以按角色来划分，但后端接口不要按角色堆模块。比如用户和管理员都会用到商品列表，就只提供一个商品查询接口，通过权限参数决定返回值是否包含上下架状态和库存成本信息，避免为每个角色重复造接口。
全局层面我还做了几件规范化的事：统一返回结构Result<T>，统一异常处理，统一分页参数。这些看起来是小事，但实际联调时能省下一大堆扯皮，后面我会详细说。
2. 后端核心细节与实现要点
2.1 工程结构与启动流程
项目结构我按下面这个方式组织，简单直观，适合中小型项目：
farmer-assist-server ├── src/main/java/com/example/farmer │ ├── controller │ ├── service │ ├── mapper │ ├── entity │ ├── dto │ ├── config │ ├── common │ │ ├── Result.java │ │ └── GlobalExceptionHandler.java │ └── FarmerApplication.java ├── src/main/resources │ ├── application.yml │ ├── mapper │ └── sql └── pom.xmlapplication.yml里配置了数据源、MyBatis-Plus、文件上传路径和自定义的业务参数。有一个细节：数据库连接串必须加上serverTimezone=Asia/Shanghai，否则查询出来的时间会比本地时间少8个小时，这个坑我当年踩过，现在每次都提前配置好。
启动流程本身没什么特殊的——改好数据库密码，执行sql目录下的建表脚本，然后在IDEA里直接运行FarmerApplication类，看到“Started FarmerApplication”日志输出就算成了。我第一次带人跑这个项目时，对方卡在数据库脚本执行顺序上，所以我建议把建库、建表、初始化数据分开写成三个sql文件，避免手忙脚乱。
2.2 数据库设计思路与关键表
整个系统我设计了8张核心表，这里列一下主要表的作用和需要注意的地方：
| 表名 | 作用 | 关键点 |
|---|---|---|
| user | 用户表 | 区分用户角色，openid唯一 |
| farmer | 农户表 | 关联user表，存店铺信息 |
| category | 商品分类表 | 树形结构预留parent_id |
| goods | 商品表 | 价格用int存分，避免浮点误差 |
| cart | 购物车表 | user_id + goods_id做唯一索引 |
| orders | 订单主表 | 存订单总金额、状态、收货信息 |
| order_item | 订单明细表 | 每个商品一条记录 |
| banner_notice | 轮播与资讯表 | type字段区分轮播图、公告、助农资讯 |
订单表拆成orders和order_item两张是电商系统的常规做法。主表存一次订单的公共信息，比如总金额、状态、收货人；明细表存每个商品的快照数据。这里说的快照就是商品名称、单价、数量在下单那一刻的拷贝，不能联表去查goods表，否则商品后来改价或者删除，历史订单就全乱了。
金额字段我统一用int类型存“分”，页面展示时再除以100。这个习惯是从支付系统开发里带过来的，浮点类型在计算金额时会出现0.1+0.2不等于0.3的问题，用整数分配合DecimalFormat就能完全规避。
2.3 统一返回结构与接口规范
前后端联调最容易扯皮的就是“你返回的数据结构和我预期不一致”。所以我在项目第一天就定了统一返回格式：
{ "code": 200, "message": "success", "data": {} }所有接口无论成功失败都走这个壳，前端封装函数里只判断code是否等于200，其余情况统一弹message。业务层面的校验失败也走这个结构，而不是通过HTTP状态码去表达——比如“库存不足”就返回code 5001，这样前端处理起来非常顺手。
分页接口额外封装了一层PageResult，包含records、total、current、size四个字段。这也和前端小程序里常用的loadMore逻辑对应上了。每次下拉到底部就传当前页码，后端返回total后前端用来判断是否还能继续加载，避免多余请求。
为了防止Controller里堆满try-catch，我写了一个全局异常处理器。业务异常类BizException携带错误码和提示信息，未知异常统一记录日志并返回“系统繁忙”。这个设计极大减少了重复代码，也让前端拿到的错误信息始终是用户能看懂的话，而不是一堆堆栈。
2.4 登录鉴权与手机号获取
小程序的登录流程和传统网页完全不同。用户点击授权后，前端通过wx.login()拿到一个临时code，这个code有效期只有5分钟，而且只能用一次。后端拿code去调用微信的code2Session接口，换取openid和session_key。
openid是用户在微信生态里的唯一标识，我把它作为用户的业务主键。第一次登录就自动注册，查不到就插入一条新用户记录。换取成功后，后端生成一个随机token返回给前端，之后所有请求都在Header里带token，通过拦截器验证登录状态。
关于绑定手机号，这里有个版本差异要提醒：老接口需要前端传encryptedData和iv，后端用session_key通过AES算法解密出手机号；新版接口则直接用getPhoneNumber获取到的code换取手机号。如果你的Spring Boot版本比较老，依赖的还是老版微信接口，那千万别盲目照搬新版代码。我这次做的是老接口，核心逻辑就是用WxCryptUtil解密，解密前必须校验appid和sid，解密失败多半是session_key过期，让用户重新登录即可。
安全方面有两个红线：session_key绝对不能返回给前端，它只在后端解密时用；token要做有效期，我设置在Redis里存7天，每次请求滑动续期，这样用户长时间不操作重新登录的成本可控。
3. 小程序端关键流程实操
3.1 小程序目录结构与全局配置
2048-小程序.zip工程解压后的核心结构是这样的：
miniprogram ├── app.js ├── app.json ├── app.wxss ├── utils │ └── request.js ├── components │ ├── goods-card │ └── empty-view └── pages ├── index ├── category ├── goods-detail ├── cart ├── order ├── user └── loginapp.json里注册所有页面路径、配置window全局样式和tabBar。tabBar我配置了首页、分类、购物车、我的四个入口，图标用纯色PNG，官方要求最多5个tab且不能使用网络图片，这个坑很多人第一次做都会碰。
utils/request.js是全项目的网络请求封装，我封装了四件事：在请求头里自动附加token、统一处理HTTP错误、对code非200的情况自动toast错误信息、对401跳转登录页。这个文件写好后，所有页面里的请求都简化为两三行代码。
3.2 首页、商品列表与详情页
首页由三块拼成：顶部轮播图、中部助农资讯列表、底部推荐商品瀑布流。轮播图数据来自banner_notice表type=0的记录，资讯列表取type=1，推荐商品则调用商品接口并传了is_recommend参数。
商品列表页用scroll-view配onReachBottom做分页加载。分类切换时重置页码并重新请求。列表页的筛选条件我放在后端做，前端只传categoryId、keyword、priceOrder这三个参数，排序逻辑统一在SQL里用ORDER BY处理，避免前端多个组件状态互相干扰。
商品详情页有几个细节要注意：价格展示要换算成元并保留两位小数；库存为0时按钮要置灰并显示“已售完”；加入购物车之前必须做登录态校验，未登录用户引导去登录页而不是静默失败。另外，详情页的图片建议全部走CDN或者对象存储，本地存储图片在小程序真机预览时有很大的带宽压力，体验差距非常明显。
3.3 购物车与下单流程
购物车我采用服务端存储，而不是本地Storage。本地存储虽然简单，但换设备就丢数据，清缓存也会清掉，体验太差。服务端购物车的表结构就是user_id + goods_id做唯一索引，加购接口做insert，重复加购就做数量累加，逻辑很清晰。
下单流程是这个系统最核心的链路。用户从购物车勾选商品点“去结算”后，进入确认订单页，展示收货地址、商品清单和应付金额。提交订单时后端要做三件事：先校验商品是否存在且上架，然后校验库存，最后预扣库存并生成订单。
库存预扣是防止超卖的关键。SQL里用UPDATE goods SET stock = stock - #{num} WHERE id = #{goodsId} AND stock >= #{num}这种条件更新，受影响行数为0就说明库存不足，直接抛业务异常。绝对不能先查出来再在Java代码里做减法，并发场景下一定会出错。
订单号生成也不是简单的时间戳，我用的规则是yyyyMMddHHmmss + 4位随机数 + userId后四位，既能保证可读性也能降低重复概率。真实高并发场景可以引入雪花算法，但这个量级下已经够用。
3.4 订单状态流转与模拟支付
订单状态我用一个status字段表示，数字对应关系如下：
| 状态值 | 含义 | 可操作动作 |
|---|---|---|
| 0 | 待付款 | 用户取消、去支付 |
| 1 | 待发货 | 农户发货 |
| 2 | 待收货 | 用户确认收货 |
| 3 | 已完成 | 订单完成，可评价 |
| 4 | 已取消 | 无 |
| 5 | 退款中 | 管理员审核退款 |
模拟支付的实现是在支付接口里不做真实扣款，而是直接生成一条支付流水记录，然后调用内部方法把订单状态从0改成1。因为状态扭转的代码在Service层是幂等的，将来接真实微信支付时，只需要在notify回调里调用同一个方法，改动非常小。
这里有一个很实用的细节：不管订单最终是否支付成功，只要创建了订单，就先记录一条支付流水pay_record。这样排查问题时能看到用户到底走没走到支付环节，而不是对着订单状态瞎猜。取消订单时如果库存已经预扣，必须执行回补操作，这个逻辑我在取消接口和超时自动取消的定时任务里都处理了。
4. 部署、联调与常见问题排查
4.1 本地开发环境搭建
本地跑通这套系统的完整步骤，我按顺序列一遍：
- 安装MySQL 5.7或8.0，创建数据库并导入
sql目录下的全部脚本。 - 用IDEA打开后端工程，等待Maven依赖下载完成，修改
application.yml中的数据库账号密码。 - 启动后端，确认8080端口正常监听。
- 用微信开发者工具导入
2048-小程序.zip，在app.js或utils/config.js里修改baseUrl为http://localhost:8080/api。 - 在开发者工具“详情-本地设置”中勾选“不校验合法域名”，这是因为本机IP不在HTTPS白名单中。
- 在开发者工具里使用测试号或自己的AppID运行，就可以完整走通登录、下单、支付流程。
开发阶段最常遇到的启动问题是端口冲突和数据库时区。端口被占用就改server.port；时区问题则是连接串里少了serverTimezone参数，加上就好。
4.2 常见问题速查表
我把联调过程中高频出现的问题整理成一个表，照着排查能省很多时间：
| 问题现象 | 根本原因 | 解决办法 |
|---|---|---|
| 小程序请求一直转圈 | baseUrl配错或后端没启动 | 确认开发者工具Network面板请求是否发出 |
| 报“url not in domain list” | 未关闭域名校验 | 详情-本地设置-勾选不校验合法域名 |
| 登录后刷新页面又回到未登录 | token没存或请求头没带 | 检查utils/request.js的登录拦截逻辑 |
| 时间为空或少了8小时 | 时区配置缺失 | 连接串加serverTimezone=Asia/Shanghai |
| 手机号解密失败 | session_key过期或code重复使用 | 重新走wx.login获取新code |
| 下单提示库存不足但实际有货 | 前端传了错误商品ID | 打印后端入参，检查购物车商品ID |
| 中文乱码 | 接口编码不一致 | 检查Spring Boot字符编码配置为UTF-8 |
| 下拉加载重复数据 | 页码没有正确累加 | 确认onReachBottom里current自增后再请求 |
4.3 上线前检查清单
如果你不只是本地玩一玩，而是准备部署到服务器甚至发布正式版本，下面这几件事一定要检查：
小程序服务端域名必须是HTTPS，并且要在微信公众平台配置request合法域名。开发阶段的http本地地址在正式环境完全不能使用，所以要提前准备域名和SSL证书。部署上我用Docker加宝塔面板比较多，后端打jar包后用Dockerfile构建镜像，数据库单独一个容器，Nginx反代到后端端口并配置HTTPS证书。
数据库备份要自动化。农产品下单数据一旦丢失非常麻烦，我习惯写一个crontab脚本每天凌晨备份并保留最近7天，这个成本很低但救过我好几次。
农户端和管理员端的权限要收口。后台接口如果裸奔，任何知道路径的人都能调用，至少要在管理端接口加上管理员token校验，并且不要把管理员的登录接口和用户登录共用一个逻辑。
5. 一些个人感受
这套系统我从零搭建到完整跑通，前后花了两周不到的时间。如果你也是第一次做类似项目，我最大的建议是不要上来就纠结某个炫酷技术，先把核心主链路跑通——用户能登录、能加购、能下单、能看到订单状态变化，系统的骨架就有了。前端报错先看Network请求是否发出、后端看日志、数据库看SQL执行情况，按这个顺序排查90%的问题都能解决。后续要扩展，可以考虑接真实微信支付、加入农产品溯源的二维码、对接地图展示助农基地位置，这些都是在这个骨架上很容易添加的部分。
