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

18 KiB

Raw Blame History

认证API

**本文引用的文件** - [routes.go](file://internal/handler/routes.go) - [auth_handler.go](file://internal/handler/auth_handler.go) - [jwt.go](file://pkg/auth/jwt.go) - [password.go](file://pkg/auth/password.go) - [user_service.go](file://internal/service/user_service.go) - [verification_service.go](file://internal/service/verification_service.go) - [captcha_handler.go](file://internal/handler/captcha_handler.go) - [captcha_service.go](file://internal/service/captcha_service.go) - [auth.go](file://internal/middleware/auth.go) - [common.go](file://internal/types/common.go) - [email.go](file://pkg/email/email.go) - [config.go](file://pkg/config/config.go)

简介

本文件面向开发者，系统性梳理认证API的设计与实现，覆盖用户注册、登录、发送验证码与重置密码四个核心端点。文档基于路由分组与处理器实现，详细说明每个API的HTTP方法、请求参数、响应格式与错误码；重点解释JWT认证机制在登录流程中的作用，以及验证码服务与邮箱服务的集成方式；并提供实际请求/响应示例路径，帮助快速理解认证流程。同时总结安全要点，包括密码加密存储、JWT过期策略与防暴力破解措施。

项目结构

认证相关能力由“路由层-处理器层-服务层-基础设施层”四层构成：

路由层：在统一的路由组下挂载认证相关端点
处理器层：负责参数绑定、调用服务、组织响应与错误处理
服务层：封装业务逻辑（用户注册/登录、验证码发送与校验、密码变更等）
基础设施层：JWT签发与校验、密码加解密、Redis验证码存储、SMTP邮件发送

graph TB
subgraph "路由层"
R["routes.go<br/>注册/auth路由组"]
end
subgraph "处理器层"
AH["auth_handler.go<br/>注册/登录/发送验证码/重置密码"]
CH["captcha_handler.go<br/>图形验证码生成/校验"]
end
subgraph "服务层"
US["user_service.go<br/>注册/登录/密码重置等"]
VS["verification_service.go<br/>验证码生成/发送/校验"]
CS["captcha_service.go<br/>图形验证码生成/校验"]
end
subgraph "基础设施层"
JWT["jwt.go<br/>JWT签发/校验"]
PW["password.go<br/>bcrypt加解密"]
EM["email.go<br/>SMTP邮件发送"]
CFG["config.go<br/>JWT/邮件/Redis等配置"]
end
R --> AH
R --> CH
AH --> US
AH --> VS
CH --> CS
US --> JWT
US --> PW
VS --> EM
VS --> CFG
CS --> CFG

图表来源

章节来源

routes.go

核心组件

路由组与端点
- /api/v1/auth/register：POST，注册
- /api/v1/auth/login：POST，登录
- /api/v1/auth/send-code：POST，发送验证码
- /api/v1/auth/reset-password：POST，重置密码
中间件
- 认证中间件：对受保护资源进行JWT校验
关键数据模型
- 请求/响应结构体定义于类型模块，包含登录、注册、验证码发送与重置密码等请求体与响应体字段

章节来源

架构总览

认证API采用“路由-处理器-服务-基础设施”的分层设计，认证流程的关键交互如下：

sequenceDiagram
participant C as "客户端"
participant H as "处理器(auth_handler)"
participant S as "服务(user_service/verification_service)"
participant J as "JWT服务(pkg/auth)"
participant E as "邮件服务(pkg/email)"
participant R as "Redis"
rect rgb(255,255,255)
Note over C,H : 注册流程
C->>H : POST /api/v1/auth/register
H->>S : VerifyCode(验证码校验)
S->>R : GET verification : code : register : email
R-->>S : 验证码
S-->>H : 校验通过
H->>S : RegisterUser(创建用户+生成JWT)
S->>J : GenerateToken(userID, username, role)
J-->>S : token
S-->>H : 用户信息+token
H-->>C : 成功响应(包含token与用户信息)
end
rect rgb(255,255,255)
Note over C,H : 登录流程
C->>H : POST /api/v1/auth/login
H->>S : LoginUser(用户名/邮箱+密码)
S->>J : GenerateToken(userID, username, role)
J-->>S : token
S-->>H : 用户信息+token
H-->>C : 成功响应(包含token与用户信息)
end
rect rgb(255,255,255)
Note over C,H : 发送验证码流程
C->>H : POST /api/v1/auth/send-code
H->>S : SendVerificationCode(生成+存储+限流+发邮件)
S->>R : SET verification : code : type : email
S->>E : 发送邮件
E-->>S : 发送结果
S-->>H : 成功
H-->>C : 成功响应
end
rect rgb(255,255,255)
Note over C,H : 重置密码流程
C->>H : POST /api/v1/auth/reset-password
H->>S : VerifyCode(验证码校验)
S->>R : GET verification : code : reset_password : email
R-->>S : 验证码
S-->>H : 校验通过
H->>S : ResetUserPassword(更新密码)
S-->>H : 成功
H-->>C : 成功响应
end

图表来源

详细组件分析

路由与端点

路由组
- /api/v1/auth：认证相关端点
- /api/v1/user：受JWT保护的用户资料端点（不在本次文档范围）
端点清单
- POST /api/v1/auth/register：注册
- POST /api/v1/auth/login：登录
- POST /api/v1/auth/send-code：发送验证码
- POST /api/v1/auth/reset-password：重置密码

章节来源

routes.go

注册接口（POST /api/v1/auth/register）

功能概述
- 接收用户名、邮箱、密码、验证码与可选头像，校验验证码后创建用户并签发JWT
请求参数
- 字段：username、email、password、verification_code、avatar
- 校验规则：用户名长度、邮箱格式、密码长度、验证码长度、头像URL格式
响应格式
- 成功：包含token与用户信息
- 失败：错误码与错误信息
错误码
- 400：请求参数错误、验证码错误、用户名/邮箱已存在、密码加密失败、生成Token失败
安全要点
- 密码经bcrypt加密存储
- 验证码有效期短且一次性使用（校验通过即删除）

章节来源

登录接口（POST /api/v1/auth/login）

功能概述
- 支持用户名或邮箱登录，校验密码后签发JWT，并记录登录日志
请求参数
- 字段：username（支持用户名或邮箱）、password
- 校验规则：必填、长度范围
响应格式
- 成功：包含token与用户信息
- 失败：401未授权
错误码
- 400：请求参数错误
- 401：用户名/邮箱或密码错误、账号被禁用
安全要点
- 密码使用bcrypt校验
- 登录成功更新最后登录时间
- 失败场景记录登录日志

章节来源

发送验证码接口（POST /api/v1/auth/send-code）

功能概述
- 根据邮箱与类型（注册/重置密码/更换邮箱）生成6位数字验证码，存储至Redis并按类型限流，随后通过SMTP发送邮件
请求参数
- 字段：email、type（枚举：register/reset_password/change_email）
- 校验规则：邮箱格式、type枚举
响应格式
- 成功：通用成功响应
- 失败：错误码与错误信息
错误码
- 400：请求参数错误、发送过于频繁、验证码已过期或不存在、验证码错误
安全要点
- 验证码有效期10分钟
- 发送频率限制1分钟/次
- 邮件服务可开关，未启用时跳过发送

章节来源

重置密码接口（POST /api/v1/auth/reset-password）

功能概述
- 通过邮箱验证码校验后，更新用户密码
请求参数
- 字段：email、verification_code、new_password
- 校验规则：邮箱格式、验证码长度、新密码长度
响应格式
- 成功：通用成功响应
- 失败：400或500
错误码
- 400：请求参数错误、验证码错误
- 500：内部错误（如用户不存在、密码加密失败）
安全要点
- 密码经bcrypt加密存储
- 验证码一次性使用（校验通过即删除）

章节来源

JWT认证机制（登录流程）

生成与签发
- 登录成功后，服务层调用JWT服务生成token，包含用户ID、用户名、角色及标准声明（过期时间、签发时间等）
校验与中间件
- 中间件从Authorization头提取Bearer token并调用JWT服务校验，校验通过后将用户信息写入上下文
过期策略
- JWT过期小时数来自配置，默认值可通过环境变量设置

sequenceDiagram
participant C as "客户端"
participant H as "处理器(Login)"
participant S as "服务(LoginUser)"
participant J as "JWT服务"
participant M as "认证中间件"
C->>H : POST /api/v1/auth/login
H->>S : LoginUser(usernameOrEmail, password)
S->>J : GenerateToken(userID, username, role)
J-->>S : token
S-->>H : 用户信息+token
H-->>C : {token, user_info}
Note over C,M : 访问受保护资源
C->>M : 携带Authorization : Bearer token
M->>J : ValidateToken(token)
J-->>M : Claims
M-->>C : 放行

图表来源

章节来源

验证码服务与邮箱服务集成

验证码生成与存储
- 生成6位数字验证码，存储于Redis，键名包含类型与邮箱，有效期10分钟
- 发送频率限制1分钟/次，避免刷屏
邮件发送
- 根据类型选择不同主题与正文模板，支持465/587端口TLS/STARTTLS
- 邮件服务可开关，未启用时跳过发送
图形验证码（captcha）
- 生成滑块拼图验证码，主图与滑块图以Base64形式返回，目标坐标保存在Redis，验证时比较偏移容差

flowchart TD
Start(["开始"]) --> GenCode["生成6位数字验证码"]
GenCode --> StoreRedis["存储到Redis<br/>键: verification:code:{type}:{email}<br/>过期: 10分钟"]
StoreRedis --> RateLimit["设置发送频率限制<br/>键: verification:rate_limit:{type}:{email}<br/>过期: 1分钟"]
RateLimit --> SendMail["发送邮件(根据类型选择模板)"]
SendMail --> MailOK{"邮件发送成功?"}
MailOK --> |是| Done(["结束"])
MailOK --> |否| Clean["删除Redis验证码键"] --> Fail(["失败"])
subgraph "图形验证码"
GStart["生成滑块拼图验证码"] --> SaveCaptcha["保存目标坐标到Redis<br/>键: captcha:{id}<br/>过期: 5分钟"]
SaveCaptcha --> ReturnBase64["返回主图/滑块图Base64与captchaId"]
Verify["前端提交dx与captchaId"] --> LoadCaptcha["从Redis读取目标坐标"]
LoadCaptcha --> Compare["比较dx与目标坐标容差"]
Compare --> |通过| DelCaptcha["删除Redis记录"]
Compare --> |失败| Warn["返回失败"]
end

图表来源

章节来源

请求/响应示例（示例路径）

注册
- 请求：POST /api/v1/auth/register
- 示例路径：注册请求体定义
- 响应：包含token与用户信息
登录
- 请求：POST /api/v1/auth/login
- 示例路径：登录请求体定义
- 响应：包含token与用户信息
发送验证码
- 请求：POST /api/v1/auth/send-code
- 示例路径：发送验证码请求体定义
- 响应：通用成功响应
重置密码
- 请求：POST /api/v1/auth/reset-password
- 示例路径：重置密码请求体定义
- 响应：通用成功响应

章节来源

common.go

依赖关系分析

组件耦合
- 处理器依赖服务层；服务层依赖JWT与密码工具、Redis与邮件服务
- 中间件依赖JWT服务，统一拦截受保护资源
外部依赖
- Redis：验证码存储与限流
- SMTP：邮件发送
- JWT：令牌签发与校验
循环依赖
- 未见循环依赖迹象

graph LR
AH["auth_handler.go"] --> US["user_service.go"]
AH --> VS["verification_service.go"]
CH["captcha_handler.go"] --> CS["captcha_service.go"]
US --> JWT["jwt.go"]
US --> PW["password.go"]
VS --> EM["email.go"]
VS --> CFG["config.go"]
CS --> CFG
M["auth.go"] --> JWT

图表来源

性能考量

Redis命中率
- 验证码键短生命周期，建议合理设置Redis内存与淘汰策略，避免热键阻塞
邮件发送
- 异步化与重试策略可进一步优化（当前实现为同步发送），避免阻塞请求线程
JWT负载
- Claims中仅包含必要字段，减少token体积，提升网络传输效率
登录日志
- 失败日志写入数据库可能带来IO压力，建议结合异步队列或批量写入

故障排查指南

登录失败
- 现象：401未授权
- 排查：确认用户名/邮箱是否存在、密码是否正确、账号状态是否正常
- 参考路径：登录失败处理
验证码错误/过期
- 现象：400错误
- 排查：确认验证码类型与邮箱匹配、是否在有效期内、是否被重复使用
- 参考路径：验证码校验
邮件发送失败
- 现象：发送验证码接口报错
- 排查：检查邮件服务开关、SMTP配置、网络连通性
- 参考路径：邮件发送
JWT无效
- 现象：访问受保护资源401
- 排查：确认Authorization头格式、token是否过期、签名是否正确
- 参考路径：JWT校验

章节来源

结论

该认证API围绕“路由-处理器-服务-基础设施”清晰分层，实现了完整的注册、登录、验证码与重置密码流程。JWT用于无状态鉴权，bcrypt保障密码安全，Redis与SMTP分别承担验证码与邮件能力。通过严格的参数校验、限流与一次性验证码使用策略，有效提升了安全性与可用性。建议后续引入图形验证码与更完善的限流策略，进一步增强抗暴力破解能力。

附录

安全最佳实践
- 密码加密：始终使用bcrypt
- JWT过期：合理设置过期时间，短期会话建议缩短
- 验证码：短有效期、一次性使用、限流
- 传输安全：生产环境强制HTTPS
- 日志脱敏：避免泄露敏感信息
环境变量与配置
- JWT密钥与过期小时数、邮件SMTP配置、Redis连接参数等均通过环境变量注入

章节来源

config.go

18 KiB Raw Blame History Unescape Escape

认证API

目录

简介

项目结构

核心组件

架构总览

详细组件分析

路由与端点

注册接口（POST /api/v1/auth/register）

登录接口（POST /api/v1/auth/login）

发送验证码接口（POST /api/v1/auth/send-code）

重置密码接口（POST /api/v1/auth/reset-password）

JWT认证机制（登录流程）

验证码服务与邮箱服务集成

请求/响应示例（示例路径）

依赖关系分析

性能考量

故障排查指南

结论

附录

18 KiB

Raw Blame History