357 lines
15 KiB
Markdown
357 lines
15 KiB
Markdown
# 个人资料管理
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [user_handler.go](file://internal/handler/user_handler.go)
|
||
- [routes.go](file://internal/handler/routes.go)
|
||
- [auth.go](file://internal/middleware/auth.go)
|
||
- [user_service.go](file://internal/service/user_service.go)
|
||
- [user_repository.go](file://internal/repository/user_repository.go)
|
||
- [common.go](file://internal/types/common.go)
|
||
- [response.go](file://internal/model/response.go)
|
||
- [user.go](file://internal/model/user.go)
|
||
- [jwt.go](file://pkg/auth/jwt.go)
|
||
- [password.go](file://pkg/auth/password.go)
|
||
- [user_handler_test.go](file://internal/handler/user_handler_test.go)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向开发者与测试人员，系统性梳理“个人资料管理”相关API，重点覆盖：
|
||
- GET /api/v1/user/profile：获取当前登录用户的详细信息
|
||
- PUT /api/v1/user/profile：更新头像与密码（邮箱修改请使用独立接口）
|
||
|
||
文档将解释 UserInfo 数据结构各字段及 JSON 序列化规则；详述密码更新的安全机制（旧密码校验与新密码加密）；说明头像 URL 的更新流程（预签名上传 URL 生成与最终更新）。同时，结合 user_handler.go 中的 GetUserProfile 与 UpdateUserProfile 函数，说明 JWT 中间件如何注入用户上下文，服务层如何调用仓库层执行持久化操作，并提供完整请求/响应示例（含成功与常见错误场景）。
|
||
|
||
## 项目结构
|
||
围绕个人资料管理的代码组织遵循“控制器-中间件-服务-仓库-模型”的分层设计，路由在 v1 组下统一挂载，用户相关接口均受 JWT 认证保护。
|
||
|
||
```mermaid
|
||
graph TB
|
||
Client["客户端"] --> Router["Gin 路由器"]
|
||
Router --> GroupV1["/api/v1 用户组<br/>启用 AuthMiddleware()"]
|
||
GroupV1 --> GetUserProfile["GET /api/v1/user/profile"]
|
||
GroupV1 --> UpdateUserProfile["PUT /api/v1/user/profile"]
|
||
GroupV1 --> AvatarUploadURL["POST /api/v1/user/avatar/upload-url"]
|
||
GroupV1 --> UpdateAvatar["PUT /api/v1/user/avatar"]
|
||
GetUserProfile --> Handler["user_handler.GetUserProfile"]
|
||
UpdateUserProfile --> Handler
|
||
AvatarUploadURL --> Handler
|
||
UpdateAvatar --> Handler
|
||
Handler --> Middleware["AuthMiddleware()<br/>注入 user_id/username/role"]
|
||
Handler --> Service["user_service.*"]
|
||
Service --> Repo["user_repository.*"]
|
||
Service --> Model["model.User"]
|
||
Handler --> Types["types.UserInfo / UpdateUserRequest"]
|
||
Handler --> Resp["model.Response / model.ErrorResponse"]
|
||
```
|
||
|
||
图表来源
|
||
- [routes.go](file://internal/handler/routes.go#L16-L41)
|
||
- [auth.go](file://internal/middleware/auth.go#L12-L56)
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L17-L193)
|
||
- [user_service.go](file://internal/service/user_service.go#L124-L164)
|
||
- [user_repository.go](file://internal/repository/user_repository.go#L17-L69)
|
||
- [common.go](file://internal/types/common.go#L42-L47)
|
||
- [response.go](file://internal/model/response.go#L1-L86)
|
||
|
||
章节来源
|
||
- [routes.go](file://internal/handler/routes.go#L16-L41)
|
||
|
||
## 核心组件
|
||
- 控制器层（Handler）
|
||
- GetUserProfile：从上下文提取 user_id，查询用户并返回 UserInfo
|
||
- UpdateUserProfile：接收 UpdateUserRequest，按需更新密码与头像，返回最新 UserInfo
|
||
- 中间件层（AuthMiddleware）
|
||
- 解析 Authorization: Bearer <token>，校验 JWT 并将用户信息写入上下文
|
||
- 服务层（Service）
|
||
- GetUserByID：封装仓库查询
|
||
- UpdateUserInfo / UpdateUserAvatar：封装仓库更新
|
||
- ChangeUserPassword：校验旧密码并加密新密码后更新
|
||
- 仓库层（Repository）
|
||
- FindUserByID / UpdateUser / UpdateUserFields：数据库读写
|
||
- 类型与模型
|
||
- types.UpdateUserRequest：请求体定义
|
||
- types.UserInfo：响应体定义
|
||
- model.User：数据库映射模型
|
||
- model.Response / model.ErrorResponse：统一响应结构
|
||
|
||
章节来源
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L17-L193)
|
||
- [auth.go](file://internal/middleware/auth.go#L12-L56)
|
||
- [user_service.go](file://internal/service/user_service.go#L124-L164)
|
||
- [user_repository.go](file://internal/repository/user_repository.go#L17-L69)
|
||
- [common.go](file://internal/types/common.go#L42-L47)
|
||
- [user.go](file://internal/model/user.go#L7-L21)
|
||
- [response.go](file://internal/model/response.go#L1-L86)
|
||
|
||
## 架构总览
|
||
以下序列图展示“获取/更新用户资料”的端到端流程，包含 JWT 中间件、控制器、服务与仓库的交互。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant R as "Gin 路由"
|
||
participant M as "AuthMiddleware"
|
||
participant H as "user_handler"
|
||
participant S as "user_service"
|
||
participant RP as "user_repository"
|
||
participant DB as "数据库"
|
||
C->>R : "GET /api/v1/user/profile"
|
||
R->>M : "鉴权中间件"
|
||
M-->>R : "注入 user_id/username/role"
|
||
R->>H : "GetUserProfile"
|
||
H->>S : "GetUserByID(user_id)"
|
||
S->>RP : "FindUserByID(user_id)"
|
||
RP->>DB : "SELECT ..."
|
||
DB-->>RP : "User"
|
||
RP-->>S : "User"
|
||
S-->>H : "User"
|
||
H-->>C : "200 + UserInfo"
|
||
C->>R : "PUT /api/v1/user/profile"
|
||
R->>M : "鉴权中间件"
|
||
M-->>R : "注入 user_id/username/role"
|
||
R->>H : "UpdateUserProfile"
|
||
H->>H : "解析请求体 UpdateUserRequest"
|
||
alt "更新密码"
|
||
H->>S : "ChangeUserPassword(user_id, old, new)"
|
||
S->>RP : "FindUserByID(user_id)"
|
||
RP->>DB : "SELECT ..."
|
||
DB-->>RP : "User"
|
||
RP-->>S : "User"
|
||
S->>S : "CheckPassword(旧密码)"
|
||
S->>S : "HashPassword(新密码)"
|
||
S->>RP : "UpdateUserFields(user_id, {password})"
|
||
RP->>DB : "UPDATE ..."
|
||
DB-->>RP : "OK"
|
||
end
|
||
alt "更新头像"
|
||
H->>S : "UpdateUserInfo(User)"
|
||
S->>RP : "UpdateUser(User)"
|
||
RP->>DB : "SAVE ..."
|
||
DB-->>RP : "OK"
|
||
end
|
||
H->>S : "GetUserByID(user_id)"
|
||
S->>RP : "FindUserByID(user_id)"
|
||
RP->>DB : "SELECT ..."
|
||
DB-->>RP : "User"
|
||
RP-->>S : "User"
|
||
S-->>H : "User"
|
||
H-->>C : "200 + 最新 UserInfo"
|
||
```
|
||
|
||
图表来源
|
||
- [routes.go](file://internal/handler/routes.go#L27-L41)
|
||
- [auth.go](file://internal/middleware/auth.go#L12-L56)
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L17-L193)
|
||
- [user_service.go](file://internal/service/user_service.go#L124-L164)
|
||
- [user_repository.go](file://internal/repository/user_repository.go#L17-L69)
|
||
|
||
## 详细组件分析
|
||
|
||
### GET /api/v1/user/profile：获取当前用户资料
|
||
- 功能概述
|
||
- 仅限已登录用户访问，通过 Authorization: Bearer <token> 进行鉴权
|
||
- 中间件将 user_id 写入上下文，控制器据此查询用户并返回 UserInfo
|
||
- 请求与响应
|
||
- 请求：Authorization: Bearer <token>
|
||
- 成功响应：200 + model.Response{ data: types.UserInfo }
|
||
- 常见错误：401 未授权、404 用户不存在
|
||
- 数据结构与序列化
|
||
- types.UserInfo 字段与 JSON 映射规则详见“附录-数据结构”
|
||
- 错误处理
|
||
- 未携带或无效的 Authorization 头：返回 401
|
||
- 查询不到用户：返回 404
|
||
|
||
章节来源
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L17-L68)
|
||
- [auth.go](file://internal/middleware/auth.go#L12-L56)
|
||
- [routes.go](file://internal/handler/routes.go#L27-L41)
|
||
- [common.go](file://internal/types/common.go#L113-L125)
|
||
- [response.go](file://internal/model/response.go#L1-L86)
|
||
|
||
### PUT /api/v1/user/profile：更新头像与密码
|
||
- 功能概述
|
||
- 支持同时更新头像 URL 与密码；若仅更新头像，可不提供密码字段
|
||
- 密码更新安全机制：必须同时提供旧密码与新密码，服务层校验旧密码并通过 bcrypt 加密新密码后更新
|
||
- 头像更新流程：先生成预签名上传 URL，上传完成后调用更新头像接口，最终返回最新 UserInfo
|
||
- 请求体 UpdateUserRequest
|
||
- avatar：可选，头像 URL
|
||
- old_password：可选，修改密码时必填
|
||
- new_password：可选，修改密码时必填
|
||
- 安全机制与流程
|
||
- 旧密码校验：服务层通过 bcrypt 校验
|
||
- 新密码加密：服务层使用 bcrypt 生成哈希
|
||
- 头像更新：控制器直接更新用户记录；若仅更新头像，服务层保存用户对象
|
||
- 错误处理
|
||
- 未授权：401
|
||
- 参数错误：400（如仅提供新密码或仅提供旧密码）
|
||
- 用户不存在：404
|
||
- 服务器错误：500
|
||
|
||
章节来源
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L70-L193)
|
||
- [user_service.go](file://internal/service/user_service.go#L141-L164)
|
||
- [password.go](file://pkg/auth/password.go#L1-L21)
|
||
- [common.go](file://internal/types/common.go#L42-L47)
|
||
- [response.go](file://internal/model/response.go#L27-L53)
|
||
|
||
### 头像上传与更新流程（补充说明）
|
||
- 生成预签名上传 URL
|
||
- POST /api/v1/user/avatar/upload-url
|
||
- 输入：file_name
|
||
- 输出：post_url、form_data、avatar_url、expires_in
|
||
- 更新头像 URL
|
||
- PUT /api/v1/user/avatar
|
||
- 输入：avatar_url（查询参数）
|
||
- 输出：最新 UserInfo
|
||
- 注意事项
|
||
- 该流程与“更新资料”接口不同，前者用于生成上传凭证，后者用于将最终 URL 写入数据库
|
||
|
||
章节来源
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L195-L326)
|
||
- [routes.go](file://internal/handler/routes.go#L34-L39)
|
||
- [common.go](file://internal/types/common.go#L68-L80)
|
||
|
||
### UserInfo 数据结构与 JSON 序列化规则
|
||
- 字段说明
|
||
- id：用户唯一标识
|
||
- username：用户名
|
||
- email：邮箱
|
||
- avatar：头像 URL
|
||
- points：积分
|
||
- role：角色（如 user）
|
||
- status：账户状态（1 正常，0 禁用，-1 删除）
|
||
- last_login_at：最近登录时间（可空）
|
||
- created_at / updated_at：创建与更新时间
|
||
- JSON 映射
|
||
- model.User 中的 Password 字段在 JSON 中不返回（避免泄露）
|
||
- 其他字段按 gorm 标签映射到 JSON
|
||
|
||
章节来源
|
||
- [user.go](file://internal/model/user.go#L7-L21)
|
||
- [common.go](file://internal/types/common.go#L113-L125)
|
||
|
||
### 请求/响应示例（含错误场景）
|
||
- 获取资料（成功）
|
||
- 请求：Authorization: Bearer <token>
|
||
- 响应：200 + { code: 200, message: "操作成功", data: { id, username, email, avatar, points, role, status, last_login_at, created_at, updated_at } }
|
||
- 更新资料（仅更新头像）
|
||
- 请求体：{ avatar: "https://example.com/new-avatar.png" }
|
||
- 响应：200 + 最新 UserInfo
|
||
- 更新资料（仅更新密码）
|
||
- 请求体：{ old_password: "...", new_password: "..." }
|
||
- 响应：200 + 最新 UserInfo
|
||
- 更新资料（参数错误）
|
||
- 请求体：{ new_password: "..." }（缺少 old_password）
|
||
- 响应：400 + { code: 400, message: "请求参数错误", error: "修改密码需要提供原密码" }
|
||
- 未授权
|
||
- 请求：未携带或无效 Authorization
|
||
- 响应：401 + { code: 401, message: "未授权，请先登录" }
|
||
- 用户不存在
|
||
- 响应：404 + { code: 404, message: "资源不存在" }
|
||
- 服务器错误
|
||
- 响应：500 + { code: 500, message: "服务器内部错误" }
|
||
|
||
章节来源
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L17-L193)
|
||
- [response.go](file://internal/model/response.go#L27-L53)
|
||
- [user_handler_test.go](file://internal/handler/user_handler_test.go#L52-L106)
|
||
|
||
## 依赖分析
|
||
- 控制器依赖
|
||
- user_handler 依赖 gin 上下文中的 user_id，来自 AuthMiddleware
|
||
- 控制器调用 user_service 的 GetUserByID、UpdateUserInfo、ChangeUserPassword、UpdateUserAvatar
|
||
- 服务层依赖
|
||
- user_service 依赖 user_repository 的 FindUserByID、UpdateUser、UpdateUserFields
|
||
- 使用 pkg/auth 的 HashPassword 与 CheckPassword
|
||
- 中间件依赖
|
||
- AuthMiddleware 依赖 pkg/auth/jwt 的 ValidateToken，将 claims 写入上下文
|
||
- 模型与类型
|
||
- model.User 作为 ORM 映射
|
||
- types.UserInfo / UpdateUserRequest 作为 API 层数据契约
|
||
|
||
```mermaid
|
||
graph LR
|
||
Handler["user_handler"] --> Service["user_service"]
|
||
Handler --> Middleware["AuthMiddleware"]
|
||
Handler --> Types["types.*"]
|
||
Handler --> Resp["model.Response / ErrorResponse"]
|
||
Service --> Repo["user_repository"]
|
||
Service --> Auth["pkg/auth/*"]
|
||
Middleware --> JWT["pkg/auth/jwt"]
|
||
Repo --> Model["model.User"]
|
||
```
|
||
|
||
图表来源
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L17-L193)
|
||
- [user_service.go](file://internal/service/user_service.go#L124-L164)
|
||
- [user_repository.go](file://internal/repository/user_repository.go#L17-L69)
|
||
- [auth.go](file://internal/middleware/auth.go#L12-L56)
|
||
- [jwt.go](file://pkg/auth/jwt.go#L1-L71)
|
||
- [password.go](file://pkg/auth/password.go#L1-L21)
|
||
- [common.go](file://internal/types/common.go#L42-L47)
|
||
- [response.go](file://internal/model/response.go#L1-L86)
|
||
- [user.go](file://internal/model/user.go#L7-L21)
|
||
|
||
## 性能考虑
|
||
- 数据库查询
|
||
- GetUserByID 使用精确主键查询，复杂度 O(1)，建议保持索引完善
|
||
- 密码处理
|
||
- bcrypt 默认成本较高，建议在高并发场景关注 CPU 开销；可通过配置调整成本值
|
||
- 缓存策略
|
||
- 对频繁读取的用户资料可在应用层引入缓存（如 Redis），减少数据库压力
|
||
- 日志与可观测性
|
||
- 控制器与服务层已记录关键错误日志，建议配合链路追踪与指标监控
|
||
|
||
## 故障排查指南
|
||
- 401 未授权
|
||
- 检查 Authorization 头是否为 Bearer <token> 格式
|
||
- 确认 token 未过期且签名正确
|
||
- 400 参数错误
|
||
- 密码更新时必须同时提供 old_password 与 new_password
|
||
- 头像 URL 必须为合法 URL
|
||
- 404 用户不存在
|
||
- 确认 user_id 是否有效；检查用户状态是否被禁用或删除
|
||
- 500 服务器错误
|
||
- 检查数据库连接与事务执行情况；查看服务层日志定位具体异常
|
||
|
||
章节来源
|
||
- [user_handler.go](file://internal/handler/user_handler.go#L27-L193)
|
||
- [user_handler_test.go](file://internal/handler/user_handler_test.go#L108-L152)
|
||
- [response.go](file://internal/model/response.go#L27-L53)
|
||
|
||
## 结论
|
||
个人资料管理 API 采用清晰的分层架构：JWT 中间件负责鉴权并将用户上下文注入控制器，控制器协调服务层完成业务逻辑，服务层通过仓库层与数据库交互。密码更新具备严格的旧密码校验与新密码加密流程，头像更新支持预签名上传与最终 URL 写入。通过统一的响应结构与完善的错误处理，系统在安全性与易用性之间取得平衡。
|
||
|
||
## 附录
|
||
|
||
### 数据结构与序列化规则
|
||
- types.UserInfo
|
||
- 字段：id、username、email、avatar、points、role、status、last_login_at、created_at、updated_at
|
||
- JSON 映射：与 model.User 字段一致，除 password 不返回
|
||
- types.UpdateUserRequest
|
||
- 字段：avatar、old_password、new_password
|
||
- 校验：密码更新时 old_password 与 new_password 必须同时提供
|
||
- model.User（数据库映射）
|
||
- 字段：id、username、password、email、avatar、points、role、status、properties、last_login_at、created_at、updated_at
|
||
- JSON：password 不返回；其他字段按标签映射
|
||
- model.Response / model.ErrorResponse
|
||
- 统一响应结构，包含 code、message、data/error
|
||
|
||
章节来源
|
||
- [common.go](file://internal/types/common.go#L42-L47)
|
||
- [common.go](file://internal/types/common.go#L113-L125)
|
||
- [user.go](file://internal/model/user.go#L7-L21)
|
||
- [response.go](file://internal/model/response.go#L1-L86) |