简介这是一套基于PHP开发的轻量级二维码防重防错管理系统面向中小型活动运营、票务管理、内部考勤或物料追踪等场景的技术人员与开发者解决多日批量生成唯一可追溯二维码、防止重复打印与扫码数据混乱等实际问题。系统包含扫码首页、按日生成带前缀与序号的二维码、批量打印、多维数据统计当日生成量、打印量、扫码次数及灵活配置模块支持1–8位前缀、年月日标识开关、序号位数设定等安装后需先完成基础参数配置方可使用。资源为5.24MB的ZIP压缩包含PHP源码文件、HTML前端页面及配置脚本等核心文件结构清晰无第三方依赖开箱即用。目前已有233人学习下载读者可直接部署运行获得完整可调试的二维码生命周期管理方案、标准化的数据统计逻辑、以及兼顾安全性和易用性的配置体系。1. 一个扫码即失效的二维码真能拦住重复提交——这不是防伪标签是业务入口的“一次锁”上周帮某高校实验室对接一个设备预约系统他们用的是现成的 PHP 后台 微信 H5 页面。问题出在「扫码预约」环节学生扫同一个二维码反复点「确认预约」后端没做任何幂等控制结果一条设备记录被生成了 7 次管理员手动删了 6 条。不是前端加了 disabled 就安全了——F5 刷新、抓包重放、Postman 直接 POST全都能绕过。这个「二维码防重防错系统-PHP」就是为这种场景而生的它不生成静态图而是动态签发带时间戳、唯一 nonce、服务端状态绑定的可扫码 URL每次扫码服务端先查状态、校验签名、原子更新为「已使用」三步缺一不可。它不依赖 Redis 集群或消息队列纯 PHP MySQL 即可跑通适合中小项目快速嵌入表单提交、活动领券、设备授权、工单触发等「一次有效」型交互。如果你正被重复下单、重复报名、重复核销搞到半夜改 SQL 回滚数据这项目就是你今晚该 clone 下来的后悔药。2. 架构与技术选型为什么是 PHP MySQL 而不是 Laravel Redis这个项目不是从零造轮子而是把「防重」这件事拆解成三个可验证、可替换、不耦合的模块码生成器Generator、状态控制器StateManager和扫码处理器Scanner。它刻意避开 Laravel 的中间件链和 Eloquent 的软删除因为真实项目里你很可能要把它塞进一个运行了 8 年的 ThinkPHP 2.1 旧系统或者集成进一套定制化 CMS 的插件目录。所以整个设计锚定两个底线不改现有路由结构、不强依赖框架生命周期。2.1 核心依赖极简清单无 Composer 强依赖项目只显式依赖PHP ≥ 7.4用到了str_contains()和match表达式MySQL 5.7需要INSERT ... ON DUPLICATE KEY UPDATE原子写入GD 扩展生成 PNG 二维码非必须可换为endroid/qr-codeComposer 包提示没有vendor/autoload.php没有composer.json。所有类都放在/lib/下通过require_once手动加载。这是为了让你能直接把/lib/QRCodeManager.php拖进任意 PHP 项目include/目录下改两行数据库配置就能用。2.2 数据库表结构一张表撑起全部状态核心只有 1 张表qr_codes字段精简到不能再少CREATE TABLE qr_codes ( id bigint unsigned NOT NULL AUTO_INCREMENT, code_key varchar(64) NOT NULL COMMENT 业务标识如 order_12345, nonce char(32) NOT NULL COMMENT 唯一随机串md5(microtime().rand()), status tinyint NOT NULL DEFAULT 0 COMMENT 0未使用,1已扫码,2已过期,3强制作废, created_at int NOT NULL DEFAULT 0 COMMENT 时间戳非 datetime, used_at int NULL DEFAULT NULL COMMENT 扫码时间戳, expire_after int NOT NULL DEFAULT 300 COMMENT 过期秒数默认5分钟, PRIMARY KEY (id), UNIQUE KEY uk_code_key_nonce (code_key,nonce), KEY idx_status_created (status,created_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;注意三个关键设计点code_key nonce是联合唯一索引保证同一业务键下绝不会生成两个相同 nonce 的码防重生成status用整型而非字符串避免WHERE status used这种低效查询MySQL 对tinyint索引扫描快一个数量级created_at存时间戳整数省去strtotime()解析开销且方便做WHERE created_at UNIX_TIMESTAMP() - 300这类计算。2.3 请求生命周期从生成 URL 到扫码回调的 5 步链路整个流程不经过任何中间件或事件总线全部由QRCodeManager类内方法串联生成阶段调用generateFor(order_12345, [expire 600])→ 生成唯一nonce→ 插入qr_codes表 → 返回带签名的 URLURL 格式/scan.php?korder_12345nabc123...s9f3d...s是sha256(code_key . nonce . secret_key)扫码访问用户打开该 URLscan.php先校验s签名 → 再查qr_codes中对应code_keynonce记录状态跃迁用INSERT ... ON DUPLICATE KEY UPDATE尝试将status从0更新为1MySQL 返回affected_rows响应决策若affected_rows 1说明抢到了执行业务逻辑如创建订单若为0返回{code:409,msg:已使用}。这个链路里没有「先 SELECT 再 UPDATE」的经典幻读陷阱——靠的是 MySQL 唯一索引 ON DUPLICATE KEY UPDATE的原子性比加SELECT ... FOR UPDATE更轻量也比应用层加锁更可靠。3. 核心模块代码逐行解析QRCodeManager.php的 4 个关键方法/lib/QRCodeManager.php是整个系统的中枢不到 300 行但每行都踩过坑。下面拆解最常被二次开发修改的 4 个方法附真实调试日志和参数说明。3.1generateFor()生成带签名的可扫码 URLpublic function generateFor(string $codeKey, array $options []): array { $nonce md5(microtime(true) . rand(1000, 9999)); $expireAfter $options[expire] ?? 300; // 默认5分钟 $createdAt time(); // 1. 原子插入防止并发生成相同 code_keynonce $sql INSERT INTO qr_codes (code_key, nonce, status, created_at, expire_after) VALUES (?, ?, 0, ?, ?); $stmt $this-pdo-prepare($sql); $result $stmt-execute([$codeKey, $nonce, $createdAt, $expireAfter]); if (!$result) { // 唯一索引冲突时重试极小概率但必须处理 usleep(10000); // 10ms 后重试 return $this-generateFor($codeKey, $options); } // 2. 生成签名防止 URL 被篡改 key/nounce $signature hash_hmac(sha256, $codeKey . | . $nonce, $this-secretKey); // 3. 返回完整 URL 和元数据 $baseUrl $this-baseUrl ?: $_SERVER[REQUEST_SCHEME] . :// . $_SERVER[HTTP_HOST]; $url sprintf(%s/scan.php?k%sn%ss%s, $baseUrl, urlencode($codeKey), urlencode($nonce), urlencode($signature) ); return [ url $url, code_key $codeKey, nonce $nonce, expire_after $expireAfter, created_at $createdAt ]; }逻辑说明第 1 步的INSERT是防重第一道闸。如果两个请求几乎同时调用generateFor(order_12345)MySQL 唯一索引会拒绝第二个插入execute()返回false触发usleep(10000)后递归重试——这是比while(!insert)更优雅的退避策略第 2 步用hash_hmac而非md5($codeKey.$nonce.$secret)因为 HMAC 能防长度扩展攻击即使攻击者知道部分参数也无法伪造签名第 3 步urlencode()不可省略$nonce是md5字符串含和/不编码会导致 URL 解析失败。3.2verifyAndConsume()扫码时的原子状态跃迁public function verifyAndConsume(string $codeKey, string $nonce, string $signature): array { // 1. 签名校验必须放在 DB 查询前防爆破 $expectedSig hash_hmac(sha256, $codeKey . | . $nonce, $this-secretKey); if (!hash_equals($expectedSig, $signature)) { return [success false, code 401, msg 签名无效]; } // 2. 查询并更新一行 SQL 完成「查状态改状态记时间」 $sql INSERT INTO qr_codes (code_key, nonce, status, created_at, expire_after, used_at) VALUES (?, ?, 1, ?, ?, ?) ON DUPLICATE KEY UPDATE status IF(status 0, 1, status), used_at IF(status 0, VALUES(used_at), used_at); $stmt $this-pdo-prepare($sql); $now time(); $result $stmt-execute([ $codeKey, $nonce, $now, 300, $now // expire_after 临时填300实际从原记录读 ]); // 3. 获取当前记录最新状态重要不能只看 execute 结果 $checkSql SELECT status, used_at FROM qr_codes WHERE code_key ? AND nonce ?; $checkStmt $this-pdo-prepare($checkSql); $checkStmt-execute([$codeKey, $nonce]); $row $checkStmt-fetch(PDO::FETCH_ASSOC); if (!$row) { return [success false, code 404, msg 记录不存在]; } if ($row[status] 1) { return [success true, code 200, msg 已成功扫码, used_at $row[used_at]]; } elseif ($row[status] 0) { // 理论上不会走到这里因为 INSERT ... ON DUPLICATE 应已更新 return [success false, code 500, msg 状态更新异常]; } else { return [success false, code 409, msg 状态非法 . $row[status]]; } }参数说明$codeKey和$nonce必须严格来自 URL Query 参数不能从 POST 或 Cookie 读取否则失去「扫码即触发」语义hash_equals()是必须的防止时序攻击比较会因字符串长度不同提前退出暴露 nonce 长度信息第 2 步 SQL 中VALUES(used_at)是关键ON DUPLICATE KEY UPDATE里的VALUES()函数能引用INSERT子句中对应字段的值确保used_at写入的是当前时间而非原记录时间。3.3getQrCodeImage()不依赖第三方库的 PNG 生成public function getQrCodeImage(string $url, int $size 300): string { // 使用 php-qrcode 库的轻量实现已内置在 /lib/qrcode/ require_once __DIR__ . /qrcode/qrlib.php; ob_start(); QRcode::png($url, false, QR_ECLEVEL_L, $size / 30, 0); // L 级纠错足够扫码 $imageData ob_get_contents(); ob_end_clean(); return $imageData; }为什么不用 endroid/qr-codeendroid/qr-code需要ext-gdext-iconv某些老旧服务器iconv编译参数不全QRcode::png()只依赖gd兼容性高$size / 30是经验参数QR_ECLEVEL_L纠错率约 7%300px 图像用模块尺寸 10px300/30既保证手机远距离可扫又避免图像过大拖慢页面。3.4revokeByCodeKey()运营后台的强制作废接口public function revokeByCodeKey(string $codeKey): int { $sql UPDATE qr_codes SET status 3, used_at ? WHERE code_key ? AND status IN (0,1); $stmt $this-pdo-prepare($sql); $result $stmt-execute([time(), $codeKey]); return $stmt-rowCount(); }使用场景用户投诉「我没扫怎么就显示已使用」客服在后台输入order_12345调用此方法将所有关联nonce置为status3强制作废status IN (0,1)条件很重要避免把已过期status2或已作废status3的记录误更新保持状态机清晰。4. 避坑指南上线前必须验证的 4 个血泪现场这套系统看似简单但在真实环境部署时有 4 个点几乎 100% 会翻车。以下全是某开发者在测试环境反复tail -f error.log抓出来的真问题按「现象 → 原因 → 解决」给出可抄作业的答案。4.1 现象生成的二维码扫出来一直是「签名无效」但 URL 里的kns参数肉眼可见正确原因scan.php中$_GET[k]和$_GET[n]未做urldecode()。当$nonce含号如md5(abc)结果浏览器 URL 编码会把当空格处理PHP 自动urldecode()时却没还原导致verifyAndConsume()里拼接的codeKey.|.$nonce和签名原文不一致。解决在scan.php开头强制urldecode()$k urldecode($_GET[k] ?? ); $n urldecode($_GET[n] ?? ); $s urldecode($_GET[s] ?? );4.2 现象高并发压测时generateFor()出现大量重试CPU 占用飙升到 90%原因usleep(10000)重试间隔太短10ms 内两次请求仍大概率撞上唯一索引冲突形成「重试风暴」。解决改用指数退避最大重试 3 次private function generateWithBackoff(string $codeKey, array $options, int $attempt 1): array { if ($attempt 3) throw new Exception(Generate failed after 3 attempts); try { return $this-generateFor($codeKey, $options); } catch (Exception $e) { $delay (int)pow(2, $attempt) * 10000; // 20ms, 40ms, 80ms usleep($delay); return $this-generateWithBackoff($codeKey, $options, $attempt 1); } }4.3 现象MySQL 报错SQLSTATE[HY000]: General error: 1364 Field expire_after doesnt have a default value原因MySQL 严格模式STRICT_TRANS_TABLES开启时INSERT INTO qr_codes (...) VALUES (?, ?, 0, ?)没给expire_after赋值而建表时该字段没设DEFAULT。解决两种方式任选其一方式一推荐修改建表语句给expire_after加DEFAULT 300方式二在generateFor()的INSERTSQL 中显式传入$expireAfter参数如代码所示。4.4 现象扫码后used_at时间戳比created_at小 1 秒原因INSERT ... ON DUPLICATE KEY UPDATE中VALUES(used_at)引用的是INSERT子句里写的?值即$now但INSERT子句里used_at传的是?占位符而ON DUPLICATE里VALUES(used_at)实际取的是INSERT语句中该位置的值——如果INSERT语句没传used_atVALUES(used_at)就是NULL。解决必须在INSERT子句中显式传入used_at值// 错误写法used_at 为空 VALUES (?, ?, 1, ?, ?) // 正确写法used_at 显式传入 VALUES (?, ?, 1, ?, ?, ?) // 最后一个 ? 是 $now5. 二次开发实战如何把「防重二维码」嵌入你的现有系统你不需要推翻重写整个后台。我以最常见的三种场景为例告诉你怎么在 30 分钟内完成集成——所有操作都在你自己的代码里加几行不碰QRCodeManager源码。5.1 场景一给 ThinkPHP 5.1 的订单页加「扫码支付」按钮假设你原有订单页 URL 是/order/detail?id12345现在想在页面底部加一个「扫码确认支付」按钮点击后生成专属二维码弹窗。步骤在控制器OrderController.php的detail()方法里引入管理器并生成 URLuse \QRCodeManager; public function detail($id) { $qrManager new QRCodeManager([ dsn mysql:hostlocalhost;dbnameyour_db, user root, pass 123456, secret_key your_app_secret_here ]); $qrData $qrManager-generateFor(pay_order_ . $id, [expire 600]); $this-assign(qr_url, $qrData[url]); return $this-fetch(); }在模板detail.html里加 JS 生成弹窗button onclickshowQrModal()扫码确认支付/button div idqr-modal styledisplay:none; img src/api/get_qr.php?url{$qr_url} alt扫码支付 p请使用微信扫描二维码/p /div script function showQrModal() { document.getElementById(qr-modal).style.display block; } /script新建/api/get_qr.php调用getQrCodeImage()?php require_once ../lib/QRCodeManager.php; $qr new QRCodeManager([...]); // 配置同上 header(Content-Type: image/png); echo $qr-getQrCodeImage($_GET[url]);注意/api/get_qr.php不能直接输出 HTML必须只输出 PNG 二进制流否则img标签无法加载。5.2 场景二对接微信公众号模板消息把二维码 URL 推送给用户微信模板消息要求跳转链接必须是备案域名下的路径不能直接跳https://xxx.com/scan.php?k...。你需要做一层跳转。改造方案新建/jump.php?php // /jump.php?code_keypay_order_12345nonceabc123... $codeKey $_GET[code_key] ?? ; $nonce $_GET[nonce] ?? ; if (!$codeKey || !$nonce) die(Invalid); // 重定向到真实扫码页带签名 $qr new QRCodeManager([...]); $signature hash_hmac(sha256, $codeKey . | . $nonce, $qr-getSecretKey()); header(Location: /scan.php?k . urlencode($codeKey) . n . urlencode($nonce) . s . urlencode($signature)); exit;在模板消息里填https://yourdomain.com/jump.php?code_keypay_order_12345nonceabc123...用户点击后自动跳转并校验。5.3 场景三审计需求——导出所有已扫码记录到 Excel项目没提供导出功能但qr_codes表结构清晰你只需写一个简单的 CLI 脚本。新建/bin/export_used.php?php require_once __DIR__ . /../lib/QRCodeManager.php; $qr new QRCodeManager([...]); $stmt $qr-getPdo()-prepare( SELECT code_key, nonce, FROM_UNIXTIME(created_at) as created, FROM_UNIXTIME(used_at) as used FROM qr_codes WHERE status 1 ORDER BY used_at DESC LIMIT 1000 ); $stmt-execute(); $rows $stmt-fetchAll(PDO::FETCH_ASSOC); // 输出 CSVExcel 可直接打开 header(Content-Type: text/csv); header(Content-Disposition: attachment; filenameused_qrcodes.csv); $fp fopen(php://output, w); fputcsv($fp, [业务键, Nonce, 生成时间, 扫码时间]); foreach ($rows as $row) { fputcsv($fp, [$row[code_key], $row[nonce], $row[created], $row[used]]); } fclose($fp);运行命令php /bin/export_used.php used.csv从那以后我每次给客户加「扫码即生效」功能都会先跑一遍phpunit --filter testConcurrentGenerate项目自带的并发生成测试再用ab -n 1000 -c 100 https://yoursite.com/scan.php?ktestnxxxsyyy压测扫码接口确认409 Conflict响应占比低于 0.1%。不是信不过代码是信不过自己没看清ON DUPLICATE KEY UPDATE里VALUES()的作用域。希望帮到你。本文还有配套的精品资源点击获取
