简介这是一套面向高校信息化建设者与微信小程序开发者设计的校园综合服务平台v1版完整前端源码聚焦学校日常管理场景如快递代取、订单接单、代理运营及学生个人中心等模块助力快速搭建轻量级校内服务应用。资源共142个文件包含23个JS逻辑文件含util.js等工具函数、23个WXSS样式文件、21个WXML结构文件、41个PNG界面截图及9个JPG后台管理图配合25个JSON配置文件构成典型小程序项目结构压缩包仅723KB轻量易部署。已有105人学习下载适合具备基础微信开发能力的中初级开发者参考学习。读者可直接获取可运行的小程序前端代码、完整的页面目录组织方式、后台管理界面视觉参考如首页、接单员、代理商等模块以及小程序端核心功能实现逻辑便于二次开发或教学演示。1. 这不是「又一个校园小程序」而是一套可落地的轻量级服务中台架构很多学校在做微信小程序时卡在「功能堆砌」和「运维失焦」之间首页轮播图加了三次快递代取流程却跑不通接单员角色权限配好了代理商提现接口却返回 502小程序端能点开页面后台日志里全是unexpected status 502 bad gateway。这个 v1 版本的「校园综合服务平台」不是 UI 原型稿它是一套完整闭环的轻量级服务中台——前端用原生微信小程序非 uni-app后端采用 Node.js MySQL 架构核心模块包括订单调度、角色分权接单员/代理商、资金流水提现、用户行为埋点util.js 封装了统一上报逻辑。它不依赖 SaaS 建站系统所有接口路径、状态码、错误响应格式都按微信生态规范对齐也不走「一键部署」黑盒路线安装文档明确要求你手动配置 Nginx 反向代理、MySQL 字符集、微信服务器域名白名单。适合高校信息中心技术人员、有 2 年以上 Node.js 开发经验的外包团队或正在做毕业设计需要真实部署链路的学生——你得亲手改config.js里的baseURL得看懂util.js里wx.request的拦截重试逻辑得在后台-接单员.jpg界面截图对应的路由表里补全/api/v1/order/accept的权限字段。2. 后端服务部署从环境初始化到接口可用的六步实操2.1 环境准备与依赖校验该平台后端基于 Express 框架构建最低兼容 Node.js v16.14.0v18.x 亦可MySQL 要求 5.7 或 8.0.23注意MySQL 8.0 默认启用caching_sha2_password插件若连接报错Client does not support authentication protocol需执行ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY your_password;。安装前先验证# 检查 Node.js 版本必须 16.14.0 node -v # 检查 npm 是否为最新稳定版避免 package-lock.json 解析异常 npm -v # 验证 MySQL 连接能力替换为你的实际 host/port/user/pass mysql -h 127.0.0.1 -P 3306 -u root -p -e SELECT VERSION();提示unexpected status 502 bad gateway多数源于 Nginx 未正确代理到 Node.js 进程或 Node.js 进程因数据库连接失败而崩溃。务必先确保mysql命令行能连通再启动服务。2.2 数据库初始化与表结构导入项目未提供 SQL 文件但后台-首页.jpg和后台-快递代取.jpg界面隐含了核心数据模型users含 role 字段区分 student/agent/courier、ordersstatus: pending/accepted/delivered/cancelled、withdrawalsamount, status, channel。需手动创建数据库并导入结构-- 创建数据库字符集必须为 utf8mb4否则微信昵称 emoji 存储失败 CREATE DATABASE campus_platform CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 切换数据库后执行建表语句此处以 orders 表为例完整建表脚本见项目根目录 /sql/init.sql CREATE TABLE orders ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, user_id BIGINT UNSIGNED NOT NULL COMMENT 下单学生ID, courier_id BIGINT UNSIGNED DEFAULT NULL COMMENT 接单员ID, agent_id BIGINT UNSIGNED DEFAULT NULL COMMENT 代理商ID, goods_desc VARCHAR(255) NOT NULL COMMENT 物品描述, pickup_location VARCHAR(128) NOT NULL COMMENT 取件地址, delivery_location VARCHAR(128) NOT NULL COMMENT 送达地址, status ENUM(pending,accepted,delivered,cancelled) DEFAULT pending, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user_status (user_id, status), KEY idx_courier_status (courier_id, status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;注意status字段使用ENUM而非VARCHAR既节省存储又防止非法值写入。idx_courier_status索引专为「接单员待处理订单列表」查询优化对应后台-接单员.jpg中的筛选逻辑。2.3 服务配置与启动配置文件位于/config/index.js关键参数必须修改参数名示例值说明db.host127.0.0.1数据库 IP生产环境不可为 localhostdb.port3306MySQL 端口db.databasecampus_platform上一步创建的数据库名wechat.appIdwx1234567890abcdef微信公众平台获取的 AppIDwechat.appSecreta1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6对应 AppSecretserver.port3000服务监听端口Nginx 反向代理目标server.baseUrlhttps://api.campus-school.edu.cn小程序wx.request的 base URL必须是 HTTPS 且已备案启动命令# 安装依赖注意项目使用 npm非 yarn npm install # 启动服务开发环境 npm run dev # 生产环境推荐使用 pm2需全局安装 npm install -g pm2 pm2 start ./bin/www --name campus-api验证接口是否就绪curl -X GET http://127.0.0.1:3000/api/v1/health -H Content-Type: application/json # 正常返回{status:ok,timestamp:1725789012}2.4 Nginx 反向代理配置解决 502 关键步骤unexpected status 502 bad gateway的根源几乎都出在这里。以下为最小可行配置保存为/etc/nginx/conf.d/campus.confupstream campus_backend { server 127.0.0.1:3000; keepalive 32; } server { listen 443 ssl http2; server_name api.campus-school.edu.cn; # SSL 证书必须微信小程序强制 HTTPS ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; # 关键透传 Host 和真实 IP供后端日志分析 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 超时设置避免长连接阻塞 proxy_connect_timeout 10s; proxy_send_timeout 30s; proxy_read_timeout 30s; location /api/v1/ { proxy_pass http://campus_backend/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # 静态资源如上传的图片可直接由 Nginx 服务 location /uploads/ { alias /var/www/campus/uploads/; expires 1h; } }重载配置并检查sudo nginx -t sudo systemctl reload nginx # 查看 Nginx 错误日志定位 502 原因 sudo tail -f /var/log/nginx/error.log提示若日志出现connect() failed (111: Connection refused)说明 Node.js 服务未运行或端口被占用若出现upstream timed out则需调大proxy_read_timeout并检查后端数据库查询是否过慢。3. 小程序端对接从登录态管理到订单状态同步3.1 登录与 session 统一管理小程序不支持 Cookie需通过code2Session换取openid并绑定自定义 session。util.js中封装了核心逻辑// util.js 片段 const login () { return new Promise((resolve, reject) { wx.login({ success: res { // 将 code 发送给后端换取 session_key 和 openid wx.request({ url: ${config.baseUrl}/api/v1/login, method: POST, data: { code: res.code }, success: resp { if (resp.data.code 200) { // 将后端返回的 token 存入 storage后续请求携带 wx.setStorageSync(token, resp.data.data.token); resolve(resp.data.data); } else { reject(new Error(resp.data.message)); } }, fail: reject }); }, fail: reject }); }); };注意/api/v1/login接口必须校验微信js_code的有效性并将openid与数据库users表关联。若小程序-我的.jpg中用户信息为空首要排查此接口返回的token是否被正确存储及后续请求是否携带。3.2 订单状态机与界面联动小程序-订单界面.jpg展示了多状态订单卡片其渲染逻辑依赖后端精确返回status字段。前端需严格匹配枚举值// pages/order/list.js data: { orderStatusMap: { pending: { text: 待接单, color: #FF9900 }, accepted: { text: 已接单, color: #0099FF }, delivered: { text: 已送达, color: #33CC33 }, cancelled: { text: 已取消, color: #999999 } } }, onLoad() { this.loadOrders(); }, loadOrders() { wx.request({ url: ${config.baseUrl}/api/v1/orders, header: { Authorization: Bearer ${wx.getStorageSync(token)} }, success: res { // 后端必须返回 status 字段前端直接映射 this.setData({ orders: res.data.data.map(o ({ ...o, statusText: this.data.orderStatusMap[o.status]?.text || 未知, statusColor: this.data.orderStatusMap[o.status]?.color || #999 })) }); } }); }3.3 提现功能的风控校验实现小程序-提现.jpg对应/api/v1/withdrawals接口后端需做三重校验余额校验SELECT balance FROM users WHERE id ?确保balance amount频率校验SELECT COUNT(*) FROM withdrawals WHERE user_id ? AND created_at DATE_SUB(NOW(), INTERVAL 24 HOUR)限制 24 小时内最多 3 次渠道校验根据channelalipay/wechat调用不同支付 SDK返回transaction_id写入withdrawals表前端提交代码// 提交提现 submitWithdrawal() { const { amount, channel } this.data.form; wx.request({ url: ${config.baseUrl}/api/v1/withdrawals, method: POST, header: { Authorization: Bearer ${wx.getStorageSync(token)} }, data: { amount, channel }, success: res { if (res.data.code 200) { wx.showToast({ title: 申请成功, icon: success }); // 跳转至提现记录页 wx.navigateTo({ url: /pages/withdraw/history }); } else { wx.showToast({ title: res.data.message, icon: none }); } } }); }提示若提现按钮点击无响应检查util.js中wx.request是否被全局拦截器阻止如未登录跳转逻辑或后端withdrawals表缺少transaction_id字段导致插入失败。4. 角色权限控制接单员与代理商的差异化路由与数据隔离4.1 后端 RBAC 权限中间件设计后台-接单员.jpg与后台-代理商.jpg界面功能差异巨大不能仅靠前端隐藏按钮。后端必须实现细粒度权限控制。项目采用基于角色的路由守卫// middleware/auth.js const checkRole (requiredRoles) { return (req, res, next) { const { role } req.user; // 由登录中间件注入 if (requiredRoles.includes(role)) { next(); } else { res.status(403).json({ code: 403, message: 权限不足 }); } }; }; // router/order.js router.get(/pending, checkRole([courier]), orderController.listPending); // 仅接单员可见 router.get(/assigned, checkRole([courier]), orderController.listAssigned); // 仅接单员可见 router.get(/commission, checkRole([agent]), agentController.getCommission); // 仅代理商可见 router.post(/settle, checkRole([agent]), agentController.settleCommission); // 仅代理商可见4.2 数据层面的租户隔离代理商管理多个接单员其数据必须隔离。orders表中agent_id字段即为租户标识。查询时强制添加条件// controller/agent.js exports.getCommission async (req, res) { const { id } req.user; // 当前登录代理商 ID const result await db.query( SELECT SUM(amount) as total FROM withdrawals WHERE agent_id ? AND status success, [id] ); res.json({ code: 200, data: result[0] }); };注意小程序-申请接单.jpg页面提交的POST /api/v1/couriers/apply接口必须校验申请人user_id是否属于当前代理商的agent_id下通过users表的referral_agent_id字段关联否则会出现跨代理商申请漏洞。4.3 前端动态菜单渲染小程序-我的.jpg底部 TabBar 根据角色动态切换。app.js中onLaunch获取用户角色后存入 globalData// app.js App({ globalData: { userInfo: null, userRole: student // 默认学生角色 }, onLaunch() { wx.getStorage({ key: userInfo, success: res { this.globalData.userInfo res.data; this.globalData.userRole res.data.role; // student / courier / agent } }); } });TabBar 页面通过getApp().globalData.userRole控制显示!-- tabbar.wxml -- view classtabbar navigator url/pages/home/index classtab-item {{ getApp().globalData.userRole student ? active : }} 首页 /navigator navigator url/pages/order/list classtab-item {{ getApp().globalData.userRole ! student ? active : }} 订单 /navigator !-- 代理商专属入口 -- navigator wx:if{{ getApp().globalData.userRole agent }} url/pages/agent/dashboard 代理中心 /navigator /view5. 生产环境排错从 502/503 到微信域名配置的实战技巧5.1 快速定位网关超时的三层检查法当出现unexpected status 502 bad gateway或unexpected status 503 service unavailable按此顺序排查层级检查项命令/操作预期结果Nginx 层进程是否存活、配置是否生效sudo systemctl status nginxsudo nginx -tactive (running)nginx: configuration file /etc/nginx/nginx.conf test is successfulNode.js 层进程是否存活、端口是否监听pm2 listsudo lsof -i :3000Statusonlinenode进程监听*:3000MySQL 层连接数是否耗尽、慢查询是否堆积mysql -e SHOW STATUS LIKE Threads_connected;mysql -e SELECT * FROM information_schema.PROCESSLIST WHERE TIME 60;Threads_connected max_connections默认151无长时间运行查询提示若pm2 list显示errored立即执行pm2 logs campus-api查看错误栈——90% 的 case 是数据库密码错误或config.js中server.baseUrl未配 HTTPS 导致微信校验失败。5.2 微信服务器域名白名单配置要点小程序-首页.jpg加载失败大概率是域名未配置。登录微信公众平台 → 开发管理 → 开发管理 → 服务器域名必须同时配置三项request 合法域名https://api.campus-school.edu.cn注意必须带https://且与config.js中server.baseUrl完全一致socket 合法域名留空本项目未用 WebSocketuploadFile 合法域名同 request 域名若小程序有图片上传注意配置后24 小时内生效且仅对已发布的小程序版本生效。开发版调试时开发者工具勾选「不校验合法域名」仅用于本地测试上线前必须关闭。5.3 修改刚进入的加载页面Splash Screen微信小程序启动时默认白屏需在app.json中配置splashscreen{ splashscreen: { alwaysShowBeforeRender: true, backgroundColor: #ffffff, loadingPage: { image: /assets/images/splash.png, text: 校园服务平台, fontSize: 16, color: #333333 } } }/assets/images/splash.png尺寸要求iPhone X 为 1125×2436pxAndroid 主流屏为 1080×1920px。若出现url: http://127.0.0.1:15721/v1/responses类似错误说明开发者工具未关闭「安全域名校验」或app.json中networkTimeout设置过短建议request: 30000。5.4 利用 util.js 进行请求监控与错误归因util.js不仅是工具函数集合更是错误诊断入口。其request方法内置了失败重试与分类打点// util.js 中 request 封装 const request (options) { return new Promise((resolve, reject) { const startTime Date.now(); wx.request({ ...options, success: res { const duration Date.now() - startTime; // 上报成功请求便于 APM 分析 if (options.url.includes(/api/v1/)) { console.log([API SUCCESS] ${options.url} ${duration}ms); } resolve(res); }, fail: err { const duration Date.now() - startTime; // 区分网络错误与业务错误 if (err.errMsg.includes(request:fail)) { console.error([NETWORK ERROR] ${options.url} ${err.errMsg} ${duration}ms); } else if (err.statusCode 502) { console.error([GATEWAY ERROR] ${options.url} 502 ${duration}ms); } reject(err); } }); }); };在真机调试时打开微信开发者工具 → Console 面板筛选GATEWAY ERROR即可快速定位哪个接口触发了 502无需翻查 Nginx 日志。提示v1符号在此项目中代表 API 版本号/api/v1/xxx所有前端请求 URL 必须包含该路径前缀后端路由注册也以此为基准。若误删v1将导致 404 错误而非 502。本文还有配套的精品资源点击获取
校园小程序服务中台：Node.js+MySQL轻量级架构实战
简介这是一套面向高校信息化建设者与微信小程序开发者设计的校园综合服务平台v1版完整前端源码聚焦学校日常管理场景如快递代取、订单接单、代理运营及学生个人中心等模块助力快速搭建轻量级校内服务应用。资源共142个文件包含23个JS逻辑文件含util.js等工具函数、23个WXSS样式文件、21个WXML结构文件、41个PNG界面截图及9个JPG后台管理图配合25个JSON配置文件构成典型小程序项目结构压缩包仅723KB轻量易部署。已有105人学习下载适合具备基础微信开发能力的中初级开发者参考学习。读者可直接获取可运行的小程序前端代码、完整的页面目录组织方式、后台管理界面视觉参考如首页、接单员、代理商等模块以及小程序端核心功能实现逻辑便于二次开发或教学演示。1. 这不是「又一个校园小程序」而是一套可落地的轻量级服务中台架构很多学校在做微信小程序时卡在「功能堆砌」和「运维失焦」之间首页轮播图加了三次快递代取流程却跑不通接单员角色权限配好了代理商提现接口却返回 502小程序端能点开页面后台日志里全是unexpected status 502 bad gateway。这个 v1 版本的「校园综合服务平台」不是 UI 原型稿它是一套完整闭环的轻量级服务中台——前端用原生微信小程序非 uni-app后端采用 Node.js MySQL 架构核心模块包括订单调度、角色分权接单员/代理商、资金流水提现、用户行为埋点util.js 封装了统一上报逻辑。它不依赖 SaaS 建站系统所有接口路径、状态码、错误响应格式都按微信生态规范对齐也不走「一键部署」黑盒路线安装文档明确要求你手动配置 Nginx 反向代理、MySQL 字符集、微信服务器域名白名单。适合高校信息中心技术人员、有 2 年以上 Node.js 开发经验的外包团队或正在做毕业设计需要真实部署链路的学生——你得亲手改config.js里的baseURL得看懂util.js里wx.request的拦截重试逻辑得在后台-接单员.jpg界面截图对应的路由表里补全/api/v1/order/accept的权限字段。2. 后端服务部署从环境初始化到接口可用的六步实操2.1 环境准备与依赖校验该平台后端基于 Express 框架构建最低兼容 Node.js v16.14.0v18.x 亦可MySQL 要求 5.7 或 8.0.23注意MySQL 8.0 默认启用caching_sha2_password插件若连接报错Client does not support authentication protocol需执行ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY your_password;。安装前先验证# 检查 Node.js 版本必须 16.14.0 node -v # 检查 npm 是否为最新稳定版避免 package-lock.json 解析异常 npm -v # 验证 MySQL 连接能力替换为你的实际 host/port/user/pass mysql -h 127.0.0.1 -P 3306 -u root -p -e SELECT VERSION();提示unexpected status 502 bad gateway多数源于 Nginx 未正确代理到 Node.js 进程或 Node.js 进程因数据库连接失败而崩溃。务必先确保mysql命令行能连通再启动服务。2.2 数据库初始化与表结构导入项目未提供 SQL 文件但后台-首页.jpg和后台-快递代取.jpg界面隐含了核心数据模型users含 role 字段区分 student/agent/courier、ordersstatus: pending/accepted/delivered/cancelled、withdrawalsamount, status, channel。需手动创建数据库并导入结构-- 创建数据库字符集必须为 utf8mb4否则微信昵称 emoji 存储失败 CREATE DATABASE campus_platform CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 切换数据库后执行建表语句此处以 orders 表为例完整建表脚本见项目根目录 /sql/init.sql CREATE TABLE orders ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, user_id BIGINT UNSIGNED NOT NULL COMMENT 下单学生ID, courier_id BIGINT UNSIGNED DEFAULT NULL COMMENT 接单员ID, agent_id BIGINT UNSIGNED DEFAULT NULL COMMENT 代理商ID, goods_desc VARCHAR(255) NOT NULL COMMENT 物品描述, pickup_location VARCHAR(128) NOT NULL COMMENT 取件地址, delivery_location VARCHAR(128) NOT NULL COMMENT 送达地址, status ENUM(pending,accepted,delivered,cancelled) DEFAULT pending, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user_status (user_id, status), KEY idx_courier_status (courier_id, status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;注意status字段使用ENUM而非VARCHAR既节省存储又防止非法值写入。idx_courier_status索引专为「接单员待处理订单列表」查询优化对应后台-接单员.jpg中的筛选逻辑。2.3 服务配置与启动配置文件位于/config/index.js关键参数必须修改参数名示例值说明db.host127.0.0.1数据库 IP生产环境不可为 localhostdb.port3306MySQL 端口db.databasecampus_platform上一步创建的数据库名wechat.appIdwx1234567890abcdef微信公众平台获取的 AppIDwechat.appSecreta1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6对应 AppSecretserver.port3000服务监听端口Nginx 反向代理目标server.baseUrlhttps://api.campus-school.edu.cn小程序wx.request的 base URL必须是 HTTPS 且已备案启动命令# 安装依赖注意项目使用 npm非 yarn npm install # 启动服务开发环境 npm run dev # 生产环境推荐使用 pm2需全局安装 npm install -g pm2 pm2 start ./bin/www --name campus-api验证接口是否就绪curl -X GET http://127.0.0.1:3000/api/v1/health -H Content-Type: application/json # 正常返回{status:ok,timestamp:1725789012}2.4 Nginx 反向代理配置解决 502 关键步骤unexpected status 502 bad gateway的根源几乎都出在这里。以下为最小可行配置保存为/etc/nginx/conf.d/campus.confupstream campus_backend { server 127.0.0.1:3000; keepalive 32; } server { listen 443 ssl http2; server_name api.campus-school.edu.cn; # SSL 证书必须微信小程序强制 HTTPS ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; # 关键透传 Host 和真实 IP供后端日志分析 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 超时设置避免长连接阻塞 proxy_connect_timeout 10s; proxy_send_timeout 30s; proxy_read_timeout 30s; location /api/v1/ { proxy_pass http://campus_backend/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # 静态资源如上传的图片可直接由 Nginx 服务 location /uploads/ { alias /var/www/campus/uploads/; expires 1h; } }重载配置并检查sudo nginx -t sudo systemctl reload nginx # 查看 Nginx 错误日志定位 502 原因 sudo tail -f /var/log/nginx/error.log提示若日志出现connect() failed (111: Connection refused)说明 Node.js 服务未运行或端口被占用若出现upstream timed out则需调大proxy_read_timeout并检查后端数据库查询是否过慢。3. 小程序端对接从登录态管理到订单状态同步3.1 登录与 session 统一管理小程序不支持 Cookie需通过code2Session换取openid并绑定自定义 session。util.js中封装了核心逻辑// util.js 片段 const login () { return new Promise((resolve, reject) { wx.login({ success: res { // 将 code 发送给后端换取 session_key 和 openid wx.request({ url: ${config.baseUrl}/api/v1/login, method: POST, data: { code: res.code }, success: resp { if (resp.data.code 200) { // 将后端返回的 token 存入 storage后续请求携带 wx.setStorageSync(token, resp.data.data.token); resolve(resp.data.data); } else { reject(new Error(resp.data.message)); } }, fail: reject }); }, fail: reject }); }); };注意/api/v1/login接口必须校验微信js_code的有效性并将openid与数据库users表关联。若小程序-我的.jpg中用户信息为空首要排查此接口返回的token是否被正确存储及后续请求是否携带。3.2 订单状态机与界面联动小程序-订单界面.jpg展示了多状态订单卡片其渲染逻辑依赖后端精确返回status字段。前端需严格匹配枚举值// pages/order/list.js data: { orderStatusMap: { pending: { text: 待接单, color: #FF9900 }, accepted: { text: 已接单, color: #0099FF }, delivered: { text: 已送达, color: #33CC33 }, cancelled: { text: 已取消, color: #999999 } } }, onLoad() { this.loadOrders(); }, loadOrders() { wx.request({ url: ${config.baseUrl}/api/v1/orders, header: { Authorization: Bearer ${wx.getStorageSync(token)} }, success: res { // 后端必须返回 status 字段前端直接映射 this.setData({ orders: res.data.data.map(o ({ ...o, statusText: this.data.orderStatusMap[o.status]?.text || 未知, statusColor: this.data.orderStatusMap[o.status]?.color || #999 })) }); } }); }3.3 提现功能的风控校验实现小程序-提现.jpg对应/api/v1/withdrawals接口后端需做三重校验余额校验SELECT balance FROM users WHERE id ?确保balance amount频率校验SELECT COUNT(*) FROM withdrawals WHERE user_id ? AND created_at DATE_SUB(NOW(), INTERVAL 24 HOUR)限制 24 小时内最多 3 次渠道校验根据channelalipay/wechat调用不同支付 SDK返回transaction_id写入withdrawals表前端提交代码// 提交提现 submitWithdrawal() { const { amount, channel } this.data.form; wx.request({ url: ${config.baseUrl}/api/v1/withdrawals, method: POST, header: { Authorization: Bearer ${wx.getStorageSync(token)} }, data: { amount, channel }, success: res { if (res.data.code 200) { wx.showToast({ title: 申请成功, icon: success }); // 跳转至提现记录页 wx.navigateTo({ url: /pages/withdraw/history }); } else { wx.showToast({ title: res.data.message, icon: none }); } } }); }提示若提现按钮点击无响应检查util.js中wx.request是否被全局拦截器阻止如未登录跳转逻辑或后端withdrawals表缺少transaction_id字段导致插入失败。4. 角色权限控制接单员与代理商的差异化路由与数据隔离4.1 后端 RBAC 权限中间件设计后台-接单员.jpg与后台-代理商.jpg界面功能差异巨大不能仅靠前端隐藏按钮。后端必须实现细粒度权限控制。项目采用基于角色的路由守卫// middleware/auth.js const checkRole (requiredRoles) { return (req, res, next) { const { role } req.user; // 由登录中间件注入 if (requiredRoles.includes(role)) { next(); } else { res.status(403).json({ code: 403, message: 权限不足 }); } }; }; // router/order.js router.get(/pending, checkRole([courier]), orderController.listPending); // 仅接单员可见 router.get(/assigned, checkRole([courier]), orderController.listAssigned); // 仅接单员可见 router.get(/commission, checkRole([agent]), agentController.getCommission); // 仅代理商可见 router.post(/settle, checkRole([agent]), agentController.settleCommission); // 仅代理商可见4.2 数据层面的租户隔离代理商管理多个接单员其数据必须隔离。orders表中agent_id字段即为租户标识。查询时强制添加条件// controller/agent.js exports.getCommission async (req, res) { const { id } req.user; // 当前登录代理商 ID const result await db.query( SELECT SUM(amount) as total FROM withdrawals WHERE agent_id ? AND status success, [id] ); res.json({ code: 200, data: result[0] }); };注意小程序-申请接单.jpg页面提交的POST /api/v1/couriers/apply接口必须校验申请人user_id是否属于当前代理商的agent_id下通过users表的referral_agent_id字段关联否则会出现跨代理商申请漏洞。4.3 前端动态菜单渲染小程序-我的.jpg底部 TabBar 根据角色动态切换。app.js中onLaunch获取用户角色后存入 globalData// app.js App({ globalData: { userInfo: null, userRole: student // 默认学生角色 }, onLaunch() { wx.getStorage({ key: userInfo, success: res { this.globalData.userInfo res.data; this.globalData.userRole res.data.role; // student / courier / agent } }); } });TabBar 页面通过getApp().globalData.userRole控制显示!-- tabbar.wxml -- view classtabbar navigator url/pages/home/index classtab-item {{ getApp().globalData.userRole student ? active : }} 首页 /navigator navigator url/pages/order/list classtab-item {{ getApp().globalData.userRole ! student ? active : }} 订单 /navigator !-- 代理商专属入口 -- navigator wx:if{{ getApp().globalData.userRole agent }} url/pages/agent/dashboard 代理中心 /navigator /view5. 生产环境排错从 502/503 到微信域名配置的实战技巧5.1 快速定位网关超时的三层检查法当出现unexpected status 502 bad gateway或unexpected status 503 service unavailable按此顺序排查层级检查项命令/操作预期结果Nginx 层进程是否存活、配置是否生效sudo systemctl status nginxsudo nginx -tactive (running)nginx: configuration file /etc/nginx/nginx.conf test is successfulNode.js 层进程是否存活、端口是否监听pm2 listsudo lsof -i :3000Statusonlinenode进程监听*:3000MySQL 层连接数是否耗尽、慢查询是否堆积mysql -e SHOW STATUS LIKE Threads_connected;mysql -e SELECT * FROM information_schema.PROCESSLIST WHERE TIME 60;Threads_connected max_connections默认151无长时间运行查询提示若pm2 list显示errored立即执行pm2 logs campus-api查看错误栈——90% 的 case 是数据库密码错误或config.js中server.baseUrl未配 HTTPS 导致微信校验失败。5.2 微信服务器域名白名单配置要点小程序-首页.jpg加载失败大概率是域名未配置。登录微信公众平台 → 开发管理 → 开发管理 → 服务器域名必须同时配置三项request 合法域名https://api.campus-school.edu.cn注意必须带https://且与config.js中server.baseUrl完全一致socket 合法域名留空本项目未用 WebSocketuploadFile 合法域名同 request 域名若小程序有图片上传注意配置后24 小时内生效且仅对已发布的小程序版本生效。开发版调试时开发者工具勾选「不校验合法域名」仅用于本地测试上线前必须关闭。5.3 修改刚进入的加载页面Splash Screen微信小程序启动时默认白屏需在app.json中配置splashscreen{ splashscreen: { alwaysShowBeforeRender: true, backgroundColor: #ffffff, loadingPage: { image: /assets/images/splash.png, text: 校园服务平台, fontSize: 16, color: #333333 } } }/assets/images/splash.png尺寸要求iPhone X 为 1125×2436pxAndroid 主流屏为 1080×1920px。若出现url: http://127.0.0.1:15721/v1/responses类似错误说明开发者工具未关闭「安全域名校验」或app.json中networkTimeout设置过短建议request: 30000。5.4 利用 util.js 进行请求监控与错误归因util.js不仅是工具函数集合更是错误诊断入口。其request方法内置了失败重试与分类打点// util.js 中 request 封装 const request (options) { return new Promise((resolve, reject) { const startTime Date.now(); wx.request({ ...options, success: res { const duration Date.now() - startTime; // 上报成功请求便于 APM 分析 if (options.url.includes(/api/v1/)) { console.log([API SUCCESS] ${options.url} ${duration}ms); } resolve(res); }, fail: err { const duration Date.now() - startTime; // 区分网络错误与业务错误 if (err.errMsg.includes(request:fail)) { console.error([NETWORK ERROR] ${options.url} ${err.errMsg} ${duration}ms); } else if (err.statusCode 502) { console.error([GATEWAY ERROR] ${options.url} 502 ${duration}ms); } reject(err); } }); }); };在真机调试时打开微信开发者工具 → Console 面板筛选GATEWAY ERROR即可快速定位哪个接口触发了 502无需翻查 Nginx 日志。提示v1符号在此项目中代表 API 版本号/api/v1/xxx所有前端请求 URL 必须包含该路径前缀后端路由注册也以此为基准。若误删v1将导致 404 错误而非 502。本文还有配套的精品资源点击获取
