简介本资源是一套面向初学者与中小型项目开发者的微信小程序排队系统全栈Demo源码聚焦餐饮、零售等轻量级线下服务场景的线上排队需求。压缩包共14个文件5个JS逻辑文件、3个WXSS样式文件、3个JSON配置文件、2个WXML页面文件及1个说明文本总大小仅11KB结构精简涵盖小程序前端页面渲染、用户授权交互、队列状态展示等核心模块后端逻辑虽未打包但代码中已预留API调用接口与数据结构注释便于快速对接自有服务。已有747人学习下载适合希望掌握微信小程序排队业务融合开发的开发者入门实践。读者可直接导入微信开发者工具运行调试完整理解从用户扫码进队、实时队列刷新到状态提示的全流程实现逻辑并基于现有WXML/WXSS/JS分层结构进行功能扩展或UI定制。1. 项目概述一个拿来即用的微信小程序排队系统最近在整理项目资料时翻出了一个几年前为本地一家社区服务中心做的微信小程序排队系统Demo。当时的需求很简单让来办事的居民特别是老年人不用在窗口前站着干等可以扫码取号然后在休息区安心坐着通过手机查看排队进度。这个Demo虽然功能不算复杂但麻雀虽小五脏俱全从用户端取号、查看队列到管理端叫号、过号处理都完整实现了。源码结构清晰注释也比较详细非常适合想入门微信小程序开发或者需要快速搭建一个轻量级排队场景的朋友参考。今天我就把这个“压箱底”的源码拿出来结合我当时的开发思路和踩过的坑从头到尾拆解一遍希望能帮你省去从零搭建的摸索时间。这个系统核心解决的就是线下排队场景的“等待焦虑”和“管理低效”问题。用户无需下载APP打开微信扫一扫就能取号实时看到自己前面还有几人预估等待时间到号了还会有微信消息提醒体验非常流畅。对管理员来说一个后台页面就能管理多个队列比如“业务咨询”、“证件办理”一键叫号、顺延、过号数据还能简单统计比手写号码纸和人工喊号省心太多。整个技术栈基于微信小程序原生框架后端用了云开发当时还叫小程序·云开发数据库、云函数、消息推送一站式搞定部署和维护成本极低。下面我就带你深入这个Demo的每一个细节。2. 系统核心设计与业务逻辑拆解2.1 为什么选择微信小程序云开发方案在做技术选型时我主要考虑了四个因素开发效率、用户体验、运维成本和项目规模。首先目标用户是社区居民微信的普及率几乎是100%小程序“无需安装、即用即走”的特性完美契合这种低频、临时的使用场景。如果让用户专门下载一个APP来排队推广成本和流失率会非常高。其次云开发CloudBase是当时微信小程序生态里快速后端服务的首选。它集成了云数据库、云函数和云存储最关键的是提供了微信生态的原生能力比如获取用户OpenID、发送订阅消息。这意味着我不需要自己购买服务器、配置域名、申请SSL证书、搭建用户鉴权体系。对于这个排队系统来说业务逻辑相对单纯但实时性要求高队列状态变化需即时同步云开发的数据库实时监听和云函数HTTP触发机制能以极低的代码量满足需求。注意微信小程序云开发现已升级为“微信云开发”部分接口和计费模式有调整但核心思路不变。本Demo基于较早的API编写在移植到新环境时需要注意对照官方最新文档更新相关调用方式。最后从项目规模看这是一个Demo级项目但设计时考虑了扩展性。比如队列类型、业务员叫号终端都是可配置的数据库设计也预留了字段。如果未来需要对接叫号屏、评价系统也有改造的空间。选择这个技术栈让我在两周内就完成了从原型到可演示的版本效率提升非常明显。2.2 核心业务流程与数据流设计整个系统的运转围绕两个角色用户、管理员和三个核心动作取号、叫号、过号展开。数据流的设计是保证系统正确性的关键。用户侧流程扫码/进入小程序用户扫描对应服务队列的二维码或直接进入小程序后选择需要办理的业务类型。授权与取号小程序请求用户授权主要用于后续发送订阅消息然后调用云函数生成一个排队号码。这个号码的生成并非简单的“当前最大号1”而是结合了队列ID、日期和当日流水号例如A202311150015其中A代表队列20231115是日期0015是当日第15个号。这样设计便于按日统计和问题追溯。加入队列与等待取号成功后用户信息OpenID、取的号码、排队时间、状态“等待中”被写入云数据库的queue_orders集合表。同时小程序端通过wx.cloud.database().collection(queue_orders).where(...).watch()监听属于该用户的、且状态为“等待中”的订单变化。实时查看与通知用户在小程序首页可以看到自己的号码、前方等待人数、预估等待时间。当管理员叫号时对应订单状态变为“叫号中”数据库变更触发监听用户小程序界面会收到强提醒。同时如果用户授权了订阅消息系统会通过云函数调用订阅消息接口发送一条服务通知到微信聊天列表防止用户切出小程序后错过叫号。管理侧流程登录与看板管理员通过专属页面登录Demo中简化了实际可结合云开发自定义登录。管理端首页是一个仪表盘展示各队列的当前叫号、等待人数、已办理数量等。叫号操作管理员选择某个队列如“综合业务”点击“叫号”。系统会执行一个云函数这个函数的逻辑是在queue_orders集合中找到该队列下状态为“等待中”的订单按取号时间正序排序取出第一条将其状态更新为“叫号中”并记录叫号时间。这个操作必须是原子的以避免多个管理员同时操作产生冲突。Demo中使用了数据库的“原子操作”和“事务”来保证。处理与过号用户前来办理后管理员点击“办理完成”该订单状态变为“已办结”。如果叫号后一段时间无人响应Demo中设为3分钟管理员可以执行“过号”操作将该订单状态置为“过号”并将其重新排入队尾即更新取号时间为当前时间状态改回“等待中”。数据集合表设计关键字段queue_orders(排队订单表):_id: 订单唯一ID。queue_id: 队列ID关联queues集合。daily_serial_num: 当日流水号用于生成显示给用户的号码。display_number: 显示号码如A001。openid: 用户唯一标识。status: 状态waiting等待中,calling叫号中,completed已办结,missed过号。create_time: 取号时间。call_time: 叫号时间。complete_time: 办结时间。queues(队列配置表):_id: 队列ID。name: 队列名称如“身份证办理”。prefix: 号码前缀如“A”。current_number: 当前叫到的号码非必须可作为缓存提升查询效率。active: 队列是否启用。这个数据流设计确保了状态变化的唯一性和可追踪性是整个系统可靠运行的基石。3. 源码关键模块解析与实现细节3.1 用户端小程序页面结构与组件用户端主要包含三个页面首页取号/看状态、我的排队历史/当前订单、个人中心。核心在首页。首页 (index/index)队列选择页面加载时通过云函数获取所有启用中的队列queues集合。使用picker组件或按钮组让用户选择。这里有个细节如果用户是扫码进入的二维码中可携带queue_id参数小程序在onLoad生命周期中获取该参数即可自动选中对应队列无需用户再次点击。取号逻辑取号按钮绑定的事件处理函数是重点。它需要依次完成检查授权调用wx.getSetting检查是否已授权订阅消息若未授权则弹窗引导授权。这里授权主要为了发送叫号通知。调用云函数调用名为takeNumber的云函数传入queue_id。切忌在前端直接操作数据库插入订单因为号码生成获取当日最大流水号并1必须是一个在服务端完成的原子操作防止并发取号产生重号。// pages/index/index.js 中取号函数片段 takeNumber: async function() { const that this; // 1. 检查订阅消息授权略 // 2. 显示加载中 wx.showLoading({ title: 取号中... }); try { // 3. 调用云函数 const res await wx.cloud.callFunction({ name: takeNumber, data: { queueId: that.data.selectedQueueId } }); // 4. 云函数返回成功包含生成的号码等信息 if (res.result.code 0) { const order res.result.data; wx.hideLoading(); // 跳转到“我的排队”页面或显示取号成功模态框 wx.navigateTo({ url: /pages/myQueue/myQueue?orderId${order._id} }); } else { wx.hideLoading(); wx.showToast({ title: res.result.msg, icon: none }); } } catch (err) { wx.hideLoading(); wx.showToast({ title: 网络开小差了请重试, icon: none }); console.error(取号失败:, err); } }实时状态监听取号成功后进入“我的排队”页面或首页状态展示区需要实时监听订单状态。这里使用云数据库的实时数据监听能力watch。// 在“我的排队”页面 onLoad 或 onShow 中 const db wx.cloud.database(); const _ db.command; this.listener db.collection(queue_orders).where({ _id: orderId, // 当前订单ID status: _.in([waiting, calling]) // 只监听等待中和叫号中状态 }).watch({ onChange: function(snapshot) { // snapshot.docs 是变化后的文档数组 if (snapshot.docs.length 0) { const latestOrder snapshot.docs[0]; // 更新页面数据触发视图渲染 that.setData({ currentOrder: latestOrder }); // 如果状态变为 calling给出强烈提示 if (latestOrder.status calling that.data.currentOrder.status ! calling) { wx.showModal({ title: 轮到您了, content: 请前往 ${latestOrder.queue_name} 窗口办理, showCancel: false }); } } }, onError: function(err) { console.error(监听失败:, err); } });重要提示watch监听会保持一个长期连接务必在页面onUnload生命周期中调用this.listener.close()关闭监听否则会导致资源泄露和意外的数据更新。3.2 后端云函数核心逻辑剖析云函数是小程序与数据库安全交互的中枢所有核心业务逻辑都在这里。1. 取号云函数 (takeNumber)这个函数必须保证在高并发下号码不重复。关键步骤原子计数使用云数据库的原子操作符inc在一个独立的counters集合中为每个队列按日维护一个自增流水号。例如文档ID为queue_A_20231115字段daily_seq每次调用inc(1)。事务创建订单使用db.runTransaction事务在事务内先原子递增获取当日流水号然后创建新的订单文档。事务确保这两个操作要么都成功要么都失败防止了“号增了但订单没创建”或“订单创建了但号没增”的中间状态。返回信息将生成的完整显示号码前缀日期流水号、订单ID、预计等待时间可根据当前队列等待订单数*平均办理时间估算返回给小程序端。// cloudfunctions/takeNumber/index.js 核心逻辑片段 const cloud require(wx-server-sdk); cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }); const db cloud.database(); const _ db.command; const $ _.aggregate; exports.main async (event, context) { const { queueId } event; const wxContext cloud.getWXContext(); const openid wxContext.OPENID; const today new Date().toISOString().split(T)[0]; // 获取YYYY-MM-DD // 1. 获取队列信息 const queueRes await db.collection(queues).doc(queueId).get(); if (!queueRes.data) { return { code: -1, msg: 队列不存在 }; } const queue queueRes.data; // 2. 使用事务原子地生成号码并创建订单 try { const result await db.runTransaction(async transaction { // a. 获取并递增当日计数器 const counterId queue_${queue._id}_${today}; const counterDoc await transaction.collection(counters).doc(counterId).get(); let nextSeq 1; if (counterDoc.data) { nextSeq counterDoc.data.daily_seq 1; await transaction.collection(counters).doc(counterId).update({ data: { daily_seq: _.inc(1) } }); } else { await transaction.collection(counters).doc(counterId).set({ data: { daily_seq: 1 } }); } // b. 生成显示号码 const displayNumber ${queue.prefix}${nextSeq.toString().padStart(3, 0)}; // 如 A001 // c. 创建排队订单 const orderData { queue_id: queueId, queue_name: queue.name, daily_serial_num: nextSeq, display_number: displayNumber, openid: openid, status: waiting, create_time: db.serverDate(), // 使用服务端时间 estimate_waiting_count: 0 // 后续可计算 }; const orderRes await transaction.collection(queue_orders).add({ data: orderData }); return { nextSeq, displayNumber, orderId: orderRes._id }; }); // 3. (可选) 异步更新队列的等待人数等统计信息避免影响主流程响应速度 // ... return { code: 0, msg: 取号成功, data: { orderId: result.orderId, number: result.displayNumber } }; } catch (err) { console.error(取号事务失败:, err); return { code: -2, msg: 系统繁忙请重试 }; } };2. 叫号云函数 (callNext)这是管理端的核心必须确保同一队列同一时刻只有一个“叫号中”的订单。查找并锁定下一个订单使用db.collection(queue_orders).where({ queue_id: queueId, status: waiting }).orderBy(create_time, asc).limit(1).get()找到最旧的一个等待订单。原子更新状态使用update操作并带上条件status: waiting。如果执行更新时该订单状态已被其他终端修改比如用户取消则更新影响条数为0说明“抢号”失败需要重新查找或提示管理员。发送订阅消息更新成功后立即调用微信订阅消息接口向订单对应的用户OpenID发送叫号通知。模板内容包含号码、队列名称、时间等。// cloudfunctions/callNext/index.js 关键片段 exports.main async (event, context) { const { queueId } event; const db cloud.database(); const _ db.command; // 1. 查找下一个等待的订单 const waitingOrderRes await db.collection(queue_orders) .where({ queue_id: queueId, status: waiting }) .orderBy(create_time, asc) .limit(1) .get(); if (waitingOrderRes.data.length 0) { return { code: 1, msg: 当前队列暂无等待用户 }; } const nextOrder waitingOrderRes.data[0]; // 2. 尝试原子更新其状态为“叫号中” const updateRes await db.collection(queue_orders).doc(nextOrder._id).update({ data: { status: calling, call_time: db.serverDate() } }); if (updateRes.stats.updated 0) { // 更新条数为0说明订单状态在查询后已被更改例如被其他管理员操作 return { code: -1, msg: 操作冲突请重试 }; } // 3. 更新队列当前叫号缓存可选用于快速查询 await db.collection(queues).doc(queueId).update({ data: { current_number: nextOrder.display_number } }); // 4. 发送微信订阅消息通知用户 try { const msgRes await cloud.openapi.subscribeMessage.send({ touser: nextOrder.openid, templateId: 你的订阅消息模板ID, page: pages/myQueue/myQueue, // 点击消息跳转的小程序页面 data: { thing1: { value: nextOrder.queue_name }, // 业务类型 number2: { value: nextOrder.display_number }, // 排队号码 time3: { value: new Date().toLocaleTimeString() } // 叫号时间 } }); console.log(消息发送成功:, msgRes); } catch (msgErr) { // 消息发送失败不应影响核心叫号业务但需记录日志 console.error(订阅消息发送失败:, msgErr); } return { code: 0, msg: 叫号成功, data: { calledNumber: nextOrder.display_number } }; };3.3 管理端实现与状态管理管理端我单独做了一个小程序页面需在app.json中配置独立的分包或页面通过简单的密码或云开发自定义登录进行权限控制。管理端核心是一个数据看板和操作面板。看板数据实时更新 管理端需要实时展示各队列的等待人数、当前叫号、已办理数。如果频繁轮询数据库会造成不必要的开销。这里有两种优化方案合理使用监听对queue_orders集合按队列和状态进行聚合查询的监听。但监听复杂查询可能性能不佳。使用定时触发云函数前端缓存我采用的方法是编写一个云函数getQueueStats通过数据库聚合管道Aggregate一次性计算出各队列的统计信息。在小程序管理端使用setInterval每10-15秒调用一次该云函数更新数据。虽然非绝对实时但对于管理场景完全够用且性能压力小。// 云函数聚合统计示例 const pipeline [ { $match: { status: waiting } }, // 过滤等待中的 { $group: { _id: $queue_id, waitingCount: { $sum: 1 } } } // 按队列分组计数 ]; // 类似地可以统计 calling, completed 状态的数量操作反馈与防重复提交 管理端的“叫号”、“完成”、“过号”按钮在点击后应立即禁用并显示加载状态直到云函数返回结果后再恢复。这是防止管理员因网络延迟重复点击导致业务逻辑错误如连续叫两个号的基本措施。4. 开发部署全流程与避坑指南4.1 环境准备与项目初始化注册小程序在微信公众平台注册一个小程序账号获取AppID。注意选择服务类目时可以选“工具-预约/报名”或“商业服务-线下商业/生活服务”等避免类目不符导致审核失败。开通云开发在微信开发者工具中找到“云开发”面板按指引开通。你会得到一个环境ID如env-xxx。创建两个环境是一个好习惯test测试和release生产。本Demo的配置指向测试环境。导入源码下载提供的grandmothern1j_微信小程序排队系统demo完整源码.zip文件并解压。用微信开发者工具打开项目目录在app.js中找到wx.cloud.init部分将env参数替换为你自己的测试环境ID。创建集合在云开发控制台的数据库面板中手动创建以下集合表queue_orders,queues,counters。counters集合的权限建议设置为“仅创建者可读写”因为它在事务中自增安全要求高。上传云函数在开发者工具的“云开发”面板或右键cloudfunctions目录下的每个子目录如takeNumber选择“上传并部署云端安装依赖”。确保所有依赖如wx-server-sdk已正确安装。4.2 关键配置与权限设置订阅消息叫号通知需要订阅消息能力。在微信公众平台后台的“功能-订阅消息”中申请一个合适的模板例如“业务办理通知”选择需要的字段如“业务类型”、“排队号码”、“叫号时间”。将模板ID复制替换云函数callNext中templateId的值。同时在小程序app.json或对应页面的.json文件中声明requiredPrivateInfos: [subscribeMessage]并在代码中按规范引导用户授权。数据库权限这是安全的重中之重。切勿将所有集合的权限设置为“所有用户可读所有用户可写”。queue_orders可设置为“所有用户可读仅创建者及管理员可写”。因为用户需要读取队列状态但只能创建取号和更新自己的订单如取消管理员需要能更新所有订单状态。queues设置为“所有用户可读仅管理员可写”。用户需要读取队列列表但只有管理员能增删改队列。counters建议设置为“仅创建者及管理员可读写”或通过云函数完全代理其读写前端不直接操作。云函数权限云函数运行在管理员权限下可以操作所有数据库。确保云函数中的逻辑都做好了输入校验和错误处理防止恶意调用。4.3 真机调试与上线前检查真机预览在开发者工具中点击“预览”生成二维码在手机上扫描测试。重点测试取号流程、状态监听更新、订阅消息接收、管理端操作。并发测试可以尝试在短时间内用多个手机或模拟多次请求进行取号检查号码是否连续、有无重复。测试管理端快速连续点击叫号是否会出现逻辑错误。网络与兼容性在弱网环境下如关闭Wi-Fi使用较慢的4G测试操作观察加载状态和错误提示是否友好。测试不同型号的安卓和iOS手机特别是小程序基础库版本较老的设备。审核要点提交审核前确保小程序有完整的隐私政策提示在app.json中配置特别是涉及收集用户OpenID。管理端页面最好做一定的权限校验避免普通用户直接访问。UI界面不能过于简陋需符合平台规范。5. 常见问题排查与性能优化建议在实际开发和后续维护中你可能会遇到以下问题这里给出我的排查思路和优化建议。5.1 高频问题速查表问题现象可能原因排查步骤与解决方案取号失败提示“系统繁忙”1. 云函数takeNumber事务冲突。2. 数据库counters集合权限不足。3. 网络异常。1. 查看云函数日志云开发控制台-日志看具体错误信息。2. 检查counters集合的权限设置确保云函数有写权限。3. 检查小程序wx.cloud.init环境ID是否正确。用户收不到叫号订阅消息1. 用户未授权或拒收。2. 订阅消息模板ID错误或未审核通过。3. 云函数中发送消息的代码报错。4. OpenID获取有误。1. 在小程序端检查授权状态引导用户开启通知。2. 核对公众平台模板ID与代码中是否一致确保模板已审核。3. 查看云函数callNext的日志确认cloud.openapi.subscribeMessage.send是否执行及报错。4. 确认存入订单的openid是调用cloud.getWXContext().OPENID获取的。管理端叫号后用户端状态没实时更新1. 数据库监听watch未正确建立或已断开。2. 监听查询条件where不匹配。3. 订单状态字段更新有误。1. 在用户端小程序控制台查看有无WebSocket连接错误。确认在页面onUnload时未误关闭监听。2. 核对监听条件中的_id和status范围是否正确。3. 去数据库查看对应订单的status字段是否已从waiting变为calling。号码不连续或出现重复号高并发下非原子操作导致。必须使用云函数事务来生成号码。确保takeNumber云函数中获取递增序列号和创建订单是在同一个db.runTransaction内完成。绝对避免前端先查询最大号再加一插入。管理端统计数字更新慢前端轮询间隔太长或聚合查询云函数性能慢。1. 适当缩短轮询间隔如5秒但需平衡服务器压力。2. 优化云函数getQueueStats为queue_orders的queue_id和status字段建立复合索引。考虑将结果缓存到另一个集合由定时触发云函数更新。5.2 性能与扩展性优化思路当排队人数非常多比如日均数千时基础版本可能会遇到性能瓶颈。可以考虑以下优化数据库查询优化索引是生命线务必为queue_orders集合的常用查询字段建立索引。例如管理端按队列和状态查最新订单queue_id, status, create_time的复合索引。用户端查询自己的订单openid, status的复合索引。可以在云开发控制台“数据库-索引管理”中添加。限制返回字段在查询时使用field方法指定只返回需要的字段减少网络传输和数据解析开销。例如监听订单状态变化时可能只需要status和display_number。状态更新的优化对于“过号重排”操作不要直接删除原订单再创建新订单。而是更新原订单的status为missed并同时更新其create_time为当前服务器时间。这样在按create_time正序查找“等待中”订单时过号的订单会自动排到队尾。这种方式更高效且保留了操作记录。前端体验优化虚拟列表如果管理端需要展示很长的历史订单列表使用小程序提供的wx.createIntersectionObserver或第三方组件库实现虚拟列表只渲染可视区域内的项目极大提升滚动性能。本地缓存将不常变化的配置信息如队列列表(queues)在小程序启动后获取并存入wx.setStorageSync。后续使用直接从本地读取减少不必要的网络请求。架构扩展思考如果单一云开发环境到达性能上限可以考虑将读操作分离。例如将队列的实时状态当前叫号、等待人数通过云函数计算后写入一个高读写性能的集合或利用云开发的“数据库触发器”在订单变化时自动更新这个状态快照。前端直接查询这个快照压力会小很多。对于超大型场所如医院、政务大厅可以考虑引入“队列分组”或“动态窗口分配”的概念。这需要更复杂的业务逻辑设计但底层的数据模型和状态机思想仍然是相通的。这个Demo源码的价值在于它提供了一个完整、可运行的最小核心模型。你可以基于它根据自己具体的业务场景添加功能比如预约时间段、排队转移、员工绩效统计、大数据展示屏对接等。开发过程中最深的体会就是清晰的状态机设计和原子性的数据操作是保证这类实时系统稳定可靠的根本。先把主干流程跑通再逐步迭代枝节功能是高效开发的不二法门。本文还有配套的精品资源点击获取