一、前言

在 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;

import com.anji.captcha.model.common.ResponseModel;
import com.anji.captcha.model.vo.CaptchaVO;
import com.anji.captcha.service.CaptchaService;
import org.springframework.web.bind.annotation.*;

import javax.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);
        return captchaService.get(captchaVO);
    }

    /**
     * 校验验证码
     * @param captchaVO 前端传递的验证数据（唯一标识+滑动坐标）
     * @return 验证结果：成功/失败
     */
    @PostMapping("/check")
    public ResponseModel check(@RequestBody CaptchaVO captchaVO) {
        return captchaService.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，轻松解决权限拦截问题；
✅ 轻量高效，支持分布式部署，生产环境稳定可用。