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

简介: 本文介绍基于Hutool与Spring Boot深度集成的验证码组件,支持线段、圆圈、扭曲、GIF四类验证码,具备自动配置、多级缓存(Caffeine+Redis)、高斯模糊增强、忽略大小写校验及一次性使用等特性,架构清晰、扩展性强,开箱即用。

[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:

  • lineCaptchaService
  • circleCaptchaService
  • shearCaptchaService
  • gifCaptchaService

每个 Bean 的创建流程:

  1. 从 HutoolCaptchaProperties 中获取对应的配置(如 properties.getLine());
  2. 调用 validate(options) 校验通用参数(宽高、干扰数、字体大小、透明度范围、模糊度范围等);
  3. 创建对应的 Builder(如 LineCaptchaBuilder);
  4. 调用 fillBuilder() 将配置填充到 Builder(包括字体、背景色、码生成器等);
  5. 对于 GIF 类型额外校验 quality、repeat、颜色范围;
  6. 返回 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 或抛出异常(根据业务封装)。

六、设计亮点

  1. 高扩展性:通过 AbstractCaptchaBuilder 和 AbstractCaptchaService 抽象层,新增一种验证码类型只需增加对应的 Builder 和 Service,并修改配置类即可。
  2. 参数强校验:在配置阶段使用 Assert 校验宽高、透明度、模糊度等,避免运行时错误。
  3. 多级缓存:验证码文本存储在本地+Redis 多级缓存中,降低 Redis 压力,提升读取性能。
  4. 模糊度增强:支持对生成的图片进行高斯模糊,增加机器识别的难度。
  5. 一次性验证码:校验成功后立即删除缓存,防止验证码被重复使用。
  6. 忽略大小写:可配置是否忽略大小写比较,提升用户体验。

七、总结

本文详细介绍了基于 Hutool 的 Spring Boot 验证码组件的设计与实现。该组件:

  • 支持四种常用验证码类型(线段、圆圈、扭曲、GIF);
  • 提供灵活的配置能力(宽高、干扰数、字体、颜色、模糊度、忽略大小写等);
  • 集成了多级缓存和一次性校验逻辑;
  • 代码结构清晰,易于扩展。
目录
相关文章
|
6月前
|
人工智能 自然语言处理 BI
用办公Agent接管Excel苦力活:跨表匹配、格式清洗、自动图表生成
本文揭秘如何用AI办公Agent自动化处理Excel月度报表:15分钟搞定跨表匹配(模糊+精确双策略)、智能清洗(日期/数字/空白全覆盖)、自动绘图(配色+标题+标签)。告别VLOOKUP、分列、手动调图,让重复劳动归零——真正的效率革命,始于教会机器做脏活。
819 4
sa-token实现网关调用认证服务统一鉴权
sa-token实现网关调用认证服务统一鉴权
1117 0
|
数据库
数据库常用到的查询积累
数据库常用到的查询积累
|
存储 负载均衡 应用服务中间件
分布式文件系统FastDFS
 FastDFS是一个开源的轻量级分布式文件系统,由阿里巴巴余庆大神开发,底层采用C语言,它对文件进行管理,功能包括:文件存储、文件同步、文件访问(文件上传、文件下载)等,解决了大容量存储和负载均衡的问题。特别适合以文件为载体的在线服务,如相册网站、视频网站等等。FastDFS为互联网量身定制,充分考虑了冗余备份、负载均衡、线性扩容等机制,并注重高可用、高性能等指标,使用FastDFS很容易搭建一套高性能的文件服务器集群提供文件上传、下载等服务。
579 0
|
3月前
|
NoSQL Java 调度
[060][调度模块]Redisson vs Redis 原生锁:两种分布式锁实现深度对比
本文深度对比调度模块中Redis原生锁与Redisson锁:前者轻量但功能简陋(无重入、无阻塞),需手动续期;后者支持可重入、自动看门狗续期、阻塞等待,API友好但依赖较重。结合场景选型更可靠。(239字)
168 1
|
3月前
|
运维 Java 调度
[059][调度模块]配置驱动的任务仓库 – 从 YAML 加载任务
本文介绍基于YAML配置驱动的任务仓库实现,支持通过`application.yml`声明定时任务(cron、开关、重试等),`YamlTaskRepository`自动解析并提供CRUD接口,无缝集成`ScheduleTaskManager`,兼顾运维灵活性与扩展性。
84 1
|
3月前
|
消息中间件 Prometheus 监控
[058][调度模块]任务生命周期事件与监听器机制
本文介绍调度模块的任务生命周期事件机制,通过`ChangeStatusEvent`事件与`ChangeStatusEventConsumer`监听器,实现任务状态(CREATED/STARTED/COMPLETED等)变更的灵活监听。支持日志、持久化、消息推送等扩展,具备高解耦性与异常隔离能力。(239字)
121 2
|
3月前
|
缓存 NoSQL Java
[037][缓存模块]基于 Guava Striped 的声明式本地锁设计与实现
本文介绍基于Guava Striped与Spring AOP实现的声明式本地锁:通过`@LocalLockable`注解+SpEL动态生成细粒度锁key,支持超时控制与中断处理,内存可控、低延迟,适用于单机高并发场景。
123 1
|
3月前
|
缓存 NoSQL 安全
[036][缓存模块]基于 Redis 自定义缓存锁的设计与实现
本文介绍基于Redis的轻量级分布式缓存锁组件,通过`@RedisLockable`注解+ AOP + Lua脚本,支持固定租期与自动续期双模式,解决缓存击穿、重复计算与资源竞争问题,具备声明式、动态Key、原子性及安全释放等特性,代码开源可扩展。(239字)
135 2
|
3月前
|
NoSQL 调度 Redis
[057][调度模块]分布式环境下定时任务的防重复执行方案
本文介绍分布式定时任务防重复执行方案,基于Redis/Redisson分布式锁,提供自动续期与固定租期两种模式,通过`key()`控制锁粒度,支持异常跳过与自定义处理,确保集群中同一任务仅单点执行。代码开源。
185 1