Go Gateway

外观

验证码验证拦截器 🔒 ​

功能概述 📝 ​

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

功能特性 ✨ ​

验证方式 ​

  • 🖼️ 图片验证码：支持自定义长度和复杂度

核心功能 ​

  • ✅ 多种验证码类型支持
  • 🔐 业务场景隔离
  • 🎯 灵活的参数获取方式
  • ⏱️ 验证码过期控制
  • 🚦 请求限流保护

配置说明 ⚙️ ​

基础配置参数 ​

参数名类型必填默认值说明
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是否启用限流保护（主要处理触发限流后，可以通过验证码恢复）

使用示例 📝 ​

基础图片验证码配置 ​

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  # 验证码长度

完整配置示例 ​

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

不同验证方式配置 ​

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

限流保护配置 ​

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

验证码接口说明

  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. 第三方服务

    • 提前申请相关密钥信息
    • 正确配置服务地域
    • 做好异常处理和降级方案

  4. 性能优化

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

🔗 相关链接 ​

Copyright © 2017-2025 wueasy.com