133 lines
6.6 KiB
Markdown
133 lines
6.6 KiB
Markdown
---
|
||
name: 用户头像上传接口
|
||
overview: 新增服务端中转的头像上传接口 POST /api/v1/user/avatar/upload，复用现有衣物上传的图片校验与 COS 上传能力，校验通过后上传 COS 并将头像 key 写入 users.avatar，最后失效用户缓存。
|
||
todos:
|
||
- id: avatar-service
|
||
content: 实现 UserService.AvatarUpload（校验、COS 上传、更新 avatar、失效缓存）与 buildUserInfoResponse 头像 URL 转换
|
||
status: completed
|
||
- id: avatar-api
|
||
content: 新增头像上传 DTO 与 UserHandler.AvatarUpload，注册 POST /user/avatar/upload 路由
|
||
status: completed
|
||
dependencies:
|
||
- avatar-service
|
||
- id: avatar-docs
|
||
content: 同步更新接口文档.md 与 README.md 的头像上传接口说明
|
||
status: completed
|
||
dependencies:
|
||
- avatar-api
|
||
---
|
||
|
||
## 产品概述
|
||
|
||
为当前用户新增"头像文件上传"能力。此前后端只允许通过 `PUT /user/profile` 传入头像 URL 字符串，现需提供方案 A（服务端中转）：客户端以 multipart 上传头像图片，后端完成校验、存储到 COS，并更新用户头像字段，返回可直接访问的头像 URL。
|
||
|
||
## 核心功能
|
||
|
||
- 新增鉴权接口 `POST /api/v1/user/avatar/upload`，multipart 字段名 `file`
|
||
- 后端校验上传文件：非空、扩展名白名单、大小上限、图片 magic bytes
|
||
- 上传成功后写入 COS，并将 COS 对象键保存到 `users.avatar`
|
||
- 更新成功后失效用户信息缓存，返回可访问的头像 URL 供前端立即展示
|
||
- 用户信息查询接口对头像做兼容转换：历史 URL 直接透传，新存 COS key 自动转可访问 URL
|
||
- 头像上传不消耗衣物 COS 上传额度
|
||
|
||
## 技术栈
|
||
|
||
- 语言/框架：Go + Gin（沿用现有项目栈）
|
||
- 存储：腾讯云 COS（复用 `global.CosClient`）
|
||
- 缓存：Redis（复用 `redisdao.UserInfoDel` 失效用户缓存）
|
||
- 持久层：GORM（复用 `mysqldao.UserDao`）
|
||
- 工具函数：复用 `pkg/upload` 的文件校验、落盘、COS 上传、URL 生成能力
|
||
- 无新增第三方依赖
|
||
|
||
## 实施方案
|
||
|
||
### 整体策略
|
||
|
||
仿照现有衣物上传 `ClothesService.Upload` 的同步链路，在用户模块新增头像上传能力：Handler 解析 multipart → Service 完成校验、落盘、上传 COS、更新数据库、失效缓存 → 返回头像 URL。
|
||
|
||
### 关键决策
|
||
|
||
1. **复用现有校验链路与错误码**：扩展名白名单（`global.UploadSetting.AllowedExtensions`）、大小上限（`global.UploadSetting.MaxSizeMB`）、magic bytes 校验，以及 `UploadFileEmpty` / `UploadFileExtNotAllow` / `UploadFileTooLarge` / `UploadFileSaveFailed` 错误码，保持与衣物上传一致。
|
||
2. **avatar 存储 COS 对象键而非完整 URL**：与衣物 `processed_image` 存 key 的语义一致，读取时统一经 `upload.GetCosUrl` 转换；对历史通过 `PUT /user/profile` 传入的 http(s) URL 直接透传，保证向后兼容。
|
||
3. **COS key 规则**：`{user.UserUUID}/{userID}/avatar/{随机名+原扩展名}`，复用 `FileGenName` 防冲突，且按用户维度隔离，避免跨用户覆盖。
|
||
4. **不扣 COS 上传额度**：头像属基础资料，与衣物图片处理（抠图/分类）成本不同，不调用 `consumeCosQuota`。
|
||
5. **上传后失效缓存**：调用 `redisdao.UserInfoDel(ctx, userID)`，使 `InfoGetBySelf` / `WxLogin` 下次回读最新头像。
|
||
|
||
### 数据流
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as 客户端
|
||
participant H as UserHandler.AvatarUpload
|
||
participant S as UserService.AvatarUpload
|
||
participant U as pkg/upload
|
||
participant COS as 腾讯云 COS
|
||
participant D as UserDao
|
||
participant R as Redis
|
||
|
||
C->>H: POST /user/avatar/upload (multipart file)
|
||
H->>H: JWT 鉴权 + MaxBytesReader 限流
|
||
H->>S: AvatarUpload(ctx, userID, fileHeader)
|
||
S->>S: 扩展名/大小/magic bytes 校验 + 读取字节
|
||
S->>D: UserGetByID 获取 UserUUID
|
||
S->>U: FileGenName + FileSaveTmpBytes
|
||
S->>U: FileUploadCos(cosKey)
|
||
U->>COS: 上传对象
|
||
S->>D: UserUpdateByID(avatar=cosKey)
|
||
S->>R: UserInfoDel 失效缓存
|
||
S-->>H: 返回头像可访问 URL
|
||
H-->>C: 统一响应
|
||
```
|
||
|
||
## 实现细节
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
project-root/
|
||
├── internal/
|
||
│ ├── dto/
|
||
│ │ └── user.go # [MODIFY] 新增 UserAvatarUploadRequest（空）/ UserAvatarUploadResponse
|
||
│ ├── service/
|
||
│ │ └── user.go # [MODIFY] 新增 AvatarUpload 方法；buildUserInfoResponse 头像 URL 转换；补充 imports
|
||
│ ├── routers/
|
||
│ │ ├── router.go # [MODIFY] 注册 POST /user/avatar/upload
|
||
│ │ └── api/v1/
|
||
│ │ └── user.go # [MODIFY] 新增 UserHandler.AvatarUpload；补充 imports
|
||
├── 接口文档.md # [MODIFY] 新增头像上传接口说明
|
||
└── README.md # [MODIFY] 同步用户接口说明
|
||
```
|
||
|
||
### 关键代码结构
|
||
|
||
```
|
||
// internal/dto/user.go
|
||
type UserAvatarUploadRequest struct{}
|
||
|
||
type UserAvatarUploadResponse struct {
|
||
Avatar string `json:"avatar"` // 头像可访问 URL
|
||
}
|
||
```
|
||
|
||
```
|
||
// internal/service/user.go
|
||
func (s *UserService) AvatarUpload(ctx context.Context, userID int64, fileHeader *multipart.FileHeader) (*dto.UserAvatarUploadResponse, *errcode.Error)
|
||
```
|
||
|
||
`buildUserInfoResponse` 中头像转换逻辑：
|
||
|
||
```
|
||
avatar := user.Avatar
|
||
if avatar != "" && !strings.HasPrefix(avatar, "http://") && !strings.HasPrefix(avatar, "https://") {
|
||
avatar = upload.GetCosUrl(avatar)
|
||
}
|
||
```
|
||
|
||
### 执行要点
|
||
|
||
- **imports 补充**：`internal/service/user.go` 需新增 `io`、`mime/multipart`、`pkg/upload`；`internal/routers/api/v1/user.go` 需新增 `net/http`、`global`、`pkg/errcode`（若缺）。
|
||
- **错误映射**：`FileSaveTmpBytes`、`FileUploadCos` 返回原生 error 时统一映射为 `errcode.UploadFileSaveFailed`；`UserGetByID` 未命中映射 `UserNotFound`，其他 DB 错误映射 `DatabaseError`；`UserUpdateByID` 失败映射 `UserUpdateFailed`。
|
||
- **同步读取字节**：multipart 临时文件在请求返回后会被清理，必须在 Service 内同步 `io.ReadAll` 后再异步/后续处理（本方案全同步，无异步环节）。
|
||
- **`buildUserInfoResponse` 影响面**：该函数同时被 `InfoGetBySelf` 与 `WxLogin` 使用，头像 URL 转换对两处一并生效，属预期行为，无需额外改动。
|
||
- **缓存失效**：复用 `ProfileUpdate` 既有模式 `_ = redisdao.UserInfoDel(ctx, userID)`，失败仅忽略（best-effort），下次读取会回落 DB 回填。
|
||
- **兼容性保障**：不修改 `PUT /user/profile` 的现有 avatar 传 URL 语义，避免破坏已有客户端；仅扩展用户信息读取时的 URL 转换。 |