简介：这是一份结合Java后端与微信小程序技术开发的跑腿平台项目资源，面向Java开发者、小程序学习者，也适合课程设计与毕业设计参考。项目覆盖用户下单、跑腿接单、订单支付和任务调度等核心流程，同时包含数据库设计、地理定位、消息推送等关键知识点，能够帮助理解从用户端到管理端的完整业务闭环。压缩包共2020个文件，整体约9.81MB，其中以png、css、html、js等前端静态资源为主，另有java源码、sql脚本和json/xml配置，便于本地部署和二次开发。已有200人学习，资源内包含前后端代码与相关配置，可据此理解功能模块与数据表结构；结合源码可重点研究Spring Boot、MyBatis、微信支付接口以及缓存、异步处理等工程实践，是一份兼具学习与实战价值的参考资料。
1. 拿到「Java 基于微信程序的跑腿平台」需求代码包，先别急着解压
会搜“Java 基于微信程序的跑腿平台的设计与实现-需求代码.rar”的人，多半是要交课程设计或毕业设计，也可能是想给校园、社区搭一个跑腿代取、同城闪送的小平台。这类压缩包装的是完整交付物：需求文档、数据库脚本、Java 后端源码、微信小程序前端。它的核心价值不是“解压即跑”，而是把跑腿业务拆成可落地的闭环——用户发单、骑手抢单、取货、送达、取消退款，这几条关键流转在前后端怎么对齐，表结构和接口怎么设计。这篇笔记适合两类人：三天内要交可演示 Demo 的学生，以及想用微信小程序快速验证本地跑腿业务的小团队。先说结论：你接手的是课设代码，不是商业系统，所以打开压缩包之前就要做个决定——你是要交作业，还是想真上线。
2. 从需求文档到模块拆解：跑腿平台先定订单状态机与六个功能域
2.1 需求文档读什么：先看用例图和后端目录，别急着开数据库
rar 包解压后，常见结构是三块：需求文档（Word/PDF，含用例图、页面原型、功能列表）、数据库脚本（.sql）、源码目录（后端 Maven 工程加小程序前端）。顺序很重要：先读需求文档里的用例图和功能说明，再回头看代码，否则很容易被源码里几个类的命名带偏，以为某个模块很复杂。
跑腿平台的用例图通常出现三个角色：用户（C 端下单）、骑手（抢单配送）、管理员（审核和结算）。围绕这三个角色，业务流程主线是“用户发单 → 系统推送/骑手抢单 → 骑手取货 → 送达确认 → 结算/评价”。读文档时我会忽略那些伪需求（比如“好友助力”“社交红包”这类扩展功能），聚焦核心闭环。有三个信息必须圈出来：订单状态枚举、取消规则、支付时机。大多数课设文档会把订单状态写成一句话，但代码里常常已经改成了不同的枚举值，所以看完文档后我会打开后端源码里的常量类或枚举类，手工对齐一遍。
还有一类信息容易漏，就是“非功能需求”。比如需求说明书里写“系统应支持较高并发”，但在代码里你要找到对应的锁、唯一索引、事务注解，否则这只是口号。自己验证的方式很简单：搜@Transactional、synchronized、UPDATE ... WHERE status这类关键词，看有没有真的落地。
2.2 角色与功能清单：用户端、骑手端、管理端各做什么
功能清单不用自己拍脑袋，需求文档里一般有功能树或页面清单。我按常见跑腿课设整理过一套功能划分，可以直接对照：
| 角色 | 核心功能 | 关键约束 |
|---|---|---|
| 用户端 | 发单（取件地址 / 送件地址 / 物品描述 / 小费）、微信支付、取消订单、订单跟踪、订单评价 | 发单前参数校验；取消订单有时间窗口 |
| 骑手端 | 抢单大厅、我的接单、取货码 / 送达码、收入流水 | 同时未完成订单数上限，防止恶意占单 |
| 管理端 | 骑手实名认证、订单仲裁、对账结算 | 结算记录不可篡改，保留完整日志 |
订单状态机是整张表的“宪法”。常见做法是定义一组枚举，而不是用自由字符串，否则报表统计时状态值五花八门，服务端校验也无从下手。我常用这一组状态：CREATED（已创建）、PAID（已支付待接单）、ACCEPTED（已接单）、PICKED_UP（已取货）、DELIVERED（已送达）、CANCELLED（已取消）、REFUNDING（退款中）。每个状态的迁入迁出都要在服务端做校验，前端按钮只能触达两个动作：发起请求、等待结果。
取消规则是另一个容易写乱的地方，业内常见约定是“三窗口”：用户在骑手接单前可无条件取消；骑手接单后取消要扣用户信用分；骑手接单后如果 15 分钟未取货，系统自动取消并把订单重新放回抢单大厅。把这些规则写进状态机的注释里，比写在 README 里更可靠。
2.3 技术选型：为什么是 Spring Boot + 微信原生小程序，而不是 uniapp
这类课设包选 Java 是常规操作，后端主流是 Spring Boot + MyBatis/MyBatis-Plus + MySQL。Spring Boot 的 starter 把配置收敛得很干净，MyBatis-Plus 能省掉大量 CRUD 样板代码，对“三天跑通 Demo”非常关键。如果源码是 SSM 三层手写 XML 映射的老工程，接手成本会高很多——这种包一般还带着过时的 Spring 版本和 JDK 7 兼容问题，不建议在它上面改需求。
前端“微信小程序”是指微信原生小程序（WXML/WXSS/JS），不是 uniapp 编译产物。原生实现的好处是调试路径最短：微信开发者工具直接预览，语法就是小程序官方语法，出错位置很直观。uniapp 的优势是一套代码出小程序、App、H5，但代价是多一层编译链，遇到平台差异时排查成本更高。如果只做微信端，我选原生；如果准备扩展到 Android/iOS/鸿蒙，才需要考虑 uniapp。但课设阶段，用原生小程序已经足够把业务闭环讲清楚。
版本选择上，给出一个不会翻车的组合：JDK 8 + Spring Boot 2.7.x + MySQL 5.7/8.0 + MyBatis-Plus 3.5.x，小程序端基础库选 3.x 的稳定版本，不要一上来就追最新基础库。这套组合的兼容文档最多，网上能搜到的踩坑记录也最全。Redis 这类组件课设包里一般没有，也不必主动引入，因为订单表在中小流量下用 MySQL 加索引完全能扛住，引入 Redis 反而让课设的复杂度失控。
3. 数据库与核心接口：把订单流转写成可落地的 SQL 与 Java 代码
3.1 核心表结构：用户表、订单表、订单日志表最少三张
跑腿平台的核心闭环依赖三张表：用户表、订单表、订单日志表。用户表存 openid 和余额，订单表存业务流转数据，订单日志表记录每一次状态变更。课设代码里常见的毛病是只有订单表没有日志表，出了问题连“这个订单为什么变成已取消”都查不到，所以我会优先确认日志表是否存在。
下面是一套可用的建表脚本，字段尽量精简，按课设标准够用：
CREATE TABLE `user` ( `id` BIGINT PRIMARY KEY AUTO_INCREMENT, `openid` VARCHAR(64) NOT NULL COMMENT '微信小程序 openid', `nickname` VARCHAR(32) DEFAULT '', `phone` VARCHAR(11) DEFAULT '', `balance` DECIMAL(10,2) DEFAULT 0.00 COMMENT '账户余额', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY `uk_openid` (`openid`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE `orders` ( `id` BIGINT PRIMARY KEY AUTO_INCREMENT, `order_no` VARCHAR(32) NOT NULL COMMENT '业务订单号', `user_id` BIGINT NOT NULL, `deliveryman_id` BIGINT DEFAULT NULL COMMENT '骑手ID，未接单为 NULL', `pickup_address` VARCHAR(200) NOT NULL COMMENT '取件地址', `delivery_address` VARCHAR(200) NOT NULL COMMENT '送件地址', `item_desc` VARCHAR(500) COMMENT '物品描述/备注', `fee` DECIMAL(10,2) NOT NULL COMMENT '配送费', `tip` DECIMAL(10,2) DEFAULT 0.00 COMMENT '小费', `status` TINYINT NOT NULL DEFAULT 0 COMMENT '0创建 1已支付待接单 2已接单 3已取货 4已送达 5已取消 6退款中', `expect_time` DATETIME DEFAULT NULL COMMENT '期望送达时间', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP, `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY `uk_order_no` (`order_no`), KEY `idx_status_create` (`status`, `create_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE `order_log` ( `id` BIGINT PRIMARY KEY AUTO_INCREMENT, `order_id` BIGINT NOT NULL, `from_status` TINYINT DEFAULT NULL, `to_status` TINYINT NOT NULL, `operator_id` BIGINT NOT NULL COMMENT '操作人ID', `operator_type` TINYINT COMMENT '1用户 2骑手 3系统', `remark` VARCHAR(200) DEFAULT '', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP, KEY `idx_order_id` (`order_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;代码里几个设计点值得说明：id是物理主键，order_no是业务编号，对外展示和日志追踪都用order_no，避免暴露自增 id 给用户端猜测订单量。status用 TINYINT 是为了节省空间，但可读性差，所以后面必须配一个OrderStatusEnum，代码里禁止出现裸数字。deliveryman_id默认 NULL，这是抢单逻辑的关键前提，下面 3.3 会用到。
3.2 下单接口：事务里完成写单与日志
用户在小程序提交发单，后端要做三件事：校验参数、计算费用、写订单记录。支付时机在课设里通常是“先创建订单，拉起支付，回调后再把状态改成已支付”，而不是下单立刻支付。这样实现的好处是订单记录永远存在，支付失败也能留痕。
public Long createOrder(OrderCreateRequest request, Long userId) { // 1. 参数校验：地址必填、物品描述长度不超过 100 if (StringUtils.isBlank(request.getPickupAddress()) || StringUtils.isBlank(request.getDeliveryAddress())) { throw new BizException("取件地址和送件地址不能为空"); } // 2. 费用规则：基础配送费 + 距离加价 + 小费 BigDecimal fee = calcFee(request.getDistance()); Orders order = new Orders(); order.setOrderNo(generateOrderNo(userId)); order.setUserId(userId); order.setPickupAddress(request.getPickupAddress()); order.setDeliveryAddress(request.getDeliveryAddress()); order.setItemDesc(request.getItemDesc()); order.setFee(fee); order.setTip(request.getTip() == null ? BigDecimal.ZERO : request.getTip()); order.setStatus(OrderStatus.CREATED.getCode()); ordersMapper.insert(order); // 3. 写一条初始日志 orderLogMapper.insert(OrderLog.of(order.getId(), null, order.getStatus(), userId, 1, "用户创建订单")); return order.getId(); }这段代码的关键在事务边界：createOrder必须被@Transactional包裹，保证订单表和日志表要么同时写入，要么同时回滚。这里的业务逻辑足够简单，不需要分布式事务，一个本地事务就能解决。calcFee是纯函数，建议单独抽出来，方便针对“3 公里内 5 元，超出每公里加 1 元”这类规则写单元测试。
generateOrderNo我习惯用“时间戳 + 用户 ID 低四位 + 随机三位数”拼一个 20 位以内的字符串，既保证可读性，又避免用数据库自增 id 当订单号暴露业务量。如果包里已经有现成的订单号生成器，别替换，直接沿用最简单的那种即可。
3.3 抢单接口：乐观锁 + 唯一索引兜底，别先查再改
抢单是跑腿平台最容易翻车的场景：两个骑手同时点“抢单”按钮，代码如果先select再update，大概率出现同一订单被两个人接走的脏数据。正确做法是把状态判断写进UPDATE的条件里，用“受影响行数”判断是否抢单成功。
@Update("UPDATE orders SET deliveryman_id = #{deliverymanId}, " + "status = 2, update_time = NOW() " + "WHERE id = #{orderId} AND status = 1 " + "AND deliveryman_id IS NULL") int takeOrder(@Param("orderId") Long orderId, @Param("deliverymanId") Long deliverymanId);public void takeOrder(Long orderId, Long deliverymanId) { int rows = ordersMapper.takeOrder(orderId, deliverymanId); if (rows == 0) { throw new BizException("手慢了，订单已被抢走"); } orderLogMapper.insert(OrderLog.of(orderId, OrderStatus.PAID.getCode(), OrderStatus.ACCEPTED.getCode(), deliverymanId, 2, "骑手接单")); }参数说明：rows是 MySQL 返回的影响行数，1 表示抢单成功，0 表示失败。条件里status = 1锁死必须是从“已支付待接单”状态进入，deliveryman_id IS NULL是二次兜底，防止同一条订单被两个并发请求同时更新。注意不用额外加synchronized或 Redis 分布式锁，因为这条 SQL 本身就是原子操作，行锁会让后到的更新阻塞或返回 0 行。只要抢单逻辑都走这个 Mapper，就不会出现超卖。
日志写入可以放在抢单成功后，也可以放在同一事务里。如果抢单成功但日志写入失败，事务回滚，订单回到待接单状态，保证日志与订单状态强一致。
4. 小程序端与后端联调：登录、定位、支付与订单列表的请求封装
4.1 登录：wx.login 换 code，后端换 openid 再发自定义 token
微信小程序不能直接在前端拿 openid，标准流程是：wx.login拿临时 code，传给后端，后端拿 code 向微信接口换 openid，然后签发自己的登录态。注意 code 是 5 分钟有效期、一次性使用，拿到就要立刻用。
// 小程序端：pages/login/login.js const login = () => { wx.login({ success: async (res) => { const { code } = res; const resp = await request({ url: '/api/login', method: 'POST', data: { code } }); wx.setStorageSync('token', resp.token); wx.setStorageSync('userInfo', resp.userInfo); } }); };@PostMapping("/api/login") public Result login(@RequestBody LoginRequest req) { String openid = wechatClient.jscode2session(req.getCode()).getOpenid(); User user = userMapper.selectByOpenid(openid); if (user == null) { user = new User(); user.setOpenid(openid); userMapper.insert(user); } String token = JwtUtil.createToken(user.getId()); return Result.success(new LoginVO(token, user)); }这段联调里有几个参数要关注：appid和appSecret必须从小程序后台的“开发管理-开发设置”里复制，不要用别人文档里的示例值。后端换 openid 时要注意隐藏appSecret，不能在代码里打印日志。前端拿到 token 后统一存到wx.setStorageSync，后续每个请求都带tokenheader。JWT 有效期建议 7 天，小程序每次启动时静默调用一次登录接口续期，避免用户一周后被强制下线。
4.2 发单页：定位、配送方式与地址解析的参数设置
发单页是跑腿小程序里表单最复杂的页面，核心交互有三个：选地址、选配送方式、填写小费和期望时间。选地址的常见做法是用wx.chooseLocation拉起微信自带的位置选择器，拿到经纬度和地址名称后再用腾讯位置服务做逆地址解析，补全结构化地址。
chooseLocation() { wx.chooseLocation({ success: (res) => { this.setData({ pickupAddress: res.address || res.name, pickupLatitude: res.latitude, pickupLongitude: res.longitude }); // 逆地址解析需要腾讯位置服务 key const key = '你的腾讯位置服务key'; wx.request({ url: `https://apis.map.qq.com/ws/geocoder/v1/?location=${res.latitude},${res.longitude}&key=${key}`, success: (resp) => { const addr = resp.data.result && resp.data.result.address; if (addr) this.setData({ pickupAddress: addr }); } }); } }); }这里的关键参数是坐标系。微信wx.getLocation默认返回wgs84坐标，但腾讯地图和国内地图服务用的是gcj02，所以调wx.chooseLocation时要把type明确设为gcj02，否则拿到的坐标在后续距离计算里会有几十米的偏差。配送方式我用radio-group实现，普通配送和加急配送分别设置系数，加急在基础费用上乘 1.5，选择后页面实时刷新费用预览。小费字段用input type="digit"，前端做一次 0 到 200 元的范围校验，后端在下单接口里再校验一次。
还需要在app.json里声明位置权限：
{ "permission": { "scope.userLocation": { "desc": "用于选择取件和送件地址" } }, "requiredPrivateInfos": ["chooseLocation", "getLocation"] }这段配置不写的话，安卓手机上调用wx.chooseLocation会直接失败，而且开发者工具里的报错信息很隐晦。
4.3 订单列表：请求封装、下拉刷新与缓存设置
订单列表是高频页面，但没必要每次进入都请求后端。常见做法是做一个带缓存时间的请求封装，缓存 60 秒内直接读本地，超时才重新请求。这样既减少服务器压力，又让页面切换时有即时反馈。
// utils/request.js const request = (options) => { return new Promise((resolve, reject) => { wx.request({ url: BASE_URL + options.url, method: options.method || 'GET', data: options.data || {}, header: { 'Content-Type': 'application/json', token: wx.getStorageSync('token') }, success: (res) => { if (res.data.code === 0) { resolve(res.data.data); } else if (res.data.code === 401) { // token 失效或过期，跳转登录 wx.removeStorageSync('token'); wx.navigateTo({ url: '/pages/login/login' }); } else { wx.showToast({ title: res.data.msg, icon: 'none' }); reject(res.data); } }, fail: (err) => { wx.showToast({ title: '网络异常', icon: 'none' }); reject(err); } }); }); };const getOrderList = () => { const cacheKey = 'order_list_cache'; const cache = wx.getStorageSync(cacheKey); if (cache && Date.now() - cache.time < 60 * 1000) { this.setData({ orderList: cache.data }); return Promise.resolve(cache.data); } return request({ url: '/api/orders', method: 'GET' }).then((list) => { wx.setStorageSync(cacheKey, { time: Date.now(), data: list }); this.setData({ orderList: list }); return list; }); };这里有个容易忽略的点：缓存命中后要同时开启wx.stopPullDownRefresh()，避免下拉刷新动画卡住。下拉刷新的正确姿势是“先展示缓存，再静默请求最新数据，成功后覆盖缓存和列表”，而不是每次下拉都转圈等网络。真机预览时BASE_URL要写成电脑的局域网 IP，不能写https://api.example.com这种假域名，具体原因见 5.2。
5. 避坑清单：跑腿平台从「能跑 Demo」到「运行不翻车」的 5 个注意点
5.1 解压即跑的假象：时区、字符集、依赖版本一步不对就起不来
现象：按 README 操作，导入 SQL 后启动后端，报Unknown column 'create_time'或Communications link failure，甚至有人遇到解压需要密码，实际只是 rar 伪加密标志位被误设置，常规解压工具直接就能解开。
原因：课设包的数据库脚本经常是旧版，代码却已迭代；或者 MySQL 连接串缺少时区和字符集参数，导致中文乱码和时间差 8 小时。JDK 版本不匹配是另一个高频问题，用 JDK 17 跑 JDK 8 的工程会直接编译失败。
解决：以代码为准，不盲信文档。启动后端后看 MyBatis 的 SQL 报错，缺列就ALTER TABLE补列。MySQL 连接串统一加?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai。JDK 8 的工程不要硬切 JDK 17，除非有把握处理javax到jakarta的迁移。
5.2 手机连不上本地后端：localhost 换成局域网 IP，再把域名配进 request 合法域名
现象：微信开发者工具里接口正常，手机扫码真机预览后所有请求全部 timeout。
原因：小程序端代码写死了http://localhost:8080，开发者工具默认不校验域名，真机预览时手机上的 localhost 指向手机自己，根本没有后端服务。
解决：把BASE_URL改成电脑的局域网 IP，比如http://192.168.1.5:8080。开发者工具里勾选“不校验合法域名”只对开发环境有效；想长期真机联调，需要在小程序后台把该 IP 加入 request 合法域名，但线上环境必须用 HTTPS 域名，不能依赖 IP。
5.3 微信支付报 appid 与 mch_id 不匹配：参数入口和签名算法优先排查
现象：调用wx.requestPayment拉起支付失败，后端收到回调提示appid and mch_id not match。
原因：小程序 AppID、商户号 mch_id、API 密钥来自三个不同的管理后台，复制错了账户；或者统一下单时漏传了sub_appid、sub_mch_id这类参数。课设阶段最常见的原因是拿别人的测试商户号直接填。
解决：核对三个值是否来自同一主体：小程序 AppID（微信公众平台）、商户号（微信支付商户平台）、APIv3 密钥（商户平台自己设置）。统一下单时appid填小程序 AppID，mch_id填商户号。如果项目还没有商户号资质，不要硬接真实支付，用“模拟支付”按钮直接调后端把订单状态改成已支付，把真实支付留到上线前替换。
5.4 并发抢单：同一订单被两个骑手同时接走
现象：用户看到订单被两个骑手接单，或骑手接单后订单状态又被其他请求改掉。
原因：后台代码是先查select再update，两个并发请求都查到同一订单状态为待接单，然后依次更新，后一个覆盖前一个。
解决：把状态判断写进UPDATE条件，采用“受影响行数”判成功（见 3.3）。抢单大厅列表查询时不要一次返回全部订单，LIMIT 20足够；骑手抢单成功后立即刷新列表，把已被人抢走的订单从本地数据里移除。日志表记录每一次状态变更，出了纠纷也有据可查。
5.5 自定义导航栏高度与顶部定位漂移：iPhone 状态栏和 gcj02 坐标系是两大元凶
现象：自定义导航栏在 iPhone 上被刘海遮挡，点击“选择地址”时定位结果与实际位置偏差几十米。
原因：自定义导航栏没有把状态栏高度算进去，直接按menuButton.top计算导致按钮位置偏高。定位坐标则是因为没有指定坐标系，微信默认返回wgs84，而腾讯地图用gcj02，国内地图服务基于后者，坐标不转换就会有偏移。
解决：用wx.getMenuButtonBoundingClientRect()获取胶囊位置，结合wx.getWindowInfo().statusBarHeight计算导航栏高度，公式是statusBarHeight + menuButton.height + (menuButton.top - statusBarHeight) * 2。定位接口显式传type: 'gcj02'，后端距离计算也统一按gcj02处理，不要出现前后端坐标系混用。
6. 从课设到能用的进阶：验证链路、超时自动取消与实时轨迹
跑腿平台做完不是终点。我会按“一条订单从发起到送达的完整生命周期”来做验证：登录、发单、支付（模拟）、骑手抢单、取货、送达、评价。验证时准备两台手机，一台当用户、一台当骑手，后端开着日志，观察每次状态变更对应的 URL 和 SQL。开发者工具里能通过的流程，在真机上可能因权限、坐标、网络环境失败，所以真机走一遍完整链路是我交付前的底线。
进阶功能优先做两个：超时未支付自动取消，和骑手实时位置上报。前者用 Spring 的@Scheduled定时任务，每分钟扫描一次status = 0 AND create_time < now() - 15 分钟的订单，将其改成CANCELLED并写日志。注意定时任务要加@EnableScheduling，且多个实例部署时要加分布式锁，避免重复执行。
骑手位置上报的简单做法是：骑手小程序每 5 秒调wx.getLocation把经纬度上报到后端一张deliveryman_location表，用户订单详情页每 5 秒轮询一次最新坐标。这个方案实现成本最低，不需要引入 WebSocket 就能演示轨迹跟踪。等流量上来再考虑用 WebSocket 或长连接推送，但课设阶段轮询已经够用。
最后提醒一句：这类项目包真正的价值不是代码本身，而是拿到代码后自己重建一遍核心逻辑。我习惯把订单状态机画在纸上，把三张表字段默写一遍，再去对照源码，往往能发现包里的表结构设计得并不合理，改完反而让答辩更有内容。希望你也能把这份跑腿平台当作业余练手的完整样本，而不是解压完就扔进仓库吃灰。这些验证方法和进阶方向，应该能帮你少走一段弯路，希望帮到你。
本文还有配套的精品资源，点击获取
