这次要聊的是微信小程序里的签到码玩法。我在去年的一次线下行业峰会上把传统的纸质签到换成了小程序签到码从入场效率到数据统计体验完全不一样。很多人以为做签到码就是生成个二维码、再扫一下这么简单实际落地时涉及登录态、动态码时效、防重复核销、页面生命周期和真机兼容一堆问题。这篇文章就把我做完一整套微信小程序签到码系统的思路和踩坑过程写出来适合正在做活动签到、课程签到、展会入场这类场景的开发者参考也适合想要快速搭一个码类业务后端的前端同学看。1. 一场活动从签到码开始业务需求拆解很多开发者的第一反应是签到码嘛生成一个二维码丢给用户就完事了真正做下去才发现需求方要的不只是一个码而是一整套围绕签到码的活动流程管理。我建议先别急着写代码把用户和管理员两条线的操作路径画出来才能知道哪些地方需要做状态机、哪些地方需要防并发。1.1 用户侧报名、领码、到场展示用户侧的使用过程通常是这样的先看到活动页面报名后得到一个专属的签到码活动当天打开小程序展示这个码工作人员扫码核销用户收到核销成功提示。这句话看起来简单但报名后得到一个签到码这个环节就隐藏了一个关键问题签到码是报名时就固定生成还是到场时再生成实际项目里两种需求都存在。针对需要提前锁定名额的活动我推荐报名成功后就生成签到码码的内容绑定用户ID和活动ID但不包含入场的具体时间。针对现场购票或临时签到可以到场后点击生成签到码按钮再由后端动态下发一个有有效期的码。用户侧的另一个痛点是码丢了。如果用户截图保存那码就是静态的容易被转发或代签。所以很多进阶需求要求动态码比如每30秒刷新一次甚至码上带时间戳和跳动水印。这个需求如果前期不确认后面改起来会特别痛苦。1.2 管理侧配置活动、扫码核销、看数据管理员的诉求比用户更复杂。首先他们要能创建活动设置活动名称、时间、地点、签到有效期其次现场要拿手机扫用户的码核销后能看到结果最后是要能导出一份签到数据比如谁来了、几点来的、谁没来。这套东西到一个完整系统里其实就是一个轻量级的活动管理后台加上一个移动端核销工具。如果公司已经有一套后台管理框架可以直接复用如果是从零开始我建议最小闭环先做三块活动配置、核销扫码、数据导出。不要一开始就去做复杂的权限角色、多级组织架构先让活动能跑起来数据能收上来后面再慢慢加。一个很容易被忽略的需求是核销记录的可追溯性。不仅要记录用户扫码时间还要记录哪个工作人员核销的、用了什么设备。一旦现场出现纠纷这些数据能说明问题。1.3 为什么码是核心连接点签到码的本质是把现实世界里人和场次的连接关系压缩成一个可以被机器快速识别的字符串。这个字符串背后承载了三层信息身份信息谁用户ID、手机号。业务信息参加什么活动活动ID、场次ID。权限信息是否有效、在哪个时间段有效、是否已经核销。所以你会发现单纯的二维码组件只是最表面的东西真正的难点在于如何设计这个码的编码规则和校验流程。如果码只是一个自增ID那肯定能扫但别人可以枚举你的码一下子把全部有效码扫一遍造成大量误核销。我后面会专门讲如何给签到码加签名和时效这是整个系统的安全地基。2. 技术选型原生小程序 自建后端我这样取舍签到码的业务不算复杂但涉及到动态码、扫码、数据同步技术选型上还是要动点脑筋。这一章我把前端框架、后端方案、二维码生成三个维度的取舍展开说。2.1 前端方案原生 vs uni-app微信小程序前端无非两个大方向原生小程序语言或者跨端框架uni-app / Taro。很多团队选uni-app是为了以后能一套代码多端复用但我自己做签到码类项目时选了原生小程序。理由很简单签到码场景重度依赖微信生态的API比如wx.login、wx.scanCode、wx.getMenuButtonBoundingClientRect原生框架对这些API的兼容和调试是最顺的。跨端框架虽然也能调但遇到基础库版本差异、自定义导航栏高度、canvas渲染这类问题时排查链路更长。如果你团队里之前已经用uni-app开发过小程序那就继续用没必要为了一个签到码重写。只是要特别注意uni-app发行到微信小程序时需在HBuilderX里配置好微信开发者工具的路径和AppID否则会卡在发行阶段。这个步骤网上教程很全但经常有人漏掉AppID导致上传失败。下面简单对比一下维度原生小程序uni-app微信API兼容性最直接封装层可能滞后真机调试效率高需要经过编译多端复用弱强签到码canvas渲染可控部分场景怪异如果你只是想快速跑通一个签到Demo原生小程序是最少折腾的路线。2.2 后端方案轻量接口服务 Redis MySQL签到码的后端并不需要很重的微服务架构一个轻量的接口服务就够。我习惯用Node.js或Java Spring Boot都行关键是三个组件要选好数据库、缓存、登录态签发。数据库用MySQL或者PostgreSQL核心就是三张表用户表、活动表、签到记录表。用户表存微信openid和基本信息活动表存活动配置签到记录表存谁在什么时间扫了哪个码。签到码的核销状态最好冗余在签到记录表里别只靠前端状态。Redis的用处主要有两个一是存签到码的临时状态比如码是否已被核销用SETNX设置一个短时锁防止并发重复核销二是存需要频繁读取的配置比如活动的签到有效期。有些团队图省事全放MySQL并发一高就容易出问题。登录态签到能力可以用JWT签发自定义token也可以直接用微信官方的session_key去维护后者会麻烦一点。标准做法是用wx.login拿到的code在后端换openid和session_key然后自己签发一个token返回给小程序后续请求都带这个token。这个流程我在第3章会详细展开。2.3 二维码生成后端出图还是前端canvas签到码在线上的形态有两种一种是二维码图片一种是条形码。条形码在扫描枪下识别率更高但手机扫码场景下二维码更通用。二维码内容怎么生成有两条路。后端生成用Java的Zxing、Node.js的qrcode库把码的内容直接画成一张图片返给前端。好处是前端渲染稳定坏处是每次动态刷新都要请求图片而且后端要处理图片缓存和流量。前端生成在小程序端用weapp-qrcode这类库把码的内容通过canvas画出来。好处是省一次网络请求动态码可以瞬间刷新坏处是canvas在部分真机上会有渲染兼容问题。我自己做动态码时选择了前端canvas生成。因为签到码每30秒变一次如果每次变化都回源取一张图片对服务端和用户流量都不友好。前端本地画码只需要在后端生成一个带签名的码值字符串前端拿到字符串画出来即可。3. 核心链路实现登录、发码、倒计时刷新这一章是全文的重点。我直接把核心链路的实现思路和代码片段写出来包括微信登录的code换token、签到码签名设计、前端动态码展示。3.1 微信登录code换token的正确姿势微信小程序端要识别用户身份标准流程是小程序端调用wx.login()获取一个临时登录凭证code。把这个code传给后端。后端拿这个code调用微信的code2Session接口换取openid和session_key。后端用openid找到或创建用户签发自己的登录token返回给前端。有同学容易混淆这里的code是微信登录凭证跟签到业务里的签到码code完全是两回事。为了避免混乱我在代码命名里会把后者叫signCode或者ticket。Node.js示例const axios require(axios); async function wxCode2Session(code) { const url https://api.weixin.qq.com/sns/jscode2session; const params { appid: 你的AppID, secret: 你的AppSecret, js_code: code, grant_type: authorization_code }; const { data } await axios.get(url, { params }); if (data.errcode) { throw new Error(data.errmsg); } // data.openid 和 data.session_key return data; }拿到openid后我一般直接签发一个JWT作为业务token后续接口从Authorization头里读取。一个反直觉的坑session_key一定不要返回给前端也不要自己保存到数据库里做业务用途。session_key是和微信加密数据解密相关的签到码根本用不到留在服务端即拿即用即可保存下来反而增加泄露风险。3.2 签到码签名与时效设计动态签到码的核心是别人拿到你的码也不能伪造一个新的。所以码的格式不能是简单的用户ID拼接活动ID而是要加签名和过期时间。我常用的码内容格式是一个JSON字符串然后做Base64编码或直接作为二维码内容{ uid: 123456, aid: 789, exp: 1710000000, sig: 5f4dcc3b5aa765d61d8327deb882cf99 }其中sig是HMAC签名用后端密钥对uid|aid|exp做哈希生成const crypto require(crypto); function generateSignCode(uid, aid, ttl 30 * 1000) { const exp Date.now() ttl; const raw ${uid}|${aid}|${exp}; const sig crypto.createHmac(sha256, SECRET).update(raw).digest(hex); const payload { uid, aid, exp, sig }; // 转成二维码内容可以直接用JSON字符串也可以做短编码 return JSON.stringify(payload); }有人会问为什么不用JWT作为签到码内容JWT当然可以但JWT体积偏大二维码密集度会提高识别率下降。另外签到码有效期通常只有几十秒JWT的过期机制和业务签名足够用但为了扫码识别率我更喜欢自定义一个精简结构。核销的时候后端要做四步校验解析码内容检查exp是否大于当前时间。用同样的密钥重新计算sig对比是否一致。检查该用户活动是否已核销过。如果码内容里带有随机数nonce还要检查这个nonce是否已被使用过防止重放攻击。动态码一般每30秒刷新一次每次刷新时后端重新算一个不同的exp和sig前端拿新值重新画码。这样即使别人截图过一会儿也会失效。3.3 前端动态码展示与定时刷新小程序端拿到签到码原始字符串后用weapp-qrcode画到canvas上。代码大致是这样的import QRCode from ../../utils/weapp-qrcode; Page({ data: { signCode: , remainSeconds: 30 }, timer: null, onShow() { this.loadSignCode(); this.startTimer(); }, onHide() { this.clearTimer(); }, async loadSignCode() { const token wx.getStorageSync(token); const res await request.get(/sign-code, { token }); this.setData({ signCode: res.data.code }); this.drawQRCode(res.data.code); }, drawQRCode(code) { QRCode.toCanvas(this.selectComponent(#qrcodeCanvas), code, { width: 200, height: 200 }); }, startTimer() { let remain 30; this.timer setInterval(() { remain--; this.setData({ remainSeconds: remain }); if (remain 0) { this.loadSignCode(); remain 30; } }, 1000); }, clearTimer() { if (this.timer) { clearInterval(this.timer); this.timer null; } } });这里有个细节倒计时结束前最好提前1到2秒刷新避免用户在扫码时正好碰上码过期。把判断条件从0改成3刷新频率做成每27秒请求一次剩下3秒缓冲。我实际测试下来这样用户体验最顺。还有一点canvas组件的选择器在自定义组件中要特别小心。如果签到码页面不是一个独立Page而是被拆成了Componentthis.selectComponent(#qrcodeCanvas)必须指向一个配置了id和canvas-id的canvas节点不然真机上经常画不出来。4. 管理端核销实战扫码、验签、防并发重复用户端动态码是一方面管理员的核销操作才是现场效率的关键。一个核销动作要同时满足快和准我在这章讲实现方式。4.1 管理员扫码的两种实现方式核销员在微信小程序里扫用户的码有两种实现路径方式一用wx.scanCode扫描用户手机上的二维码。方式二不用扫码直接在同一个程序的管理页面里通过后台数据拿到用户码。很明显方式二不现实因为堆在一起没法区分谁是谁。所以主流程用的是wx.scanCode。它可以直接打开小程序内的扫码界面扫码成功后回调里拿到二维码原始内容。wx.scanCode({ success: (res) { const signCode res.result; this.verifySignCode(signCode); }, fail: (err) { wx.showToast({ title: 扫码失败, icon: none }); } });需要注意wx.scanCode并不要求被扫的码必须是小程序码任何内容格式的二维码都能扫出来。所以用户端用普通二维码图片完全没问题。如果团队内部有自己的硬件扫描枪也可以让扫描枪直接读取到码内容后通过接口传过来。这种方式需要额外的硬件对接但对于高峰人流场景识别率更高我们现场是两者都备着。4.2 核销接口校验逻辑与防重复设计核销接口我设计为POST /api/verify请求体里带signCode和操作员ID。后端校验逻辑如下解析码字符串若解析失败直接返回无效签到码。校验签名sig是否正确防止篡改。校验exp时间是否过期。检查数据库里该用户活动是否已经存在核销记录如果存在返回该用户已签到。通过Redis执行SETNX lockkey设计为sign:verify:{userId}:{activityId}设置过期时间几秒防止并发重复提交。操作数据库插入签到记录并删除Redis lock。Node.js伪代码async function verify(signCode, operatorId) { const payload parseCode(signCode); if (!payload) return { error: 无效码 }; const expectedSig sign(payload.uid, payload.aid, payload.exp); if (payload.sig ! expectedSig) return { error: 签名校验失败 }; if (Date.now() payload.exp) return { error: 二维码已过期 }; const existed await checkSignRecord(payload.uid, payload.aid); if (existed) return { error: 已签到请勿重复操作 }; const lockKey sign:verify:${payload.uid}:${payload.aid}; const locked await redis.set(lockKey, 1, EX, 5, NX); if (!locked) return { error: 正在处理中请稍候 }; try { await insertSignRecord(payload.uid, payload.aid, operatorId); return { success: true }; } finally { await redis.del(lockKey); } }这里最需要注意的是防重复核销。现场人多的时候管理员手速快可能同一个码连续扫了两次或者网络延迟导致前端重试。如果没有Redis锁或数据库唯一索引就可能插入两条重复签到记录。数据库里给(user_id, activity_id)加唯一索引是最底线的保障Redis锁只是性能优化。还有一个容易忽略的边界如果用户是大会员同一个用户报名了两场活动那userId activityId才是唯一维度不能只查userId。活动间的隔离一定不能漏。4.3 核销结果反馈与数据闭环核销成功后管理员端界面要给出明确的反馈。我在项目中采用成功绿勾 声音提示 用户信息标签失败则用红叉 原因文案。这样在嘈杂的现场管理员不用一直盯着屏幕读字。用户端的反馈也要同步。很多人会忽略这一点管理员扫码核销成功后用户手机上的码应该立即变成已核销状态。实现方式有两种轮询用户端定时查询核销状态简单但有延迟。WebSocket/订阅消息实时推送但实现复杂。签到场景通常用轮询就够了。用户端每10秒查一次核销状态状态变为已核销后页面自动跳转到结果页。如果用户一直停留在码页面轮询还能顺便检查二维码是否即将过期。核销完成后数据闭环的最后一步是统计。我在后台做了两张报表一张是核销流水记录每次核销的操作员、时间、用户另一张是活动汇总直接展示应到人数、实到人数、核销率。这个汇总数据的来源一定要用核销记录表聚合不能直接统计用户报名表因为报名后可能有人取消。5. 真实项目里的坑从开发到上线的经验清单前面几章讲的是设计思路和代码逻辑这一章我想把实际开发中踩到的那些坑单独列出来。这些坑不一定都会出现在你项目里但遇到了能省很多排查时间。5.1 自定义导航栏高度适配签到码页面为了UI好看经常需要沉浸式背景这时就要用自定义导航栏。自定义导航栏最大的问题是不同机型顶部安全区高度不一样尤其是刘海屏和灵动岛机型。正确的做法是用wx.getMenuButtonBoundingClientRect()拿到胶囊按钮的位置配合wx.getSystemInfoSync()里的statusBarHeight动态算出导航栏高度。不能写死在设计稿里。我见过不少项目在iPhone上好好的换成安卓直接顶到状态栏上就是没做动态高度。const { statusBarHeight } wx.getSystemInfoSync(); const menuButton wx.getMenuButtonBoundingClientRect(); const navBarHeight (menuButton.top - statusBarHeight) * 2 menuButton.height; this.setData({ statusBarHeight, navBarHeight });5.2 canvas在真机上的渲染问题动态码用canvas画在开发者工具上一切正常一上真机会遇到几种情况二维码画出来是黑的、canvas不刷新、或者canvas层级盖住了别的元素。我踩得最深的一个坑是在自定义组件里使用canvas时canvas-id和通过selectComponent获取的节点必须完全匹配而且canvas组件本身要设置type2d。如果你还在用旧版canvas接口可能会出现canvas绘制正常但扫码时识别不到的情况。建议统一使用新版type2d的canvas接口对后续维护更友好。5.3 定时器与页面生命周期管理动态码页面如果只是简单地在onLoad里启动一个setInterval用户切到后台再回来时定时器可能还在跑但页面已经重新渲染容易出现码已经变了倒计时还是10秒的错乱。我在项目里强制要求在onShow里启动或重置定时器。在onHide和onUnload里清除定时器。页面从后台回前台时第一时间重新请求签到码不要等定时器自然触发。这样还能解决另一个问题动态码在后台期间可能已经过期回到前台后立即刷新避免用户看到已过期的码还拿去扫码。5.4 本地调试、抓包与域名白名单小程序开发过程中本地接口联调是个高频痛点。默认情况下小程序只能请求HTTPS合法的业务域名。开发阶段可以在开发者工具里勾选不校验合法域名但真机预览时这个选项不生效必须把后端接口域名配到小程序后台的服务器域名里或者用内网IP配到开发环境。如果要做接口抓包我一般用Charles或Fiddler这类工具把手机代理指向电脑再装好证书。但注意小程序对HTTPS证书的校验非常严格如果后端是自签名证书抓包时会直接报错。最简单的办法是本地起一个HTTP服务先在开发者工具里调试再部署到测试环境用正式HTTPS域名做真机验证。这个过程可能会遇到一个报错handshake failed due to invalid upgrade header: null这通常是WebSocket连接和代理冲突导致的。如果只是普通HTTP API请求出现这个报错时优先检查代理配置是否把HTTP流量也指向了不支持隧道代理的服务。5.5 时间同步、截图代签等业务边界签到码的时效判断后端一定不要跟前端时间比对而是跟前端传过来的exp字段比对。这个exp是后端在生成签码时自己写的所以即使前端把系统时间改慢后端还是能用绝对时间判断。截图代签是活动方很头疼的问题。电话里跟我说能不能彻底防止我的答案是技术手段可以降低风险但无法100%杜绝。首先用动态码缩短码的有效期截图还没送到朋友手里就过期了其次可以在码中心区域放一个每秒跳动的时间水印管理员扫的时候肉眼扫一眼再激进一点可以结合用户允许定位后核销时校验用户和管理员的距离。这些手段组合起来代签成本会高很多。还有一个细节如果活动分为多天签到码必须在每天重新生成或者码内容里包含日期字段。否则用户用第一天的码在第二天来签到后端会直接放行这就出大事故了。我在设计表结构时把activity_id细化为session_id每场次一个独立ID从根上避免跨场次使用的可能。最后再说一个每次做签到项目都会提醒自己的点签到码不是做一个页面而是做一套授权与校验闭环。码只是入口真正的核心是服务端那套签名、时效、幂等、防重的规则。把这些规则想清楚不管前端用原生还是uni-app后端用什么语言都能很快落地。希望这篇实战记录能帮你少踩几个坑在做微信小程序签到码的时候把力气花在最值得花的地方。
