[038][验证码模块]基于 Hutool 的 Spring Boot 验证码组件设计与实现

[038][验证码模块]基于 Hutool 的 Spring Boot 验证码组件设计与实现

一、概述

验证码是防止恶意机器人攻击、保障系统安全的重要手段。在实际项目中，我们需要灵活支持多种验证码类型（线段干扰、圆圈干扰、扭曲干扰、GIF 动态验证码），并且要求验证码的生成、校验、缓存等流程能够统一管理、易于扩展。

本文介绍一个基于 Hutool 验证码库、深度集成 Spring Boot 的验证码组件。该组件提供了自动配置、多级缓存、模糊度处理、忽略大小写校验等特性，可以快速嵌入任何 Spring Boot 项目中使用。

二、模块架构

整体架构分为三层：

自动配置层：HutoolCaptchaConfiguration 读取配置属性，校验参数，创建对应的 Builder 和 Service Bean。 构建器层：AbstractCaptchaBuilder 及其子类负责封装 Hutool 原生验证码对象的创建与属性填充。 服务层：AbstractCaptchaService 及其子类负责验证码生成、缓存存储、校验逻辑，并对外提供统一的 draw() 和 verify() 接口。

此外，组件依赖一个多级缓存模板 Beha viorCaptchaCacheTemplate，用于存储验证码文本（key 为 UUID，value 为验证码字符串），支持本地缓存 Redis 两级缓存，提升性能。

┌─────────────────────────────────────────────┐│ Spring Boot AutoConfiguration ││(HutoolCaptchaConfiguration) │└─────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼┌─────────┐┌─────────┐┌─────────┐│Line ││Circle ││Shear│... (Gif)│Builder││Builder││Builder│└────┬────┘└────┬────┘└────┬────┘ │││ ▼▼▼┌─────────┐┌─────────┐┌─────────┐│Line ││Circle ││Shear││Service││Service││Service│└─────────┘└─────────┘└─────────┘ │ ▼ ┌─────────────────────┐ │Beha viorCaptchaCache │ │Template (Multi-level)│ └─────────────────────┘

三、核心类分析

3.1 配置类：HutoolCaptchaConfiguration

该配置类使用 @Configuration(proxyBeanMethods = false) 提升启动性能。它分别创建了四个验证码 Service Bean：

lineCaptchaService circleCaptchaService shearCaptchaService gifCaptchaService

每个 Bean 的创建流程：

从 HutoolCaptchaProperties 中获取对应的配置（如 properties.getLine()）； 调用 validate(options) 校验通用参数（宽高、干扰数、字体大小、透明度范围、模糊度范围等）； 创建对应的 Builder（如 LineCaptchaBuilder）； 调用 fillBuilder() 将配置填充到 Builder（包括字体、背景色、码生成器等）； 对于 GIF 类型额外校验 quality、repeat、颜色范围； 返回 Service 实例。

关键参数校验

// 透明度 0~1Assert.isTrue(transparency >= 0 && transparency <= 1, "...");// 模糊度 0~30Assert.isTrue(fuzziness >= 0 && fuzziness <= 30, "...");

3.2 抽象构建器：AbstractCaptchaBuilder

采用 Fluent 风格（@Accessors(fluent = true, chain = true)）使属性设置可链式调用。核心方法：

createCaptcha()：抽象方法，由子类实现具体 Hutool 验证码的实例化。 fill(AbstractCaptcha captcha)：设置字体和背景色，支持文字透明度。 build()：模板方法，先创建再填充，返回配置好的验证码对象。

子类实现示例

public class LineCaptchaBuilder extends AbstractCaptchaBuilder { @Overrideprotected LineCaptcha createCaptcha() { return new LineCaptcha(width(), height(), generator(), interfereCount());}}

3.3 抽象服务：AbstractCaptchaService

实现了 CaptchaService 接口（该接口未在代码中给出，但可推断包含 draw() 和 verify() 方法）。提供以下公共能力：

模糊处理：调用 GaussianBlur.execute(image, fuzziness) 对生成的验证码图片进行高斯模糊，增强防破解能力。 缓存存储：生成随机 UUID 作为 key，将验证码文本存入 Beha viorCaptchaCacheTemplate。 图片转 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 缓存模板：Beha viorCaptchaCacheTemplate

继承自 AbstractMultiLevelCacheTemplate，该模板实现了多级缓存（Caffeine Redis）。缓存名称为 beha vior-captcha，默认过期时间可由底层配置统一管理。valueGenerator 方法在此处直接返回 key 本身，因为验证码场景中不存在缓存穿透时需要回源生成值的需求（验证码是由上层主动生成的，缓存未命中时不会自动生成）。

四、配置方式

在 Spring Boot 的 application.yml 中可以进行如下配置（示例）：

tutorials4j:captcha:hutool:line:width: 150height: 40interfere-count: 2background-color: WHITEfuzziness: 5valid-ignore-case: truecode:length: 4generator: "RANDOM_NUMBER" # 实际对应一个 CodeGenerator 工厂font:name: "DIALOG"style: "BOLD"size: 30circle:# 类似配置...shear:# ...gif:width: 120height: 40interfere-count: 1quality: 10repeat: 0min-color: 0max-color: 255

需要特别留意的是，generator 这个配置项必须能根据 length 返回一个 CodeGenerator 实例。原因很直接，代码里调用的是 code.getGenerator().apply(code.getLength())，这实际上已经说明：配置属性中的 generator 本质上是一个 Function 类型，一般需要通过自定义转换器来完成这层映射。

五、使用示例

5.1 生成验证码

假设通过 REST Controller 暴露接口：

@RestController@RequiredArgsConstructorpublic class CaptchaController { private final LineCaptchaService lineCaptchaService;@GetMapping("/captcha/line")public Map getLineCaptcha() { return lineCaptchaService.draw();}}

返回示例：

{ "key": "a1b2c3d4e5f6","category": "HUTOOL_LINE","captchaImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."}

前端拿到 key 和 captchaImage 后，将 captchaImage 赋值给 显示，并保存 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）； 提供灵活的配置能力（宽高、干扰数、字体、颜色、模糊度、忽略大小写等）； 集成了多级缓存和一次性校验逻辑； 代码结构清晰，易于扩展。