验证码操作处理

文件分析

这是一个验证码控制器，负责：

1. 生成图形验证码（字符型或数学计算型）
2. 将验证码存储到 Redis
3. 以 Base64 格式返回验证码图片

# CaptchaController 验证码控制器文档

## 📋 文件信息

- **包路径**: `com.ruoyi.web.controller.common`
- **类名称**: `CaptchaController`
- **注解**: `@RestController`
- **职责**: 验证码操作处理

---

🔧 依赖注入

字段名	类型	注入方式	Bean 名称	说明
captchaProducer	Producer	@Resource	captchaProducer	普通字符验证码生成器
captchaProducerMath	Producer	@Resource	captchaProducerMath	数学计算验证码生成器
redisCache	RedisCache	@Autowired	-	Redis 缓存操作
configService	ISysConfigService	@Autowired	-	系统配置服务

注意: Producer 接口有两个实现类，因此使用 @Resource(name = "...") 明确指定注入的 Bean。

---

🎯 核心方法

getCode(HttpServletResponse response)

请求方式: GET
请求路径: /captchaImage
异常声明: throws IOException

方法功能

生成验证码图片，将其存储到 Redis，并返回验证码 UUID 和 Base64 编码的图片数据。

执行流程

mermaid
graph LR
    A[开始] --> B[检查验证码是否启用]
    B -->|禁用| C[返回 captchaEnabled=false]
    B -->|启用| D[生成唯一 UUID]
    D --> E[构造 Redis Key]
    E --> F[根据类型生成验证码]
    F -->|math| G[数学计算型验证码]
    F -->|char| H[字符型验证码]
    G --> I[存储到 Redis]
    H --> I
    I --> J[转换为 Base64]
    J --> K[返回 JSON 响应]

业务逻辑详解

1. 验证码开关检查

java
boolean captchaEnabled = configService.selectCaptchaEnabled();

通过系统配置判断验证码是否启用。

2. 生成验证码标识

java
String uuid = IdUtils.simpleUUID();
String verifyKey = CacheConstants.CAPTCHA_CODE_KEY + uuid;

• 生成唯一 UUID 作为验证码ID
• Redis Key 格式: captcha_code:{uuid}

3. 验证码类型判断

根据 RuoYiConfig.getCaptchaType() 配置选择生成方式：

类型	值	说明	示例
math	数学计算	生成算术题，格式: 表达式@答案	3+5@8
char	随机字符	生成随机字符串	aB7k

4. 存储到 Redis

java
redisCache.setCacheObject(verifyKey, code, Constants.CAPTCHA_EXPIRATION, TimeUnit.MINUTES);

• Key: captcha_code:{uuid}
• Value: 验证码答案
• 过期时间: CAPTCHA_EXPIRATION 分钟（默认 2 分钟）

5. 返回结果

json
{
  "code": 200,
  "msg": "操作成功",
  "captchaEnabled": true,
  "uuid": "a1b2c3d4e5f6",
  "img": "/9j/4AAQSkZJRgABA..."
}

字段	类型	说明
captchaEnabled	Boolean	验证码是否启用
uuid	String	验证码唯一标识，登录时需传递
img	String	Base64 编码的验证码图片

---

📦 外部依赖

Kafka 验证码库

xml
<dependency>
    <groupId>com.github.penggle</groupId>
    <artifactId>kaptcha</artifactId>
</dependency>

通过 Producer 接口生成验证码图片。

---

💡 使用场景

1. 登录页面: 用户登录时显示验证码
2. 注册页面: 防止批量注册
3. 找回密码: 验证操作真实性
4. 敏感操作: 防止恶意提交

---

⚠️ 注意事项

1. Redis 依赖

• 验证码答案存储在 Redis 中
• 确保 Redis 服务正常运行
• 验证码有过期时间，超时需重新获取

2. 验证流程

前端提交验证码时需：

java
// 1. 根据 uuid 从 Redis 获取验证码答案
String cachedCode = redisCache.getCacheObject("captcha_code:" + uuid);

// 2. 比对用户输入的答案
if (userInput.equals(cachedCode)) {
    // 验证成功
    redisCache.deleteObject("captcha_code:" + uuid); // 一次性使用
}

3. 线程安全

• Producer 必须是 Spring 单例Bean
• 图中已通过 name 属性明确指定 Bean，避免注入冲突

---

🔐 安全特性

特性	说明
过期机制	验证码 2 分钟后自动失效
一次性使用	验证成功后应删除 Redis 中的记录
UUID 随机	每次生成不同的 UUID，防止预测
可配置	可通过系统配置开关验证码

---

📝 配置项

验证码类型配置

yaml
# application.yml
ruoyi:
  captchaType: math  # math=数学计算, char=随机字符

验证码过期时间

java
// Constants.CAPTCHA_EXPIRATION = 2 (分钟)

---

🔄 相关类

类名	说明
RedisCache	Redis 缓存操作封装
ISysConfigService	系统配置服务接口
IdUtils	ID 工具类，生成 UUID
Base64	Base64 编码工具
RuoYiConfig	若依系统配置

---

文档生成时间: 2026-08-31

---

这个 Markdown 文档包含了文件的完整分析，包括：
- 📋 基本信息
- 🔧 依赖注入说明
- 🎯 核心方法详解（含流程图、业务逻辑）
- 📦 外部依赖
- 💡 使用场景
- ⚠️ 注意事项
- 🔐 安全特性
- 📝 配置项
- 🔄 相关类

你可以直接将这个文档保存到项目中，比如放到 `doc/` 目录下！