跑腿平台实战：Spring Boot后端+微信小程序全链路资源拆解

简介这份基于Java与微信小程序技术的跑腿平台项目资料面向Java后端开发者、小程序学习者及需要完成课程设计或毕业设计的在校生。资源共2020个文件压缩包大小约9.81MB涵盖png、css、html、svg等前端静态资源java、js、json、xml等后端与逻辑代码以及wxml、wxss、sql等小程序与数据库脚本其中48个Java文件对应后台服务模块87个JS文件提供页面交互逻辑便于从界面设计到数据存储进行系统梳理。目前已有200人浏览学习适合作为项目实战参考。包内提供完整源码、页面素材与数据库初始化脚本目录结构清晰可结合jQuery Mobile等前端框架快速还原跑腿平台的用户下单、后台接单等核心流程也能对照微信小程序项目结构理解WXML/WXSS的组件化开发方式是毕业设计、课设答辩或进阶提升的实用范本。1. 跑腿平台这套资源到底装了什么先看清单再看架构做 Java 后端的人大多接过微信小程序的项目而跑腿平台是这类项目里最典型的一种用户端是小程序骑手端是后台中间夹着一堆订单状态流转、微信支付回调、位置计算和任务分配逻辑。这套资源的价值在于它把「需求文档 代码」凑齐了不是只有一堆截图和 PPT适合两类人一是做 Java 课程设计或毕业设计的学生二是想快速摸清微信小程序 Spring Boot 整套链路怎么串起来的在职开发者。你拿到手能直接照着把项目跑起来也能拿里面的表结构和接口设计当模板改造成自己的业务。先说清楚这套资源的技术底座后端是 Java 生态主体用 Spring Boot 搭建数据访问层用 MyBatis缓存用 Redis前端是微信小程序原生开发涉及 WXML、WXSS 和 JavaScript数据库以 MySQL 为主配套微信登录、微信支付、订阅消息和地图 API 的集成。下文我会按「后端骨架 → 小程序端链路 → 任务调度 → 避坑 → 上线自查」五个部分把这套资源真正能落地的细节拆开讲。2. 后端骨架与数据库设计Spring Boot、MyBatis、订单状态机2.1 为什么是 Spring Boot 而不是 SSM需求文档的隐藏信息这套资源里需求文档的措辞是「后台管理系统 小程序接口」这个表述基本就锁定了技术选型。跑腿平台的核心后端功能是用户管理、订单处理、支付接口集成这类 CRUD 密集、接口数量多、需要快速迭代的业务Spring Boot 的自动配置和 starter 机制能省掉大量 XML 配置。相比传统的 SSMSpring SpringMVC MyBatisSpring Boot 把 Tomcat 内嵌、数据源自动配置、JSON 序列化这些事情都收敛到 application.yml 里对单人开发或者小团队协作来说效率高得多。我一般会用 Spring Boot 2.7.x 版本配 JDK 8原因很实际2.7.x 还在 Spring 官方维护周期的人类友好区且与微信支付 V3 的 SDK 兼容性稳定。如果你拿到手的代码是 2.x 版本别急着升 3.x微信支付 SDK 和很多老依赖在 3.x 下需要额外适配不值得在这个项目里折腾。2.2 application.yml 与多环境配置连接池、Redis、日志一个都不能少跑腿平台这种项目本地开发、测试服务器、生产环境至少三套配置。我会在 resources 目录下拆出 application-dev.yml、application-test.yml、application-prod.yml主配置里用 spring.profiles.active 切换。下面是一份核心配置的参考写法server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/paotui?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 hikari: maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 30000 idle-timeout: 600000 redis: host: localhost port: 6379 database: 0 timeout: 3000ms lettuce: pool: max-active: 8 max-idle: 8 min-idle: 0 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.paotui.entity configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl logging: level: com.paotui.mapper: debug这段配置里有三个关键的工程化细节第一HikariCP 连接池的 maximum-pool-size 设为 20对跑腿平台这个量级足够设太大反而浪费数据库连接资源第二MyBatis 的 map-underscore-to-camel-case 必须开这样数据库的 order_status 才能自动映射到 Java 属性的 orderStatus少写大量 resultMap第三mapper 层日志输出用 StdOutImpl开发阶段能直接看到 SQL 和参数排查问题效率翻倍。Redis 在这里承担的不是简单缓存而是订单并发去重和用户会话管理。比如用户重复提交同一个跑腿订单我会在 Redis 里用 SETNX 命令对 userId orderId 做幂等标记过期时间设 30 秒防止请求重试导致订单被创建两次。这个设计在需求文档里没有展开但实际跑起来你会发现这是高频踩坑点。2.3 订单表与跑腿员表状态机是订单模块的灵魂跑腿平台的订单流转比普通电商复杂因为涉及用户、跑腿员、平台三方状态同步。这张订单表是整套系统的核心字段设计直接决定后续写 SQL 的体验字段名类型说明idbigint主键雪花算法生成order_novarchar(32)订单编号全局唯一user_idbigint下单用户 IDcourier_idbigint接单跑腿员 ID可空pickup_addressvarchar(255)取件地址delivery_addressvarchar(255)送达地址pickup_lng / pickup_latdecimal(10,6)取件经纬度delivery_lng / delivery_latdecimal(10,6)送达经纬度goods_typetinyint物品类型1 文件 2 食品 3 药品 4 其他order_statustinyint0 待支付 1 待接单 2 已接单 3 配送中 4 已完成 5 已取消payment_statustinyint0 未支付 1 已支付 2 已退款distancedecimal(10,2)预估距离单位 kmfeedecimal(10,2)跑腿费用create_time / update_timedatetime创建与更新时间order_status 这个字段是整个订单模块的状态机。从代码角度我会用一个 OrderStatusEnum 来管理状态流转禁止在业务代码里直接写魔法数字。状态流转的合法路径只有这几条待支付 → 待接单支付成功→ 已接单跑腿员接单→ 配送中跑腿员开始配送→ 已完成用户确认或系统自动确认待支付 → 已取消用户取消或超时待接单 → 已取消用户取消。不要允许任何非法跳转比如从待支付直接跳到配送中这在代码层面必须拦截。实现方式很简单写一个状态流转校验方法在 Service 层更新状态前先对比当前状态和期望前置状态不一致直接抛业务异常。这套资源代码里如果只有简单的 update 语句没有校验你在二次开发时一定要自己补上。2.4 任务调度策略距离 接单数 评分的加权评分算法跑腿平台的灵魂问题是一个订单产生了推给谁最简单的做法是广播给附近所有跑腿员谁先抢到算谁的但这样会导致热点区域订单扎堆、偏远区域无人接单。这套资源里提到「最近接单原则、优先级排序」实际落地我会做加权评分public class DispatchScorer { private static final double WEIGHT_DISTANCE 0.5; private static final double WEIGHT_LOAD 0.3; private static final double WEIGHT_RATING 0.2; public double score(Courier courier, Order order) { double distanceScore calculateDistanceScore(courier, order); double loadScore calculateLoadScore(courier); double ratingScore courier.getRating() / 5.0; return WEIGHT_DISTANCE * distanceScore WEIGHT_LOAD * loadScore WEIGHT_RATING * ratingScore; } private double calculateDistanceScore(Courier courier, Order order) { double distance GeoUtil.distance( courier.getLat(), courier.getLng(), order.getPickupLat(), order.getPickupLng()); return Math.max(0, 1 - distance / 5.0); } private double calculateLoadScore(Courier courier) { int activeOrders courier.getActiveOrders(); return Math.max(0, 1 - activeOrders / 5.0); } }这段代码的逻辑是分数越高越优先推送距离权重最高占 50%距离越近分数越接近 1跑腿员当前在途订单数占 30%防止一个人挂太多单导致配送超时历史评分占 20%服务质量好的跑腿员能获得更多订单。实际推送时可以配合 Redis 的 GEO 命令先筛选出以取件点为中心 3 公里内的在线跑腿员再对这个候选集合做评分排序避免所有跑腿员都参与计算。参数怎么调是学问。WEIGHT_DISTANCE 设太高偏远区域永远没人接单设太低跑腿员满城跑不划算。我一般会把距离权重的距离阈值从 5 公里改成可配置项放到 application.yml 里后续运营可以根据数据调整。另外每次订单被取消后权重调整一次慢慢逼近这个区域的最优参数。3. 微信小程序端登录、下单、支付、通知的完整链路3.1 登录链路wx.login 换 openid别把 code2Session 当登录小程序端的登录逻辑是新手最容易搞错的环节。很多人直接把 wx.login 返回的 code 当成用户身份存起来这是错的。正确姿势是小程序端调用 wx.login 拿到临时 code把 code 发给后端后端拿着 code 去微信的 code2Session 接口换 openid 和 session_key然后后端自己生成一个业务 token 返回给小程序。后续所有请求都带这个 token而不是每次都用 code。RestController RequestMapping(/api/auth) public class AuthController { Autowired private AuthService authService; PostMapping(/login) public Result login(RequestBody LoginRequest request) { // 1. 用 wx.login 返回的 code 换 openid String openid authService.code2Openid(request.getCode()); // 2. 查数据库新用户则自动注册 User user authService.findOrCreateUser(openid); // 3. 生成业务 token有效期 7 天 String token JwtUtil.generateToken(user.getId(), 7 * 24 * 3600); return Result.ok().put(token, token).put(userId, user.getId()); } }这里几个关键点第一code 是一次性的有效期五分钟用一次就失效所以后端拿到 code 必须立刻调用微信接口第二换到的 openid 是用户在小程序体系内的唯一标识同一个用户在不同小程序里 openid 不同但同一小程序内是稳定的第三session_key 不能返给前端它是后续解密手机号、支付时用的敏感信息只能保存在后端。JWT token 的过期时间设置成 7 天比较合适太短用户要频繁登录太长有安全风险。Redis 里可以同时存一份 token 和 userId 的映射做主动注销时用。3.2 下单与微信支付统一下单、回调验签与幂等处理用户下单后跳转支付小程序端通过 wx.requestPayment 拉起微信支付。这里的完整链路是小程序端先调后端接口创建订单并获取支付参数后端接收请求后调用微信支付 V3 的 JSAPI 下单接口拿到预支付交易会话标识 prepay_id再签名返回给小程序端。小程序端拉起支付后结果不是即时返回给后端的而是微信服务器异步通知后端配置的 notify_url。public String createOrder(Long userId, OrderCreateDTO dto) { // 1. 幂等检查Redis SETNX userId 业务唯一键 boolean firstCall redisTemplate.opsForValue() .setIfAbsent(order:create: userId, 1, Duration.ofSeconds(30)); if (!firstCall) { throw new BizException(请勿重复提交订单); } // 2. 创建订单状态为待支付 Order order new Order(); order.setOrderNo(OrderNoGenerator.generate()); order.setUserId(userId); order.setOrderStatus(OrderStatusEnum.WAITING_PAY.getCode()); orderMapper.insert(order); // 3. 调微信支付统一下单 String prepayId wechatPayService.jsapiPay(order.getOrderNo(), order.getFee()); return buildPayParams(prepayId); }支付回调的处理是这里最容易翻车的点。微信服务器会以 POST 方式把支付结果通知到 notify_url后端拿到回调后要做的第一件事是验签确认这个回调确实来自微信然后更新订单状态。这有个坑必须等订单状态从待支付变成已支付后再返回 success 给微信如果回调处理失败微信会按照一定策略重试通常是 15 秒、15 秒、30 秒、3 分钟、10 分钟、20 分钟、30 分钟、30 分钟、30 分钟、60 分钟、3 小时、3 小时、3 小时、6 小时、6 小时总计 24 小时。幂等处理的思路是回调里先查订单表如果订单已经是已支付状态直接返回成功不再重复更新。因为微信重试机制的存在一个订单的支付回调可能被推送多次不处理幂等就会出现重复发货或者状态被覆盖。3.3 订单状态刷新轮询、订阅消息与下拉刷新的取舍用户下单后需要实时看到订单状态变化待接单、已接单、配送中、已完成。小程序端怎么知道状态变了三种方案轮询、WebSocket、订阅消息。轮询最简单小程序端每隔一段时间请求一次订单详情接口。这个方案在订单量不大的场景下完全够用实现成本最低。我会把轮询间隔设为 5 秒用 setInterval 实现页面进入前台时启动退到后台时清除。注意微信小程序在页面隐藏后setInterval 会被系统挂起等回到前台时一次性触发多次请求所以要在 onShow 里重新校准状态。startPolling(orderId) { this.intervalId setInterval(() { this.fetchOrderDetail(orderId) }, 5000) }, onHide() { if (this.intervalId) { clearInterval(this.intervalId) } }, onShow() { if (this.orderId) { this.stopPolling() this.startPolling(this.orderId) } }订阅消息适合在订单状态变更的关键节点做通知比如取件人到附近了、订单完成了。但微信的订阅消息机制有坑用户的一次订阅只能发送一次模板消息用户不主动订阅就不能发。所以正确的做法是在用户下单成功后立即弹出订阅授权框请求订阅「订单状态变更通知」但用户拒绝后不能反复弹窗只能在小程序里每个页面设置引导入口。3.4 请求封装Request 统一处理 token 与错误码小程序端的网络请求必须封装一层否则每个页面都写 wx.request 的话光是处理 token 过期和错误码就能让人崩溃。我会在 utils/request.js 里统一封装const request (url, method, data) { const token wx.getStorageSync(token) return new Promise((resolve, reject) { wx.request({ url: BASE_URL url, method: method || GET, data: data || {}, header: { Content-Type: application/json, Authorization: token ? Bearer ${token} : }, success: (res) { if (res.statusCode 401) { // token 过期跳转登录页 wx.removeStorageSync(token) wx.navigateTo({ url: /pages/login/login }) reject(new Error(登录已过期)) return } if (res.data.code ! 0) { wx.showToast({ title: res.data.msg, icon: none }) reject(new Error(res.data.msg)) return } resolve(res.data.data) }, fail: (err) { wx.showToast({ title: 网络异常, icon: none }) reject(err) } }) }) }这段封装解决了三个高频问题一是所有请求自动带 token不用每个页面手动设置 header二是 401 时自动清 token 并跳登录页避免用户卡在失效页面三是统一错误处理后端返回的业务错误码直接弹 toast页面里只要处理成功分支代码会干净很多。注意 BASE_URL 要区分环境开发时指向本地局域网 IP真机预览时指向线上域名。微信开发者工具里可以把「不校验合法域名」勾选上但真机预览时必须关掉否则请求会被拦截。4. 避坑清单六条血泪经验照着排查少熬两个通宵4.1 真机预览失败request 合法域名与 HTTP 明文限制现象开发者工具里一切正常一到真机预览就白屏请求全部失败报错提示 url not in domain list。原因微信小程序真机运行时强制校验 request 合法域名只有配置在微信公众平台后台的域名才能被调用且必须开启 HTTPS。本地开发时用 http://192.168.x.x 这种地址在开发工具里能跑因为勾选了不校验合法域名但真机上会被直接拦截。解决在微信公众平台「开发管理 → 开发设置 → 服务器域名」里把后端域名加进 request 合法域名列表同时后端必须配置 HTTPS 证书。开发阶段如果后端还没有域名可以用内网穿透工具把本地服务暴露成 HTTPS 域名但注意这只是临时方案正式上线必须用备案域名。另外本地方向开发时建议在小程序代码里把 BASE_URL 写成 config 文件分 dev 和 prod 两套。4.2 支付回调收不到notify_url 的公网可达与验签顺序现象小程序端支付成功钱也扣了但订单状态一直停在待支付跑腿员看不到单子。原因notify_url 配置不正确或者后端验签逻辑有误导致回调处理失败。这里最常见的坑是本地联调用的是内网穿透的临时域名穿透服务不稳定导致微信回调投递失败另一个坑是微信支付 V3 的回调数据格式你以为收到的 body 是 JSON实际是加密的 resource 字段需要先用 APIv3 密钥解密。解决先确认 notify_url 在公网能通过浏览器直接访问返回不是 502 或超时再确认支付时的 notify_url 是完整的 URL不是相对路径最后检查回调解密逻辑。我会在回调接口的第一行加日志打印请求头和时间戳这样能立刻确认请求是否到达。调试阶段可以让微信平台配置的 notify_url 指向测试服务器配合日志排查。4.3 订阅消息总失败一次性订阅的授权时序现象用户下单时明明点了允许订阅但后期发送模板消息时接口报错提示订阅次数不够或用户未授权。原因微信的订阅消息规则是用户每次授权只能接收一次对应模板的消息如果想持续接收需要在每次发送前重新引导用户授权。很多新手以为授权一次就能永久收到。解决在关键节点重新引导授权。比如订单状态变化时先检查该用户是否有可用的订阅次数后端记录剩余次数不足时在订单详情页展示「开启状态通知」按钮用户点击后调 wx.requestSubscribeMessage 重新授权。后端发送时用模板消息的「一次性模板」机制没权限就静默失败不阻塞核心流程。4.4 订单超时未支付状态机需要定时任务兜底现象用户创建订单后不支付订单一直停在待支付状态占用跑腿员的可见额度数据库里堆积脏数据。原因下单时没有设置支付超时时间也没有定时任务把超时订单置为取消。解决下单时设置 expire_time now 30分钟Spring 里用 Scheduled 定时任务每分钟扫一次待支付订单把超过 expire_time 的订单置为已取消。这套资源里如果没实现定时任务一定要补上。代码就三件事查超时订单列表、批量更新状态、释放对应跑腿员的接单数。定时任务加个分布式锁防止多实例部署时重复执行。4.5 地图坐标偏移GPS 坐标与高德 GCJ-02 的转换现象用户定位的经纬度传回来直接画出路线发现取件点和实际位置偏了几百米。原因微信小程序 wx.getLocation 返回的是 WGS84 坐标系而高德地图用的是 GCJ-02 坐标系两者之间有几米到几百米的偏移直接用肯定对不上。解决调用高德 API 时把坐标做转换或者在小程序端用 wx.getLocation 的 type 参数设为 gcj02让微信直接返回 GCJ-02 坐标。如果后端要和其他地图服务对接统一在处理入口做 WGS84 转 GCJ-02 的转换。这类坐标转换有现成算法库别自己写公式直接引入 geohash 相关的工具类。4.6 MySQL 连接超时连接池参数与 wait_timeout 的匹配现象系统运行一晚上第二天早上第一次请求报错 Communications link failure重启后又正常。原因MySQL 默认 wait_timeout 是 8 小时空闲连接超过这个时间会被数据库主动断开而 HikariCP 连接池不知道旧连接已失效还把它作为可用连接发给业务线程。解决在 HikariCP 配置里增加 connection-test-query: SELECT 1并设置 max-lifetime 小于数据库的 wait_timeout。一般设 max-lifetime: 180000030分钟连接池会定期主动回收旧连接。同时数据库的 wait_timeout 设置为 4 小时比较合理太大浪费资源太小容易触发这个坑。5. 从能跑到敢上线一份十分钟自查清单与进阶玩法5.1 上线前自查清单下面这份清单是我每次发版前都会强制走一遍的不是形式主义是真的能拦住大部分上线事故。第一支付回调幂等验证模拟微信回调推两次确认订单状态不会被重复更新第二定时任务分布式锁在测试环境起两个实例确认超时订单只被处理一次第三数据库索引检查order_user_id、order_courier_id、order_status 都建索引否则订单列表一多全表扫描第四HTTPS 证书确认证书链完整微信小程序的 request 合法域名配置的是原子域名不是 IP第五日志级别调成 INFO避免生产环境打印大量 DEBUG SQL 把磁盘打满。5.2 进阶一把调度算法改成可配置的评分策略如果系统上线后发现某些区域订单没人接硬编码的权重参数就不好调了。把 DispatchScorer 里的三个权重挪到配置中心Nacos 或 Apollo或者简单一点直接放数据库表里运营后台可以随时调整。这样不用改代码重新发版只需要更新配置就能动态改变派单行为。我一般还会把每次派单的评分明细写日志候选跑腿员数量、每个人的距离分、负载分、最终分数、被选中的跑腿员这样后续可以离线分析权重设置是否合理。5.3 进阶二用本地消息表做支付与订单的最终一致微信支付回调改成可靠的最终一致性方案支付回调进来后不直接更新订单状态而是先写入一张本地消息表状态标记为「待处理」然后由独立的异步任务处理订单状态变更和业务通知。这样即使业务处理失败消息还在可以重试。这张本地消息表就是可靠消息最终一致性的最小实现比直接引入 RocketMQ 的复杂度低得多适合这个项目的体量。回调处理流程变成验签 → 落消息表 → 返回 success 给微信 → 异步任务处理消息 → 更新订单状态 → 发送订阅消息。这套资源拿回来后别急着跑先看三样东西application.yml 里的数据库连接、微信小程序的 appid 配置、支付相关的密钥。跑起来之后再从订单状态机开始看代码理解每一条状态流转的前置条件和后续动作。我从那以后每次接手类似项目都强制自己先把状态机和支付回调链路画清楚再动手改代码比直接调试省太多时间。希望帮到你。本文还有配套的精品资源点击获取