概述
后台管理端走的是「账号 + 密码」登录,没有手机短信那道天然防线,所以登录前必须先过一道图形验证码。这里拆解 mf-admin 里获取图片验证码这一个接口的完整实现:Hutool 生成图片、uuid 关联、Redis 存储、图片流返回,以及实读工程时发现的一个坑,验证码存进 Redis 后没有设置过期时间。
纲要
- 业务背景
- B 端(管理后台)账号密码登录为什么必须加图形验证码
- 图片验证码 vs 短信验证码的对比
- 接口设计
GET /system/users/verification:入参 uuid,响应图片流- 核心设计:uuid 关联机制
- 前端生成 uuid → 后端以此为 key 存验证码 → 登录时带回 uuid 比对
- 为什么不用 sessionId
- 代码实现(实读 mf-admin 工程)
- Hutool
CaptchaUtil.createLineCaptcha(299, 97) captcha.getCode()存 Redis(CAP_CODE_+uuid,未设 TTL)captcha.write(response.getOutputStream())输出图片- 完整时序(Mermaid)
- 已知坑:验证码永不过期 + 修复方案
- 异常与边界、可复现验证、常见误解澄清
为什么 B 端登录必须加图片验证码
交友项目的 C 端(手机 App)登录靠手机号 + 短信验证码,运营商通道本身有频控,同一号码短时间发不了太多次,刷接口的成本天然偏高。B 端管理后台不一样:登录方式是用户名 + 密码,接口是公开的 HTTP 入口,如果没有验证码,攻击者可以写一个脚本对着登录接口无限循环尝试密码,这就是暴力破解。
图片验证码的作用是在登录流程前插一道「人机识别」:机器要先把图片里的扭曲文字识别出来才能提交登录请求,识别本身有失败率,配合「验证码错误直接拒绝」的逻辑,暴力破解的成本被大幅抬高。
顺带把图形验证码和短信验证码放在一起对比,两者在项目里各有分工:
| 维度 | 图片验证码 | 短信验证码 |
|---|---|---|
| 使用端 | B 端管理后台 | C 端手机 App |
| 防护目标 | 防机器暴力破解密码 | 防恶意注册、确认手机号归属 |
| 成本 | 几乎为零,本地生成图片 | 每条短信都要向运营商付费 |
| 时效 | 本项目未设过期(见后文坑) | 一般 1~5 分钟 |
| 防刷手段 | 识别难度 + 频率限制 | 运营商频控 + 发送次数限制 |
| 交互 | 用户看图输入,识别错误需刷新 | 用户等短信,有到达延迟 |
一句话概括:C 端手机号自带短信频控这层保护,B 端没有,所以 B 端必须自己补一道图形验证码,而且它免费。
接口设计
接口定义(YAPI 文档:管理后台项目):
| 项目 | 内容 |
|---|---|
| 请求地址 | /system/users/verification |
| 请求方式 | GET |
| 请求参数 | uuid(String,前端生成,query 参数) |
| 响应 | 图片流(JPEG 二进制),无 JSON 包装 |
| 网关路由 | http://网关:8888/admin/system/users/verification(/admin/** 路由到 mf-admin,StripPrefix=1) |
| 网关白名单 | 该接口在 gateway.excludedUrls 中,不需要 token |
响应不是 JSON,而是直接把验证码图片的二进制内容写进响应体,浏览器把它当作图片渲染。实读工程时确认 verification 方法返回值是 void,图片通过 HttpServletResponse 的输出流写出,方法上直接 throws IOException。
+----------------------------------------------------------+
| 浏览器(管理后台登录页) |
| +----------------------------------------------------+ |
| | 用户名: [________] 密码: [________] | |
| | 验证码: [____] [验证码图片] [看不清?换一张] | |
| | [登录] | |
| +----------------------------------------------------+ |
+----------------------------------------------------------+
| ^
| GET /system/users/verification | 图片流渲染到 <img>
| ?uuid=xxxx |
v |
+----------------------------------------------------------+
| 网关 :8888 /admin/** -> mf-admin (StripPrefix=1) |
+----------------------------------------------------------+
|
v
+----------------------------------------------------------+
| mf-admin :18083 |
| SystemController.verification(uuid, response) |
| 1. LineCaptcha 生成图片 + 文本 |
| 2. Redis: SET CAP_CODE_{uuid} = code |
| 3. captcha.write(response.getOutputStream()) |
+----------------------------------------------------------+
要点:
uuid由前端生成并拼在请求上,同一 uuid 刷新验证码时覆盖旧值- 图片以
<img>标签展示,「看不清换一张」就是换个新 uuid 重新请求 - 该接口在网关
excludedUrls白名单里,登录前无 token 也能访问
核心设计:uuid 关联机制
图片验证码有个天然难题:HTTP 是无状态的,服务端生成验证码之后,下一次登录请求怎么知道用户输的应该和哪张图对应?交友项目的答案是用一个 uuid 串起「取验证码」和「登录」两次请求,完整链路是:
- 前端(登录页)生成一个 uuid,拼在验证码接口的请求参数上
- 后端生成验证码文本,以
CAP_CODE_ + uuid为 key 存入 Redis - 前端展示图片,登录时把
username / password / verificationCode / uuid一起提交 - 后端用同一个 uuid 拼 key 去 Redis 取值比对,验证通过后
delete删除
用 Mermaid 把这条链路画出来:
为什么用 uuid 而不是 sessionId
用会话也能关联验证码,把验证码放进 HttpSession,登录时从 session 里取。交友项目没有这么做,原因和它的架构有关:
- 前后端分离:管理后台前端是独立部署的 Vue 工程,后端只提供接口。如果依赖 session,就得保证浏览器每次都带 cookie,跨域场景(网关 8888 与前端不同源)下 cookie 的处理是额外负担。
- 分布式部署:工程接入了 Nacos,
mf-admin天然可能多实例。session 存在单台机器内存里,请求被负载均衡到另一台就取不到了,除非引入 session 复制或黏性会话。Redis 本来就是共享存储,验证码放 Redis,任何实例都能取到。 - 无状态演进:这套系统登录态用 JWT,本身就是无状态设计,认证环节再去依赖 session 反而破坏一致性。
uuid 方案把关联信息完全外置到 Redis,服务端不需要记住「谁取过验证码」,只认 key。这是前后端分离 + 分布式环境下最通用的做法。
一次性使用与重试语义
实读 AdminService.login() 确认的细节:
- 验证正确 → 立即删除:
redisTemplate.delete(key)紧跟在比对通过之后,验证码用后即焚,一张图只能登录一次,防止重放。 - 验证失败 → 不删除:比对失败直接抛
BusinessException("验证码错误"),Redis 里的 key 还在,用户可以直接再输一次。产品语义是「验证码错可以原地重试,不要逼用户刷新图片」。 - 一个隐藏语义:删除发生在密码校验之前,也就是说验证码对、密码错,这个验证码同样被消费掉了,下次登录要刷新图片。这个顺序是实读工程时确认的实况,讲义代码同款逻辑。
代码实现
工程位置
mf
├── mf-admin # 管理后台服务 (端口 18083)
│ ├── pom.xml # 引入 hutool-all
│ └── src/main/java/com/mf/admin
│ ├── AdminServerApplication.java
│ ├── controller
│ │ └── SystemController.java # 验证码接口在这里
│ ├── service
│ │ └── AdminService.java # 登录时取 Redis 比对验证码
│ ├── mapper/AdminMapper.java
│ ├── interceptor/ # TokenInterceptor / AdminHolder
│ └── exception/ # BusinessException / ExceptionAdvice
├── mf-commons
│ └── src/main/java/com/mf/commons/utils
│ └── Constants.java # CAP_CODE_ 常量
└── mf-gateway # 网关 (端口 8888)
值得说明:团队协作里容易想当然地把「验证码生成」放进 Service 层,实读工程发现这个项目的实现就在 SystemController 里,三行逻辑一步到位,ManagerService 里并没有验证码相关方法。逻辑确实短,放 Controller 无伤大雅;如果后面要统一验证码风格(数字、中文、算术题),再下沉到 Service 也不迟。
依赖
hutool-all 已在 mf-admin/pom.xml 中引入:
<dependency>
<groupId>cn.hutool</groupId>
<artifactId>hutool-all</artifactId>
</dependency>
版本由父工程统一管理。Hutool 的 cn.hutool.captcha 包提供了几种验证码实现:LineCaptcha(线段干扰)、CircleCaptcha(圆圈干扰)、ShearCaptcha(扭曲干扰),本项目用的是最经典的 LineCaptcha。
Redis key 常量
package com.mf.commons.utils;
public class Constants {
// 管理后台验证码在 Redis 中的 key 前缀
public static final String CAP_CODE = "CAP_CODE_";
// ...其余常量
}
统一前缀的好处:redis-cli 里 keys CAP_CODE_* 一眼能找出所有验证码,排查问题方便;也避免和手机验证码等其他 key 冲突。
SystemController.verification
实读 mf-admin 的 SystemController,接口如下:
package com.mf.admin.controller;
import cn.hutool.captcha.CaptchaUtil;
import cn.hutool.captcha.LineCaptcha;
import com.mf.admin.service.AdminService;
import com.mf.commons.utils.Constants;
import com.mf.model.vo.AdminVo;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.Map;
@RestController
@RequestMapping("/system/users")
public class SystemController {
@Autowired
private AdminService adminService;
@Autowired
private RedisTemplate<String,String> redisTemplate;
//获取验证码图片
@GetMapping("/verification")
public void verification(String uuid, HttpServletResponse response) throws IOException {
//1、生成验证码对象(图片 + 验证码文本)
LineCaptcha captcha = CaptchaUtil.createLineCaptcha(299, 97);
//2、验证码文本存入 Redis,key = CAP_CODE_ + uuid
String code = captcha.getCode();
redisTemplate.opsForValue().set(Constants.CAP_CODE + uuid, code);
//3、将验证码图片写入响应输出流
captcha.write(response.getOutputStream());
}
// ... login / profile 略
}
逐段拆解:
第一步:生成验证码对象。 CaptchaUtil.createLineCaptcha(299, 97) 创建一个 LineCaptcha 实例,宽 299 像素、高 97 像素,正好匹配登录页 <img> 的展示尺寸。这个对象同时持有两样东西:渲染好的图片(内存里的 BufferedImage)和验证码文本(getCode() 可取)。不指定字符数和干扰线参数时走 Hutool 默认值(4 位字符 + 默认数量干扰线),需要定制可以换用四参数重载 createLineCaptcha(width, height, codeCount, lineCount)。验证码的难与易就在这几个参数之间:字符多、干扰线密就难认,反过来用户体验好但防护弱。
第二步:文本存 Redis。 captcha.getCode() 取出验证码文本,用 CAP_CODE_ + uuid 作 key 写入。uuid 是前端带来的,每个登录页会话一个,天然不会互相覆盖;同一个 uuid 反复刷新验证码,则后面的 set 覆盖前面的值,语义正确。注意这一句 set 只传了 key 和 value,没有传过期时间,这是实读工程时发现的坑,后文专门说。
第三步:图片写响应。 captcha.write(response.getOutputStream()) 把图片二进制写进响应体。方法返回 void,没有 JSON 包装;LineCaptcha 输出的默认图片类型是 JPEG,浏览器拿到响应后按图片渲染。IO 操作必须处理 IOException,这里直接在方法签名上声明抛出,交给全局异常处理。
登录侧的消费逻辑(对照)
为了完整性,把 AdminService.login() 里消费验证码的部分也贴出来(后续文章会展开整个登录流程):
package com.mf.admin.service;
import cn.hutool.crypto.SecureUtil;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.mf.admin.exception.BusinessException;
import com.mf.admin.mapper.AdminMapper;
import com.mf.commons.utils.Constants;
import com.mf.commons.utils.JwtUtils;
import com.mf.model.domain.Admin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.stereotype.Service;
import org.springframework.util.StringUtils;
import java.util.HashMap;
import java.util.Map;
@Service
public class AdminService {
@Autowired
private AdminMapper adminMapper;
@Autowired
private RedisTemplate<String,String> redisTemplate;
public Map login(Map map) {
//1、获取请求参数(username, password, verificationCode, uuid)
String username = (String) map.get("username");
String password = (String) map.get("password");
String verificationCode = (String) map.get("verificationCode");
String uuid = (String) map.get("uuid");
//2、用登录请求带回的 uuid 拼 key,取出生成时存入的验证码
String key = Constants.CAP_CODE + uuid;
String value = redisTemplate.opsForValue().get(key);
if (StringUtils.isEmpty(value) || !verificationCode.equals(value)) {
//取不到(key 不存在)或比对不一致:验证码错误
//key 不删除,用户可直接重试
throw new BusinessException("验证码错误");
}
//3、比对通过,验证码用后即删,防止重放
redisTemplate.delete(key);
//4、校验用户名密码、签发 token(下一篇展开)
QueryWrapper<Admin> qw = new QueryWrapper<Admin>().eq("username", username);
Admin admin = adminMapper.selectOne(qw);
password = SecureUtil.md5(password);
if (admin == null || !password.equals(admin.getPassword())) {
throw new BusinessException("用户名或者密码错误");
}
Map tokenMap = new HashMap();
tokenMap.put("id", admin.getId());
tokenMap.put("username", admin.getUsername());
String token = JwtUtils.getToken(tokenMap);
Map retMap = new HashMap();
retMap.put("token", token);
return retMap;
}
}
注意 "验证码错误" 分支覆盖了两种情况:key 不存在(没取过验证码 / 已被消费 / 未设 TTL 时永不过期所以不存在自然失效)和文本不一致。异常统一由 ExceptionAdvice 转成错误响应。
已知的坑:验证码永不过期
实读工程确认,存验证码的这行代码:
redisTemplate.opsForValue().set(Constants.CAP_CODE + uuid, code); // 没有 TTL
set 没带过期时间,key 会一直留在 Redis 里。后果有两层:
- 产品层面:验证码「短时效」的防护意义被削弱。用户十分钟前请求的图,十分钟后仍能拿它登录,图没变,机器拿到图片后有充足时间离线识别再提交。
- 存储层面:每次刷新登录页都写入一个 key,无人清理,日积月累 Redis 里堆满
CAP_CODE_*垃圾数据。
修复方式是 set 时带上过期时间,把「验证码 2 分钟内有效」写进代码:
import java.util.concurrent.TimeUnit;
// 修复:验证码存入 2 分钟后自动过期
redisTemplate.opsForValue().set(Constants.CAP_CODE + uuid, code, 2, TimeUnit.MINUTES);
过期后 opsForValue().get(key) 返回 null,登录侧现有的判空逻辑(StringUtils.isEmpty(value) → 抛「验证码错误」)不需要任何改动,天然兼容。过期时长参考短信验证码的惯例,1~5 分钟都是合理取值,产品上也可以配成「点击图片刷新」来引导用户重新获取。
异常与边界
| 场景 | 现象 / 行为 | 说明 |
|---|---|---|
| Redis 不可用 | set 抛异常,接口 500,验证码图片拿不到 | 验证码强依赖 Redis,Redis 挂了登录功能整体不可用,属于合理设计;生产上监控 Redis 健康即可 |
| 验证码未设过期 | key 永不过期,安全性与存储双重隐患 | 本项目实况,修复见上文 |
| 同一 uuid 重复请求 | 后写的覆盖先写的,旧图立即失效 | Redis SET 天然覆盖语义,行为正确 |
| uuid 为空 | key 退化为 CAP_CODE_,所有空 uuid 请求共用一个 key | 实际不会发生(前端固定生成 uuid),但服务端未校验,严谨做法是先判空 |
| 响应 Content-Type | Controller 未显式设置,Hutool 按图片格式输出二进制 | 浏览器靠内容嗅探正常渲染;如需严谨可在写出前 response.setContentType("image/jpeg") |
| 登录时 key 不存在 | 抛 BusinessException("验证码错误") | 覆盖「没取过 / 已消费 / (修复 TTL 后)已过期」三种情况 |
| 验证码对但密码错 | 验证码已被删除,需刷新图片重试 | 删除发生在密码校验之前,实读确认的顺序 |
| 网关直达 | 必须走 http://网关:8888/admin/...,同时直连 18083 也通 | 该接口在 excludedUrls 白名单,网关不校验 token |
可复现验证
按下面的步骤可以完整走一遍(假设本机已启动 Nacos、Redis、MySQL):
# 1. 启动管理后台服务(端口 18083)
# 运行 AdminServerApplication
# 2. 请求验证码接口,把响应保存为图片
curl "http://localhost:18083/system/users/verification?uuid=test-123" -o captcha.jpg
# 3. 查看 Redis 里存进去的验证码文本
redis-cli
127.0.0.1:6379> KEYS CAP_CODE_*
1) "CAP_CODE_test-123"
127.0.0.1:6379> GET CAP_CODE_test-123
"x8kf"
# 4. 打开 captcha.jpg,肉眼读出验证码(比如 x8kf)
# 5. 走网关再验一次,确认路由和白名单生效
curl "http://localhost:8888/admin/system/users/verification?uuid=test-456" -o captcha2.jpg
在管理后台登录页输入肉眼读到的验证码提交登录,能进入系统即说明「生成 → 存储 → 展示 → 比对」整条链路是通的。验证码比对的具体校验发生在登录接口(POST /system/users/login),实现细节在下一篇展开。
常见误解澄清
| 误解 | 实际情况 |
|---|---|
| 验证码存在 Session 里 | 存 Redis,key 是 CAP_CODE_+uuid,与 session 无关;前后端分离 + 多实例下 session 不可靠 |
| uuid 是后端生成的 | 前端生成,拼在请求参数上带来;后端只负责用它拼 key |
| 验证码错误后必须刷新图片 | 不用。失败分支不删 key,同一张图可以直接再输一次 |
| 验证码会自动过期 | 不会。工程实读确认 set 未带 TTL,这是已知坑,建议 set(key, code, 2, TimeUnit.MINUTES) 修复 |
| 每次刷新验证码会在 Redis 里堆多个 key | 不会。同一个 uuid 的 SET 是覆盖语义,一个 uuid 始终只有一个 key |
| 验证码接口返回 JSON | 返回的是图片二进制流,方法返回值是 void,直接写响应输出流 |
| 验证码生成逻辑在 Service 层 | 实读确认在 SystemController.verification,ManagerService 里没有验证码方法 |
| 验证码对了就一定能登录 | 不一定。验证码删除发生在密码校验之前,密码错还是要刷新图片重来 |
官方文档
总结
- B 端账号密码登录没有短信频控兜底,图片验证码是防机器暴力破解的第一道也是唯一一道人机屏障,且本地生成、零成本。
- 实现只有三步:
CaptchaUtil.createLineCaptcha(299, 97)生成图片与文本 → 文本以CAP_CODE_+uuid存 Redis →captcha.write()把图片流写进响应。 - uuid 由前端生成,作为关联两次请求的凭证,替代 session 是前后端分离 + 分布式架构下的必然选择;验证码验证通过即删、失败不删的语义让「重试」和「防重放」各得其所。
- 工程实读发现的坑:存验证码没有设置 TTL,验证码永不过期。一行
set(key, code, 2, TimeUnit.MINUTES)即可修复,登录侧判空逻辑天然兼容。 - 后续文章接着走登录的后半程:管理员登录:根据用户名密码登录获取 token,验证码过了关之后,怎么查库校验密码、怎么用 JWT 签发 token。
2万+



被折叠的 条评论
为什么被折叠?



