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

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

本项目代码: gitee.com/yunjiao-sou…

一、概述

验证码是防止恶意机器人攻击、保障系统安全的重要手段。在实际项目中，我们需要灵活支持多种验证码类型（线段干扰、圆圈干扰、扭曲干扰、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：

lineCaptchaService
circleCaptchaService
shearCaptchaService
gifCaptchaService

每个 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）；
提供灵活的配置能力（宽高、干扰数、字体、颜色、模糊度、忽略大小写等）；
集成了多级缓存和一次性校验逻辑；
代码结构清晰，易于扩展。

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