[038][验证码模块]基于 Hutool 的 Spring Boot 验证码组件设计与实现
一、概述
验证码是防止恶意机器人攻击、保障系统安全的重要手段。在实际项目中，我们需要灵活支持多种验证码类型（线段干扰、圆圈干扰、扭曲干扰、GIF 动态验证码），并且要求验证码的生成、校验、缓存等流程能够统一管理、易于扩展。
本文介绍一个基于 Hutool 验证码库、深度集成 Spring Boot 的验证码组件。该组件提供了自动配置、多级缓存、模糊度处理、忽略大小写校验等特性，可以快速嵌入任何 Spring Boot 项目中使用。
二、模块架构
整体架构分为三层：
- 自动配置层：
HutoolCaptchaConfiguration读取配置属性，校验参数，创建对应的 Builder 和 Service Bean。 - 构建器层：
AbstractCaptchaBuilder及其子类负责封装 Hutool 原生验证码对象的创建与属性填充。 - 服务层：
AbstractCaptchaService及其子类负责验证码生成、缓存存储、校验逻辑，并对外提供统一的draw()和verify()接口。
此外，组件依赖一个多级缓存模板 BehaviorCaptchaCacheTemplate，用于存储验证码文本（key 为 UUID，value 为验证码字符串），支持本地缓存 + Redis 两级缓存，提升性能。
┌─────────────────────────────────────────────┐
│ Spring Boot AutoConfiguration │
│ (HutoolCaptchaConfiguration) │
└─────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Line │ │Circle │ │Shear │ ... (Gif)
│Builder │ │Builder │ │Builder │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│Line │ │Circle │ │Shear │
│Service │ │Service │ │Service │
└─────────┘ └─────────┘ └─────────┘
│
▼
┌─────────────────────┐
│BehaviorCaptchaCache │
│Template (Multi-level)│
└─────────────────────┘
三、核心类分析
3.1 配置类：HutoolCaptchaConfiguration
该配置类使用 @Configuration(proxyBeanMethods = false) 提升启动性能。它分别创建了四个验证码 Service Bean：
lineCaptchaServicecircleCaptchaServiceshearCaptchaServicegifCaptchaService
每个 Bean 的创建流程：
- 从
HutoolCaptchaProperties中获取对应的配置（如properties.getLine()）； - 调用
validate(options)校验通用参数（宽高、干扰数、字体大小、透明度范围、模糊度范围等）； - 创建对应的 Builder（如
LineCaptchaBuilder）； - 调用
fillBuilder()将配置填充到 Builder（包括字体、背景色、码生成器等）； - 对于 GIF 类型额外校验
quality、repeat、颜色范围； - 返回 Service 实例。
关键参数校验
// 透明度 0~1
Assert.isTrue(transparency >= 0 && transparency <= 1, "...");
// 模糊度 0~30
Assert.isTrue(fuzziness >= 0 && fuzziness <= 30, "...");
3.2 抽象构建器：AbstractCaptchaBuilder<C>
采用 Fluent 风格（@Accessors(fluent = true, chain = true)）使属性设置可链式调用。核心方法：
createCaptcha()：抽象方法，由子类实现具体 Hutool 验证码的实例化。fill(AbstractCaptcha captcha)：设置字体和背景色，支持文字透明度。build()：模板方法，先创建再填充，返回配置好的验证码对象。
子类实现示例
public class LineCaptchaBuilder extends AbstractCaptchaBuilder<LineCaptcha> {
@Override
protected LineCaptcha createCaptcha() {
return new LineCaptcha(width(), height(), generator(), interfereCount());
}
}
3.3 抽象服务：AbstractCaptchaService
实现了 CaptchaService 接口（该接口未在代码中给出，但可推断包含 draw() 和 verify() 方法）。提供以下公共能力：
- 模糊处理：调用
GaussianBlur.execute(image, fuzziness)对生成的验证码图片进行高斯模糊，增强防破解能力。 - 缓存存储：生成随机 UUID 作为 key，将验证码文本存入
BehaviorCaptchaCacheTemplate。 - 图片转 Base64：将 BufferedImage 写入 PNG 字节流，然后转换为
data:image/png;base64,...格式，方便前端直接渲染。 - 校验逻辑：从缓存中获取正确的验证码，根据
ignoreCase配置比较用户输入，校验成功后删除缓存（一次性使用）。
关键代码片段
protected CaptchaData createCaptchaData(String code, BufferedImage image) {
try (ByteArrayOutputStream out = new ByteArrayOutputStream()) {
image = handleFuzziness(image);
ImgUtil.writePng(image, out);
String key = IdUtil.fastSimpleUUID();
captchaCacheTemplate.put(key, code);
return new CaptchaData().key(key).code(code).category(getCategory())
.captchaImage(out.toByteArray());
} catch (IOException e) {
throw new CaptchaException("生成验证码图片异常", e);
}
}
3.4 GIF 验证码的特殊处理
GifCaptchaService 并未复用 createCaptchaData，因为 Hutool 的 GifCaptcha 直接提供了 getImageBytes() 方法返回 GIF 字节数据，无需手动转换。同时 GIF 验证码的 code 通过 captcha.getCode() 获取（内部已自动生成），而其他类型需要手动调用 generator.generate()。
3.5 缓存模板：BehaviorCaptchaCacheTemplate
继承自 AbstractMultiLevelCacheTemplate<String, String>，该模板实现了多级缓存（Caffeine + Redis）。缓存名称为 behavior-captcha，默认过期时间可由底层配置统一管理。valueGenerator 方法在此处直接返回 key 本身，因为验证码场景中不存在缓存穿透时需要回源生成值的需求（验证码是由上层主动生成的，缓存未命中时不会自动生成）。
四、配置方式
在 Spring Boot 的 application.yml 中可以进行如下配置（示例）：
tutorials4j:
captcha:
hutool:
line:
width: 150
height: 40
interfere-count: 2
background-color: WHITE
fuzziness: 5
valid-ignore-case: true
code:
length: 4
generator: "RANDOM_NUMBER" # 实际对应一个 CodeGenerator 工厂
font:
name: "DIALOG"
style: "BOLD"
size: 30
circle:
# 类似配置...
shear:
# ...
gif:
width: 120
height: 40
interfere-count: 1
quality: 10
repeat: 0
min-color: 0
max-color: 255
注意：generator 配置需要能够根据 length 返回一个 CodeGenerator 实例，代码中使用了 code.getGenerator().apply(code.getLength())，这意味着配置属性中 generator 是一个 Function<Integer, CodeGenerator> 类型，通常通过自定义转换器实现。
五、使用示例
5.1 生成验证码
假设通过 REST Controller 暴露接口：
@RestController
@RequiredArgsConstructor
public class CaptchaController {
private final LineCaptchaService lineCaptchaService;
@GetMapping("/captcha/line")
public Map<String, Object> getLineCaptcha() {
return lineCaptchaService.draw();
}
}
返回示例：
{
"key": "a1b2c3d4e5f6",
"category": "HUTOOL_LINE",
"captchaImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
前端拿到 key 和 captchaImage 后，将 captchaImage 赋值给 <img src="..."> 显示，并保存 key 用于下一步校验。
5.2 校验验证码
@PostMapping("/captcha/verify")
public boolean verify(@RequestParam String key, @RequestParam String userCode) {
return lineCaptchaService.verify(key, userCode);
}
校验成功返回 true，并且缓存中的验证码会被自动删除；失败返回 false 或抛出异常（根据业务封装）。
六、设计亮点
- 高扩展性：通过
AbstractCaptchaBuilder和AbstractCaptchaService抽象层，新增一种验证码类型只需增加对应的 Builder 和 Service，并修改配置类即可。 - 参数强校验：在配置阶段使用
Assert校验宽高、透明度、模糊度等，避免运行时错误。 - 多级缓存：验证码文本存储在本地+Redis 多级缓存中，降低 Redis 压力，提升读取性能。
- 模糊度增强：支持对生成的图片进行高斯模糊，增加机器识别的难度。
- 一次性验证码：校验成功后立即删除缓存，防止验证码被重复使用。
- 忽略大小写：可配置是否忽略大小写比较，提升用户体验。
七、总结
本文详细介绍了基于 Hutool 的 Spring Boot 验证码组件的设计与实现。该组件：
- 支持四种常用验证码类型（线段、圆圈、扭曲、GIF）；
- 提供灵活的配置能力（宽高、干扰数、字体、颜色、模糊度、忽略大小写等）；
- 集成了多级缓存和一次性校验逻辑；
- 代码结构清晰，易于扩展。
