tianaiCAPTCHA 技术文档

1. 安装指南

1.1 环境要求

• Java 8+
• Maven 3.0+

1.2 Maven依赖安装

在项目的pom.xml文件中添加以下依赖：

<dependency>
    <groupId>cloud.tianai.captcha</groupId>
    <artifactId>tianai-captcha</artifactId>
    <version>1.5.2</version>
</dependency>

1.3 SpringBoot项目特别说明

对于SpringBoot项目，建议使用专门的starter工具：

• tianai-captcha-springboot-starter

2. 项目使用说明

2.1 核心组件初始化

首先需要构建ImageCaptchaApplication实例，负责验证码的生成和校验：

ImageCaptchaApplication application = TACBuilder.builder()
        .addDefaultTemplate() // 添加默认模板
        .addResource("SLIDER", new Resource("classpath", "META-INF/cut-image/resource/1.jpg"))
        .addResource("WORD_IMAGE_CLICK", new Resource("classpath", "META-INF/cut-image/resource/1.jpg"))
        .addResource("ROTATE", new Resource("classpath", "META-INF/cut-image/resource/1.jpg"))
        .build();

2.2 验证码类型

目前支持以下验证码类型：

• SLIDER：滑块验证码
• ROTATE：旋转验证码
• CONCAT：滑动还原验证码
• WORD_IMAGE_CLICK：文字点选验证码

3. API使用文档

3.1 生成验证码

// 生成滑块验证码
CaptchaResponse<ImageCaptchaVO> res = application.generateCaptcha("SLIDER");

3.2 校验验证码

// 校验验证码
String id = res.getId(); // 从生成响应中获取ID
ImageCaptchaTrack imageCaptchaTrack = null; // 前端传回的轨迹数据
ApiResponse<?> valid = application.matching(id, new MatchParam(imageCaptchaTrack));

3.3 二次验证示例

CacheStore cacheStore = new LocalCacheStore();
if (valid.isSuccess()) {
    String token = UUID.randomUUID().toString();
    cacheStore.setCache(token, new AnyMap(), 5L, TimeUnit.MINUTES);
}

4. 项目安装方式

4.1 标准安装

1. 在项目中添加Maven依赖
2. 初始化ImageCaptchaApplication
3. 调用API生成和校验验证码

4.2 SpringBoot项目安装

1. 使用专门的starter工具
2. 按照starter文档进行配置

4.3 资源文件配置

可以通过addResource方法添加自定义背景图片资源：

.addResource("验证码类型", new Resource("资源类型", "资源路径"))

其中资源类型支持：

• classpath：类路径资源
• file：文件系统资源
• url：网络资源

5. 注意事项

1. 该项目只负责生成和校验验证码数据，二次验证需要自行实现
2. 建议配合tianai-captcha-web-sdk使用
3. 验证码类型字符串需使用大写形式