14 KiB
14 KiB
用户登录
**本文引用的文件** - [auth_handler.go](file://internal/handler/auth_handler.go) - [routes.go](file://internal/handler/routes.go) - [jwt.go](file://pkg/auth/jwt.go) - [password.go](file://pkg/auth/password.go) - [user_service.go](file://internal/service/user_service.go) - [common.go](file://internal/types/common.go) - [response.go](file://internal/model/response.go) - [user.go](file://internal/model/user.go) - [token.go](file://internal/model/token.go) - [token_service.go](file://internal/service/token_service.go) - [auth.go](file://internal/middleware/auth.go)目录
简介
本文件面向“用户登录”API，围绕 /api/v1/auth/login 端点进行完整说明，覆盖：
- HTTP 方法与路由
- 请求体结构（用户名或邮箱登录）
- 响应格式（包含JWT token与用户信息）
- 错误码与错误处理
- JWT令牌生成流程（访问令牌与声明）
- 登录成功/失败后的审计日志记录（IP、User-Agent）
- 安全建议（防暴力破解、错误提示模糊化）
项目结构
该登录流程涉及以下模块协作：
- 路由层：注册 /api/v1/auth/login 路由
- 控制器层：处理登录请求、参数校验、调用服务层
- 服务层：用户查找、密码校验、令牌生成、登录日志记录
- 认证与密码：JWT服务、bcrypt密码加解密
- 数据模型：用户、登录日志、令牌
- 中间件：JWT认证中间件用于后续受保护接口
graph TB
Client["客户端"] --> Routes["路由注册<br/>/api/v1/auth/login"]
Routes --> Handler["控制器 Login()<br/>参数绑定/错误处理"]
Handler --> Service["服务层 LoginUser()<br/>查找用户/校验密码/生成JWT"]
Service --> JWT["JWT服务 GenerateToken()<br/>签发访问令牌"]
Service --> ModelUser["用户模型 User"]
Service --> ModelLog["登录日志 UserLoginLog"]
Handler --> Resp["统一响应 Response/ErrorResponse"]
Client --> Middleware["认证中间件 AuthMiddleware()<br/>Bearer Token 校验"]
图表来源
章节来源
核心组件
- 路由与控制器
- /api/v1/auth/login 由控制器 Login 处理，负责参数绑定、IP/User-Agent采集、调用服务层并返回统一响应。
- 服务层
- LoginUser 支持用户名或邮箱登录；校验用户状态与密码；生成JWT；更新最后登录时间；记录成功/失败日志。
- 认证与密码
- JWT服务提供 GenerateToken/ValidateToken；密码使用 bcrypt 进行哈希与校验。
- 数据模型
- User：用户信息；UserLoginLog：登录审计日志；Token：令牌模型（用于后续刷新/失效等场景）。
- 统一响应
- Response/ErrorResponse 提供统一的状态码与消息封装。
章节来源
架构总览
登录端到端序列图（POST /api/v1/auth/login）：
sequenceDiagram
participant C as "客户端"
participant R as "路由"
participant H as "控制器 Login()"
participant S as "服务层 LoginUser()"
participant J as "JWT服务"
participant U as "用户模型"
participant L as "登录日志"
C->>R : "POST /api/v1/auth/login"
R->>H : "进入 Login 控制器"
H->>H : "ShouldBindJSON 绑定请求体"
H->>S : "LoginUser(jwtService, username, password, ip, ua)"
S->>U : "根据用户名或邮箱查找用户"
S->>S : "校验用户状态"
S->>S : "bcrypt 校验密码"
S->>J : "GenerateToken(userID, username, role)"
J-->>S : "返回JWT字符串"
S->>U : "更新 last_login_at"
S->>L : "logSuccessLogin/logFailedLogin"
S-->>H : "返回 user, token"
H-->>C : "200 成功响应或401失败响应"
图表来源
详细组件分析
接口定义与请求/响应
- HTTP 方法与路径
- 方法：POST
- 路径：/api/v1/auth/login
- 请求体结构
- 字段：username（支持用户名或邮箱）、password（6-128字符）
- 参数校验：必填、长度约束
- 响应格式
- 成功：统一响应，data 包含 token 与 userInfo
- 失败：统一错误响应，包含 code 与 message
- 错误码
- 400：请求参数错误
- 401：未授权（用户名/邮箱或密码错误、账号被禁用等）
章节来源
请求体结构与参数校验
- 请求体字段
- username：支持用户名或邮箱
- password：6-128字符
- 参数校验
- Gin 绑定时会触发结构体 tag 校验（必填、长度范围）
- 实际行为
- 控制器层在绑定失败时直接返回400
章节来源
登录流程与JWT生成
- 登录流程要点
- 识别登录方式：包含@视为邮箱，否则为用户名
- 校验用户状态（仅状态为正常才允许登录）
- 使用 bcrypt 校验密码
- 生成JWT访问令牌（包含用户ID、用户名、角色等声明）
- 更新最后登录时间
- 记录登录日志（成功/失败均记录IP与User-Agent）
- JWT声明内容
- 包含 user_id、username、role
- 默认包含过期时间、签发时间、生效时间、签发者等注册声明
- 令牌有效期
- 由JWT服务配置的过期小时数决定
flowchart TD
Start(["进入 LoginUser"]) --> Detect["判断登录方式<br/>用户名或邮箱"]
Detect --> FindUser["查找用户"]
FindUser --> Status{"用户状态正常？"}
Status -- 否 --> LogFail["记录失败日志<br/>原因：账号被禁用"]
LogFail --> ReturnErr["返回错误"]
Status -- 是 --> CheckPwd["bcrypt 校验密码"]
CheckPwd --> PwdOK{"密码正确？"}
PwdOK -- 否 --> LogFail2["记录失败日志<br/>原因：密码错误"]
LogFail2 --> ReturnErr
PwdOK -- 是 --> GenToken["GenerateToken(userID, username, role)"]
GenToken --> UpdateTime["更新 last_login_at"]
UpdateTime --> LogSuccess["记录成功日志"]
LogSuccess --> Done(["返回 user, token"])
ReturnErr --> Done
图表来源
章节来源
响应格式与错误码
- 成功响应
- data：包含 token 与 userInfo（id、username、email、avatar、points、role、status、last_login_at、created_at、updated_at）
- 失败响应
- 400：请求参数错误
- 401：未授权（用户名/邮箱或密码错误、账号被禁用）
- 统一响应封装
- Response/ErrorResponse 提供 code、message、data/error 字段
章节来源
登录日志记录（IP、User-Agent）
- 记录内容
- 成功/失败均记录：用户ID、IP地址、User-Agent、登录方式（PASSWORD）、是否成功、失败原因
- 记录时机
- 成功：登录成功后记录
- 失败：用户不存在、账号禁用、密码错误等情况下记录
- 存储位置
- 写入 user_login_logs 表
章节来源
安全考虑与建议
- 防暴力破解
- 建议在网关或应用层增加速率限制（例如基于IP或用户名的限流），在失败时延长冷却时间或临时封禁
- 可结合验证码机制（当前登录接口未强制验证码，但注册/重置密码有验证码流程）
- 错误提示模糊化
- 当前服务层对“用户不存在/密码错误/账号禁用”均返回统一的“用户名/邮箱或密码错误”，避免泄露具体原因
- 令牌管理
- 当前登录仅返回JWT访问令牌；若需刷新令牌，可参考后续令牌服务（刷新/失效等）能力
- 传输安全
- 建议仅在HTTPS下提供登录接口，防止凭据被窃听
章节来源
依赖关系分析
- 控制器依赖
- 控制器 Login 依赖：JWT服务、日志、Redis（注册流程）、服务层 LoginUser
- 服务层依赖
- LoginUser 依赖：用户仓库（查找用户）、JWT服务（生成令牌）、密码工具（bcrypt）、登录日志仓库（写入日志）
- 认证依赖
- JWT服务依赖：golang-jwt库；密码工具依赖：bcrypt
- 模型依赖
- User、UserLoginLog、Token 模型用于数据持久化与审计
graph LR
H["控制器 Login()"] --> S["服务层 LoginUser()"]
H --> J["JWT服务 GenerateToken()"]
S --> U["User 模型"]
S --> L["UserLoginLog 模型"]
S --> P["bcrypt 密码校验"]
H --> R["路由 RegisterRoutes()"]
M["认证中间件 AuthMiddleware()"] --> J
图表来源
章节来源
性能考量
- 登录路径涉及数据库查询与密码校验，建议：
- 对用户表建立合适的索引（username、email）
- 密码校验使用 bcrypt，默认成本适中，可根据硬件能力调整
- 登录日志写入采用异步或批量策略（当前为同步写入，注意高并发下的I/O影响）
- JWT生成与校验为CPU密集度较低的操作，主要瓶颈在数据库与密码校验
故障排查指南
- 常见问题与定位
- 400 参数错误：检查请求体字段是否缺失或长度不符合要求
- 401 未授权：核对用户名/邮箱是否存在、账号状态是否正常、密码是否正确
- 登录日志未记录：确认日志写入是否成功，检查数据库连接与表结构
- 日志与审计
- 成功/失败日志均包含 IP 与 User-Agent，便于追踪来源设备与来源网络
- 令牌相关
- 若后续引入刷新令牌，可参考令牌服务中的刷新/失效逻辑
章节来源
结论
/api/v1/auth/login 提供了完整的用户名或邮箱登录能力，具备参数校验、密码校验、JWT签发与登录日志记录。当前实现聚焦于登录流程本身，后续可在速率限制、验证码、刷新令牌等方面进一步增强安全性与可用性。
附录
API定义与示例
- 端点
- 方法：POST
- 路径：/api/v1/auth/login
- 请求体
- username：字符串，必填，支持用户名或邮箱
- password：字符串，必填，长度6-128
- 成功响应
- code：200
- data：包含 token 与 userInfo
- 示例（结构示意）
- data: { token: "...", userInfo: { id, username, email, avatar, points, role, status, last_login_at, created_at, updated_at } }
- 失败响应
- 400：请求参数错误
- 401：未授权（用户名/邮箱或密码错误、账号被禁用）
章节来源
JWT声明与令牌生命周期
- 声明内容
- user_id、username、role
- 过期时间、签发时间、生效时间、签发者等注册声明
- 令牌类型
- 当前登录返回访问令牌；刷新/失效等能力可参考令牌服务
章节来源