做一个校园外卖小程序这事儿，本身就是一个特别典型的全栈练手项目。市面上这类项目或者毕设题，十有八九是“小程序端 + 后台管理”两件套，但真正把“用户下单、商家接单、配送跟踪”整条链路跑通的并不多。我用 uniapp 写小程序前端，python 写后端接口，从零搭了一个校园外卖订单系统，整个过程踩了不少坑，也总结了一些可以直接抄作业的经验，今天一次性说出来。
这套系统覆盖了用户端、商家端和配送端三条业务线，核心功能包括微信登录、菜品浏览、购物车、下单支付（模拟）、商家接单、订单状态流转、配送完成等等。如果你正在做类似的项目、准备搞毕业设计，或者单纯想学 uniapp 加 python 前后端分离的开发模式，这篇内容应该能帮你省下大量试错时间。
1. 项目整体设计与技术选型思路
1.1 为什么选 uniapp + python
先聊技术选型。
小程序开发有原生和跨平台框架两条路。原生微信小程序用 wxml、wxss、js 写，语法不难，但代码只能在微信里跑，以后想同步出 H5 或者 App，基本得重写。uniapp 不一样，它基于 Vue 语法，一套代码可以编译到微信小程序、H5、支付宝小程序、App 等多个平台。对于校园项目来说，老师演示的时候可能在电脑浏览器里看 H5 版，评委老师微信扫码看小程序版，用 uniapp 直接一份代码全搞定，非常合适。
后端选 python，其实是图开发效率。Java 写后端当然也行，但对一个订单系统来说，python 的 Flask 框架能让你把重点放在业务逻辑而不是繁琐的配置上。一个 Flask 应用几十行就能跑起来，配合 SQLAlchemy 操作数据库，开发速度很快，调试也方便。对于课程设计或者毕设这种时间紧、任务重的场景，python 后端是性价比最高的选择。
1.2 系统角色与功能划分
校园外卖和普通外卖最大的区别是配送范围集中在校园内，商家可能是食堂窗口、校内小店或者周边支持配送到校的店铺。我设计的时候把系统分成了三个端：
- 用户端（小程序）：浏览菜品、按分类筛选、加入购物车、提交订单、模拟支付、查看订单状态、确认收货。
- 商家端（小程序或 H5）：菜品管理（上下架、改价）、订单管理（接单、备餐、出餐）、店铺信息维护。
- 配送端（小程序）：查看待接配送订单、接单配送、标记送达。
另外还有一个后台管理（web），用来管理用户、商家审核、数据统计。不同角色通过后端接口做权限校验，整个系统是典型的前后端分离架构，小程序和 web 都通过 HTTP 接口访问 python 后端，后端统一返回 JSON 数据。
1.3 架构设计与接口风格
架构上没搞花活，就是三层：前端 uniapp -> 后端 Flask -> MySQL 数据库。
接口设计遵循 RESTful 风格，资源用名词表示，方法用 HTTP 动词：
- POST /api/auth/login 微信登录
- GET /api/stores 店铺列表
- GET /api/stores/1/menus 获取某个店铺的菜单
- POST /api/cart/add 加入购物车
- POST /api/order/create 创建订单
- PUT /api/order/1/status 更新订单状态
这里提一个关键点：不要在小程序端存真实的用户余额或者做真实扣款逻辑。微信支付需要企业资质和商户号，个人开发者和普通学生基本申请不下来，所以项目里默认走模拟支付，也就是用户点“支付”按钮后，前端调后端一个接口，后端直接把这个订单状态改成“已支付”，同时生成一条模拟支付记录。这样做既能演示完整流程，又不会卡在资质审核上。如果有需要，后续接真实微信支付只是替换一个支付接口的事。
2. 数据库设计与核心模块拆解
2.1 核心数据表设计
数据库是订单系统的地基。我设计的时候重点考虑了用户、店铺、菜品、购物车、订单、订单明细这六张核心表，外加一张地址表。
用户表（user）主要字段：
- id：主键自增
- openid：微信用户的唯一标识，登录时从微信接口拿到
- nickname：昵称
- avatar：头像
- phone：手机号（用于取餐联系）
- role：角色，1 用户 / 2 商家 / 3 骑手
- create_time：创建时间
店铺表（store）主要字段：
- id
- user_id：关联商家用户
- name：店铺名称
- logo：店铺头像
- notice：公告
- status：营业状态，1 营业中 / 0 休息中
菜品表（menu）主要字段：
- id
- store_id：所属店铺
- category：菜品分类（比如套餐、主食、饮品）
- name：菜名
- image：菜品图片
- price：价格
- stock：库存
- sales：月售数量
- status：1 上架 / 0 下架
这里有个细节：菜品分类不能单独建表。虽然正规商用系统会建 category 表，但对于这种体量的小程序，直接在 menu 表里加一个 category 字符串字段就够了，查询的时候 group by 一下就能实现分类展示，省掉一次连表查询，代码也简单很多。
购物车表（cart）主要字段：
- id
- user_id
- menu_id
- quantity：数量
- selected：是否勾选
订单表（order）主要字段：
- id
- order_no：订单编号，唯一索引
- user_id：下单用户
- store_id：店铺
- total_amount：订单总金额
- status：订单状态（下面细说）
- address：配送地址
- remark：备注
- create_time / pay_time / finish_time：时间戳
订单明细表（order_item）主要字段：
- id
- order_id：关联订单
- menu_id
- menu_name：冗余菜品名，防止菜品删除后查不到
- price：下单时的单价快照
- quantity：数量
这里必须强调快照的重要性。用户下单之后，商家完全可能改价格或者下架菜品，如果订单明细表里不存一份当时的价格和菜名，后面查历史订单就会看到错误信息，甚至关联不到菜品。所以menu_name 和 price 一定要存冗余字段，这是新手非常容易漏掉的一个设计。
2.2 订单状态机的设计
订单状态是整个系统最核心的逻辑。我设计了六个状态，用整数存储，方便前后端用数字做字典映射：
| 状态值 | 含义 | 说明 |
|---|---|---|
| 0 | 待支付 | 用户已下单但未模拟支付 |
| 1 | 待接单 | 已支付成功，等待商家接单 |
| 2 | 备餐中 | 商家已接单，正在制作 |
| 3 | 配送中 | 骑手已接单，正在配送 |
| 4 | 已完成 | 用户确认收货或骑手标记送达 |
| 5 | 已取消 | 超时未支付或用户主动取消 |
状态流转是这个逻辑：
待支付 0 -> 支付成功后变成 1 待接单；商家接单变成 2 备餐中；商家出餐后变成 3 配送中；骑手送达或用户确认后变成 4 已完成。
后端做状态更新的时候，不能只改一个 status 字段就完事。我每次状态变更都会校验当前状态是否符合预期，比如只有 status=1 的订单才能被商家接单变成 status=2。这么做是防止两个端同时操作同一个订单的时候把状态搞乱。
2.3 接口设计要点
接口设计有几个容易被忽略的点，在这里专门说一下。
一是小程序端的请求封装。uniapp 自带的 uni.request 是异步回调风格，用起来比较绕。我封装了一个 Promise 风格的 request 函数，统一处理 baseURL、token、错误提示，代码看起来会清爽很多。
二是后端接口返回格式要统一。我用的格式很简单：
{ "code": 200, "msg": "success", "data": {} }业务异常时 code 用 400 或 500，msg 存放错误提示，前端拿到非 200 的 code 直接 toast 提示。这个统一格式在处理登录态失效、参数校验失败时特别好用。
三是分页查询必须有。菜品列表、订单列表这些接口，数据量上来之后不分页会让小程序非常卡。我的做法是接口接收 page 和 page_size 参数，返回总条数和当前页数据，前端用 uni-app 的 scroll-view 做上拉加载。
3. 核心功能实操与代码实现
3.1 小程序端登录与请求封装
小程序登录流程是：前端调 wx.login 拿到临时 code，把 code 发给后端，后端用这个 code 去向微信接口换 openid 和 session_key，然后查用户表，没有就自动注册，最后生成一个 token 返回给前端。
后端登录接口核心代码：
@app.route('/api/auth/login', methods=['POST']) def login(): data = request.get_json() code = data.get('code') # 调用微信接口换取 openid url = 'https://api.weixin.qq.com/sns/jscode2session' params = { 'appid': app.config['WX_APPID'], 'secret': app.config['WX_SECRET'], 'js_code': code, 'grant_type': 'authorization_code' } resp = requests.get(url, params=params).json() openid = resp.get('openid') if not openid: return jsonify({'code': 400, 'msg': '登录失败', 'data': None}) user = User.query.filter_by(openid=openid).first() if not user: user = User(openid=openid, nickname='微信用户', role=1) db.session.add(user) db.session.commit() token = generate_token(user.id) return jsonify({'code': 200, 'msg': 'ok', 'data': {'token': token, 'user': user.to_dict()}})前端封装 request 的代码：
// utils/request.js const BASE_URL = 'http://127.0.0.1:5000/api' export function request(url, method = 'GET', data = {}) { return new Promise((resolve, reject) => { uni.request({ url: BASE_URL + url, method, data, header: { 'Authorization': uni.getStorageSync('token') }, success: (res) => { if (res.data.code === 200) { resolve(res.data.data) } else if (res.data.code === 401) { uni.navigateTo({ url: '/pages/login/login' }) } else { uni.showToast({ title: res.data.msg, icon: 'none' }) reject(res.data) } }, fail: (err) => { uni.showToast({ title: '网络异常', icon: 'none' }) reject(err) } }) }) }登录成功之后，token 存到 uni.setStorageSync，后续所有请求带上 Authorization 头，后端通过解析 token 拿到用户身份。整个流程一句话总结：前端不信任任何本地存储的用户信息，所有身份识别都靠 token。
3.2 购物车与下单流程的实现
购物车这里有个设计选择：数据存在本地还是后端。我最后选了前端本地存储购物车 + 后端下单时统一校验的方案。
为什么不用后端购物车？因为校园外卖小程序的用户多是学生，购物车数据量不大，存在本地可以减少接口请求，用户操作起来也更流畅。用户把菜品加入购物车，其实就是往本地缓存里写一条记录，包含 menu_id、名称、价格、数量、店铺 id。
但下单的时候绝对不能直接把前端传过来的金额拿去入库。这句话我要加粗：金额计算必须后端重新算。用户可以在前端篡改请求参数把总价改成 1 分钱，如果后端不校验，订单金额就错了。所以前端购物车只是展示用的，后端创建订单接口收到菜品明细后，会去数据库重新查价格、重新计算总金额。
下单接口后端核心逻辑：
@app.route('/api/order/create', methods=['POST']) def create_order(): user_id = get_current_user_id() data = request.get_json() items = data.get('items') address = data.get('address') remark = data.get('remark', '') if not items: return jsonify({'code': 400, 'msg': '购物车为空'}) store_id = items[0]['store_id'] total = 0 order_items = [] for item in items: menu = Menu.query.get(item['menu_id']) if not menu or menu.status == 0: return jsonify({'code': 400, 'msg': '菜品已下架: ' + item['menu_name']}) if menu.stock < item['quantity']: return jsonify({'code': 400, 'msg': '库存不足: ' + menu.name}) amount = float(menu.price) * int(item['quantity']) total += amount order_items.append({ 'menu_id': menu.id, 'menu_name': menu.name, 'price': float(menu.price), 'quantity': item['quantity'] }) order_no = generate_order_no() order = Order( order_no=order_no, user_id=user_id, store_id=store_id, total_amount=round(total, 2), status=0, address=address, remark=remark ) db.session.add(order) db.session.flush() # 拿到 order.id for oi in order_items: db.session.add(OrderItem(order_id=order.id, **oi)) db.session.commit() return jsonify({'code': 200, 'msg': 'ok', 'data': {'order_id': order.id, 'order_no': order_no}})这里有几个细节值得细说：
- db.session.flush() 的作用是先把 order 写入数据库拿到自增 id，但还没提交事务，这样 order_item 就能拿到 order_id。
- 下单时先检查库存，但真正的库存扣减放到支付成功之后。这里的设计逻辑是：用户下单后可能不支付，如果下单就扣库存，会导致大量无效订单把库存占住，造成“假性售罄”。
- 创建订单返回的 order_no 一定要做唯一处理，我用的是日期加随机数加用户 id 拼接，基本上不会重复。
3.3 商家端订单处理流程
商家端的功能核心是订单状态的推进。商家在小程序里看到待接单的订单列表，点击“接单”按钮，前端调后端接口把订单状态从 1 改成 2；备餐完成后点“出餐”，状态从 2 改成 3。
商家端接口需要注意权限控制。不能随便传一个 order_id 就能修改状态。后端更新订单状态之前，必须先查订单归属的 store_id 是不是当前登录商家自己的店铺。这个校验一句话代码，但漏掉的话整个系统就存在越权漏洞，任何用户改一下订单号就能操作别人店铺的订单。
状态更新接口示例：
@app.route('/api/order/<int:order_id>/status', methods=['PUT']) def update_order_status(order_id): user_id = get_current_user_id() user = User.query.get(user_id) if user.role != 2: return jsonify({'code': 403, 'msg': '没有权限'}) order = Order.query.get(order_id) store = Store.query.filter_by(user_id=user_id).first() if not store or order.store_id != store.id: return jsonify({'code': 403, 'msg': '不是本店订单'}) status = request.get_json().get('status') # 状态流转校验 valid_transitions = {1: [2], 2: [3]} if order.status not in valid_transitions or status not in valid_transitions[order.status]: return jsonify({'code': 400, 'msg': '非法的状态变更'}) order.status = status if status == 2: order.receive_time = datetime.now() elif status == 3: order.delivery_time = datetime.now() db.session.commit() return jsonify({'code': 200, 'msg': 'ok'})3.4 订单状态同步方案
用户端怎么实时看到订单状态变化？很多新手会第一时间想到 WebSocket，但校园项目真的没必要为了实时性引入 WebSocket。我这里的做法是用户端定时轮询。
具体做法是：订单详情页和订单列表页在 onShow 的时候拉一次最新的订单状态，同时在订单详情页加了一个定时器，每 5 秒请求一次订单详情接口，拿到最新状态刷新页面。页面隐藏（onHide）的时候清除定时器。
这个方案的优点是简单、稳定、不依赖额外的中间件；缺点是有最多 5 秒的延迟，但对于订单状态展示来说完全够用。如果后面想做得更高级，可以用 uniapp 的 websocket 或者定时推送，但那是锦上添花的事，不是核心。
前端轮询代码：
// 页面开始显示时启动轮询 onShow() { this.loadOrderDetail() this.timer = setInterval(() => { this.loadOrderDetail() }, 5000) }, onHide() { if (this.timer) { clearInterval(this.timer) this.timer = null } }4. 联调、打包与上线避坑实录
4.1 小程序访问后端接口的域名问题
前后端联调阶段最容易踩的第一个坑是域名校验。微信开发者工具里，不校验合法域名这个选项一旦关了，直接访问 http://127.0.0.1:5000 是可以的，但等到真机预览或者发布体验版的时候，微信要求所有请求的 URL 必须是 HTTPS 并且在小程序后台配置了合法域名。
校园项目拿不到备案域名和 HTTPS 证书的情况很正常，真机调试时有几个变通方案：
- 方案一：用内网穿透工具把本地 Flask 服务映射成一个公网 HTTPS 地址，小程序里临时配置这个地址调试，不校验域名打开。注意这里说的是普通开发调试工具，不是别的什么。
- 方案二：后端服务器直接用云服务器，把 Flask 跑在 80 端口上，小程序后台配置服务器域名，然后开发者工具里关闭不校验合法域名做测试。
如果只是做课程设计，方案一省事；如果要演示给老师看，方案二更稳。我自己实际项目里用方案二，因为省得每次开电脑还要额外启动一个映射工具。
4.2 模拟支付的实现思路
前面说了真实微信支付很难落地，我做了模拟支付流程：用户点击“去支付”后，弹出确认支付的对话框，显示订单金额，用户点确认，前端调后端支付接口，后端把订单状态从 0 改成 1，同时写一条支付流水记录，然后前端跳转到支付成功页。
支付接口长这样：
@app.route('/api/order/<int:order_id>/pay', methods=['POST']) def pay_order(order_id): user_id = get_current_user_id() order = Order.query.get(order_id) if not order or order.user_id != user_id: return jsonify({'code': 403, 'msg': '订单不存在'}) if order.status != 0: return jsonify({'code': 400, 'msg': '订单状态不正确'}) order.status = 1 # 待接单 order.pay_time = datetime.now() # 扣减菜品库存 items = OrderItem.query.filter_by(order_id=order.id).all() for item in items: menu = Menu.query.get(item.menu_id) if menu: menu.stock -= item.quantity menu.sales += item.quantity db.session.add(PaymentRecord( order_id=order.id, amount=order.total_amount, pay_type='mock', status=1 )) db.session.commit() return jsonify({'code': 200, 'msg': '支付成功'})4.3 图片上传与存储
菜品图片是外卖系统的门面。图片上传逻辑是：小程序端选图 -> uni.uploadFile 上传到后端 -> 后端保存到服务器本地目录 -> 返回图片的 URL。
开发的时候要注意几个问题。一是服务端接收文件要限制大小和格式，防止用户传一个几十 MB 的图片把服务器打爆。二是不用把图片存到数据库，存文件路径就行。三是在部署时图片目录的权限要设置对，否则前端访问图片 URL 会 404。
Flask 接收图片的代码：
@app.route('/api/upload', methods=['POST']) def upload(): file = request.files.get('file') if not file: return jsonify({'code': 400, 'msg': '没有文件'}) filename = generate_uuid() + '.' + file.filename.split('.')[-1] save_path = os.path.join(app.config['UPLOAD_FOLDER'], filename) file.save(save_path) url = app.config['BASE_URL'] + '/static/' + filename return jsonify({'code': 200, 'msg': 'ok', 'data': {'url': url}})4.4 uniapp 多端适配差异
uniapp 虽然号称一套代码多端运行，但实际写起来，H5 端和小程序端还是有差异的。我踩过的几个比较典型的坑：
- H5 端的跨域问题：浏览器访问本地 Flask 接口，会因为跨域被拦截。解决方法是 Flask 后端加 CORS 支持，或者前端开发时配置 uniapp 的 proxy 选项。我直接用 flask-cors 扩展，两行代码解决问题。
- 小程序端不支持 DOM 操作：uniapp 的视图层是小程序自己的渲染机制，不能使用 document、window 这些浏览器对象。做滚动加载时不能用 document.getElementById，而是用 scroll-view 的 bindscrolltolower 事件，或者页面 onReachBottom 生命周期。
- rpx 单位和 px 的换算：小程序端常用的 rpx 单位在 H5 端需要配置换算，否则在不同屏幕上页面会变形。uniapp 官方提供的设计稿宽度是 750，按这个标准切图基本没问题。
- 图片路径问题：本地图片在小程序端不能直接用相对路径引用，容易找不到。我统一把所有图片资源放到 static 目录下，用绝对路径引用，虽然每次打包会多一些资源，但是最省心。
5. 常见问题排查与优化建议
5.1 几个高频 Bug 的排查经验
金额精度问题
后端用 float 做金额计算，两个小数相加可能得到 0.1 + 0.2 = 0.30000000000000004 这样的结果。在前端展示时可能感知不到，但一旦做累计求和就会发现总金额差了那么一点点。我的做法是后端所有金额计算用 Decimal 类型，数据库里金额字段用 DECIMAL(10,2)，入库之前统一 round 到两位小数。前端展示时再用 toFixed(2) 处理一遍，双保险。
时间显示问题
python 后端返回 datetime 对象，序列化成 JSON 的时候，Flask 默认会变成类似 "Sun, 09 Jun 2024 08:30:00 GMT" 的格式，前端 new Date() 解析这种格式在小程序端会有兼容性问题。我写了一个通用的 to_dict 方法，把所有时间字段统一转成字符串 "2024-06-09 08:30:00"，前端再格式化展示，就不会出现时间显示 NaN 的问题。
库存并发问题
如果两个用户同时下单购买同一个菜品的最后一份，后端的扣库存逻辑可能会把库存扣成负数。课程设计不用上什么分布式锁，最简单的处理是下单扣库存时用原子性的 SQL 更新语句：
UPDATE menu SET stock = stock - 1 WHERE id = ? AND stock > 0然后检查受影响的行数，如果是 0 就说明库存不足，返回失败。这个方案在单机部署的校园项目里足够可靠了。
5.2 性能优化与体验细节
系统能跑起来之后，我开始优化一些体验细节，这些细节虽然不直接影响功能，但能明显提升演示效果。
列表渲染优化：菜单列表和订单列表用 v-for 渲染时，每一项都绑定一个复杂的对象，当数据量大的时候页面会卡。我给每个列表项加了唯一 key，并且把不需要响应式更新的字段用普通变量存，减少 Vue 的响应式系统负担。
图片懒加载：uniapp 的 image 组件自带 lazy-load 属性，给菜品列表的图片加上 lazy-load="true"，滚动时才加载图片，滑动起来明显流畅很多。
空数据状态：购物车为空、订单列表为空、搜索无结果，这些场景都要有对应的空状态页面。我放了简单的一句话加一张灰色占位图，虽然丑，但至少用户知道是空的，不会以为系统坏了。
下拉刷新：小程序页面开启 enablePullDownRefresh，用户下拉就能刷新菜品库存和订单状态，感知上会比定时轮询更顺手。
5.3 后续功能的扩展方向
如果时间充裕，有几个方向可以继续做，而且都是加分项。
- 优惠券模块：加一张 coupon 表，下单时选择优惠券抵扣金额，能丰富订单系统逻辑。
- 配送定位：接入地图 API 做骑手位置展示，用户端可以看到骑手到哪了。校园里面的定位不需要太精准，调坐标展示个大概位置就行。
- 消息推送：用小程序订阅消息，商家接单、订单送达的时候给用户推送一条通知。微信的订阅消息一次授权只能推送一条，限制比较多，但演示效果很好。
- 数据统计图表：后台管理页面用图表展示每日订单量、销售额趋势，这个能给项目增色不少，做起来也不难，前端引一个图表库就能搞定。
我个人做完这套系统最大的体会是：做项目别追求技术栈的新奇，关键是核心链路要完整、逻辑要严谨。一个用户能下单、商家能接单、状态能流转、订单能追踪的系统，哪怕界面朴素一点，也比堆了一堆炫酷技术但流程断了半截的强得多。最后再分享一个小技巧：开发的时候前后端接口联调，遇到问题先打印请求参数和返回结果，别猜；把 uni.request 的 success 回调里 res 整个打印出来，绝大多数联调问题一眼就能定位到是前端传参错了还是后端逻辑错了。
