CarrotSkin/backend

Fork 0

Files

lan a4b6c5011e

SonarQube Analysis / sonarqube (push) Has been cancelled

Details

chore(git): 更新.gitignore以忽略新的本地文件

2025-11-30 08:33:17 +08:00

14 KiB

Raw Blame History

邮件服务集成

**本文引用的文件列表** - [email.go](file://pkg/email/email.go) - [manager.go](file://pkg/email/manager.go) - [config.go](file://pkg/config/config.go) - [verification_service.go](file://internal/service/verification_service.go) - [auth_handler.go](file://internal/handler/auth_handler.go) - [redis.go](file://pkg/redis/redis.go) - [manager.go](file://pkg/redis/manager.go)

简介

本文件面向CarrotSkin项目的开发者与运维人员，系统性介绍基于SMTP的邮件服务实现与集成方式。重点覆盖以下内容：

邮件服务核心结构体与方法（如Service、SendVerificationCode等）的实现逻辑
SMTP服务器参数配置（主机、端口、认证信息）与客户端初始化流程
注册验证、密码重置、更换邮箱等场景的邮件发送流程
与用户认证流程的集成方式（验证码生成、有效期管理、频率限制与安全考虑）
初学者本地测试配置建议（如使用MailHog）
高级用户可扩展的方向（错误重试机制、连接池优化、监控指标）

项目结构

邮件服务位于独立的pkg模块中，并与配置、Redis缓存、业务服务层以及HTTP处理器协同工作。整体组织如下：

配置层：集中定义EmailConfig并通过环境变量加载
邮件服务层：封装SMTP发送、主题与HTML正文构建
缓存层：使用Redis存储验证码与频率限制
业务服务层：生成验证码、校验验证码、根据类型路由到具体邮件方法
HTTP处理器：对外暴露发送验证码接口，调用业务服务层

graph TB
subgraph "配置层"
CFG["EmailConfig<br/>环境变量绑定"]
end
subgraph "邮件服务层"
SVC["Service<br/>send()/Send* 方法"]
MGR["manager.go<br/>Init/GetService/MustGetService"]
end
subgraph "缓存层"
RCL["Redis Client<br/>Set/Get/Del/Exists"]
end
subgraph "业务服务层"
VSRV["verification_service.go<br/>SendVerificationCode/VerifyCode"]
end
subgraph "HTTP处理器"
AH["auth_handler.go<br/>SendVerificationCode 接口"]
end
CFG --> MGR
MGR --> SVC
SVC --> RCL
AH --> VSRV
VSRV --> SVC
VSRV --> RCL

图表来源

章节来源

核心组件

Service（邮件服务）
- 职责：封装SMTP发送、主题与HTML正文构建、TLS/STARTTLS选择、日志记录
- 关键方法：SendVerificationCode、SendResetPassword、SendEmailVerification、SendChangeEmail、send
manager（邮件服务管理器）
- 职责：全局单例初始化、线程安全获取实例、未初始化保护
- 关键方法：Init、GetService、MustGetService
配置（EmailConfig）
- 字段：Enabled、SMTPHost、SMTPPort、Username、Password、FromName
- 来源：环境变量绑定与默认值设置
验证码服务（verification_service）
- 职责：生成6位数字验证码、存储到Redis、设置频率限制、按类型路由到具体邮件方法
Redis客户端（redis）
- 职责：连接管理、基础KV与集合操作、连接健康检查
HTTP处理器（auth_handler）
- 职责：对外暴露发送验证码接口，调用业务服务层

章节来源

架构总览

下图展示从HTTP请求到邮件发送的完整链路，包括验证码生成、存储、频率限制与邮件发送。

sequenceDiagram
participant C as "客户端"
participant H as "auth_handler.SendVerificationCode"
participant VS as "verification_service.SendVerificationCode"
participant RS as "Redis Client"
participant ES as "email.Service"
participant SMTP as "SMTP服务器"
C->>H : "POST /api/v1/auth/send-code"
H->>VS : "调用发送验证码(类型, 邮箱)"
VS->>RS : "检查频率限制(键 : rate_limit)"
RS-->>VS : "存在/不存在"
VS->>VS : "生成6位数字验证码"
VS->>RS : "写入验证码(键 : code)"
VS->>RS : "设置频率限制(键 : rate_limit)"
VS->>ES : "根据类型调用具体发送方法"
ES->>SMTP : "SMTP发送(465隐式TLS/587 STARTTLS)"
SMTP-->>ES : "结果"
ES-->>VS : "结果"
VS-->>H : "结果"
H-->>C : "发送成功响应"

图表来源

详细组件分析

Service（邮件服务）类图

Service负责SMTP发送、主题与HTML正文构建、TLS/STARTTLS选择与日志记录。

classDiagram
class Service {
-cfg : EmailConfig
-logger : Logger
+SendVerificationCode(to, code, purpose) error
+SendResetPassword(to, code) error
+SendEmailVerification(to, code) error
+SendChangeEmail(to, code) error
-send(to, subject, body) error
-getSubject(purpose) string
-getBody(code, purpose) string
}

图表来源

email.go

章节来源

email.go

发送流程与TLS策略

主题与正文
- 主题根据用途动态选择（邮箱验证、重置密码、更换邮箱）
- 正文为HTML模板，包含验证码展示与有效期提示
SMTP连接策略
- 465端口：使用隐式TLS（SendWithTLS）
- 587端口：使用STARTTLS（Send）
认证方式
- 使用PlainAuth进行SMTP认证
错误处理
- 失败时记录详细上下文（收件人、主题、SMTP主机与端口）
- 成功时记录成功日志

flowchart TD
Start(["进入 send 方法"]) --> Build["构建邮件对象<br/>From/To/Subject/HTML/Headers"]
Build --> Auth["构造SMTP认证信息"]
Auth --> Addr["拼接地址 host:port"]
Addr --> PortCheck{"端口为465?"}
PortCheck --> |是| TLS["配置TLS(隐式)<br/>SendWithTLS"]
PortCheck --> |否| StartTLS["Send(显式STARTTLS)"]
TLS --> Result{"发送成功?"}
StartTLS --> Result
Result --> |否| LogErr["记录错误日志并返回错误"]
Result --> |是| LogOK["记录成功日志并返回nil"]

图表来源

email.go

章节来源

email.go

验证码生成与存储（verification_service）

验证码生成
- 6位纯数字随机验证码
存储与有效期
- Redis键命名规范：verification:code:{type}:{email}，有效期10分钟
频率限制
- Redis键：verification:rate_limit:{type}:{email}，限制1分钟内仅允许一次
类型路由
- register -> SendEmailVerification
- reset_password -> SendResetPassword
- change_email -> SendChangeEmail
- 其他 -> SendVerificationCode

flowchart TD
Enter(["进入 SendVerificationCode"]) --> RL["检查频率限制键是否存在"]
RL --> |存在| RateErr["返回发送过于频繁错误"]
RL --> |不存在| Gen["生成6位验证码"]
Gen --> Store["写入Redis: code键 + 过期10分钟"]
Store --> Limit["写入Redis: rate_limit键 + 过期1分钟"]
Limit --> Route{"根据类型路由"}
Route --> |register| SendEV["SendEmailVerification"]
Route --> |reset_password| SendRP["SendResetPassword"]
Route --> |change_email| SendCE["SendChangeEmail"]
Route --> |其他| SendVC["SendVerificationCode"]
SendEV --> Done(["返回成功"])
SendRP --> Done
SendCE --> Done
SendVC --> Done

图表来源

verification_service.go

章节来源

verification_service.go

HTTP处理器集成（auth_handler）

发送验证码接口
- 解析请求、调用业务服务层、记录日志、返回响应
注册流程中的验证码校验
- 在注册接口中调用VerifyCode校验验证码，失败即拒绝注册

章节来源

依赖关系分析

组件耦合
- Service依赖EmailConfig与Zap日志
- verification_service依赖Redis Client与email.Service
- auth_handler依赖verification_service与日志、Redis
外部依赖
- SMTP客户端库用于发送邮件
- Redis客户端库用于KV与限流
可能的循环依赖
- 当前结构清晰，未见循环依赖迹象

graph LR
CFG["EmailConfig"] --> MGR["manager.Init/GetService"]
MGR --> SVC["Service"]
SVC --> SMTP["SMTP服务器"]
VS["verification_service"] --> SVC
VS --> RCL["Redis Client"]
AH["auth_handler"] --> VS

图表来源

章节来源

性能与可靠性

连接池与并发
- Redis客户端内置连接池（PoolSize），建议结合业务规模调整
- 邮件发送为短连接，建议避免在同一请求中频繁发送
错误重试
- 当前实现未内置自动重试；可在业务层增加指数退避重试策略
监控指标
- 建议采集：邮件发送成功率、耗时、失败原因分布、Redis读写延迟
安全与合规
- 生产环境TLS校验建议开启（InsecureSkipVerify=false）
- 密码等敏感信息仅在内存中传输，避免落盘

[本节为通用建议，无需列出章节来源]

故障排查指南

常见问题定位
- 邮件服务未启用：检查EmailConfig.Enabled与环境变量
- SMTP认证失败：核对Username/Password与SMTPHost/SMTPPort
- TLS握手失败：确认端口与TLS策略匹配（465隐式TLS vs 587 STARTTLS）
- Redis连接失败：检查Redis配置与网络连通性
日志与告警
- 发送失败会记录详细上下文，优先查看日志中的错误堆栈
- 建议在网关或进程外添加告警规则（如连续失败阈值）
本地测试
- 使用MailHog作为本地SMTP代理，便于调试与演示

章节来源

结论

CarrotSkin的邮件服务以简洁、可测试的方式实现了基于SMTP的验证码邮件发送，配合Redis完成验证码生成、存储与频率控制。通过HTTP处理器与业务服务层的清晰分层，系统具备良好的可维护性与扩展性。建议在生产环境中完善错误重试、连接池优化与监控指标，以进一步提升稳定性与可观测性。

[本节为总结性内容，无需列出章节来源]

附录

SMTP配置与初始化

配置项（EmailConfig）
- Enabled：是否启用邮件功能
- SMTPHost：SMTP服务器主机
- SMTPPort：SMTP服务器端口（常用465或587）
- Username/Password：SMTP认证凭据
- FromName：发件人显示名称
环境变量绑定
- EMAIL_ENABLED、EMAIL_SMTP_HOST、EMAIL_SMTP_PORT、EMAIL_USERNAME、EMAIL_PASSWORD、EMAIL_FROM_NAME
初始化步骤
- 通过manager.Init传入EmailConfig与Logger，随后通过MustGetService获取实例
- 在应用启动阶段完成初始化，确保后续调用可用

章节来源

场景化使用路径

注册验证
- HTTP接口：auth_handler.SendVerificationCode
- 业务流程：verification_service.SendVerificationCode -> email.Service.SendEmailVerification
密码重置
- 业务流程：verification_service.SendVerificationCode -> email.Service.SendResetPassword
更换邮箱
- 业务流程：verification_service.SendVerificationCode -> email.Service.SendChangeEmail

章节来源

本地测试建议（MailHog）

启动MailHog作为本地SMTP代理
将EmailConfig配置指向MailHog的SMTP地址与端口
通过auth_handler的发送验证码接口验证端到端流程
在MailHog Web界面查看邮件内容与收件人信息

[本节为通用建议，无需列出章节来源]

14 KiB Raw Blame History Unescape Escape

邮件服务集成

目录

简介

项目结构

核心组件

架构总览

详细组件分析

Service（邮件服务）类图

发送流程与TLS策略

验证码生成与存储（verification_service）

HTTP处理器集成（auth_handler）

依赖关系分析

性能与可靠性

故障排查指南

结论

附录

SMTP配置与初始化

场景化使用路径

本地测试建议（MailHog）

14 KiB

Raw Blame History