Java微信小程序跑腿平台开发实战：从需求文档到代码落地

简介这是一份面向Java后端开发者与微信小程序学习者的跑腿平台完整实现资料对应基于微信小程序下单、后台接单派单的典型O2O业务场景。资源围绕Spring Boot、MyBatis、微信支付与消息推送、MySQL数据库设计等核心知识点展开包含项目源码、需求说明、数据表脚本及前端页面资源。压缩包内共2020个文件其中java源码与xml配置对应服务端逻辑wxml、wxss、js构成小程序前端大量png、svg、css与html多为界面素材和移动端静态页面另含sql数据库脚本整体约9.81MB。已有200人学习下载。文件结构较为清晰适合需要快速了解跑腿平台模块划分、用户下单/接单流程、支付与位置服务集成方式的初学者也可作为毕业设计或课程项目的参考模板按需提取使用。1. 跑腿平台不是外卖系统的换皮Java 与微信小程序之外需求文档才是主心骨“Java 基于微信程序的跑腿平台的设计与实现-需求代码.rar”这个标题里Java 和微信小程序最显眼但真正决定项目成败的反而是最后那四个字需求代码。把压缩包解压后如果里面只有一堆 Controller 和几张表结构截图没有需求文档整套代码就是个黑匣子。反过来先读需求再碰代码一小时内就能画出全貌用户在小程序里下单代取件、代送件骑手端抢单配送管理员在后台做审核和结算Java 后端用 Spring Boot 暴露接口MySQL 存用户、订单、结算数据。这套方案适合两类人拿它做毕业设计的学生想用最小成本验证同城跑腿业务的产品负责人。前者照着骨架梳理代码和文档就能准备答辩后者可以直接拿它当 MVP 试运行等单量起来再逐步替换核心模块。跑腿平台作为微信小程序项目实例里业务闭环比较完整的一类值得动手跑一遍。2. 把需求文档拆成模块跑腿平台的用户、骑手与订单三权分立2.1 需求文档里必须圈出的四张表用户表、订单表、骑手表、结算表拿到“需求代码.rar”后先建一个临时目录把需求文档和代码分开摆放。我一般先打开文档的目录结构而不是直接看 pom.xml。跑腿平台的核心数据模型就四张表需求文档里所有叙述最终都会落到它们身上。用户表普通下单人和骑手可以共用一张表用 role 字段区分。很多需求文档会把“用户”和“骑手”分开描述但从数据库设计角度看一个人既可以是下单用户也可以注册成为骑手。让 user_role 在 0 和 1 之间切换比拆两张表更贴合实际业务。订单表订单主状态字段设为 status约定 0 待接单、1 已接单、2 配送中、3 已完成、4 已取消。不少新手做毕设时会把“配送中”这个状态省掉答辩时被老师一句“骑手取到货之后到送达之前系统处于什么状态”问住。建议保留一个字段的成本可以忽略但业务故事完整得多。骑手表存接单量、完成量、评分。做骑手排行榜和后台统计时直接查这张表聚合不用去 order 表反复 group by查询性能差一个量级。结算表记录每笔订单的跑腿费、平台抽成、骑手所得。需求文档没写结算逻辑自己也要补一个简单版本这是答辩高频问题“订单完成之后钱怎么分、什么时候分、退单怎么退”。三句话能说清楚分数就稳了。2.2 管理后台与小程序对不上帐需求文档与接口清单的两个脱节点看过不少毕设项目最常见的毛病是“小程序有下单按钮后端却没有创建订单的接口”或者反过来“后端设计了优惠券表小程序压根没有入口”。破解办法是开工前维护一份接口清单把页面和后端方法逐一对应小程序下单页的“提交订单”按钮对应后端POST /api/order/create下单成功后跳转的列表页对应GET /api/order/list?status0骑手端“我要抢单”按钮对应POST /api/order/grab。这份清单用 Excel 或 Markdown 都行填满“接口名、请求方法、请求参数、返回字段、所属页面”五列。代码写完后逐项勾选没勾上的要么是多余接口要么是漏掉的页面一目了然。第二个脱节点在登录。需求文档通常写“用户可以使用微信授权登录”但这是一句 UI 描述落到 Java 后端其实是两个动作小程序wx.login()拿到临时 code后端用 code 换 openid再签发一个自定义 token 返回给小程序。文档里一句话代码里是两个接口加一张用户表。这个认知差异是跑腿平台项目里最容易被低估的工作量。2.3 用 SQL 建模跑腿订单状态字段与时间戳的配套设计创建订单表的 SQL我一般这样写CREATE TABLE order ( id bigint(20) NOT NULL AUTO_INCREMENT, order_no varchar(32) NOT NULL COMMENT 订单号对外展示用, user_id bigint(20) NOT NULL COMMENT 下单用户, courier_id bigint(20) DEFAULT NULL COMMENT 接单骑手接单前为空, pickup_address varchar(255) NOT NULL COMMENT 取件地址, delivery_address varchar(255) NOT NULL COMMENT 送件地址, item_type varchar(50) DEFAULT NULL COMMENT 物品类型文件/餐食/包裹, note varchar(500) DEFAULT NULL COMMENT 备注, fee decimal(10,2) NOT NULL DEFAULT 0.00 COMMENT 跑腿费, status tinyint(4) NOT NULL DEFAULT 0 COMMENT 0待接单 1已接单 2配送中 3已完成 4已取消, create_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, accept_time datetime DEFAULT NULL COMMENT 接单时间, finish_time datetime DEFAULT NULL COMMENT 完成时间, PRIMARY KEY (id), KEY idx_status (status), KEY idx_user_id (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这张表有几个跑腿平台特有的设计点。order_no不能直接拿自增 id 对外展示订单号会印在小票上、会被用户报给客服自增 id 会暴露平台单量。省事的做法是时间戳加随机数yyyyMMddHHmmss拼 4 位随机数生成 18 位订单号。courier_id在接单前是 NULL所以“待接单”列表天然要过滤这个字段。查询时我会同时写status 0 AND courier_id IS NULL前者控制状态语义后者兜底脏数据。accept_time和finish_time则承接“配送中”状态的取证——接单时写前者完成时写后者管理后台的订单时长统计直接相减不用从 create_time 开始猜。取消订单时注意别复用 finish_time建议单独加 cancel_time 字段。后端接口判断条件也顺带写成UPDATE order SET status4 WHERE id? AND status0让“只有待接单能取消”这个规则落在 SQL 条件里而不是先查出来再在 Java 里判断避免两个请求同时把订单改到不同状态。3. 用 Java 实现登录与抢单链路code2Session 与订单状态机的落地代码3.1 小程序登录换取 openidwx.login 到 code2Session 的完整实现跑腿平台的第一个接口不是下单而是登录。用户打开小程序前端调用wx.login()拿到一个临时 code这个 code 只能用一次有效期五分钟。前端把 code 传给后端后端拿 code 加 appid 和 secret 调微信的 code2Session 接口换取 openid 和 session_key。登录接口的 Java 代码RestController RequestMapping(/api/user) public class UserController { Resource private UserService userService; PostMapping(/login) public Result login(RequestBody LoginRequest request) { // request.code 来自 wx.login() 的返回值五分钟有效 String openid userService.getOpenidByCode(request.getCode()); if (openid null) { return Result.error(code已失效请重新登录); } // 根据 openid 查用户查不到则自动注册 User user userService.findOrCreateByOpenid(openid); // 签发自定义登录态 token后续接口在 Header 里带这个 String token JwtUtil.createToken(user.getId(), user.getRole()); return Result.ok(token); } }逻辑说明getOpenidByCode方法里封装一次 HTTP 调用请求微信的jscode2session接口。微信返回的 JSON 里有 openid这是用户在这套小程序里的唯一身份标识用它作为用户表的业务主键比自增 id 更稳妥——同一个用户换设备登录自增 id 可能查出两条记录openid 永远只有一个。注意code 换 openid 后无需保存 session_key。早期教程会建议存 session_key 用来解密手机号但现在的微信小程序基本都用getPhoneNumber组件取手机号后端调官方接口换取不再走解密流程。这个接口做完建议顺手把 JWT 工具类里的过期时间调好。跑腿平台的骑手可能一整天挂着小程序token 有效期至少 7 天第 5 章会专门聊登录态过期的问题。3.2 下单与抢单接口的幂等设计防止同一订单被两个骑手抢到跑腿平台最真实的并发场景在抢单10 个骑手盯着同一个订单几乎同时点了接单。如果接单接口写成“先 select 再 update”两个骑手都读到 status0都进入 update订单就被抢了两次。安全的抢单逻辑Transactional public boolean grabOrder(Long orderId, Long courierId) { Order order orderMapper.selectById(orderId); if (order null || order.getStatus() ! 0) { throw new BusinessException(订单不存在或已被抢); } // 条件更新把当前状态放进 where并发下只有一个人能成功 int rows orderMapper.grab(orderId, courierId); if (rows 0) { throw new BusinessException(手慢了订单已被其他骑手抢走); } // 抢单成功记录日志、推送消息 return true; }对应的 SQLUPDATE order SET status 1, courier_id #{courierId}, accept_time NOW() WHERE id #{orderId} AND status 0逻辑说明数据库行锁保证同一时刻只有一个更新成功rows 0说明状态被别人改掉了。注意事务范围不要包太多操作抢单接口的目标是 10 毫秒级响应别在里面写 Redis 预扣、发短信之类的事。下单接口也要防重复。用户连续点两次“提交订单”前端按钮置灰是一道防线后端的兜底方案是加request_id字段。前端进入下单页时生成 UUID提交时带上后端先查SELECT id FROM order WHERE request_id #{requestId}已存在就直接返回现有订单不再创建。这个方案比单纯前端控制可靠用户连点、网络重试、小程序冷启动重复提交都产生不了重复单。3.3 订单状态机的 Java 实现让状态流转只走合法路径订单五个状态如果不做约束代码里到处是if (status 1)迟早出现“已完成”跳回“已接单”这种脏数据。我在项目里会集中维护一张状态流转表public class OrderStatusMachine { private static final MapInteger, SetInteger TRANSITIONS new HashMap(); static { // 待接单 - 已接单 / 已取消 TRANSITIONS.put(0, new HashSet(Arrays.asList(1, 4))); // 已接单 - 配送中 / 已取消 TRANSITIONS.put(1, new HashSet(Arrays.asList(2, 4))); // 配送中 - 已完成 TRANSITIONS.put(2, new HashSet(Collections.singletonList(3))); // 已完成、已取消为终态没有后续流转 } public static void validate(int from, int to) { SetInteger allowed TRANSITIONS.get(from); if (allowed null || !allowed.contains(to)) { throw new BusinessException(非法的订单状态流转: from - to); } } }使用方式// 骑手确认送达订单必须处于配送中 OrderStatusMachine.validate(order.getStatus(), 3); orderMapper.updateStatus(order.getId(), 3);逻辑说明状态机的价值是把“订单能不能从 A 到 B”的规则收拢到一处。骑手端“确认送达”按钮调用validate(1, 3)会直接抛异常因为订单还在已接单状态于是“没去取件就送达”的怪数据从源头被拦住。这个类在答辩时很好讲实际上也是 Java 基础面试八股文里常问的状态模式的一种轻量应用。需要扩展规则时比如“配送中超时自动取消”只要在 TRANSITIONS 里给状态 2 加一条到 4 的流转再挂一个定时任务就行。改一处全平台生效。4. 小程序端从下单到接单轮询刷新与订单按钮组的状态同步4.1 首页与下单页的代码骨架绕开顶部导航栏高度的适配坑小程序首页通常是“搜索框 分类卡片 订单列表”的布局。顶部导航栏有两种做法用默认导航栏省事但很多跑腿平台需求文档会写“自定义导航栏”比如把品牌色和位置信息直接嵌在顶栏里。这时候要在 app.json 里给对应页面配navigationStyle: custom然后自己写导航栏视图。自定义导航栏第一个坑是状态栏高度。iPhone 的刘海屏会顶掉内容需要动态获取const systemInfo wx.getWindowInfo(); Page({ data: { statusBarHeight: systemInfo.statusBarHeight, } });WXML 里给导航栏视图设置padding-top: {{statusBarHeight}}px。这个高度在 iPhone 上是 44 或 47在 Android 上是 24 左右硬编码会直接翻车——网上“微信小程序顶部导航栏高度”的搜索热度高就是因为这个坑踩的人多。下单页的地址选择是跑腿平台特有的交互。用户要填取件地址和送件地址两个地址都来自wx.chooseLocationwx.chooseLocation({ success: (res) { this.setData({ pickup.address: res.address, pickup.latitude: res.latitude, pickup.longitude: res.longitude }); }, fail: () { wx.showToast({ title: 需要授权位置信息才能下单, icon: none }); } });逻辑说明wx.chooseLocation返回的地址是结构化文本但后端保存时不能只存文本下单接口要接收取件和送件的经纬度共 4 个坐标字段外加两个地址文本字段。管理后台做区域筛选、距离排序都依赖这 4 个坐标。同时记得在 app.json 里配置permission.scope.userLocation的提示文案否则基础库直接不弹授权框。4.2 待接单列表的刷新策略定时轮询与 WebSocket 的取舍骑手端首页是待接单列表需要时刻知道有没有新单。WebSocket 全量推送更实时但链路长后端要维持长连接、处理重连和心跳新手项目先别碰。先用定时轮询把业务跑通单量上来再换。保守做法是每 5 秒拉一次startPolling() { this.pollingTimer setInterval(() { wx.request({ url: ${app.globalData.baseUrl}/api/order/list, data: { status: 0, page: 1, size: 20 }, success: (res) { if (res.data.code 0) { this.setData({ orders: res.data.data.records }); } } }); }, 5000); } onHide() { this.stopPolling(); } onUnload() { this.stopPolling(); } stopPolling() { if (this.pollingTimer) { clearInterval(this.pollingTimer); this.pollingTimer null; } }逻辑说明页面卸载前务必clearInterval这是小程序内存泄漏的高发点。用户切后台再回来setInterval 仍在跑白耗流量和 CPU。更细的写法是onShow里开启轮询、onHide里停止配合生命周期才能把轮询控制住。轮询间隔按单量调整单量少的区域 10 秒高峰期 3 秒再短就该考虑 WebSocket 了。另外轮询接口要带cache: no-cache。小程序请求默认会走缓存不加这个参数某些机型上列表永远是第一次请求的结果骑手端看到的订单状态和用户端对不上体验很糟糕。4.3 订单卡片的状态按钮用 wx:if 渲染不同操作一个订单卡片在用户端可能展示“等待骑手接单”“骑手已接单”“配送中”“已完成”四种形态按钮组跟着状态走view classorder-card view classorder-status{{item.statusText}}/view block wx:if{{item.status 0}} button sizemini bindtapcancelOrder>const statusTextMap [等待接单, 骑手已接单, 配送中, 已完成, 已取消]; list.forEach(item { item.statusText statusTextMap[item.status] || 未知状态; });后端返回 int 型 status前端拿它当数组下标比一长串item.status 0 ? ... : ...清爽得多。如果后端用了自定义状态枚举前端也要维护同一份映射表两边的数字含义必须完全一致这是前后端联调时最容易扯皮的点。5. 跑腿平台常见问题排查登录态、定位、支付回调等五个踩坑记录5.1 登录态静默失效明明登录过过几小时却被弹回未登录现象用户在小程序里授权登录后过几个小时再打开点击下单后端返回“未登录”。但小程序右上角明明显示已登录。原因自定义 token 过期时间太短。JwtUtil.createToken里如果只签 2 小时小程序端又没有在收到 401 时自动刷新 token就会出现这个现象。另一种隐蔽情况是小程序缓存被系统清理前端存的 token 还在后端却已经找不到对应会话。解决token 有效期调到 7 天在全局请求封装里统一拦截 401收到后重新wx.login()换 code再调后端 refresh 接口换新 token然后重放当前请求。refresh 流程要做防抖避免多个并发请求同时触发多次刷新。5.2 状态机太死板骑手接单后想取消接口直接报错现象联调时发现骑手误抢了订单想取消但状态机只允许“已接单 → 配送中”取消接口抛异常。原因初期把“骑手取消”和“用户取消”混为一谈认为只有待接单才能取消忽略了实际场景中骑手也可能需要取消。解决区分取消主体。用户只能在待接单状态取消骑手接单后要取消走“协商取消”流程新增状态 5 待取消骑手发起后通知用户和管理员管理员确认后再置为 4 已取消。状态机里补一条1 - 5的流转即可上线前把这个流程写进需求文档避免答辩时被挑刺。5.3 定位授权被拒后下单页白屏现象用户点击“选地址”系统弹出授权框被拒绝小程序白屏或者报错fail auth deny。原因代码里假设wx.chooseLocation一定成功fail 回调里只弹了个 toast没有处理auth deny分支。部分基础库版本在权限被拒后连续调用wx.chooseLocation会直接走 fail页面数据停在半加载状态。解决fail 回调里判断err.errMsg是否包含auth deny如果是就调用wx.openSetting引导用户去设置页打开位置权限。同时准备一个手动输入地址的兜底弹层用户拒绝授权后仍能通过文字输入完成下单白屏问题从根上杜绝。5.4 支付回调验签失败订单卡在待支付现象用户确实付了款微信服务器也回调了后端接口但验签一直失败后端日志刷sign not match订单状态始终不动。原因回调验签时把原始报文转成 JSON 对象再重新序列化字段顺序变了签名自然对不上。微信支付的签名是基于原始字符串按字典序拼接后计算的任何格式化操作都会破坏签名。解决回调接口里用request.getInputStream()读原始字节流先把字节流完整读出来验证签名验证通过后再从字节流做业务解析不要先转对象再序列化。用官方 SDK 的 V3 接口可以少踩一半坑核心原则是“验签用原始报文解析用原始字节”。5.5 订单神秘消失管理后台按用户查询查不到记录现象运营反馈某个用户的订单不见了但用户手机里能看到订单列表而且订单已完成。原因订单表与管理后台列表的联查用了INNER JOIN关联骑手表courier_id为 NULL 的记录还未被接单的订单直接被内连接过滤掉了。筛选条件为空时管理后台就在查一个被内连接筛过的视图漏数据成为必然。解决订单列表一律用LEFT JOIN关联骑手表对courier_id的过滤显式写成courier_id IS NULL不依赖连接结果。顺手检查所有管理后台报表凡是订单表为主表的查询都要保证订单一行不被膨胀成多行必要时用 DISTINCT 或 GROUP BY 兜底。6. 把毕设跑成真正能试运行的平台压一组接口数据与三个扩展点6.1 用压测暴露慢 SQL下单接口不应该超过 200 毫秒本地开发完不要急着让同学点着玩。用 JMeter 起 500 个线程打下单接口如果平均响应超过 200 毫秒基本可以断定 order 表缺索引。用EXPLAIN看执行计划type是 ALL 就是全表扫描。确认后补两组索引ALTER TABLE order ADD INDEX idx_create_time (create_time); ALTER TABLE order ADD INDEX idx_courier_status (courier_id, status);这两个索引覆盖了骑手端最常见的查询WHERE status 0和WHERE courier_id ? AND status IN (...)。跑腿平台的核心压力集中在列表页和抢单操作索引到位后同样压测响应时间会有非常直观的下降。6.2 三个值得扩展的点距离计价、骑手评分、Redis 缓存列表第一个是距离计价。下单时用地图 API 算取送两点距离按“基础价 每公里阶梯价”自动填跑腿费避免用户每次手动改价也减少订单被低价单浪费运力的情况。第二个是骑手评分。订单完成后双方互评评分写进骑手表管理后台排序时直接引用。评分体系还能延伸出信用分、优先派单等玩法业务故事更完整。第三个是 Redis 缓存待接单列表。订单量上来后WHERE status 0 ORDER BY create_time DESC这个查询的压力会很明显。把待接单列表缓存进 Redis新单创建时失效缓存抢单接口响应能压到 50 毫秒以下。要注意缓存和数据库的一致性双写或订阅 Binlog 二选一别只更新一头。我接手这类项目几年最后总会在答辩前习惯性地把“下单 → 抢单 → 配送 → 完成”全流程手动过一遍再故意把手机系统时间改到跨天重新测一趟。小程序里的缓存、登录态、订单状态全都躲不开时间这个变量。希望这篇笔记能帮你少踩几个坑把跑腿平台真正跑起来。本文还有配套的精品资源点击获取