做过后台管理系统或者用户端项目的朋友应该都懂,登录、注册、短信发送接口,但凡没加人机验证,用不了几天就会被爬虫或者恶意脚本暴力刷接口,轻则接口压力飙升,重则数据泄露、短信费用超标。传统的字符验证码不仅用户体验差,稍微懂点技术的用OCR就能轻松破解,根本顶不住。
今天就给大家分享一套零冗余、纯免费的接入方案,不用手写复杂逻辑,依托现成开源组件,SpringBoot3项目直接快速落地高可用行为验证码,完美解决接口防刷痛点。
它就是纯开源免费的tianai-captcha,刚好精准适配上述痛点:它自带SpringBoot Starter自动装配,省去手动配置Bean的繁琐操作,而且支持的验证类型格外全面,覆盖滑块、旋转、滑动还原、文字点选、曲线匹配等主流模式,既能有效拦截爬虫脚本暴力破解,又大幅优化了用户操作体验,比难用又易破解的传统字符验证码强太多,登录、短信发送、表单提交这类高频防刷接口,用它都完全适配。
一、环境与依赖说明
先确认项目基础环境,避免版本冲突踩坑:
- JDK版本:17及以上
- SpringBoot版本:3.2.5
- 构建工具:Maven
- tianai-captcha:1.5.5
tianai-captcha官方提供了SpringBoot Starter,不用手动配置Bean,直接引入依赖即可,这也是我选它的核心原因之一,省去大量自定义配置。
二、引入Maven依赖
直接在项目的pom.xml中添加starter依赖,不用额外引入其他包,Starter内部已封装好自动配置、验证码生成、校验核心逻辑:
<!-- tianai-captcha SpringBoot3适配Starter --> cloud.tianai.captcha tianai-captcha-springboot-starter 1.5.5 <!-- SpringBoot3 Web依赖,必选,用于提供接口 --> org.springframework.boot spring-boot-starter-web <!-- 可选:项目用到Redis的话,验证码会自动存入Redis,分布式部署推荐;不用Redis默认用本地内存,单机测试足够 --> org.springframework.boot spring-boot-starter-data-redis 依赖引入后,刷新Maven,等待下载完成,不用做任何额外的包扫描配置,Starter的自动装配会生效。
三、application.yml极简配置
不用写复杂配置,只需要开启默认资源、设置过期时间即可,新手直接用下面的配置,分布式项目加Redis相关配置就行:
server: port: 8080# tianai-captcha核心配置# 行为验证码配置, 详细请看 cloud.tianai.captcha.autoconfiguration.ImageCaptchaProperties 类captcha: # 如果项目中使用到了redis,滑块验证码会自动把验证码数据存到redis中, 这里配置redis的key的前缀,默认是captcha:slider prefix: captcha # 验证码过期时间,默认是2分钟,单位毫秒, 可以根据自身业务进行调整 expire: # 默认缓存时间 2分钟 default: 10000 # 针对 点选验证码 过期时间设置为 2分钟, 因为点选验证码验证比较慢,把过期时间调整大一些 WORD_IMAGE_CLICK: 20000 # 使用加载系统自带的资源, 默认是 false(这里系统的默认资源包含 滑动验证码模板/旋转验证码模板,如果想使用系统的模板,这里设置为true) init-default-resource: true # 缓存控制, 默认为false不开启 local-cache-enabled: false # 缓存开启后,验证码会提前缓存一些生成好的验证数据, 默认是20 local-cache-size: 20 # 缓存开启后,缓存拉取失败后等待时间 默认是 5秒钟 local-cache-wait-time: 5000 # 缓存开启后,缓存检查间隔 默认是2秒钟 local-cache-period: 2000 # 缓存开启后,忽略的字段,默认是 ""(不忽略任何字段) local-cache-ignored-cache-fields: "" # 配置字体包,供文字点选验证码使用,可以配置多个,不配置使用默认的字体 font-path: - classpath:font/SimHei.ttf secondary: # 二次验证, 默认false 不开启 enabled: false # 二次验证过期时间, 默认 2分钟 expire: 120000 # 二次验证缓存key前缀,默认是 captcha:secondary keyPrefix: "captcha:secondary"# Redis配置(分布式项目必配,单机测试可省略)spring: data: redis: host: localhost port: 6379 database: 0 timeout: 5000四、自定义验证码背景图
默认的验证码背景图是组件自带的通用模板,用在实际项目里辨识度不高,而且风格和项目UI容易不匹配,所以我们可以通过自定义配置类,替换成自己项目的背景图,适配不同验证类型,也能让验证码界面更贴合整体项目风格。
配置前先做好准备工作:在项目 resources 目录下新建 bgimages 文件夹,把准备好的背景图片放进去,图片尺寸建议适配验证码默认比例,避免拉伸变形;下面这段配置类,负责加载本地背景图并绑定对应验证码类型,代码直接复制后修改图片路径即可。
import cloud.tianai.captcha.common.constant.CaptchaTypeConstant;import cloud.tianai.captcha.resource.ResourceStore;import cloud.tianai.captcha.resource.common.model.dto.Resource;import cloud.tianai.captcha.resource.impl.LocalMemoryResourceStore;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;@Configurationpublic class CaptchaResourceConfiguration { /** * 配置验证码资源存储器 * @return ResourceStore */ @Bean public ResourceStore resourceStore() { // 使用简单的本地内存存储器,实际项目中可以使用数据库等存储 LocalMemoryResourceStore resourceStore = new LocalMemoryResourceStore(); // 配置背景图 // arg1: 验证码类型(SLIDER、ROTATE、CONCAT、WORD_IMAGE_CLICK) // arg2: Resource对象,包含: 资源类型(calsspath、file、url)、文件路径、tag标签 resourceStore.addResource(CaptchaTypeConstant.SLIDER, new Resource("classpath", "bgimages/1.png", "default")); resourceStore.addResource(CaptchaTypeConstant.SLIDER, new Resource("classpath", "bgimages/2.png", "default")); resourceStore.addResource(CaptchaTypeConstant.ROTATE, new Resource("classpath", "bgimages/3.png", "default")); resourceStore.addResource(CaptchaTypeConstant.CONCAT, new Resource("classpath", "bgimages/4.png", "default")); resourceStore.addResource(CaptchaTypeConstant.WORD_IMAGE_CLICK, new Resource("classpath", "bgimages/5.png", "default")); return resourceStore; }}五、开发验证码接口(生成+校验)
直接写一个Controller,提供两个核心接口:验证码生成接口、验证码校验接口,代码直接复制,注释写清每一步作用。

先导入需要的包,避免导错类:
import cloud.tianai.captcha.application.ImageCaptchaApplication;import cloud.tianai.captcha.application.vo.ImageCaptchaVO;import cloud.tianai.captcha.common.response.ApiResponse;import cloud.tianai.captcha.generator.common.model.dto.GenerateParam;import com.example.shardingspheredemo.entity.CheckParam;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.*;@RestController@RequestMapping("/captcha")public class CaptchaController { // 直接注入Starter提供的核心操作类 @Autowired private ImageCaptchaApplication imageCaptchaApplication; /** * 1. 生成行为验证码 * @param type 验证码类型,默认滑块验证码,支持SLIDER、ROTATE、WORD_IMAGE_CLICK * @return 验证码数据,直接返回给前端渲染 */ @PostMapping("/generate") public ApiResponse generateCaptcha( @RequestParam(value = "type", defaultValue = "SLIDER") String type) { // 调用核心方法生成验证码,返回前端需要的图片、滑块、校验ID等数据 return imageCaptchaApplication.generateCaptcha(GenerateParam.builder() .type(type) .build()); } /** * 2. 校验验证码(前端拖动/点选后调用) */ @PostMapping("/check") public ApiResponse<!--?--> checkCaptcha(@RequestBody CheckParam param) { // 校验参数:唯一ID + 用户操作轨迹 ApiResponse<!--?--> response = imageCaptchaApplication.matching(param.getId(), param.getData()); // 校验成功后,可在这里生成临时token,存入Redis,供登录接口二次校验,防止验证码复用 if (response.isSuccess()) { // 业务扩展:生成validToken,返回给前端,登录时携带 return ApiResponse.ofSuccess("验证通过"); } return response; }} 代码说明:
- 默认滑块验证码,前端传type=ROTATE就是旋转验证码,type=WORD_IMAGE_CLICK就是文字点选
- 校验成功后一定要做防复用处理,生成临时token,避免一个验证码多次调用接口
六、接口测试+前端对接
6.1 后端接口测试
启动SpringBoot项目,直接用Postman测试生成接口,访问:
POST http://localhost:8080/captcha/generate?type=SLIDER
正常返回结果包含:验证码唯一ID、背景图base64、滑块图base64、校验相关参数,前端直接拿这些数据渲染即可。
6.2 前端极简对接
tianai-captcha有官方原生JS SDK,不用依赖Vue/React,直接引入即可,前端核心逻辑:
- 请求后端生成接口,获取验证码数据
- 渲染验证码组件,监听用户操作
- 用户操作完成后,携带id和轨迹调用校验接口
前端代码不用自己手写,直接去Gitee官方仓库下载web-sdk,引入对应的js和css,初始化时对接后端接口就行,适配所有前端框架。
七、扩展优化
- 开启二次验证:敏感接口(如支付、修改密码)开启二次验证,配置captcha.secondary.enabled=true
- 日志监控:添加AOP监控验证码接口调用频次,拦截异常请求
- 限流防护:给验证码接口加接口限流,防止恶意请求打满服务器
八、总结
SpringBoot3集成tianai-captcha全程不到10分钟,依赖+配置+接口三步搞定,比自己手写验证码逻辑省太多时间,而且行为验证码的用户体验远优于传统字符验证码,安全性能也能满足大部分项目需求。
整个集成过程没有复杂的自定义配置,Starter封装得很完善,新手也能快速落地,适合登录、注册、短信发送、表单提交等需要人机验证的场景。
💻 配套实训环境与动手练习
本文涉及的相关技术指令、开发环境与工具链已内置在边学边练在线实验室中,无需繁琐安装配置,随时在浏览器中实践体验: