扫码登录最小实现：Spring Boot + Redis 状态机与用户价值埋点

“不知道用户有什么用就扫走吧”这句话放在扫码登录功能里往往意味着产品还没定义清楚用户价值二维码就已经上线了。用户扫码之后系统只是拿到一个临时身份标识却不知道他是谁、从哪个页面来、扫码后做了什么也没有办法判断这个入口是否值得保留。扫码登录的技术难点其实不在生成二维码而在于二维码状态管理、用户身份关联、登录态下发以及扫码事件的数据归因。下面用一个基于 Spring Boot Redis 的扫码登录最小实现来拆解扫码链路、状态机、接口设计、用户价值埋点和常见排错方法适合后端开发、全栈开发以及需要和业务方确认扫码场景的产品技术同学。学完可以跑通扫码登录闭环并回答“这个扫码入口对系统到底有什么用”。1. 先定义用户价值再写扫码接口1.1 扫码不等于获取用户先区分三种身份很多业务方把“扫码”等同于“获取用户”这是最容易被带偏的地方。用户扫一下二维码系统其实只拿到一次访问行为离“可运营的用户”还差很远。技术上至少要把三类标识分开看。标识典型来源生命周期用途匿名设备标识 deviceIdWeb 端 localStorage、App 端设备ID长期存在但可以清空标记“谁在扫码”不一定是登录用户临时票据 qrCodeId服务端创建二维码时生成通常几十秒到几分钟关联一次扫码流程避免直接用业务 ID 暴露在二维码中用户身份 user_id / token登录、绑定、注册成功后获得跟随账号和会话判断这个用户是否有权限、是否可运营、能否跟踪行为如果只记录 qrCodeId不关联 deviceId也不关联 user_id那么扫码之后的数据就是孤立的。用户价值无从谈起。如果直接把 user_id 放在二维码 URL 里风险又太高别人拿到码就能冒充用户。所以设计扫码接口时第一步不是写 Controller而是把所有身份标识定义清楚哪些是服务端生成的、哪些是用户授权后获得的、哪些只做匿名统计用。1.2 扫码后至少要能回答四个问题一个扫码入口上线后到底有没有用可以从四个问题判断who谁扫的。扫码时是匿名设备还是已登录用户。when什么时候扫的二维码生成到扫码之间隔了多久。where用户从哪个页面、哪个渠道扫的。what扫码后完成了什么动作是登录、绑定、注册还是只打开了页面但没有后续。围绕这四个问题扫码事件表至少需要包含下面这些字段。字段含义是否必填qr_code_id二维码唯一编号是scene扫码场景如 login、bind、register是device_id扫码设备标识推荐user_id确认后的用户 ID确认后写入status本次扫码最终状态是referer_url来源页面推荐page_url用户停留页面推荐created_at扫码事件发生时间是如果一张表能回答上面四个问题这个扫码入口才不算“扫码后把人扫走了”。否则后续做分析时只能看到一堆次数不知道谁带来的、带来了什么。1.3 场景不同扫码后的用户价值定义不同扫码登录并不是唯一的扫码场景。扫码点餐、扫码绑定设备、扫码加入企业通讯录、扫码留资每种场景对“用户有什么用”的定义都不一样。场景扫码后核心动作用户是谁沉淀价值成功指标登录确认授权进入系统已注册用户登录态和访问行为登录成功率、次日回访注册填写手机号或授权手机号创建账号新访客新增账号和后续行为注册转化率绑定设备将设备与账号绑定已有账号设备与账号的关联关系绑定成功率扫码点餐打开菜单、下单本地用户或游客点餐记录、偏好菜品下单转化率企微/钉钉扫码确认身份并登录后台组织成员成员身份和组织关系认证成功率也就是说在写任何扫码接口前要先和业务方确认扫码之后用户完成什么动作这个动作产生的数据存到哪里。如果业务方只回答“先让用户扫一下”那这个需求大概率还要再评审。2. 扫码登录的完整链路二维码状态机是核心2.1 标准流程Web 首页、手机端和服务端的协作扫码登录的经典流程是一条多端协作链路。Web 端向服务端请求创建二维码。服务端生成 qrCodeId保存二维码状态返回二维码内容。Web 端把二维码内容渲染成图片同时开始轮询状态。手机端扫描二维码向服务端上报扫码。手机端确认授权服务端把状态改为已确认并生成登录态。Web 端轮询到已确认状态拿到登录态后跳转进入系统。这里的核心不是“扫码”动作本身而是状态机。二维码从创建到使用会经历未扫、已扫、已确认、过期、取消等状态。如果状态不统一就会出现“手机已经确认但网页一直等待”这类经典问题。2.2 二维码状态定义与流转建议使用以下状态集合。状态含义触发方式后续可流转到CREATED二维码已创建等待扫码Web 创建二维码SCANNED、EXPIREDSCANNED已扫码等待确认手机端上报扫码CONFIRMED、CANCELED、EXPIREDCONFIRMED用户已确认授权手机端确认接口终态CANCELED用户取消授权手机端取消接口终态EXPIRED二维码过期定时过期或读取时判断终态状态流转要遵循单向原则不能允许已确认的二维码再变回已扫。否则会产生重复登录和令牌覆盖问题。实现时可以在更新状态的方法里做条件更新例如只有当前状态是 SCANNED 时才允许更新为 CONFIRMED。2.3 用轮询而不是 WebSocket是更稳的起步方案Web 端获取扫码结果常见方案有轮询、WebSocket、SSE。最小实现建议先做轮询原因是代码逻辑简单前端只需定时请求一个接口。天然兼容浏览器限制不需要额外维护长连接。大多数扫码登录场景对实时性要求不高2 到 3 秒轮询一次已经足够。WebSocket 和 SSE 适合需要服务端主动推送的场景但会引入连接管理、心跳、断线重连等问题。扫码登录在初期完全可以用轮询跑通等用户量上来后再根据监控数据替换。3. 环境准备与项目骨架3.1 技术选型与依赖示例使用 Java 17、Spring Boot 3.x、Redis 作为二维码状态存储。之所以选 Redis是因为二维码状态天然适合使用带过期时间的 Key-Value 存储TTL 可以直接控制二维码有效期比存数据库再写定时任务更方便。组件版本示例作用Java17运行环境Spring Boot3.2.xWeb 服务和依赖注入Redis6.x / 7.x二维码状态和登录态存储spring-boot-starter-web与 Boot 版本一致提供 REST 接口spring-boot-starter-data-redis与 Boot 版本一致操作 Redislombok可选减少样板代码Maven 依赖如下实际项目按自己的版本号调整。dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId scopeprovided/scope /dependency如果不想用 Lombok可以把 getter setter 写全不影响流程。3.2 项目目录结构一个最小扫码登录服务的包结构可以这样组织。src/main/java/com/example/qrlogin/ ├── QrLoginApplication.java ├── controller/ │ └── QrCodeController.java ├── service/ │ └── QrCodeService.java ├── model/ │ ├── QrCodeResponse.java │ ├── QrStatusResponse.java │ └── QrScanEvent.java └── config/ └── RedisConfig.java目录结构不需要复杂核心是把 Controller、Service、模型分开。扫码事件存储和登录态生成可以在 Service 中按方法拆分。3.3 配置文件在application.yml中配置 Redis 连接和自定义参数。server: port: 8080 spring: data: redis: host: 127.0.0.1 port: 6379 timeout: 3000ms app: qr: expire-seconds: 120 redis-prefix: qr:code:expire-seconds控制二维码有效期常见设置为 60 到 120 秒。太短用户来不及扫码太长会积压过多无效二维码和潜在过期重放问题。生产环境建议放到配置中心不要硬编码。4. 核心代码二维码生成、状态流转与登录态4.1 二维码内容设计不要在二维码内容里直接放 user_id 或敏感业务参数。二维码内容应该是类似这样的地址https://api.example.com/scan?qrCodeId6f8a2c9e1b4d4a6fscenelogin其中qrCodeId由服务端随机生成用于查询二维码状态scene用于标记业务场景例如 login、bind、register。qrCodeId必须随机不能使用递增 ID避免被遍历猜测。示例中使用简化随机字符串生产环境建议使用 NanoID 或加密安全随机数。4.2 创建二维码接口创建二维码时服务端把状态写入 RedisKey 为qr:code:{qrCodeId}Value 为 Hash包含状态、场景、创建时间等字段同时设置 TTL。Service public class QrCodeService { private static final String QR_PREFIX qr:code:; private final StringRedisTemplate redisTemplate; public QrCodeService(StringRedisTemplate redisTemplate) { this.redisTemplate redisTemplate; } public QrCodeResponse createQrCode(String scene) { String qrCodeId randomQrCodeId(); String key QR_PREFIX qrCodeId; MapString, String map new HashMap(); map.put(status, CREATED); map.put(scene, scene); map.put(deviceId, ); map.put(userId, ); map.put(createdAt, String.valueOf(System.currentTimeMillis())); redisTemplate.opsForHash().putAll(key, map); redisTemplate.expire(key, Duration.ofSeconds(120)); String qrContent https://api.example.com/scan?qrCodeId qrCodeId scene scene; QrCodeResponse response new QrCodeResponse(); response.setQrCodeId(qrCodeId); response.setQrContent(qrContent); response.setExpiresIn(120); return response; } private String randomQrCodeId() { String uuid UUID.randomUUID().toString().replace(-, ); return uuid.substring(0, 16); } }这里要注意几点Hash 的putAll是批量写入字段之后单独修改某个字段时不会覆盖其他字段。必须设置 TTL。不设置 TTL 会让过期二维码一直占用 Redis 内存还可能出现很久以前的二维码在查询时被认为是有效状态。二维码内容中的域名和参数要和前端实际渲染逻辑一致。如果前后端分离二维码图片由前端生成服务端只返回内容。4.3 扫码与确认接口手机端扫码后调用扫描接口把二维码状态从CREATED改为SCANNED并记录扫码设备。状态流转要加判断不能直接覆盖。public QrStatusResponse scan(String qrCodeId, String deviceId) { String key QR_PREFIX qrCodeId; if (!redisTemplate.hasKey(key)) { throw new RuntimeException(二维码不存在或已过期); } String status (String) redisTemplate.opsForHash().get(key, status); if (CREATED.equals(status)) { redisTemplate.opsForHash().put(key, status, SCANNED); redisTemplate.opsForHash().put(key, deviceId, deviceId); } else if (SCANNED.equals(status)) { String currentDevice (String) redisTemplate.opsForHash().get(key, deviceId); if (!deviceId.equals(currentDevice)) { throw new RuntimeException(二维码已在其他设备扫码请刷新后重试); } } else { throw new RuntimeException(二维码状态已更新不能重复扫码); } return buildStatusResponse(qrCodeId); }确认接口在扫码之后执行。用户需要先完成登录或者服务端在确认接口中完成新用户创建。确认成功后将状态改为CONFIRMED并生成登录态写入 Redis。public QrStatusResponse confirm(String qrCodeId, String userId) { String key QR_PREFIX qrCodeId; if (!redisTemplate.hasKey(key)) { throw new RuntimeException(二维码不存在或已过期); } String status (String) redisTemplate.opsForHash().get(key, status); if (!SCANNED.equals(status)) { throw new RuntimeException(当前状态不允许确认请重新扫码); } redisTemplate.opsForHash().put(key, status, CONFIRMED); redisTemplate.opsForHash().put(key, userId, userId); String token UUID.randomUUID().toString().replace(-, ); String tokenKey login:token: token; redisTemplate.opsForValue().set(tokenKey, userId, Duration.ofHours(24)); QrStatusResponse response buildStatusResponse(qrCodeId); response.setToken(token); return response; }确认接口本身可以返回 token但更安全的做法是只让确认结果在服务端保存Web 端通过轮询接口统一获取。实际项目可以在确认接口返回成功后调用一个指定轮询接口避免 token 在多个地方传递。4.4 轮询获取登录态Web 端每隔 2 秒左右请求轮询接口。轮询接口只读取状态不修改状态。public QrStatusResponse poll(String qrCodeId) { return buildStatusResponse(qrCodeId); } private QrStatusResponse buildStatusResponse(String qrCodeId) { String key QR_PREFIX qrCodeId; QrStatusResponse response new QrStatusResponse(); response.setQrCodeId(qrCodeId); if (!redisTemplate.hasKey(key)) { response.setStatus(EXPIRED); return response; } MapObject, Object entries redisTemplate.opsForHash().entries(key); response.setStatus(String.valueOf(entries.getOrDefault(status, UNKNOWN))); response.setScene(String.valueOf(entries.getOrDefault(scene, ))); response.setUserId(String.valueOf(entries.getOrDefault(userId, ))); if (CONFIRMED.equals(response.getStatus())) { String token fakeTokenByUserId(response.getUserId()); response.setToken(token); } return response; }fakeTokenByUserId在示例中可以理解为查询确认时保存的 token。为了避免查不到更稳的方式是在确认时把 token 也写入同一个 Hash或者用专门字段保存 token然后在轮询接口中直接返回。生产环境需要给轮询接口加频率限制。建议前端轮询间隔不小于 1 秒服务端按 IP 或 qrCodeId 做限流防止被高频请求打满。4.5 登录态生成与校验登录态是否要用 JWT取决于项目规模。用随机 token服务端可控注销容易适合内部系统和需要主动踢人的场景。用 JWT无状态适合分布式网关统一校验但注销和过期处理更复杂。示例中采用的是随机 token 方案token 有效期 24 小时实际项目根据业务调整。登录校验时每次请求从请求头取出 token查询 Redis 是否存在存在则得到 userId。public String getUserIdByToken(String token) { String key login:token: token; return redisTemplate.opsForValue().get(key); }所有需要登录的接口都要通过一个拦截器或过滤器校验 token不能只在登录接口里校验。5. 用户价值不是口号要落到事件表和统计 SQL5.1 在扫码链路中透传业务场景参数要回答“用户有什么用”前提是知道用户从哪里来、在哪个场景扫码。创建二维码时scene是必传参数。前端访问二维码页面时还要把referer_url、page_url、渠道参数一起传给服务端。PostMapping(/code) public QrCodeResponse createCode(RequestParam String scene, RequestParam(required false) String refererUrl, RequestParam(required false) String pageUrl) { return qrCodeService.createQrCode(scene); }这里的scene是业务的核心归因维度。写死login也可以但不够。建议 follow 一套规范qr_login电脑端扫码登录。qr_bind账号绑定。qr_register扫码后注册。qr_member会员落地页扫码。场景名统一由服务端维护前端不要随意传。5.2 异步记录扫码事件避免阻塞登录扫码事件是低频数据但会产生副作用。最稳妥的方式是发送到消息队列异步消费。最小实现可以用 SpringAsync或一个简单的线程池把事件写入 MySQL 或日志文件。扫码事件表结构如下CREATE TABLE qr_scan_event ( id BIGINT AUTO_INCREMENT PRIMARY KEY, scene VARCHAR(50) NOT NULL, qr_code_id VARCHAR(64) NOT NULL, device_id VARCHAR(64) DEFAULT , user_id VARCHAR(64) DEFAULT , status VARCHAR(20) NOT NULL, referer_url VARCHAR(255) DEFAULT , page_url VARCHAR(255) DEFAULT , created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP );记录的事件不仅要覆盖扫码成功也要记录二维码过期、扫码后未确认、重复扫码等状态。只有完整记录才能计算真正的转化漏斗。INSERT INTO qr_scan_event (scene, qr_code_id, device_id, user_id, status, referer_url, page_url) VALUES (?, ?, ?, ?, ?, ?, ?);异步写入的核心原因是扫码流程对实时性敏感不能因为事件表写入慢导致用户确认登录被阻塞。5.3 用 SQL 回答“用户有什么用”数据落库之后可以统计不同场景的扫码转化率。SELECT scene, COUNT(*) AS scan_count, SUM(CASE WHEN status SCANNED THEN 1 ELSE 0 END) AS scanned_count, SUM(CASE WHEN status CONFIRMED THEN 1 ELSE 0 END) AS confirmed_count, SUM(CASE WHEN user_id ! THEN 1 ELSE 0 END) AS bound_user_count FROM qr_scan_event GROUP BY scene ORDER BY scan_count DESC;这个 SQL 能直接看出每个场景下有多少人扫了码多少人完成确认多少人关联到了已有账号。如果某个场景的confirmed_count接近于 0说明用户扫完就走当前入口可能只是增加了一次无意义访问。更进一步可以围绕user_id关联用户行为表分析扫码登录用户之后是否产生了订单、收藏、浏览等业务动作。到这一步才算是真正回答了标题里的问题。6. 运行验证从 curl 到 Redis 状态检查6.1 启动服务与准备测试环境学习环境启动前确认已安装 Redis 并能在 6379 端口访问。redis-cli ping命令返回PONG说明 Redis 可用。然后启动 Spring Boot 服务。mvn spring-boot:run如果使用 Spring Boot 3建议先确认 Java 17 已安装。6.2 用 curl 走完扫码登录流程第一步创建二维码。curl -X POST http://localhost:8080/api/qr/code?sceneqr_loginrefererUrlhttps%3A%2F%2Fexample.com%2Flogin响应示例{ qrCodeId: 6f8a2c9e1b4d4a6f, qrContent: https://api.example.com/scan?qrCodeId6f8a2c9e1b4d4a6fsceneqr_login, expiresIn: 120 }第二步模拟手机扫码。curl -X POST http://localhost:8080/api/qr/scan?qrCodeId6f8a2c9e1b4d4a6fdeviceIdtest-device-01响应中status应为SCANNED。第三步模拟用户确认授权。curl -X POST http://localhost:8080/api/qr/confirm?qrCodeId6f8a2c9e1b4d4a6fuserIdu_10001响应中status应为CONFIRMED同时返回 token。第四步网页轮询获取登录态。curl -X GET http://localhost:8080/api/qr/poll?qrCodeId6f8a2c9e1b4d4a6f响应中能看到status为CONFIRMED并且带出 token。6.3 用 Redis 命令检查状态流转执行过程里可以随时查看 Redis 中的二维码状态。redis-cli keys qr:code:*对返回的 key 执行redis-cli hgetall qr:code:6f8a2c9e1b4d4a6f创建后应看到status: CREATED扫码后应看到status: SCANNED确认后应看到status: CONFIRMED和userId: u_10001。再查看登录态redis-cli keys login:token:* redis-cli get login:token:xxxxxxxx如果看到userId说明登录态已经写入 Redis。6.4 学习环境与生产环境的验证差异本地环境能跑通只是第一步。生产环境至少还需要以下检查检查项本地环境生产环境Redis 连接单机直连集群或哨兵需要连接池、超时设置二维码内容域名localhost必须使用 HTTPS 域名二维码有效期可以放宽到 120 秒根据业务确认通常 60 到 120 秒日志控制台输出集中日志平台记录扫码和确认日志监控无扫码成功数、失败数、状态异常数指标限流无轮询和扫码接口按 IP、用户限流不要用本地 Redis 的配置直接上生产。连接超时、内存淘汰策略、Key 清理策略都要单独评估。7. 常见问题排查从现象倒推原因问题现象常见原因检查方式处理建议网页一直显示等待扫码扫码接口没有把状态改为 SCANNED或前端没有轮询到确认结果查看 Redis 中二维码 Hash看 status 字段查看接口日志检查 scan 和 confirm 接口的状态机判断确保状态更新成功二维码提示已过期Redis Key 不存在或 TTL 过短redis-cli ttl qr:code:{id}查看剩余时间调整app.qr.expire-seconds创建二维码时确认设置了 expire用户确认后网页没有跳转token 没有在轮询接口中返回或前端只处理了旧状态调用 poll 接口看是否返回 token前后端确认状态枚举一致CONFIRMED 状态必须返回 token同一个二维码被多台设备扫scan 接口或前端未做设备限制查看 Hash 中 deviceId 是否被覆盖在 scan 接口中判断 deviceId已被扫码后提示其他设备二维码无法创建Redis 不可用或 Maxmemory 策略触发启动日志、redis-cli ping检查 Redis 连接配置适当扩容或清理无用 Key扫码统计中没有数据scene 未透传或事件表未记录扫码动作查看事件表数据确认创建二维码时是否传了 scene创建接口中把 scene 和来源参数统一透传到事件表排查扫码登录问题建议按以下顺序推进先查 Redis 中二维码是否存在、状态是什么。再查接口日志确认 scan、confirm、poll 三个接口是否都被调用。再查 token 是否正确写入 Redis。最后查前端是否按状态枚举处理响应。大多数问题都出在状态更新和前端状态判断不一致而不是二维码生成本身。8. 最佳实践别让用户成为扫走的数据8.1 上线前的用户价值检查清单在开发完扫码登录后先用这张清单做一次自检。是否区分了匿名设备标识、临时票据、用户身份扫码入口是否传入 scene并且 scene 有统一枚举扫码后是否能记录来源页面和当前页面是否记录了扫码、确认、取消、过期等事件状态在用户确认授权前是否明确告知要获取哪些信息二维码失效后是否清理了 Redis Key登录态是否设置了有效期并支持注销轮询和扫码接口是否有限流如果清单里有一项是“没有”不要急着上线。缺数据意味着后续无法回答“用户有什么用”。8.2 安全和合规检查扫码登录涉及用户授权和登录态安全设计必须前置。二维码内容不要携带 user_id、手机号等敏感信息只放随机票据。扫码确认接口要校验当前状态不能允许 CREATED 状态直接确认。登录态 token 要设置有效期服务端需要支持注销。所有扫码相关接口必须有异常处理和日志失败原因要可追溯。涉及收集用户信息时要遵守最小必要原则并给用户授权选择。学习环境可以简化但生产环境不能省。扫码授权只有得到用户明确同意才能进行后续数据关联。8.3 从扫码登录到用户运营的最小闭环扫码登录跑通后可以继续把闭环补完整。新用户扫码后先进入注册或授权页补充手机号后创建账号。老用户扫码后直接确认登录并可以下发当前会话。扫码绑定业务场景时要把qr_bind和qr_login分开统计。登录成功后把 user_id 写入后续业务请求上下文方便记录行为。只有形成了“扫码 - 识别 - 授权 - 登录 - 业务行为”的完整链路扫码入口才能从工具变成用户运营的一部分。8.4 可以继续扩展的方向基础扫码登录完成后还可以按需要扩展接入 OAuth2 授权码模式让第三方系统通过扫码获得授权。在二维码中增加签名参数防止二维码内容被篡改。使用 WebSocket 或 SSE 替代轮询提升扫码结果推送实时性。增加二维码渠道参数统计不同活动页和广告页的扫码效果。将扫码事件接入消息队列统一处理后进行实时转化率分析。扩展时不要一次性全上优先补齐数据埋点和状态监控。等到数据能说明问题再决定是否增加实时推送和更复杂的授权方案。回到标题那句话如果不知道用户有什么用就急着上二维码用户扫码带来的只是一次无归属的访问。反过来把who、when、where、what四类数据在扫码链路里完整落下来扫码入口才真正有价值。开发扫码登录先设计状态机和数据归因再写二维码生成和登录态顺序不能反。