330 lines
12 KiB
Markdown
330 lines
12 KiB
Markdown
# 发送验证码
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go)
|
||
- [routes.go](file://internal/handler/routes.go)
|
||
- [verification_service.go](file://internal/service/verification_service.go)
|
||
- [common.go](file://internal/types/common.go)
|
||
- [email.go](file://pkg/email/email.go)
|
||
- [manager.go](file://pkg/email/manager.go)
|
||
- [redis.go](file://pkg/redis/redis.go)
|
||
- [manager.go](file://pkg/redis/manager.go)
|
||
- [config.go](file://pkg/config/config.go)
|
||
- [main.go](file://cmd/server/main.go)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向“发送验证码”API，围绕 /api/v1/auth/send-code 端点进行完整说明。内容包括：
|
||
- 接口概述与HTTP规范
|
||
- 请求体结构与字段约束（email、type）
|
||
- 响应格式与错误码
|
||
- 验证码生成、存储与过期策略（Redis）
|
||
- 邮件服务集成（pkg/email）
|
||
- 不同验证码类型（注册、重置密码、更换邮箱）的处理逻辑
|
||
- 实际请求与响应示例
|
||
- 安全注意事项（频率限制、邮箱格式）
|
||
|
||
## 项目结构
|
||
/api/v1/auth/send-code 属于认证模块，位于 Gin 路由分组 /api/v1/auth 下，由处理器负责接收请求、绑定参数、调用服务层发送验证码，并通过 Redis 与邮件服务完成验证码的持久化与发送。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Client["客户端"] --> Router["Gin 路由<br/>/api/v1/auth/send-code"]
|
||
Router --> Handler["处理器<br/>SendVerificationCode"]
|
||
Handler --> Service["服务层<br/>SendVerificationCode/VerifyCode"]
|
||
Service --> Redis["Redis 客户端<br/>存储验证码/频率限制"]
|
||
Service --> Email["邮件服务<br/>发送验证码邮件"]
|
||
Email --> SMTP["SMTP 服务器"]
|
||
```
|
||
|
||
图表来源
|
||
- [routes.go](file://internal/handler/routes.go#L16-L26)
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
|
||
- [redis.go](file://pkg/redis/redis.go#L60-L83)
|
||
- [email.go](file://pkg/email/email.go#L29-L105)
|
||
|
||
章节来源
|
||
- [routes.go](file://internal/handler/routes.go#L16-L26)
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
|
||
## 核心组件
|
||
- 路由与处理器
|
||
- 路由注册：/api/v1/auth/send-code 绑定到 SendVerificationCode 处理器。
|
||
- 处理器职责：参数绑定、调用服务层发送验证码、记录日志、返回统一响应。
|
||
- 服务层
|
||
- 生成6位数字验证码；按 type 与 email 组合键存储至 Redis，设置过期时间；设置发送频率限制；调用邮件服务发送对应类型的邮件。
|
||
- Redis
|
||
- 提供 Set/Get/Del/Exists 等基础操作，封装过期时间控制与错误处理。
|
||
- 邮件服务
|
||
- 基于 SMTP 的邮件发送，支持 465（隐式 TLS）与 587（显式 TLS）端口；根据 type 选择不同主题与正文模板。
|
||
- 类型定义
|
||
- SendVerificationCodeRequest 包含 email 与 type 字段，type 限定为 register/reset_password/change_email。
|
||
|
||
章节来源
|
||
- [routes.go](file://internal/handler/routes.go#L16-L26)
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L14-L24)
|
||
- [redis.go](file://pkg/redis/redis.go#L60-L83)
|
||
- [email.go](file://pkg/email/email.go#L29-L105)
|
||
- [common.go](file://internal/types/common.go#L49-L54)
|
||
|
||
## 架构总览
|
||
发送验证码的端到端流程如下：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant H as "处理器<br/>SendVerificationCode"
|
||
participant S as "服务层<br/>SendVerificationCode/VerifyCode"
|
||
participant R as "Redis 客户端"
|
||
participant E as "邮件服务<br/>SendVerificationCode"
|
||
participant M as "SMTP 服务器"
|
||
C->>H : POST /api/v1/auth/send-code<br/>{email, type}
|
||
H->>H : 绑定请求体并校验
|
||
H->>S : SendVerificationCode(ctx, redis, email, type)
|
||
S->>R : Exists(rate_limit_key)
|
||
alt 已存在
|
||
S-->>H : 返回“发送过于频繁”
|
||
H-->>C : 400 错误
|
||
else 不存在
|
||
S->>S : 生成6位数字验证码
|
||
S->>R : Set(code_key, code, 10分钟)
|
||
S->>R : Set(rate_limit_key, 1, 1分钟)
|
||
S->>E : 根据type发送邮件
|
||
E->>M : 发送邮件
|
||
M-->>E : 成功/失败
|
||
alt 邮件发送失败
|
||
S->>R : Del(code_key)
|
||
S-->>H : 返回“发送邮件失败”
|
||
H-->>C : 400 错误
|
||
else 成功
|
||
S-->>H : 返回成功
|
||
H-->>C : 200 成功
|
||
end
|
||
end
|
||
```
|
||
|
||
图表来源
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
|
||
- [redis.go](file://pkg/redis/redis.go#L60-L83)
|
||
- [email.go](file://pkg/email/email.go#L29-L105)
|
||
|
||
## 详细组件分析
|
||
|
||
### HTTP 端点定义
|
||
- 方法：POST
|
||
- 路径：/api/v1/auth/send-code
|
||
- 功能：根据邮箱与类型发送验证码邮件，并在 Redis 中存储验证码及频率限制。
|
||
|
||
章节来源
|
||
- [routes.go](file://internal/handler/routes.go#L16-L26)
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
|
||
### 请求体结构
|
||
- 字段
|
||
- email: 必填，需符合邮箱格式
|
||
- type: 必填，枚举值为 register/reset_password/change_email
|
||
- 参数绑定与校验
|
||
- 使用 Gin 的绑定与验证机制，确保 email 符合邮箱格式，type 在允许范围内。
|
||
|
||
章节来源
|
||
- [common.go](file://internal/types/common.go#L49-L54)
|
||
|
||
### 响应格式
|
||
- 成功
|
||
- 状态码：200
|
||
- 结构：统一响应体，包含 message 字段提示“验证码已发送，请查收邮件”
|
||
- 失败
|
||
- 状态码：400
|
||
- 结构：统一错误响应体，包含错误码与错误信息
|
||
|
||
章节来源
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
|
||
### 错误码与错误场景
|
||
- 400 参数错误
|
||
- 请求体绑定失败或参数校验失败
|
||
- 400 发送过于频繁
|
||
- Redis 中存在频率限制键（1分钟内）
|
||
- 400 邮件发送失败
|
||
- 邮件服务未启用或 SMTP 发送异常
|
||
- 400 验证码已过期或不存在
|
||
- 验证码校验时 Redis 中无对应键
|
||
|
||
章节来源
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
|
||
|
||
### 验证码生成与存储（Redis）
|
||
- 生成规则
|
||
- 6位数字验证码
|
||
- 存储键
|
||
- 验证码键：verification:code:{type}:{email}
|
||
- 过期时间：10分钟
|
||
- 频率限制
|
||
- 频率限制键：verification:rate_limit:{type}:{email}
|
||
- 过期时间：1分钟
|
||
- Redis 操作
|
||
- Set/SetEx：写入验证码与频率限制
|
||
- Get：读取验证码用于校验
|
||
- Del：验证成功后删除验证码键
|
||
- Exists：检查是否处于发送冷却
|
||
|
||
章节来源
|
||
- [verification_service.go](file://internal/service/verification_service.go#L14-L24)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
|
||
- [redis.go](file://pkg/redis/redis.go#L60-L83)
|
||
|
||
### 邮件服务集成（pkg/email）
|
||
- 初始化
|
||
- 通过全局初始化函数完成一次性初始化，随后通过 MustGetService 获取实例
|
||
- 发送逻辑
|
||
- 根据 type 选择不同主题与正文模板
|
||
- 支持 465（隐式 TLS）与 587（显式 TLS）两种端口模式
|
||
- 当邮件服务未启用时，返回“邮件服务未启用”的错误
|
||
- 主题与正文
|
||
- 注册：邮箱验证
|
||
- 重置密码：重置密码
|
||
- 更换邮箱：更换邮箱验证
|
||
- 默认：通用验证码
|
||
|
||
章节来源
|
||
- [email.go](file://pkg/email/email.go#L29-L105)
|
||
- [manager.go](file://pkg/email/manager.go#L1-L43)
|
||
- [main.go](file://cmd/server/main.go#L71-L74)
|
||
|
||
### 不同验证码类型的处理逻辑
|
||
- 注册（register）
|
||
- 邮件主题：邮箱验证
|
||
- 通常配合注册接口使用，注册时需提供验证码
|
||
- 重置密码（reset_password）
|
||
- 邮件主题：重置密码
|
||
- 与 /api/v1/auth/reset-password 配合使用
|
||
- 更换邮箱（change_email）
|
||
- 邮件主题：更换邮箱验证
|
||
- 与用户更换邮箱流程配合使用
|
||
- 默认（其他）
|
||
- 通用验证码主题
|
||
|
||
章节来源
|
||
- [verification_service.go](file://internal/service/verification_service.go#L106-L118)
|
||
- [email.go](file://pkg/email/email.go#L107-L139)
|
||
|
||
### 安全考虑
|
||
- 邮箱格式验证
|
||
- 请求体中 email 字段使用邮箱格式校验
|
||
- 发送频率限制
|
||
- Redis 中按 type+email 维度设置1分钟冷却，避免刷屏
|
||
- 验证码有效期
|
||
- Redis 中验证码设置10分钟过期，过期即失效
|
||
- 重复使用防护
|
||
- 验证码校验成功后立即删除键，防止二次使用
|
||
- 邮件服务开关
|
||
- 若未启用邮件服务，发送验证码会直接失败，避免泄露敏感信息
|
||
|
||
章节来源
|
||
- [common.go](file://internal/types/common.go#L49-L54)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
|
||
- [redis.go](file://pkg/redis/redis.go#L60-L83)
|
||
- [email.go](file://pkg/email/email.go#L29-L40)
|
||
|
||
## 依赖关系分析
|
||
- 处理器依赖服务层
|
||
- 服务层依赖 Redis 与邮件服务
|
||
- 邮件服务依赖配置与日志
|
||
- Redis 客户端依赖配置与日志
|
||
- 全局初始化顺序：配置 -> 日志 -> 数据库 -> JWT -> Redis -> 对象存储 -> 邮件服务
|
||
|
||
```mermaid
|
||
graph LR
|
||
H["处理器<br/>auth_handler.go"] --> S["服务层<br/>verification_service.go"]
|
||
S --> R["Redis 客户端<br/>redis.go"]
|
||
S --> E["邮件服务<br/>email.go"]
|
||
E --> Cfg["配置<br/>config.go"]
|
||
E --> Lg["日志"]
|
||
R --> Cfg
|
||
R --> Lg
|
||
Main["服务启动<br/>main.go"] --> E
|
||
Main --> R
|
||
```
|
||
|
||
图表来源
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
|
||
- [redis.go](file://pkg/redis/redis.go#L60-L83)
|
||
- [email.go](file://pkg/email/email.go#L29-L105)
|
||
- [config.go](file://pkg/config/config.go#L49-L107)
|
||
- [main.go](file://cmd/server/main.go#L27-L74)
|
||
|
||
章节来源
|
||
- [main.go](file://cmd/server/main.go#L27-L74)
|
||
|
||
## 性能考量
|
||
- Redis 操作均为 O(1)，Set/Get/Del/Exists 均为常数时间复杂度
|
||
- 验证码长度固定为6位，生成与比较成本低
|
||
- 邮件发送为外部依赖，受网络与SMTP服务器性能影响
|
||
- 建议
|
||
- 合理设置 Redis 连接池大小（PoolSize）
|
||
- 控制邮件发送并发，避免瞬时高峰导致SMTP限流
|
||
- 对高频请求开启更严格的频率限制（如增加冷却时间）
|
||
|
||
[本节为通用性能建议，不直接分析具体文件]
|
||
|
||
## 故障排查指南
|
||
- 400 参数错误
|
||
- 检查请求体是否包含 email 与 type，且 type 是否在允许范围内
|
||
- 400 发送过于频繁
|
||
- 等待1分钟冷却时间，或检查 Redis 中 rate_limit 键是否仍存在
|
||
- 400 邮件发送失败
|
||
- 确认邮件服务已启用（EMAIL_ENABLED=true）
|
||
- 检查 SMTP 配置（主机、端口、用户名、密码、发件人名称）
|
||
- 查看日志中 SMTP 发送错误信息
|
||
- 400 验证码已过期或不存在
|
||
- 检查 Redis 中 code 键是否存在与过期时间
|
||
- 确认验证码是否已被验证成功后删除
|
||
|
||
章节来源
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
|
||
- [email.go](file://pkg/email/email.go#L29-L105)
|
||
- [redis.go](file://pkg/redis/redis.go#L60-L83)
|
||
|
||
## 结论
|
||
/api/v1/auth/send-code 端点通过 Gin 处理器接收请求，调用服务层完成验证码生成、Redis 存储与频率限制、邮件发送等流程。其设计遵循最小暴露面原则：严格参数校验、冷却时间、过期时间与删除机制共同保障安全性与可用性。结合 pkg/email 与 pkg/redis 的稳定实现，整体具备良好的扩展性与可维护性。
|
||
|
||
[本节为总结性内容，不直接分析具体文件]
|
||
|
||
## 附录
|
||
|
||
### 请求与响应示例
|
||
- 请求示例
|
||
- 方法：POST
|
||
- 路径：/api/v1/auth/send-code
|
||
- 请求体：
|
||
- email: user@example.com
|
||
- type: register 或 reset_password 或 change_email
|
||
- 成功响应示例
|
||
- 状态码：200
|
||
- 响应体：包含 message 字段，提示“验证码已发送，请查收邮件”
|
||
- 失败响应示例
|
||
- 状态码：400
|
||
- 响应体：包含错误码与错误信息，如“发送过于频繁，请稍后再试”或“发送邮件失败”
|
||
|
||
章节来源
|
||
- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
|
||
- [common.go](file://internal/types/common.go#L49-L54) |