Spring Boot + Vue 校园跑腿平台实战：订单状态机、并发抢单与部署避坑

校园跑腿平台这类项目，这几年无论是作为毕业设计、课程设计，还是校内创业团队的起步系统，出镜率都非常高。核心诉求其实很直白：把代拿快递、代买饭、帮忙跑腿这些零散需求，变成一个能在线发布、接单、结算的小闭环。今天要聊的这套基于 Spring Boot + Vue 的校园跑腿便利平台，就是很典型的前后端分离全栈项目，自带完整数据库脚本和文档，适合拿来学架构、做课设，或者当二次开发的基础模板。

这套系统解决的实际问题是什么？站在学生视角，下单入口要足够轻，打开页面就能发单；站在跑腿同学视角，要有清晰的任务列表和状态流转，不然都不知道自己该干嘛；站在管理员视角，要能管人、管单、管分类，而不是靠群聊爬楼来统计。所以系统的功能边界完全是围着这三类角色转的。后端重点是订单状态机和权限控制，前端重点是订单流程的可视化交互。这篇文章我会按需求拆解、数据库设计、后端实现、前端实现、部署运行、问题排查的顺序过一遍，重点讲清楚每一步为什么这么选，以及我在实际调试中踩过的坑。

1. 项目整体设计与功能拆解

1.1 从校园场景反推需求清单

写这类系统，最忌讳一上来就建表写接口。校园跑腿和外面的同城配送看起来像，实际差别很大：地理范围固定，基本就在校区几公里内，距离短、频次高、单笔金额低；用户身份集中，基本都是在校学生，注册认证可以比社会化平台简单；时间规律性强，早中晚和节假日是高峰，其他时段单量稀疏；信任关系特殊，下单的学生和接单的学生往往在同一个校区甚至同一栋宿舍楼，平台不需要做很重的信用评价体系，但必须能追踪订单状态。

从这些场景特征反推系统能力，核心功能就浮出来了：用户注册登录、发布订单、抢单接单、状态流转、订单结算、个人中心、管理员后台。每个功能背后都对应着具体的业务规则，比如下单时要不要填期望送达时间，接单后配送员能不能看到下单人手机号，超时订单怎么处理，用户取消订单后余额怎么退。这些规则如果不在设计阶段定清楚，后端的接口会反复推翻重来。

这里我要特别强调一个容易被忽略的需求：并发。校内高峰期，同一分钟可能出现几十个订单被发布和抢购，如果不处理并发，就会发生两个人同时抢到同一单的情况。这个需求在界面上看不出来，但它属于系统质量的一部分，比按钮好不好看重要得多。

1.2 角色权限：三类用户，一套规则

系统用户角色我固定为三类：普通用户（下单方）、配送员（接单方）和管理员。

普通用户权限很朴素：发布跑腿订单、查看历史订单、取消未接单的订单、确认收货。配送员除了浏览可接订单、抢单，还要能更新配送状态、上传送达凭证。管理员承担全局管理职责：用户管理、订单管理、分类管理、系统参数和数据统计。

权限模型的确定直接决定后端接口的访问控制怎么写。我用的是基于角色的访问控制（RBAC）思路，后端统一拦截请求，根据当前登录用户的角色判断操作是否被允许。这里有个非常重要的建议：不要让权限判断散落在各个 Controller 里，那样接口多了以后会非常难维护。建议抽一个公共拦截器或者权限注解，在方法上声明需要的角色，统一处理，后期改权限规则只需要动一处。

还有一个细节：学生可以既是普通用户又是配送员，所以用户和角色实际上是多对多的关系。我这里是让一个账号可以同时绑定两种角色，接单和下单业务互不干扰，登录后前端根据上下文区分当前是哪种操作场景。

1.3 为什么是 Spring Boot + Vue 的组合

技术选型这方面，我几乎没有犹豫就定了 Spring Boot + Vue。

前后端分离已经是主流，这个组合生态成熟、资料多，学生看文档能上手，老师讲项目也讲得清楚。开发效率也在线：Spring Boot 把后端配置大量收敛，Vue 的组件化加响应式特性让订单状态刷新这类交互写起来比较直观。具体细化一下，前端我用 Vue 3 + Element Plus，UI 组件库能省掉大半样式时间；后端用 Spring Boot 3.x，配合 MyBatis Plus 做数据库操作。

可能有人会问，为什么不用 JPA，或者原生 MyBatis。JPA 做单表 CRUD 确实舒服，但多表关联、复杂查询时 SQL 控制不够直接；原生 MyBatis 又需要手写大量 XML。MyBatis Plus 是折中方案，单表操作调用内置方法，复杂查询再手写 SQL，开发体感最顺。数据库用 MySQL 8.x，中小型业务系统的标准选择。文件存储如果只是部署演示，直接放到本地磁盘目录就行，没必要引入对象存储增加复杂度。

2. 数据库设计：先把订单状态机想清楚

2.1 核心表和关键字段

数据库是整个系统最容易返工的部分，我宁愿在设计阶段多花时间，也不愿意后期天天改表。这个项目的核心实体主要有用户、角色、订单、订单状态记录、校园地址、服务分类、公告、充值流水。

用户表要预留的字段包括学号、昵称、手机号、密码摘要、头像、角色标识。用学号做登录名，比单独设计用户名更贴近校园场景。订单表是核心，字段要兼顾业务扩展：订单编号、下单人 ID、配送员 ID、物品描述、物品类型、取件地址、送达地址、期望送达时间、订单金额、跑腿费、状态、备注、创建时间、完成时间。订单编号必须唯一且有可读性，我用的是日期加随机码，比如 202505121030 加 5 位随机串，并发下单也不容易撞。

地址不建议直接存一个文本。因为后续要做统计，比如哪个宿舍楼订单最多，用文本没法聚合。最好拆一张地址表，包含校区、楼栋、门牌号、详细备注，下单时前端级联选择，后端存地址 ID，统计查询会顺畅很多。

2.2 订单状态机设计

订单状态是整个业务的灵魂，我定义成这些状态：

• 待接单（0）：刚发布，等待配送员抢单
• 已接单（1）：配送员确认接单，准备取件
• 配送中（2）：配送员已取件，正在送达
• 已完成（3）：用户确认收货，流程结束
• 已取消（4）：用户取消或系统超时取消
• 异常（5）：骑手长时间未取件、物品遗失等异常情况

这里有个关键设计：状态不要只存一个字段在订单表里，要单独建一张状态记录表，每次变更追加一条记录。为什么要这么做？因为业务上需要留痕。用户想知道订单几点几分进入“配送中”，几点几分完成；管理员处理纠纷时也要看到完整轨迹。直接在订单表上覆盖更新，历史无法回溯，排查问题时非常被动。状态记录表就是订单的流水账，每一条记录包含订单 ID、原状态、新状态、操作人、变更时间、备注。

状态机的约束必须显式写在后端。前端的“下一步”按钮再好看也只是界面交互，后端接口要校验当前状态是否允许跳转到目标状态。比如待接单的订单不能直接变成已完成，已取消的订单不能再接单。我把合法流转写成一个映射表，非法流转直接抛业务异常，前端收到错误提示后就知道操作不被允许。

2.3 索引、初始化数据和字符集

建表后千万别忽略索引。这个项目核心查询路径有两个：按状态查可接单列表、按用户查历史订单。数据量上来以后，没有索引就是全表扫描，页面会越来越卡。我在订单表的用户 ID、状态、创建时间字段上都加了索引，覆盖高频查询条件。另外提醒一句，索引也不是越多越好，每个索引都会降低写入性能，像描述、备注这种基本不参与查询的字段，没必要建索引。

初始化数据方面，除了默认管理员账号和角色，我还内置了常见服务分类：快递代取、外卖代送、超市代购、文件打印、其他跑腿。用户第一次打开系统就能看到分类，界面不至于空荡荡。分类放在配置表里，由管理员在后台维护，用户端动态读取。数据库导入脚本我统一用 utf8mb4 字符集，避免中文乱码问题，这一点在后续部署时很关键。

3. 后端实现：Spring Boot 不只是写 CRUD

3.1 工程结构与登录鉴权

后端工程结构我习惯按业务模块分包，而不是按技术分层分包。按技术分层就是 controller、service、mapper 各放一个包，时间久了找代码全凭记忆；按业务模块分包则是把 order、user、system 等模块各立一个包，包内部再分 controller、service、mapper。对这类中小型系统来说，按业务分包更直观，也方便多人协作。

登录鉴权用 JWT，不需要像企业系统那样引入复杂的会话管理。用户通过学号和密码登录，后端校验成功后签发 token，前端存起来，每次请求放到请求头。这样后端不需要存 session，也为以后扩展小程序端留了余地。

密码存储必须加密，我这里用 BCrypt，Spring Security 里可以直接集成。有同学图省事用 MD5 加盐，不是不行，但 BCrypt 内置随机盐，安全性好而且不需要自己维护盐值，更省心。

3.2 抢单并发：一个必须处理的细节

抢单是纯后端逻辑里技术含量最高的点。多个配送员同时点击同一个订单，如果后端只是简单查询再更新，并发环境下必出问题：两个请求可能同时读到“待接单”状态，然后同时执行更新，结果两个人都以为抢单成功。

解决办法其实不复杂，我推荐先用数据库乐观锁。在订单表加 version 字段，更新时带上版本号条件：

java复制boolean success = orderMapper.update(
    new UpdateWrapper<Order>()
        .eq("id", orderId)
        .eq("status", 0)
        .eq("version", currentVersion)
        .set("status", 1)
        .set("delivery_user_id", userId)
        .set("version", currentVersion + 1)
);

如果 update 返回的影响行数为 1，说明抢单成功；如果为 0，说明订单已被别人抢走，返回“手慢了”的提示。这个方案简单、无需引入中间件，对校园跑腿这个量级完全够用。以后单量大了，可以再引入 Redis 分布式锁或队列削峰，但现阶段乐观锁已经能解决核心问题。

3.3 通知推送：轮询还是 WebSocket

订单状态变化后，怎么通知到用户？我提供了两种方式：页面轮询和 WebSocket 实时推送。最初为了快速验证功能，前端每 5 秒拉一次订单最新状态，实现简单，稳定性也够。但骑手工作台那种高频场景，轮询体验比较一般，我后来接入了 WebSocket，后端在订单状态变化时推送消息给对应前端的会话。

WebSocket 有两个坑要提前规避。第一是鉴权问题：WebSocket 握手不像普通 HTTP 请求那样自然携带 JWT，前端需要在连接地址里带上 token 参数，后端在拦截器里校验，校验不通过就拒绝握手。第二是断线重连问题：用户切到后台再回来，连接可能已经断了，如果不做重连，订单消息就收不到。我的做法是前端监听连接断开事件，定期尝试重连，同时连接成功后主动拉取一次最新状态兜底，避免漏掉断线期间发生的事件。

3.4 文件上传与全局异常处理

用户上传物品照片、送达凭证，功能不复杂，但细节容易被忽略。Spring Boot 里用 MultipartFile 接文件，然后写到磁盘。两个注意点：一是默认上传大小限制需要调大，我用 multipart 配置调到 10MB；二是文件名不能直接用用户原始名，容易冲突也可能携带特殊字符。我会用 UUID 生成新文件名，保留扩展名。

全局异常处理也是后端必须做的一环。我配了一个全局异常处理器，把业务异常、参数校验异常、数据库异常分别映射到不同的返回码和提示信息。前后端约定统一的响应结构：

json复制{
  "code": 200,
  "message": "success",
  "data": {}
}

有了这个结构，前端拦截器可以统一处理错误，比如 code 为 401 时跳登录页，code 非 200 时弹提示。没有统一错误包装，前端就只能靠猜状态码来定位问题，联调效率会低很多。

4. 前端实现：Vue 里的核心交互

4.1 前端结构与路由设计

前端我会用 Vue 3 + Vite 搭建，这里有一个明确的体验差异：Vite 的冷启动速度比 Webpack 快太多，日常开发改代码，保存后基本秒级刷新，对调试体验提升非常大。

页面按角色组织会清晰很多。普通用户端包含首页、发单页、可接单大厅、我的订单、个人中心；配送员端包含任务大厅、进行中任务、历史任务；管理后台包含仪表盘、用户管理、订单管理、分类管理、公告管理。路由设计上我做了路由懒加载，按模块拆分路由文件，而不是把几百行路由塞在一个文件里。

权限控制放在路由守卫里：未登录用户只能访问登录注册页和部分公开页面；登录后根据角色权限跳转到对应的端。这个守卫逻辑必须写清楚，否则用户直接改一下 URL 就能访问管理页面，权限体系就形同虚设了。

4.2 API 封装与请求拦截

前端请求层统一用 Axios 封装，封装价值体现在两个地方：统一注入 token 和统一处理响应。请求拦截器里从本地存储读取 token，放到请求头；响应拦截器里判断业务 code，401 跳登录页，非 200 弹错误提示。

我见过不少项目把 axios.get 直接写在页面组件里，那样也不是不能跑，但接口地址一变、错误处理逻辑要改，几十个文件翻起来是真痛苦。封装一层之后，业务组件里只需要调用封装的 api 方法，参数和响应结构都约定好了，后续维护成本大大降低。

环境配置我用 Vite 的环境变量区分开发、测试、生产。本地开发通过 proxy 代理到后端，避免跨域；生产环境打包后由 Nginx 反代 /api 到后端服务地址。

4.3 状态管理与订单流程交互

状态管理用 Pinia，比 Vuex 在使用体验上更顺手。这个项目里需要全局共享的状态主要是当前登录用户信息和角色标识，以及骑手工作台里的待接单筛选条件。下单页和列表页的局部状态没有必要放全局，直接在组件里管理即可。

订单流程的交互是前端最复杂的地方。从发单开始，用户选择分类、填写取件和送达地址、设置跑腿费，提交后跳转到订单详情页。订单详情页根据订单状态动态渲染操作按钮：待接单显示“取消订单”，已接单显示“确认收货”，配送中则显示“等待送达”的提示。这个动态渲染和后端状态码要保持一一对应，最怕前端写错魔法数字导致按钮错乱。我的做法是前端也定义一份和后端一致的状态枚举常量，组件里引用常量而不是散落的数字，减少出错概率。

5. 从源码到运行：部署与联调记录

5.1 环境准备与项目导入

拿到一套源码和数据库脚本，第一步不是点运行按钮，而是先看文档里的版本要求。我这个后端要求 JDK 17+、MySQL 8.x、Maven 3.6+，前端要求 Node.js 16+。版本不对，会出现各种莫名其妙的坑，比如 JDK 版本太低导致 Spring Boot 起不来，Node 版本太老导致依赖装不上模块。

导入项目前，我习惯先扫一眼目录结构，确认后端和前端是同一个仓库下的两个目录。后端用 IDEA 直接导入 Maven 工程，前端在命令行走 npm install。导入后的第一件事不是启动，而是检查配置文件里的数据库账号密码是否和本机环境匹配。

5.2 后端启动与配置要点

启动后端的核心前提是数据库已经初始化。项目会附一份 init.sql，里面包含建库、建表、初始数据三段内容。用 Navicat 或命令行导入前注意确认数据库字符集是 utf8mb4，否则导入的中文注释和初始数据容易乱码。

application.yml 里有几个配置要重点看：数据源 URL、用户名密码、MyBatis 映射位置、上传文件路径、JWT 密钥。数据源 URL 格式是 jdbc:mysql://localhost:3306/数据库名，用户名密码改成自己的。上传路径建议配绝对路径，比如 /data/upload，避免打包后相对路径定位出错。

然后是启动类运行。如果控制台没有报错，看到 Tomcat started on port(s): 8080，说明后端已就绪。这里有个小坑：8080 端口被占用会导致启动失败，如果本机其他服务占了端口，可以在配置里改成 8081，但前端代理地址也要同步修改，否则两边端口对不上。

5.3 前端启动与联调排查

前端装完依赖后，跑 npm run dev。Vite 默认端口是 5173，打开浏览器就能看到登录页。第一次启动会遇到两个高频问题。

第一个是接口跨域报错。原因是前端地址是 http://localhost:5173，后端是 http://localhost:8080，两者不同源。解决方式是 Vite 配置里设置 proxy，把 /api 路径代理到后端 8080，浏览器看到的请求是同源的，跨域问题直接消失。

第二个是登录一直失败。这种情况一般不是前端的问题，而是后端没启动，或者数据库连接失败。我的排查习惯是先用浏览器或 Postman 直接访问后端的接口地址，比如 http://localhost:8080/api/user/login，如果能返回 JSON 说明后端正常，再回头查前端代理配置；如果后端都连不通，优先检查数据库连接和端口启动日志，定位路径会快很多。

6. 高频问题排查与避坑经验

6.1 数据库相关报错

数据库连接报错是整个项目里出现频率最高的问题。我整理过一张速查表，基本覆盖日常遇见的情况：

这里多说一句：MySQL 8.x 的驱动类名和早期版本不一样。老项目习惯写 com.mysql.jdbc.Driver，但新版驱动实际是 com.mysql.cj.jdbc.Driver，配置里写错启动时会直接报找不到类。pom.xml 里依赖和驱动类名要配套。

6.2 跨域与接口响应异常

前后端分离项目，跨域几乎躲不掉。如果前端没有配置代理，也可以从后端加全局 CORS 配置解决。但这里我要提醒，不要图省事直接配置“允许所有来源 + 允许所有请求头”，校园项目安全等级没那么高，但端口限定一下对排查问题也有帮助，太宽松只会掩盖来源的问题。

接口返回 404 或 405，多半是请求路径写错或请求方式不对。比如后端定义的是 GetMapping，前端却发了 POST 请求，自然 405。统一响应结构后，前端要根据 code 做提示，不要把后端的堆栈信息直接展示给用户，既不美观也容易暴露实现细节。

6.3 订单状态错乱与数据不同步

订单状态错乱在很多新手项目里很常见。典型症状是前端显示“待接单”，后端实际已经是“配送中”，或者取消订单后骑手页面仍然出现该订单。这类问题基本可以归结为两点：状态流转没有在后端统一校验，或者前端依赖了本地存储的旧数据。

后端要把状态流转校验写成强制逻辑，前端下拉刷新、WebSocket 消息、进入页面主动刷新齐上，确保页面数据不会长期停留在旧版本。我实测下来，订单详情页在进入时重新拉一次接口，比什么都指望 WebSocket 推送可靠得多。

6.4 打包部署时的经典问题

最后再讲一个部署阶段的经典场景：本地一切正常，打包上服务器就不行。我排查过不少这种情况，几乎都是这几类原因：

• 配置文件里的数据库地址用了 localhost，而服务器上的 MySQL 并不是本地，而是一个单独的实例。部署环境必须把数据库地址改成可访问的服务器地址。
• frontend 构建后的 dist 目录没有正确的代理配置。Nginx 里如果没有将 /api 反向代理到后端端口，页面能打开但接口全挂。
• 后端 jar 包运行时缺少上传目录，文件上传直接报错。需要在服务器上提前创建上传目录并设置好权限。

我建议部署前把数据库、后端、前端三者分开验证。先把后端 jar 跑起来，直接访问接口确认正常；再验证数据库连通；最后挂上 Nginx 看一眼静态页面和接口代理。一块一块确认，比全链路启动成功但接口一个都调不通要省时得多。

我自己做这套系统的最大体会是：这类平台真正难的不是某个功能点，而是把订单状态、角色权限、前后端交互串成一条完整链路。如果你准备做一个类似项目，我建议先花一晚上把订单状态机和表结构画清楚，再去堆功能。拿到源码也别急着跑，先看一遍数据库脚本，跟着文档走一遍部署流程，比自己盲改配置快得多。后续如果想把系统扩展成小程序端，这套后端接口基本可以复用，主要工作量集中在前端适配；如果加在线支付，还需要对接支付平台的回调接口，数据库里也要预留支付流水表。先把订单状态和异常流程这些基本功打扎实，这个项目才真正能跑起来、扛得住并发、经得起用。