diff --git a/readme.md b/readme.md index 2c2fd0d..ae7c45a 100644 --- a/readme.md +++ b/readme.md @@ -1,7 +1,8 @@ 这是一个滑块验证码的实现 ## [在线体验](https://www.tianai.cloud) ## 验证码demo移步 [tianai-captcha-demo](https://gitee.com/tianai/tianai-captcha-demo) -## 不说废话，直接上成品 + + ![](image/1.png) ![](image/2.png) ![](image/3.png) @@ -15,7 +16,9 @@ ## 快速上手 - 如果是SpringBoot开发者可直接使用SpringBoot快速启动器[tianai-captcha-springboot-starter](https://gitee.com/tianai/tianai-captcha-springboot-starter) -1. 导入xml + +### 1. 导入xml + ```xml @@ -24,46 +27,76 @@ 1.2.7 ``` -2. 使用 `SliderCaptchaTemplate`获取滑块验证码 +### 2. 使用 `SliderCaptchaTemplate`获取滑块验证码 + ```java public static void main(String[] args) throws InterruptedException { SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager(); StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true); // 生成滑块图片 SliderCaptchaInfo slideImageInfo = sliderCaptchaTemplate.getSlideImageInfo(); - // 获取背景图片的base64 - String backgroundImage = slideImageInfo.getBackgroundImage(); - // 获取滑块图片 - slideImageInfo.getSliderImage(); - System.out.println(slideImageInfo); - // 计算滑块到凹槽的百分比，用户存到缓存中供校验使用 + // 负责计算一些数据存到缓存中，用于校验使用 + // SliderCaptchaValidator负责校验用户滑动滑块是否正确和生成滑块到凹槽的百分比值 SliderCaptchaValidator sliderCaptchaValidator = new BasicCaptchaTrackValidator(); - // 滑块的百分比 + // 计算滑块到凹槽的百分比，用户存到缓存中供校验使用 float percentage = sliderCaptchaValidator.calcPercentage(slideImageInfo.getX(), SliderCaptchaInfo.getBgImageWidth()); - - // 校验 - - // 用户传来的百分比和滑块的百分比校验是否正确，如果正确的话说明移动到了指定凹槽 - boolean check =sliderCaptchaValidator.checkPercentage(0.2f, percentage); - // 用户传来的行为轨迹和滑动百分比进行校验，(有了滑动行为轨迹校验，是对 checkPercentage(..)方法的增强,建议使用这个方法进行校验 ) - check = sliderCaptchaValidator.valid(sliderCaptchaTrack, percentage); - + // 这个map数据应该存到缓存中，校验的时候需要用到该数据 + Map map = new HashMap<>(4); + map.put("percentage", percentage); + // map中可添加自定义数据用于自定义逻辑校验 } ``` -# 常用接口 -- 自定义 `SliderCaptchaValidator` 校验器 +### 3. 使用`SliderCaptchaValidator`校验 + ```java -// 该接口负责对用户滑动验证码后传回的数据进行校验，比如滑块是否滑到指定位置，滑块行为轨迹是否正常等等 -// 该接口的默认实现有 -// SimpleSliderCaptchaValidator 校验用户是否滑到了指定缺口处 -// BasicCaptchaTrackValidator 是对 SimpleSliderCaptchaValidator增强 -// BasicCaptchaTrackValidator是对SimpleSliderCaptchaValidator的增强 对滑动轨迹进行了简单的验证 -// 友情提示 因为BasicCaptchaTrackValidator 里面校验滑动轨迹的算法已经开源，有强制要求的建议重写该接口的方法，避免被破解 +SliderCaptchaValidator sliderCaptchaValidator = new BasicCaptchaTrackValidator(); + +// 用户传来的行为轨迹和进行校验 +// - sliderCaptchaTrack为前端传来的滑动轨迹数据 +// - map 为生成验证码时缓存的map数据 +boolean check = sliderCaptchaValidator.valid(sliderCaptchaTrack, map); +// 如果只想校验用户是否滑到指定凹槽即可，也可以使用 +// - 参数1 用户传来的百分比数据 +// - 参数2 生成滑块是真实的百分比数据 +check =sliderCaptchaValidator.checkPercentage(0.2f, percentage); ``` -- 添加自定义图片资源 - - 自定义图片资源大小为 590*360 格式为jpg + +# 常用接口 + +### 生成带有混淆滑块的图片 + +```java +SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager(); +StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true); +// 生成滑块图片 +SliderCaptchaInfo slideImageInfo = sliderCaptchaTemplate.getSlideImageInfo(GenerateParam.builder() + .sliderFormatName("jpeg") + .backgroundFormatName("png") + // 是否添加混淆滑块 + .obfuscate(true) + .build()); +``` + +### 生成webp格式的滑块图片 + +```java +SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager(); +StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true); +// 生成滑块图片 +SliderCaptchaInfo slideImageInfo = sliderCaptchaTemplate.getSlideImageInfo(GenerateParam.builder() + .sliderFormatName("webp") + .backgroundFormatName("webp") + // 是否添加混淆滑块 + .obfuscate(false) + .build()); +``` + +### 添加自定义图片资源 + +- 自定义图片资源大小为 590*360 格式为jpg + ```java ResourceStore resourceStore = sliderCaptchaResourceManager.getResourceStore(); // 添加classpath目录下的 aa.jpg 图片 @@ -72,12 +105,14 @@ public static void main(String[] args) throws InterruptedException { resourceStore.addResource(new Resource(URLResourceProvider.NAME, "http://www.xx.com/aa.jpg")); // 内置了通过url 和 classpath读取图片资源，如果想扩展可实现 ResourceProvider 接口，进行自定义扩展 ``` -- 添加自定义模板资源 - - 系统内置了2套模板，可以到QQ群:1021884609 文件中获取更多模板或者自己制作模板 - - 模板图片格式 - - 滑块大小为 110*110 格式为png - - 凹槽大小为 110*110 格式为png - - 模板大小为 110*360 格式为png，该图为固定格式，是一张纯透明图片 +### 添加自定义模板资源 + +- 系统内置了2套模板，可以到QQ群:1021884609 文件中获取更多模板或者自己制作模板 +- 模板图片格式 + - 滑块大小为 110*110 格式为png + - 凹槽大小为 110*110 格式为png + - 模板大小为 110*360 格式为png，该图为固定格式，是一张纯透明图片 + ```java ResourceStore resourceStore = sliderCaptchaResourceManager.getResourceStore();= Map template1 = new HashMap<>(4); @@ -94,8 +129,30 @@ public static void main(String[] args) throws InterruptedException { //为方便快速上手 系统本身自带了一张图片和两套滑块模板，如果不想用系统自带的可以不让它加载系统自带的 // 第二个构造参数设置为false时将不加载默认的图片和模板 SliderCaptchaTemplate sliderCaptchaTemplate = new DefaultSliderCaptchaTemplate(sliderCaptchaResourceManager, false); + ``` + +### 自定义 `SliderCaptchaValidator` 校验器 + +```java +// 该接口负责对用户滑动验证码后传回的数据进行校验，比如滑块是否滑到指定位置，滑块行为轨迹是否正常等等 +// 该接口的默认实现有 +// SimpleSliderCaptchaValidator 校验用户是否滑到了指定缺口处 +// BasicCaptchaTrackValidator 是对 SimpleSliderCaptchaValidator增强 +// BasicCaptchaTrackValidator是对SimpleSliderCaptchaValidator的增强 对滑动轨迹进行了简单的验证 +// 友情提示 因为BasicCaptchaTrackValidator 里面校验滑动轨迹的算法已经开源，有强制要求的建议重写该接口的方法，避免被破解 ``` -- 扩展，对`StandardSliderCaptchaTemplate`增加了缓存模块 + +### 自定义 `ResourceProvider` 实现自定义文件读取策略， 比如 oss之类的 + +```java + // 实现了 ResourceProvider 后 + SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager(); + StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true); + // 注册 + sliderCaptchaResourceManager.registerResourceProvider(new CustomResourceProvider()); +``` +### 扩展，对`StandardSliderCaptchaTemplate`增加了缓存模块 + ```java public static void main(String[] args) throws InterruptedException { // 使用 CacheSliderCaptchaTemplate 对滑块验证码进行缓存，使其提前生成滑块图片 @@ -115,13 +172,5 @@ public static void main(String[] args) throws InterruptedException { System.out.println(slideImageInfo); } ``` -- 自定义 `ResourceProvider` 实现自定义文件读取策略， 比如 oss之类的 -```java - // 实现了 ResourceProvider 后 - SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager(); - StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true); - // 注册 - sliderCaptchaResourceManager.registerResourceProvider(new CustomResourceProvider()); -``` # qq群: 1021884609 \ No newline at end of file