tianai-captcha 入门：行为验证码接入指南
登录接口裸奔一晚上，脚本就能帮你把密码库撞穿。验证码是人机之间的第一道闸，这篇讲怎么用 tianai-captcha 把这道闸装上。
为什么需要行为验证码
传统的图形验证码（扭曲字母数字）有两个问题：对用户不友好（看不清、输错率高），对机器不再有效（OCR 识别率高得吓人）。行为验证码换了个思路——滑块拼图、点选文字，用户拖一下就完成验证，体验顺滑；而脚本要过这关，得模拟真实拖拽轨迹、图像识别缺口位置，成本一下子抬高几个数量级。
tianai-captcha 是国内开源的一款行为验证码组件，支持滑动拼图、旋转、滑动复原等多种玩法，提供 Spring Boot starter，后端生成校验数据和前端展示组件都齐了。
引入与配置
<dependency>
<groupId>cloud.tianai.captcha</groupId>
<artifactId>tianai-captcha-springboot-starter</artifactId>
<version>1.4.1</version>
</dependency>
starter 引入后基本零配置可跑，常用配置：
tianai-captcha:
# 验证码缓存前缀（配合 redis 时使用）
prefix: captcha
# 二次验证开关：第一次滑过之后换正式的加密校验，防重放
secondary-validation: true
background:
url: https://example.com/captcha-bg/ # 自定义背景图目录
背景图可以直接用内置的，也可以放几张自己的图，滑动拼图的观感立刻个性化。
后端两步：生成 + 校验
第一步，生成验证码，返回给前端渲染：
@RestController
@RequestMapping("/captcha")
public class CaptchaController {
@Autowired
private CaptchaService captchaService;
@PostMapping("/generate")
public Response<CaptchaVO> generate() {
ImageCaptchaVO image = (ImageCaptchaVO) captchaService.generateCaptcha(
ImageType.SLIDE_BLOCK.getValue());
// image.id 和 image.backgroundImage 等返回给前端
return Response.success(convert(image));
}
}
第二步，校验。用户滑完，前端把滑动轨迹和位置提交上来：
@PostMapping("/check")
public Response<String> check(@RequestBody CaptchaCheckRequest req) {
ImageCodeVO imageCode = buildImageCode(req);
boolean match = captchaService.matching(imageCode);
if (!match) {
throw new BizException(ResponseCodeEnum.CAPTCHA_MISMATCH);
}
// 校验通过：发一个一次性 ticket，登录接口凭 ticket 免二次验证
String ticket = issueOneTimeTicket();
return Response.success(ticket);
}
这里有个防重放的关键设计：滑块坐标是固定答案，如果直接把「校验通过」当作登录凭证，攻击者拿到坐标参数就能无限重放。所以正确做法是校验通过后签发一个一次性、短时效的 ticket（通常存 Redis 60 秒），真正的登录接口只认 ticket。tianai 的 secondary-validation 机制就是干这个的。
前端接入
官方提供了对应的 JS 组件，引入后只要指定后端的生成/校验地址：
import TianAiCaptcha from 'tianai-captcha-js'
const captcha = new TianAiCaptcha({
el: '#captcha-box',
generateUrl: '/api/captcha/generate',
checkUrl: '/api/captcha/check',
onSuccess: (ticket) => {
// 拿到 ticket，塞进登录请求，走真正的登录逻辑
login(username, password, ticket)
},
})
captcha.show()
用户体验路径：点登录 → 弹出滑块 → 滑对 → 登录成功。全程不离开当前页面。
生产环境三个提醒
背景图与安全的关系：滑动拼图的安全性部分来自缺口位置不可预测，背景图固定几张且被脚本扒走分析后，识别难度会下降，定期换图有实际意义。
频控仍然要有：验证码挡的是自动化批量行为，但人工肉鸡（打码平台）可以真人滑。登录接口该有的 IP 频控、账号失败锁定，一样都不能省。验证码是第一道闸，不是唯一一道。
无障碍与降级：滑块验证码对部分视障用户不友好，条件允许的话提供邮箱验证码等替代通道，别把真实用户挡在门外。
小结
tianai-captcha 的价值在于把「生成拼图、校验轨迹、防重放」这一整套打包成了 starter，后端十几行代码就有工业级的验证码能力。接入时记住核心链路：生成 → 前端滑 → 校验换一次性 ticket → ticket 走登录，顺序不能乱，重放攻击也就无机可乘。本站登录接口的人机校验就是这条链路在跑。