Go Gateway

外观

验证码验证拦截器 🔒 ​

功能概述 📝 ​

验证码验证拦截器用于对接口进行验证码校验，支持多种验证方式和场景，有效防止恶意请求和自动化攻击。

功能特性 ✨ ​

验证方式 ​

  • 🖼️ 图片验证码：支持自定义长度和复杂度
  • ☁️ 阿里云验证码：集成阿里云智能验证服务，提供更强的安全防护
  • 🛡️ 腾讯云验证码：集成腾讯云天御验证码服务，提供智能风险识别和防护
  • 🔗 通用 CAP 验证码：支持自建/第三方兼容的 siteverify 接口

核心功能 ​

  • ✅ 多种验证码类型支持（图片验证码、阿里云智能验证、腾讯云天御验证码）
  • 🔐 业务场景隔离
  • 🎯 灵活的参数获取方式
  • ⏱️ 验证码过期控制
  • 🚦 请求限流保护
  • 🛡️ 智能风险识别（阿里云验证码、腾讯云验证码）
  • 🌐 多地域部署支持

配置说明 ⚙️ ​

基础配置参数 ​

参数名类型必填默认值说明
enabledboolean否false是否启用验证码拦截器
rulesarray[object]是-验证规则配置列表

验证规则配置(rules) ​

参数名类型必填默认值说明
generate-urlsarray[string]否-生成验证码的接口地址列表
verify-urlsarray[string]是-需要验证码校验的接口地址列表
business-keystring否bearer业务标识，用于隔离不同业务验证码
parameter-typestring是-参数获取类型：header(请求头)、query(查询参数)、body(请求体)
code-field-namestring否-验证码临时ID参数名
value-field-namestring否-验证码值参数名
expireDuration否5m验证码有效期，如30m表示30分钟
image-typestring否-类型；string 数字字母，number 数字，math 数学，random 随机
image-widthnumber否-图片宽度
image-heightnumber否-图片高度
image-lengthnumber否-图片长度
rate-limiterboolean否false是否启用限流保护（主要处理触发限流后，可以通过验证码恢复）
verify-typestring否-验证类型：aliyun（阿里云）、tencent（腾讯云）、cap（通用）
verify-uristring否-第三方验证码 API 地址；支持 https:// 或 lb://<service>/<path>（通过 Nacos 解析为健康实例）
verify-timeoutDuration否10s第三方验证码请求超时时间
verify-paramsmap[string]string否-不同类型的参数参见下文“各类型参数说明”

各类型参数说明（verify-params） ​

  1. 阿里云 aliyun
  • sceneId：场景 ID（必填）
  • accessKeyId：AK（必填）
  • accessKeySecret：SK（必填）
  • captchaVerifyParam：前端返回的验证码字段名（必填，根据 parameter-type 从 header/query/body 读取）
  • host：服务域名，默认 captcha.cn-shanghai.aliyuncs.com（可选）
  1. 腾讯云 tencent
  • region：地域，默认 ap-guangzhou（可选）
  • secretId：密钥 ID（必填）
  • secretKey：密钥 Key（必填）
  • appId：验证码应用 ID（必填）
  • appSecretKey：验证码应用密钥（必填）
  • randstr：前端返回的随机串字段名（必填，根据 parameter-type 读取）
  • ticket：前端返回的票据字段名（必填，根据 parameter-type 读取）
  1. 通用 CAP cap
  • secret：验证密钥（必填）
  • siteKey：站点 key（必填；当前实现不拼入 URL，仅校验非空）
  • responseField：前端 token 字段名，默认 response

使用示例 📝 ​

基础图片验证码配置 ​

yaml
# 基础图片验证码配置
gateway:
  filter:
    captcha:
      enabled: true  # 是否启用，默认false
      rules:
        - generate-urls: 
            - /demo/captcha  # 生成验证码接口
          verify-urls: 
            - /demo/login    # 需要验证的接口
          business-key: login  # 业务标识
          parameter-type: body  # 参数获取方式
          code-field-name: code  # 验证码ID字段
          value-field-name: captcha  # 验证码值字段
          expire: 5m  # 5分钟有效期
          image-width: 150  # 图片宽度
          image-height: 70  # 图片高度
          image-length: 5  # 验证码长度

阿里云验证码配置 ​

需要外网访问权限；默认域名 https://captcha.cn-shanghai.aliyuncs.com/。

yaml
# 阿里云智能验证码配置
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        - verify-urls:
            - /api/login
            - /api/register
          parameter-type: body  # 从请求体获取验证参数
          verify-type: aliyun
          # verify-uri: https://captcha.cn-shanghai.aliyuncs.com/  # 不配置走默认域名
          verify-timeout: 10s
          verify-params:
            sceneId: "your_scene_id"
            accessKeyId: "your_access_key_id"
            accessKeySecret: "your_access_key_secret"
            captchaVerifyParam: "captchaVerifyParam"  # 前端返回的字段名，按 parameter-type 从请求中读取
            # host: "captcha.cn-shanghai.aliyuncs.com"

腾讯云验证码配置 ​

需要外网访问权限；默认域名 https://captcha.tencentcloudapi.com/。

yaml
# 腾讯云天御验证码配置
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        - verify-urls:
            - /api/login
            - /api/register
          parameter-type: body  # 从请求体获取验证参数
          verify-type: tencent
          verify-timeout: 10s
          verify-params:
            secretId: "your_secret_id"
            secretKey: "your_secret_key"
            appId: "your_app_id"
            appSecretKey: "your_app_secret_key"
            randstr: "randStr"  # 前端随机串字段名
            ticket: "ticket"    # 前端票据字段名
            # region: "ap-beijing"

通用 CAP 验证码配置 ​

用于自建或第三方兼容的通用 siteverify 接口。官网地址：https://capjs.js.org/

yaml
# 通用 CAP 验证码配置
gateway:
  routes: #路由配置
    - id: cap
      uri: http://192.168.3.200:3001
      predicates:
        - Path=/cap/*/challenge,/cap/*/redeem
      filters:
        - StripPrefix=1
  filter:
    captcha:
      enabled: true
      rules:
        - verify-type: cap
          verify-urls:
            - /demo/login2
          parameter-type: body
          verify-uri: http://192.168.3.200:3001/147e6084b8/siteverify
          verify-params: 
            siteKey: 147e6084b8
            secret: mBgKjyhIixitcbuIFevGItjYTNtHThw8v7Zyqsq1LMRA4UFswiBVQ
            responseField: captcha

说明：部分 CAP 服务的接口为 POST https://<instance>/<site_key>/siteverify，当前实现不将 siteKey 拼入 verify-uri，仅在参数中校验其非空。


响应说明：仅当响应为 `{ "success": true }` 时认为验证通过。

完整配置示例 ​

yaml
# 完整的验证码配置示例
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        # 登录验证码（数字字母混合）
        - generate-urls:
            - /auth/captcha
          verify-urls:
            - /auth/login
            - /auth/register
          business-key: auth
          parameter-type: body
          code-field-name: captchaId
          value-field-name: captchaCode
          expire: 5m
          image-type: string  # 数字字母混合
          image-width: 120
          image-height: 40
          image-length: 4
          rate-limiter: true
        
        # 重置密码验证码（纯数字）
        - generate-urls:
            - /password/captcha
          verify-urls:
            - /password/reset
          business-key: password-reset
          parameter-type: body
          code-field-name: code
          value-field-name: captcha
          expire: 10m
          image-type: number  # 纯数字
          image-width: 100
          image-height: 35
          image-length: 6
        
        # 敏感操作验证码（数学运算）
        - generate-urls:
            - /admin/captcha
          verify-urls:
            - /admin/delete/**
            - /admin/config/**
          business-key: admin-operation
          parameter-type: header
          code-field-name: X-Captcha-Id
          value-field-name: X-Captcha-Code
          expire: 3m
          image-type: math  # 数学运算
          image-width: 150
          image-height: 50
          image-length: 3
          rate-limiter: true
        
        # 公开接口验证码（随机类型）
        - generate-urls:
            - /public/captcha
          verify-urls:
            - /public/feedback
            - /public/contact
          business-key: public
          parameter-type: query
          code-field-name: captcha_id
          value-field-name: captcha_value
          expire: 15m
          image-type: random  # 随机类型
          image-width: 80
          image-height: 30
          image-length: 4
        
        # 腾讯云验证码（高安全级别）
        - verify-urls:
            - /secure/login
            - /secure/payment
          business-key: secure-operation
          parameter-type: body
          verify-type: tencent
          verify-timeout: 10s
          verify-params:
            secretId: "your_secret_id"
            secretKey: "your_secret_key"
            appId: "your_tencent_app_id"
            appSecretKey: "your_tencent_secret_key"
            region: "ap-beijing"
            randstr: "randStr"
            ticket: "ticket"

        # 通用 CAP 验证码
        - verify-urls:
            - /cap/verify
          parameter-type: body
          verify-type: cap
          verify-timeout: 8s
          verify-uri: https://captcha.example.com/siteverify
          verify-params:
            secret: "your_cap_secret"
            responseField: "response"

不同验证方式配置 ​

yaml
# 不同参数获取方式的验证码配置
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        # Header方式获取参数
        - generate-urls:
            - /api/captcha/header
          verify-urls:
            - /api/secure/login
          business-key: secure-auth
          parameter-type: header
          code-field-name: X-Captcha-Token
          value-field-name: X-Captcha-Value
          expire: 5m
          image-type: string
          image-width: 120
          image-height: 40
          image-length: 5
        
        # Query方式获取参数
        - generate-urls:
            - /api/captcha/query
          verify-urls:
            - /api/public/submit
          business-key: public-submit
          parameter-type: query
          code-field-name: token
          value-field-name: code
          expire: 10m
          image-type: number
          image-width: 100
          image-height: 35
          image-length: 4
        
        # Body方式获取参数（推荐）
        - generate-urls:
            - /api/captcha/body
          verify-urls:
            - /api/user/login
            - /api/user/register
          business-key: user-auth
          parameter-type: body
          code-field-name: captchaToken
          value-field-name: captchaInput
          expire: 5m
          image-type: string
          image-width: 150
          image-height: 60
          image-length: 5
          rate-limiter: true

业务场景配置 ​

yaml
# 不同业务场景的验证码配置
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        # 用户注册验证码（中等复杂度）
        - generate-urls:
            - /user/register/captcha
          verify-urls:
            - /user/register
          business-key: user-register
          parameter-type: body
          code-field-name: regCaptchaId
          value-field-name: regCaptchaCode
          expire: 10m
          image-type: string
          image-width: 120
          image-height: 40
          image-length: 4
          rate-limiter: true
        
        # 找回密码验证码（高复杂度）
        - generate-urls:
            - /password/forgot/captcha
          verify-urls:
            - /password/forgot
          business-key: password-recovery
          parameter-type: body
          code-field-name: forgotCaptchaId
          value-field-name: forgotCaptchaCode
          expire: 5m
          image-type: math
          image-width: 150
          image-height: 50
          image-length: 3
          rate-limiter: true
        
        # 评论提交验证码（低复杂度）
        - generate-urls:
            - /comment/captcha
          verify-urls:
            - /comment/submit
          business-key: comment-submit
          parameter-type: body
          code-field-name: commentCaptchaId
          value-field-name: commentCaptchaCode
          expire: 15m
          image-type: number
          image-width: 80
          image-height: 30
          image-length: 4
        
        # 支付验证码（最高安全级别）
        - generate-urls:
            - /payment/captcha
          verify-urls:
            - /payment/confirm
            - /payment/transfer
          business-key: payment-security
          parameter-type: body
          code-field-name: paymentCaptchaId
          value-field-name: paymentCaptchaCode
          expire: 3m
          image-type: math
          image-width: 200
          image-height: 80
          image-length: 5
          rate-limiter: true
        
        # 腾讯云验证码（企业级安全）
        - verify-urls:
            - /enterprise/login
            - /enterprise/sensitive-operation
          business-key: enterprise-security
          parameter-type: body
          verify-type: tencent
          verify-timeout: 15s
          verify-params:
            secretId: "your_secret_id"
            secretKey: "your_secret_key"
            appId: "your_enterprise_app_id"
            appSecretKey: "your_enterprise_secret_key"
            region: "ap-shanghai"
            randstr: "randStr"
            ticket: "ticket"

限流保护配置 ​

yaml
# 带限流保护的验证码配置
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        # 登录接口限流保护
        - generate-urls:
            - /auth/login/captcha
          verify-urls:
            - /auth/login
          business-key: login-protection
          parameter-type: body
          code-field-name: captchaId
          value-field-name: captchaCode
          expire: 5m
          image-type: string
          image-width: 120
          image-height: 40
          image-length: 5
          rate-limiter: true  # 启用限流保护
        
        # API接口限流恢复
        - generate-urls:
            - /api/rate-limit/captcha
          verify-urls:
            - /api/**
          business-key: api-rate-limit
          parameter-type: header
          code-field-name: X-Rate-Limit-Captcha-Id
          value-field-name: X-Rate-Limit-Captcha-Code
          expire: 2m
          image-type: math
          image-width: 100
          image-height: 35
          image-length: 3
          rate-limiter: true

自定义验证码配置 ​

自定义验证码功能提供了更清晰、更美观的验证码图片生成能力，支持高度自定义的外观配置。

字体大小自适应 ​

自定义验证码支持字体大小自适应功能，可以根据图片尺寸自动计算合适的字体大小：

启用自适应字体大小：

yaml
custom-image-font-size: 0  # 设置为0或负数启用自适应

自适应计算规则：

  • 字体大小 = 图片高度 × 0.55
  • 最小字体大小：24px
  • 最大字体大小：72px

示例：

  • 图片高度80px → 字体大小44px
  • 图片高度100px → 字体大小55px
  • 图片高度60px → 字体大小33px

这样可以确保不同尺寸的验证码图片都有合适的字体显示效果，无需手动调整字体大小。

自定义验证码特性 ​

  1. 高清晰度: 使用优化的字体渲染算法，确保验证码清晰可读
  2. 可配置外观: 支持自定义背景色、字体色、字体大小等
  3. 智能干扰: 可控制的噪点和干扰线，在保证安全性的同时维持可读性
  4. 灵活扭曲: 可调节的字符扭曲程度，防止机器识别
  5. PNG格式: 输出高质量的PNG格式图片，支持透明度
  6. 多种类型: 支持字符串、数字、数学运算、随机类型

自定义验证码配置参数 ​

yaml
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        - generate-urls:
            - /api/captcha/generate
          verify-urls:
            - /api/captcha/verify
          business-key: "custom-captcha"
          code-field-name: "code"
          value-field-name: "value"
          parameter-type: "body"
          expire: "5m"
          
          # 基础图片配置
          image-type: "string"        # 验证码类型: string(字符串), number(数字), math(数学运算), random(随机)
          image-width: 240           # 图片宽度，建议 200-300
          image-height: 80           # 图片高度，建议 60-100
          image-length: 4            # 验证码长度，建议 4-6
          
          # 自定义验证码外观配置
          custom-image-font-size: 36                    # 字体大小，建议 24-48
          custom-image-background-color: "255,255,255"  # 背景颜色，RGB格式 "R,G,B"
          custom-image-font-color: "0,0,0"              # 字体颜色，RGB格式 "R,G,B"
          
          # 自定义验证码干扰配置
          custom-image-noise-level: 2                   # 噪点级别 (0-10)，0为无噪点，10为最多噪点
          custom-image-distortion-level: 1              # 扭曲级别 (0-10)，0为无扭曲，10为最大扭曲
          custom-image-line-count: 2                    # 干扰线数量，建议 0-5
          custom-image-dot-count: 50                    # 干扰点数量，建议 0-100

配置参数详细说明 ​

参数名称类型默认值说明
custom-image-font-sizeint36字体大小，建议范围 24-48
custom-image-background-colorstring"255,255,255"背景颜色，RGB格式 "R,G,B"
custom-image-font-colorstring"0,0,0"字体颜色，RGB格式 "R,G,B"
custom-image-noise-levelint0噪点级别，范围 0-10，0表示无噪点
custom-image-distortion-levelint0扭曲级别，范围 0-10，0表示无扭曲
custom-image-line-countint0干扰线数量，建议 0-5
custom-image-dot-countint0干扰点数量，建议 0-100

验证码类型说明 ​

  • string: 生成字母数字组合验证码（如：A3K9）
  • number: 生成纯数字验证码（如：1234）
  • math: 生成数学运算验证码（如：2+3=?，答案为5）
  • random: 随机选择上述类型之一

颜色配置说明 ​

颜色使用RGB格式配置，格式为 "R,G,B"，其中R、G、B分别表示红、绿、蓝三个颜色分量，取值范围0-255。

常用颜色配置：

  • 白色背景："255,255,255"
  • 黑色字体："0,0,0"
  • 蓝色字体："0,100,200"
  • 红色字体："200,50,50"
  • 灰色背景："240,240,240"

不同场景的配置示例 ​

高安全性配置（适用于重要操作） ​

yaml
image-type: "math"
custom-image-font-size: 40
custom-image-background-color: "245,245,245"
custom-image-font-color: "50,50,50"
custom-image-noise-level: 4
custom-image-distortion-level: 3
custom-image-line-count: 3
custom-image-dot-count: 80

用户友好配置（适用于一般登录） ​

yaml
image-type: "string"
custom-image-font-size: 36
custom-image-background-color: "255,255,255"
custom-image-font-color: "0,0,0"
custom-image-noise-level: 1
custom-image-distortion-level: 1
custom-image-line-count: 1
custom-image-dot-count: 30

简洁清晰配置（适用于移动端） ​

yaml
image-type: "number"
custom-image-font-size: 42
custom-image-background-color: "255,255,255"
custom-image-font-color: "0,0,0"
custom-image-noise-level: 0
custom-image-distortion-level: 0
custom-image-line-count: 0
custom-image-dot-count: 0

API使用示例 ​

生成自定义验证码 ​

bash
# 请求生成验证码
curl -X POST http://localhost:8080/api/captcha/generate \
  -H "Content-Type: application/json"

# 响应示例
{
  "code": 0,
  "successful": true,
  "data": {
    "code": "uuid-generated-code",
    "captcha": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

验证验证码 ​

bash
# 请求验证验证码
curl -X POST http://localhost:8080/api/captcha/verify \
  -H "Content-Type: application/json" \
  -d '{
    "code": "uuid-generated-code",
    "value": "用户输入的验证码"
  }'

# 验证成功响应
{
  "code": 0,
  "successful": true,
  "message": "验证码验证成功"
}

# 验证失败响应
{
  "code": 400,
  "successful": false,
  "message": "验证码错误或已过期"
}

注意事项 ​

  1. 性能考虑: 高级干扰效果（noise-level > 5）会增加图片生成时间
  2. 可读性平衡: 过高的扭曲和干扰级别可能影响用户体验
  3. 移动端适配: 移动端建议使用较大的字体和较少的干扰
  4. 数学运算: math类型验证码的答案长度可能不固定，前端需要适配
  5. 颜色对比: 确保字体颜色与背景颜色有足够的对比度

验证码接口说明

  1. 接口返回数据格式：
json
{
    "code": 0,
    "successful": true,
    "msg": null,
    "data": {
        "captcha": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAJYAAABGCAIAAAChXfqaAAAaOUlEQVR4nOxcd3hUVdo/d",
        "code": "0076c56f3b374350ac659cd236ad0052"
    },
    "encrypt": false
}
  1. 验证接口请求参数：
json
{
    "accountNo": "admin",
    "password": "123456",
    "code": "88e8d3552ed0d2b8467bc5e497614e69",
    "captcha": "4myn"
}

⚠️ 注意事项 ​

  1. 安全配置

    • 验证码接口需要合理配置权限
    • 验证码有效期建议5分钟以内
    • 建议开启限流保护机制

  2. 接口要求

    • 自定义验证接口必须支持POST请求
    • 必须使用JSON格式的请求体
    • 需要正确处理超时情况

  3. 第三方服务

    • 提前申请相关密钥信息
    • 正确配置服务地域
    • 做好异常处理和降级方案
    • 阿里云：需要申请 SceneId 与 AccessKey（accessKeyId/accessKeySecret），并按前端字段名提供 captchaVerifyParam
    • 腾讯云：需要申请 secretId/secretKey、appId/appSecretKey，并提供前端字段名 randstr/ticket
    • CAP：需要提供 secret 与前端返回 token 的字段名 responseField

  4. 性能优化

    • 合理设置验证码复杂度
    • 适当配置限流阈值
    • 监控验证码服务性能

  5. 负载均衡与内网代理（lb://）

    • verify-uri 支持 lb://<service>/<path>，将通过 Nacos 发现健康实例并使用 http://ip:port/<path> 访问。
    • 阿里云/腾讯云在 lb:// 代理场景下仍按云厂商的 Host 与签名规范构建请求头，确保签名校验不受影响。

进阶与联动 ​

  • 响应加密：当开启 gateway.filter.response-encrypt 并命中相应规则时，生成验证码响应会被加密返回（支持 DES3/SM4，商户密钥可按 appId 定制）。
  • 超时控制：verify-timeout 使用 Go 的 Duration 格式（例如 500ms、2s、1m）。
  • 参数提取：parameter-type 决定从 header/query/body 读取字段名，字段名由各类型的 verify-params 指定。

lb:// 使用示例 ​

yaml
gateway:
  filter:
    captcha:
      enabled: true
      rules:
        - verify-urls:
            - /api/login
          parameter-type: body
          verify-type: aliyun
          verify-timeout: 10s
          verify-uri: lb://aliyun-proxy/aliyun/captcha  # 通过内网代理阿里云验证
          verify-params:
            sceneId: "scene_xxx"
            accessKeyId: "ak_xxx"
            accessKeySecret: "sk_xxx"
            captchaVerifyParam: "captchaVerifyParam"
            host: "captcha.cn-shanghai.aliyuncs.com"

以上配置将通过 Nacos 选择 aliyun-proxy 的健康实例并以 http://ip:port/aliyun/captcha 访问，同时仍使用 host: captcha.cn-shanghai.aliyuncs.com 进行阿里云签名。

🔗 相关链接 ​

Copyright © 2017-2025 wueasy.com