一、前言在 Web 开发中验证码是防止恶意攻击、暴力破解、机器人刷接口的核心防线而滑动验证码相比传统图形验证码体验更流畅、安全性更高是目前主流的验证方案。本文基于AJ-Captcha安居客开源的滑动验证码组件手把手教你在SpringBoot Spring Security项目中集成滑动验证码、点选验证码解决接口放行、配置优化、前后端对接等问题代码可直接复用二、AJ-Captcha 简介AJ-Captcha 是一款开源、轻量、无侵入的 Java 验证码组件支持滑动验证码拼图最常用用户体验极佳点选验证码文字 / 图片点选安全性更高支持本地缓存 / Redis 缓存支持接口限流、超时设置开箱即用无需复杂配置适配 SpringBoot/SpringMVC官方 GitHubaj-captcha三、环境准备1. 核心依赖在pom.xml中引入 AJ-Captcha 启动器1.4.0 版本稳定易用!-- AJ-Captcha 滑动验证码核心依赖 --dependencygroupIdcom.anji-plus/groupIdartifactIdcaptcha-spring-boot-starter/artifactIdversion1.4.0/version/dependency项目结构参考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(valuetype, defaultValueslide)String captchaType){CaptchaVO captchaVOnew 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?typeslide接口后端返回背景图、滑块图、唯一标识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轻松解决权限拦截问题✅ 轻量高效支持分布式部署生产环境稳定可用。