如何给你的系统添加验证码功能

为什么需要验证码？

就像商场入口需要安检一样，很多网站的重要操作（比如登录、支付）都需要输入验证码来确保安全。本指南将教你如何在系统中添加这个"安检"功能。

📝 具体步骤

第一步：准备工作

首先，我们需要添加一个生成验证码的工具。就像需要一个印章来制作印记一样，我们需要hutool这个工具来生成验证码。

在你的项目配置文件pom.xml中添加：

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-captcha</artifactId>
    <version>${hutool.version}</version>
</dependency>

第二步：创建验证码生成接口

就像需要一个专门的窗口来发放验证码，我们需要创建一个接口来生成验证码：

@PostMapping(value = "/captcha", produces = MediaType.APPLICATION_JSON_VALUE)
public Mono<ResultVo<CaptchaVo>> captcha() {
    // 创建一个验证码
    // 大小：150x60像素，5个字符，150条干扰线（让机器人难以识别）
    AbstractCaptcha captcha = CaptchaUtil.createLineCaptcha(150,60,5,150);
    
    // 设置验证码内容范围
    // 只使用数字和大写字母，去掉容易混淆的字符（比如0和O）
    captcha.setGenerator(new RandomGenerator("23456789ABCDEFGHJKLMNPQRSTUVWXYZ",5));
    
    // 获取验证码文本
    String captchaCode = captcha.getCode();
    
    // 打包验证码信息
    CaptchaVo vo = new CaptchaVo();
    vo.setCode(captchaCode);                    // 验证码的编号
    vo.setCaptcha(captcha.getImageBase64Data());// 验证码图片
    
    return Mono.just(ResultVo.ok(vo));
}

💡 特别提醒： 这个接口必须返回ResultVo<CaptchaVo>类型的结果，就像快递必须有固定格式的单号一样。

第三步：设置系统配置

就像设置安检规则一样，我们需要在系统中配置验证码的使用规则。在你的配置文件（application.yml或application.yaml）中添加：

wueasy:
  gateway:
    filter:
      session:
        enabled: true  # 开启验证功能
        items:
        - type: redis # 使用redis存储验证信息
          redis-auto-expire: true  # 自动延长有效期
          expire: PT1H  # 设置1小时后过期
          urls:  # 需要验证的地址
          - /demo/**
          user-login-urls: /demo/login  # 登录地址
          security-visitor-urls:  # 不需要验证就能访问的地址
          - /demo/login
          - /demo/captcha
      
      captcha:  # 验证码相关设置
        enabled: true  # 启用验证码
        items:
        - generate-urls:  # 获取验证码的地址
          - /demo/captcha
          verify-urls:  # 需要验证码的地址
          - /demo/login
          code-field-name: code  # 验证码编号的名称
          value-field-name: captcha  # 验证码值的名称
          parameter-type: body  # 参数传递方式

# Redis数据库设置（用于临时存储验证码）
spring:
  data:
    redis:
      database: 9
      host: 127.0.0.1  # 数据库地址
      port: 6379       # 端口号
      password: 123456 # 密码
      timeout: 3000    # 超时时间

第四步：如何使用

1️⃣ 获取验证码

就像去服务台领取号码一样，先获取验证码：

POST http://127.0.0.1:8080/demo/captcha

2️⃣ 使用验证码

在登录时，需要提供验证码信息：

{
    "accountNo": "admin",         // 账号
    "password": "123456",        // 密码
    "code": "27c6e1a15600fbe82b3907bbe2831ce0",  // 验证码编号
    "captcha": "1234"           // 你看到的验证码内容
}

3️⃣ 登录成功

系统会给你一个通行证（访问令牌）：

{
    "code": 0,
    "data": {
        "authorization": "demo:1:2f202192dd2744b9f5589080d765e43e"  // 通行证
    },
    "successful": true
}

❓ 常见问题解答

1. 看不到验证码图片？

• ✓ 检查图片数据是否完整
• ✓ 确认网页是否正确显示图片
• ✓ 尝试刷新页面

2. 验证码总是错误？

• ✓ 确认输入的验证码是否正确（区分大小写）
• ✓ 检查验证码是否已过期
• ✓ 确认使用的是最新获取的验证码

3. 系统配置问题？

• ✓ 检查配置文件的格式是否正确
• ✓ 确认所有地址配置是否正确
• ✓ 验证Redis数据库是否正常运行

🎯 使用小贴士

1. 开发测试时：

   • 可以适当延长验证码有效期
   • 建议打开详细日志方便调试

2. 正式使用时：

   • 验证码要定期更换
   • 注意保护验证码信息
   • 定期清理过期数据

🆘 需要帮助？

如果遇到问题，可以这样做：

1. 📝 查看系统日志：./logs/gateway.log
2. 🔍 检查Redis数据库连接
3. 🌐 确认网络是否正常
4. 💬 联系技术支持