外观
验证码验证拦截器 🔒
功能概述 📝
验证码验证拦截器用于对接口进行验证码校验，支持多种验证方式和场景，有效防止恶意请求和自动化攻击。
功能特性 ✨
验证方式
- 🖼️ 常规图片验证码：支持自定义长度和复杂度
- 🔄 自定义验证接口：支持业务系统自定义验证逻辑
- 🌐 第三方验证：支持腾讯云和阿里云验证码服务
核心功能
- ✅ 多种验证码类型支持
- 🔐 业务场景隔离
- 🎯 灵活的参数获取方式
- ⏱️ 验证码过期控制
- 🚦 请求限流保护
配置说明 ⚙️
基础配置参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| enabled | boolean | 否 | false | 是否启用验证码拦截器 |
| items | array | 是 | - | 验证规则配置列表 |
验证规则配置(items)
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| generate-urls | array | 否 | - | 生成验证码的接口地址列表 |
| verify-urls | array | 是 | - | 需要验证码校验的接口地址列表 |
| business-key | string | 否 | - | 业务标识，用于隔离不同业务验证码 |
| parameter-type | string | 是 | - | 参数获取类型：header(请求头)、query(查询参数)、body(请求体) |
| code-field-name | string | 否 | - | 验证码临时ID参数名 |
| value-field-name | string | 否 | - | 验证码值参数名 |
| expire | string | 否 | PT5M | 验证码有效期，如PT30M表示30分钟 |
| verify-type | string | 否 | ordinary | 验证方式：ordinary: 常规验证servlet: 接口验证tencent: 腾讯云验证码aliyun: 阿里云验证码 |
| verify-uri | string | 否 | - | 自定义验证接口地址(verify-type=servlet时必填) |
| verify-timeout | string | 否 | PT1M | 验证请求超时时间 |
| verify-params | object | 否 | - | 验证参数配置(key-value形式) |
| rate-limiter | boolean | 否 | false | 是否启用限流保护 |
使用示例 📝
1. 常规图片验证码
yaml
wueasy:
gateway:
filter:
captcha:
enabled: true #是否启用，默认false
items:
- generate-urls:
- /demo/captcha # 生成验证码接口
verify-urls:
- /demo/login # 需要验证的接口
business-key: login # 业务标识
parameter-type: body # 参数获取方式
code-field-name: code # 验证码ID字段
value-field-name: captcha # 验证码值字段
expire: PT5M # 5分钟有效期
rate-limiter: true # 启用限流验证码接口说明
- 生成验证码接口示例：
java
@PostMapping("/captcha")
public Mono<ResultVo<CaptchaVo>> captcha() {
// 创建验证码
AbstractCaptcha captcha = CaptchaUtil.createLineCaptcha(150, 60, 5, 150);
// 设置字符生成器
captcha.setGenerator(new RandomGenerator("23456789ABCDEFGHJKLMNPQRSTUVWXYZ", 5));
CaptchaVo vo = new CaptchaVo();
vo.setCode(captcha.getCode()); // 验证码ID
vo.setCaptcha(captcha.getImageBase64Data()); // Base64图片数据
return Mono.just(ResultVo.ok(vo));
}- 接口返回数据格式：
json
{
"errorNo": 0,
"data": {
"code": "88e8d3552ed0d2b8467bc5e497614e69",
"captcha": "data:image/png;base64,..."
}
}- 验证接口请求参数：
json
{
"accountNo": "admin",
"password": "123456",
"code": "88e8d3552ed0d2b8467bc5e497614e69",
"captcha": "4myn"
}2. 自定义验证码
yaml
wueasy:
gateway:
filter:
captcha:
enabled: true
items:
- verify-urls:
- /demo/login
parameter-type: body
verify-type: servlet
verify-uri: lb://web1/verifyCaptcha # 负载均衡方式
# verify-uri: http://127.0.0.1:8081/verifyCaptcha # 直接指定地址
verify-params: # 验证参数映射
code: code
captcha: captcha自定义验证接口说明
验证接口必须满足以下要求：
- 使用POST方法
- 支持JSON格式的请求体
- 返回ResultVo格式数据
- 示例代码：
java
@PostMapping("/verifyCaptcha")
public Mono<ResultVo<Void>> verifyCaptcha(@RequestBody @Valid DataMap map) {
// 自定义验证逻辑
log.info("验证参数：{}", JsonHelper.toJsonString(map));
log.info("用户信息：{}", JsonHelper.toJsonString(UserHelper.getSystemParameter()));
return Mono.just(ResultVo.ok());
}3. 腾讯云验证码
yaml
wueasy:
gateway:
filter:
captcha:
enabled: true
items:
- verify-urls:
- /demo/login
parameter-type: body
verify-type: tencent
verify-params:
secretId: YOUR_SECRET_ID # 腾讯云密钥ID
secretKey: YOUR_SECRET_KEY # 腾讯云密钥Key
captchaAppId: YOUR_APP_ID # 验证码应用ID
appSecretKey: YOUR_APP_KEY # 验证码应用密钥
randstr: randstr # 随机字符串参数名
ticket: ticket # 验证票据参数名
region: ap-guangzhou # 服务地域4. 阿里云验证码
yaml
wueasy:
gateway:
filter:
captcha:
enabled: true
items:
- verify-urls:
- /demo/login
parameter-type: body
verify-type: aliyun
verify-params:
sceneId: YOUR_SCENE_ID # 场景ID
accessKeyId: YOUR_ACCESS_KEY # 访问密钥ID
accessKeySecret: YOUR_SECRET_KEY # 访问密钥Secret
captchaVerifyParam: captchaVerifyParam # 验证参数名
# host: captcha.cn-shanghai.aliyuncs.com # 可选，默认上海地域⚠️ 注意事项
安全配置
- 验证码接口需要合理配置权限
- 验证码有效期建议5分钟以内
- 建议开启限流保护机制
接口要求
- 自定义验证接口必须支持POST请求
- 必须使用JSON格式的请求体
- 需要正确处理超时情况
第三方服务
- 提前申请相关密钥信息
- 正确配置服务地域
- 做好异常处理和降级方案
性能优化
- 合理设置验证码复杂度
- 适当配置限流阈值
- 监控验证码服务性能