SpringBoot 集成 AJ-Captcha 实现滑动验证码，保姆级教程 + 避坑指南

一、前言

在 Web 开发中，验证码是防止恶意攻击、暴力破解、机器人刷接口的核心防线，而滑动验证码相比传统图形验证码，体验更流畅、安全性更高，是目前主流的验证方案。
本文基于AJ-Captcha（安居客开源的滑动验证码组件），手把手教你在SpringBoot + Spring Security项目中集成滑动验证码、点选验证码，解决接口放行、配置优化、前后端对接等问题，代码可直接复用！

二、AJ-Captcha 简介

AJ-Captcha 是一款开源、轻量、无侵入的 Java 验证码组件，支持：
滑动验证码（拼图）：最常用，用户体验极佳
点选验证码：文字 / 图片点选，安全性更高
支持本地缓存 / Redis 缓存，支持接口限流、超时设置
开箱即用，无需复杂配置，适配 SpringBoot/SpringMVC
官方 GitHub：aj-captcha

三、环境准备

1. 核心依赖
在pom.xml中引入 AJ-Captcha 启动器，1.4.0 版本稳定易用：

<!-- AJ-Captcha 滑动验证码核心依赖 --><dependency><groupId>com.anji-plus</groupId><artifactId>captcha-spring-boot-starter</artifactId><version>1.4.0</version></dependency>

2. 项目结构（参考）

com.itl.project ├── system/controller/CaptchaCodeController.java# 验证码接口控制器├── framework/config/SecurityConfig.java# SpringSecurity配置└── application.yml# 验证码配置文件

四、后端核心代码实现

1. 验证码控制器（CaptchaCodeController）
提供获取验证码和校验验证码两个核心接口，直接调用 AJ-Captcha 提供的CaptchaService即可，无需手写逻辑：

package com.itl.project.system.controller;importcom.anji.captcha.model.common.ResponseModel;importcom.anji.captcha.model.vo.CaptchaVO;importcom.anji.captcha.service.CaptchaService;importorg.springframework.web.bind.annotation.*;importjavax.annotation.Resource;/** * 滑动验证码接口控制器 */ @RestController @RequestMapping("/captcha")public class CaptchaCodeController{// AJ-Captcha 核心服务类 @Resource private CaptchaService captchaService;/** * 获取验证码（支持GET/POST） * @param captchaType 验证码类型：slide(滑动)、block(点选)* @return 验证码图片、坐标等数据 */ @RequestMapping(value="/get", method={RequestMethod.GET, RequestMethod.POST})public ResponseModel get(@RequestParam(value="type", defaultValue="slide")String captchaType){CaptchaVO captchaVO=new CaptchaVO();captchaVO.setCaptchaType(captchaType);returncaptchaService.get(captchaVO);}/** * 校验验证码 * @param captchaVO 前端传递的验证数据（唯一标识+滑动坐标） * @return 验证结果：成功/失败 */ @PostMapping("/check")public ResponseModel check(@RequestBody CaptchaVO captchaVO){returncaptchaService.check(captchaVO);}}

2. YML 配置文件
在application.yml中添加验证码配置，自定义图片、缓存、限流规则：

aj: captcha: aes-status:false# 关闭AES加密（测试环境，生产可开启）cache-type:local# 缓存类型：local(本地)、redis(分布式)expires-in:300# 验证码有效期：5分钟（单位秒）req-frequency-limit-count:50# 接口限流：50次/分钟cache-number:1000# 本地缓存最大数量jigsaw: classpath:images/jigsaw# 滑动验证码背景图存放路径pic-click: classpath:images/pic-click# 点选验证码背景图路径slip-offset:30# 滑动误差允许值（像素） 越大精度越好 也就是越容易通过

3. Spring Security 放行验证码接口（关键！）
如果项目使用Spring Security，必须放行/captcha/get和/captcha/check接口，否则会被拦截无法访问：

// SecurityConfig.java 核心配置 @Override protected void configure(HttpSecurity httpSecurity)throws Exception{httpSecurity .csrf().disable().sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS).and().authorizeRequests()// 放行登录、验证码接口 .antMatchers("/login","/captcha/get", // 放行获取验证码"/captcha/check"// 放行校验验证码).permitAll()// 其他请求需要认证 .anyRequest().authenticated();}

五、前后端对接流程

1. 前端请求获取验证码
前端调用GET /captcha/get?type=slide接口；
后端返回背景图、滑块图、唯一标识（token）；
前端渲染滑动验证码组件，用户拖动滑块完成验证。

2. 前端提交验证结果
前端将验证码 token + 滑动坐标封装为CaptchaVO；
调用POST /captcha/check接口提交验证；
后端返回验证结果，验证通过后才可执行登录 / 提交表单。

3. 接口返回格式（标准 JSON）

// 获取验证码成功{"repCode":"0000","repMsg":"success","data":{"captchaType":"slide","token":"xxxx-xxxx-xxxx","backgroundImage":"data:image/png;base64,xxxx","sliderImage":"data:image/png;base64,xxxx"}}// 验证成功{"repCode":"0000","repMsg":"验证成功","data":true}

六、常见问题 & 避坑指南

1. 验证码接口 401/403 无权限
原因：Spring Security 未放行接口
解决方案：在SecurityConfig中添加/captcha/**放行规则。

2. 本地运行正常，部署服务器报错
原因：服务器未加载验证码背景图
解决方案：确保classpath:images/目录下存在验证码图片，或改为绝对路径。

3. 验证码验证失败（坐标不匹配）
原因：滑动误差值设置过小
解决方案：调大slip-offset（建议 30-50 像素）。

4. 分布式环境下验证码失效
原因：使用本地缓存cache-type: local
解决方案：改为cache-type: redis，集成 Redis 缓存。

七、扩展优化

生产环境开启 AES 加密：aes-status: true，防止前端数据篡改；
自定义验证码图片：替换jigsaw和pic-click路径下的图片，适配项目风格；
接口限流：调整req-frequency-limit-count，防止恶意刷接口；
结合登录接口：登录前强制校验验证码，验证通过才执行登录逻辑。

八、总结

AJ-Captcha 是 SpringBoot 项目集成滑动验证码的最优选择，核心优势：
✅ 零代码侵入，仅需控制器 + 配置文件即可完成集成；
✅ 支持滑动 / 点选双验证码模式，满足不同场景；
✅ 适配 Spring Security，轻松解决权限拦截问题；
✅ 轻量高效，支持分布式部署，生产环境稳定可用。