做一个校园外卖小程序这事儿本身就是一个特别典型的全栈练手项目。市面上这类项目或者毕设题十有八九是“小程序端 后台管理”两件套但真正把“用户下单、商家接单、配送跟踪”整条链路跑通的并不多。我用 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主要字段iduser_id关联商家用户name店铺名称logo店铺头像notice公告status营业状态1 营业中 / 0 休息中菜品表menu主要字段idstore_id所属店铺category菜品分类比如套餐、主食、饮品name菜名image菜品图片price价格stock库存sales月售数量status1 上架 / 0 下架这里有个细节菜品分类不能单独建表。虽然正规商用系统会建 category 表但对于这种体量的小程序直接在 menu 表里加一个 category 字符串字段就够了查询的时候 group by 一下就能实现分类展示省掉一次连表查询代码也简单很多。购物车表cart主要字段iduser_idmenu_idquantity数量selected是否勾选订单表order主要字段idorder_no订单编号唯一索引user_id下单用户store_id店铺total_amount订单总金额status订单状态下面细说address配送地址remark备注create_time / pay_time / finish_time时间戳订单明细表order_item主要字段idorder_id关联订单menu_idmenu_name冗余菜品名防止菜品删除后查不到price下单时的单价快照quantity数量这里必须强调快照的重要性。用户下单之后商家完全可能改价格或者下架菜品如果订单明细表里不存一份当时的价格和菜名后面查历史订单就会看到错误信息甚至关联不到菜品。所以menu_name 和 price 一定要存冗余字段这是新手非常容易漏掉的一个设计。2.2 订单状态机的设计订单状态是整个系统最核心的逻辑。我设计了六个状态用整数存储方便前后端用数字做字典映射状态值含义说明0待支付用户已下单但未模拟支付1待接单已支付成功等待商家接单2备餐中商家已接单正在制作3配送中骑手已接单正在配送4已完成用户确认收货或骑手标记送达5已取消超时未支付或用户主动取消状态流转是这个逻辑待支付 0 - 支付成功后变成 1 待接单商家接单变成 2 备餐中商家出餐后变成 3 配送中骑手送达或用户确认后变成 4 已完成。后端做状态更新的时候不能只改一个 status 字段就完事。我每次状态变更都会校验当前状态是否符合预期比如只有 status1 的订单才能被商家接单变成 status2。这么做是防止两个端同时操作同一个订单的时候把状态搞乱。2.3 接口设计要点接口设计有几个容易被忽略的点在这里专门说一下。一是小程序端的请求封装。uniapp 自带的 uni.request 是异步回调风格用起来比较绕。我封装了一个 Promise 风格的 request 函数统一处理 baseURL、token、错误提示代码看起来会清爽很多。二是后端接口返回格式要统一。我用的格式很简单{ code: 200, msg: success, data: {} }业务异常时 code 用 400 或 500msg 存放错误提示前端拿到非 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, paramsparams).json() openid resp.get(openid) if not openid: return jsonify({code: 400, msg: 登录失败, data: None}) user User.query.filter_by(openidopenid).first() if not user: user User(openidopenid, nickname微信用户, role1) 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_noorder_no, user_iduser_id, store_idstore_id, total_amountround(total, 2), status0, addressaddress, remarkremark ) db.session.add(order) db.session.flush() # 拿到 order.id for oi in order_items: db.session.add(OrderItem(order_idorder.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_iduser_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_idorder.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_idorder.id, amountorder.total_amount, pay_typemock, status1 )) 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-loadtrue滚动时才加载图片滑动起来明显流畅很多。空数据状态购物车为空、订单列表为空、搜索无结果这些场景都要有对应的空状态页面。我放了简单的一句话加一张灰色占位图虽然丑但至少用户知道是空的不会以为系统坏了。下拉刷新小程序页面开启 enablePullDownRefresh用户下拉就能刷新菜品库存和订单状态感知上会比定时轮询更顺手。5.3 后续功能的扩展方向如果时间充裕有几个方向可以继续做而且都是加分项。优惠券模块加一张 coupon 表下单时选择优惠券抵扣金额能丰富订单系统逻辑。配送定位接入地图 API 做骑手位置展示用户端可以看到骑手到哪了。校园里面的定位不需要太精准调坐标展示个大概位置就行。消息推送用小程序订阅消息商家接单、订单送达的时候给用户推送一条通知。微信的订阅消息一次授权只能推送一条限制比较多但演示效果很好。数据统计图表后台管理页面用图表展示每日订单量、销售额趋势这个能给项目增色不少做起来也不难前端引一个图表库就能搞定。我个人做完这套系统最大的体会是做项目别追求技术栈的新奇关键是核心链路要完整、逻辑要严谨。一个用户能下单、商家能接单、状态能流转、订单能追踪的系统哪怕界面朴素一点也比堆了一堆炫酷技术但流程断了半截的强得多。最后再分享一个小技巧开发的时候前后端接口联调遇到问题先打印请求参数和返回结果别猜把 uni.request 的 success 回调里 res 整个打印出来绝大多数联调问题一眼就能定位到是前端传参错了还是后端逻辑错了。