跳至主要內容

md-captcha-starter

1. 模块定位

验证码聚合模块，坐标 top.mddata.base:md-captcha-starter，下辖两个独立子 starter：

  • md-graphic-captcha-starter：图形验证码（基于 easy-captcha ），GraphicCaptchaService 生成图片；
  • md-slider-captcha-starter：滑块/点选验证码（基于 anji-captcha），内置缓存实现。

2. 源码解读

md-captcha-starter
├── md-graphic-captcha-starter
│   └── top.mddata.base.captcha.graphic
│       ├── GraphicCaptchaService.java        # 生成/校验图形验证码
│       └── properties/GraphicCaptchaProperties.java  # mdp.captcha.graphic.*
└── md-slider-captcha-starter
    └── top.mddata.base.captcha.slider
        ├── SliderCaptchaAutoConfiguration.java       # 自动配置
        ├── SliderCaptchaCacheServiceImpl.java / SliderCaptchaCacheAutoConfiguration.java
        └── properties/SliderCaptchaProperties.java   # mdp.captcha.slider.*

滑块验证码的缓存有三种装配分支（cache-type）：default（本地内存）、redis（分布式，多实例部署必选）、custom（应用自己提供缓存 Bean）。

3. 可配置参数

3.1 图形验证码（前缀 mdp.captcha.graphic）

配置项默认值说明
mdp.captcha.graphic.enabledtrue开关
mdp.captcha.graphic.typeSPEC类型（SPEC 等，见 GraphicCaptchaType）
mdp.captcha.graphic.length4字符数
mdp.captcha.graphic.width111宽（px）
mdp.captcha.graphic.height36高（px）
mdp.captcha.graphic.font-name—字体
mdp.captcha.graphic.font-size25字号

3.2 滑块验证码（前缀 mdp.captcha.slider，字段核对自 SliderCaptchaProperties）

配置项默认值说明
mdp.captcha.slider.enabledtrue开关
mdp.captcha.slider.enable-aestrue前端轨迹 AES 加密
mdp.captcha.slider.typeBLOCKPUZZLEBLOCKPUZZLE 滑块拼图 / PICCLICK 文字点选
mdp.captcha.slider.cache-typedefaultdefault 本地内存 / redis / custom（多实例部署必须 redis）
mdp.captcha.slider.jigsaw-base-map-path—滑块底图资源路径
mdp.captcha.slider.pic-click-base-map-path—点选底图资源路径
mdp.captcha.slider.slip-offset5容错偏移量
mdp.captcha.slider.font-type / water-font / font-style / font-sizeWenQuanZhengHei.ttf 等字体与水印样式
mdp.captcha.slider.water-mark""水印文案
mdp.captcha.slider.req-frequency-limit-enable0接口防刷开关
mdp.captcha.slider.req-get-lock-limit / req-get-lock-seconds5 / 300get 接口锁定阈值/秒数
mdp.captcha.slider.req-get-minute-limit / req-check-minute-limit / req-verify-minute-limit100 / 100 / 100各接口每分钟限次
mdp.captcha.slider.cache-number1000本地缓存验证码数量
mdp.captcha.slider.timing-clear180定时清理周期（秒）
mdp.captcha.slider.history-data-clear-enable0历史数据清理

4. 扩展点

  • 滑块缓存：cache-type=custom 时应用提供自己的缓存实现 Bean（SliderCaptchaCacheAutoConfiguration 按 @ConditionalOnProperty 三分支装配）。
  • 底图资源：jigsaw-base-map-path/pic-click-base-map-path 可指向 classpath 或自定义目录，换图不换代码。
  • 两种验证码相互独立，可只引其一。

5. 功能扩展建议

想做什么推荐做法
集群部署滑块验证码cache-type=redis（本地内存在多实例下校验必失败）
登录防刷开 req-frequency-limit-enable，按业务量调 req-*-minute-limit
短信/邮件发码前加人机校验滑块通过后再放行发码接口，复用现有登录流程的接法
自定义验证码样式换 *-base-map-path 底图；图形验证码调 type/length/width/height

6. 二次开发注意事项

多实例 + default 缓存 = 验证失败

滑块验证码状态默认存本地内存，负载均衡打到不同实例时"这边生成、那边校验"必然失败。多实例部署必须 cache-type=redis（redis 未配好时启动也会暴露问题，留意日志）。

配置值多为字符串类型

SliderCaptchaProperties 中限流/尺寸等大量字段是 String 类型（anji-captcha 约定），配置时按字符串写（如 "5"/"100" 语义），改造成数字字段需同步 anji-captcha 读取逻辑。

Copyright © 2026-present henhen6