12 KiB
12 KiB
验证码API
**本文引用的文件** - [routes.go](file://internal/handler/routes.go) - [captcha_handler.go](file://internal/handler/captcha_handler.go) - [captcha_service.go](file://internal/service/captcha_service.go) - [redis.go](file://pkg/redis/redis.go) - [response.go](file://internal/model/response.go) - [auth_handler.go](file://internal/handler/auth_handler.go) - [captcha_handler_test.go](file://internal/handler/captcha_handler_test.go) - [captcha_service_test.go](file://internal/service/captcha_service_test.go)目录
简介
本文件面向验证码服务API的使用者与维护者，围绕路由组“/api/v1/captcha”下的两个核心端点：
- GET /generate：生成图形验证码（滑块拼图），返回主图、滑块图、验证码唯一标识及目标Y坐标等信息。
- POST /verify：验证用户提交的滑动偏移量，判断是否在容差范围内，并在验证通过后清理缓存。
文档将详细说明验证码的生成机制（基于滑块拼图算法）、有效期管理（Redis过期策略）、验证流程与状态处理，并给出请求/响应示例。同时，说明该服务如何与注册、登录、更换邮箱等功能集成以提升安全性。
项目结构
验证码API位于路由组“/api/v1/captcha”，由处理器与服务层共同实现，底层依赖Redis进行验证码数据的临时存储与过期控制。
graph TB
subgraph "路由层"
R["routes.go<br/>注册 /api/v1/captcha/* 路由"]
end
subgraph "处理器层"
GH["captcha_handler.go<br/>Generate/Verify"]
end
subgraph "服务层"
CS["captcha_service.go<br/>GenerateCaptchaData/VerifyCaptchaData"]
end
subgraph "基础设施"
RC["redis.go<br/>Client 封装"]
end
R --> GH
GH --> CS
CS --> RC
图表来源
章节来源
核心组件
- 路由注册：在路由组“/api/v1/captcha”下注册“/generate”和“/verify”两个端点。
- 处理器：负责参数绑定、调用服务层、组织响应。
- 服务层：负责验证码生成（滑块拼图）、目标坐标提取、Redis存储与过期设置、验证偏移量、容差判断、验证后清理。
- Redis客户端：提供Set/Get/Del等基础能力，封装错误处理。
章节来源
架构总览
验证码API采用“路由 -> 处理器 -> 服务 -> Redis”的分层设计。生成阶段将目标坐标与容差信息写入Redis并设置过期时间；验证阶段读取目标坐标，计算容差并判定有效性，通过后立即删除对应键，防止重复使用。
sequenceDiagram
participant C as "客户端"
participant G as "Generate 处理器"
participant S as "验证码服务"
participant R as "Redis 客户端"
C->>G : GET /api/v1/captcha/generate
G->>S : GenerateCaptchaData(ctx, redisClient)
S->>S : 生成滑块拼图数据
S->>R : Set(key=captcha : id, value={tx,ty}, expire=5m)
S-->>G : 返回 masterImage, tileImage, captchaId, y
G-->>C : JSON {code,data{masterImage,tileImage,captchaId,y}}
图表来源
章节来源
详细组件分析
路由与端点
- 路由组“/api/v1/captcha”
- GET /generate：生成验证码数据（主图、滑块图、验证码ID、目标Y坐标）。
- POST /verify：验证用户提交的滑动偏移量。
章节来源
生成验证码（GET /generate）
- 输入：无显式请求体。
- 输出：包含以下字段的数据对象
- masterImage：主图（base64字符串）
- tileImage：滑块图（base64字符串）
- captchaId：验证码唯一标识（用于后续验证）
- y：目标Y坐标（前端可据此定位滑块初始位置）
- 内部流程要点
- 生成唯一ID作为验证码会话标识。
- 生成滑块拼图数据，提取目标X/Y坐标。
- 将目标坐标序列化后写入Redis，键名前缀为“captcha:”，过期时间为300秒（5分钟）。
- 返回主图、滑块图、captchaId与修正后的Y坐标给前端。
请求/响应示例（路径）
- 请求：GET /api/v1/captcha/generate
- 响应：JSON
- code：200
- data.masterImage：主图（base64）
- data.tileImage：滑块图（base64）
- data.captchaId：验证码ID
- data.y：目标Y坐标
章节来源
验证验证码（POST /verify）
- 请求体字段
- captchaId：必填，验证码唯一标识
- dx：必填，用户滑动的X轴偏移量
- 验证逻辑
- 从Redis读取目标坐标（tx, ty）。
- 使用容差值（默认±3像素）判断 dx 是否在 [tx-3, tx+3] 范围内。
- 若通过：删除Redis中的验证码记录，返回成功；若失败：返回失败。
- 错误处理
- 参数缺失或格式错误：返回400。
- Redis查询失败或键不存在：返回500或提示“验证码已过期或无效”。
请求/响应示例（路径）
- 请求：POST /api/v1/captcha/generate
- JSON：{ "captchaId": "...", "dx": 123 }
- 响应：
- 成功：JSON { "code": 200, "msg": "验证成功" }
- 失败：JSON { "code": 400, "msg": "验证失败，请重试" }
章节来源
验证流程与容差机制
flowchart TD
Start(["开始"]) --> Read["读取Redis中的目标坐标(tx, ty)"]
Read --> Found{"键是否存在？"}
Found --> |否| Expired["返回错误：验证码已过期或无效"]
Found --> |是| Calc["计算 |dx - tx|"]
Calc --> Check{"是否 ≤ 容差(3)？"}
Check --> |是| Delete["删除Redis键"]
Delete --> Pass["返回验证成功"]
Check --> |否| Fail["返回验证失败"]
Expired --> End(["结束"])
Pass --> End
Fail --> End
图表来源
章节来源
与注册/登录/更换邮箱的安全集成
- 注册（/api/v1/auth/register）
- 在注册流程中，前端需先获取图形验证码并完成验证，再提交邮箱验证码（通过 /api/v1/auth/send-code 发送）。
- 后端在注册接口处验证邮箱验证码的有效性，确保注册过程安全。
- 登录（/api/v1/auth/login）
- 登录流程通常不强制要求图形验证码，但可在高风险场景（如异常IP、频繁尝试）引入图形验证码作为二次防护。
- 更换邮箱（/api/v1/user/change-email）
- 更换邮箱时，建议增加图形验证码与邮箱验证码双重校验，降低账户被恶意修改的风险。
章节来源
依赖关系分析
- 路由层依赖处理器层暴露的处理函数。
- 处理器层依赖服务层提供的生成与验证方法。
- 服务层依赖Redis客户端进行数据持久化与过期控制。
- 通用响应模型用于统一返回格式（尽管验证码端点未直接使用该模型，但整体风格一致）。
graph LR
Routes["routes.go"] --> Handler["captcha_handler.go"]
Handler --> Service["captcha_service.go"]
Service --> Redis["redis.go"]
Handler --> Model["response.go"]
图表来源
章节来源
性能考虑
- 生成阶段
- 滑块拼图生成与base64编码在单次请求中完成，建议在前端缓存主图/滑块图以减少重复生成开销。
- 验证阶段
- Redis读取与删除均为O(1)，验证逻辑简单，延迟低。
- 过期策略
- 默认5分钟过期，避免长期占用内存；过期后自动失效，无需手动清理。
- 并发与重复使用
- 验证通过后立即删除Redis键，防止同一验证码被重复使用。
章节来源
故障排查指南
- 生成失败
- 现象：返回500，消息包含“生成验证码失败”。
- 可能原因：滑块拼图生成异常、Redis写入失败。
- 排查步骤：检查Redis连接状态、确认滑块拼图资源可用。
- 验证失败
- 现象：返回500或400，消息提示“验证码已过期或无效”或“验证失败，请重试”。
- 可能原因：captchaId无效或已过期、dx不在容差范围内、Redis读取异常。
- 排查步骤：确认captchaId正确、dx传值合理、Redis键存在且未过期。
- 参数错误
- 现象：返回400，消息提示“参数错误”。
- 可能原因：缺少captchaId或dx、JSON格式不正确。
- 排查步骤：检查请求体字段与类型。
章节来源
结论
验证码API通过滑块拼图与Redis过期机制，提供了轻量级、易部署的人机验证方案。其与注册、登录、更换邮箱等关键流程结合，可显著提升账户安全。建议在高风险场景引入图形验证码作为附加防护，并优化前端缓存策略以提升用户体验。
附录
请求/响应示例（路径）
- 获取验证码
- 请求：GET /api/v1/captcha/generate
- 响应：JSON { "code": 200, "data": { "masterImage": "...", "tileImage": "...", "captchaId": "...", "y": 123 } }
- 验证验证码
- 请求：POST /api/v1/captcha/verify
- JSON：{ "captchaId": "...", "dx": 123 }
- 响应：
- 成功：JSON { "code": 200, "msg": "验证成功" }
- 失败：JSON { "code": 400, "msg": "验证失败，请重试" }
- 请求：POST /api/v1/captcha/verify
章节来源
单元测试要点（路径）
- 验证码生成与过期时间
- 测试：TestGenerateCaptchaData_ExpireTime
- 断言：过期时间为300秒（5分钟）
- 验证码验证逻辑
- 测试：TestVerifyCaptchaData_Logic
- 断言：在容差范围内（±3）返回成功，超出范围返回失败
- Redis键生成
- 测试：TestVerifyCaptchaData_RedisKey
- 断言：键名为“captcha:{id}”
- 处理器响应格式与错误处理
- 测试：TestCaptchaHandler_ResponseFormat、TestCaptchaHandler_ErrorHandling
- 断言：成功/失败响应格式与HTTP状态码
章节来源