398 lines
13 KiB
Markdown
398 lines
13 KiB
Markdown
# 查询藏品点赞用户列表接口设计
|
||
|
||
## 1. 需求概述
|
||
|
||
**接口名称**: `GET /api/v1/social/assets/:asset_id/likers`
|
||
|
||
**功能描述**: 查询指定藏品的所有点赞用户列表
|
||
|
||
**权限控制**: 仅登录用户可访问
|
||
|
||
**返回内容**: 点赞用户的基本信息（昵称、头像、粉丝等级、点赞时间）
|
||
|
||
---
|
||
|
||
## 2. 现有代码分析
|
||
|
||
### 2.1 相关数据模型
|
||
|
||
**AssetLike 模型** (`pkg/models/asset.go`):
|
||
```go
|
||
type AssetLike struct {
|
||
ID int64 // 点赞记录ID
|
||
AssetID int64 // 资产ID
|
||
UserID int64 // 用户ID
|
||
StarID int64 // 明星ID
|
||
ExhibitionID int64 // 展览ID
|
||
CreatedAt int64 // 点赞时间
|
||
}
|
||
```
|
||
|
||
**关联关系**:
|
||
- `AssetLike.Asset` -> Asset
|
||
- `AssetLike.User` -> User
|
||
- `AssetLike.Star` -> Star
|
||
|
||
### 2.2 现有 Repository 层
|
||
|
||
`asset_like_repository.go` 已有的方法:
|
||
- `GetByAsset(assetID, limit, offset)` - 分页获取点赞记录
|
||
- `CountByAsset(assetID)` - 统计点赞数
|
||
|
||
**问题**: 没有 JOIN 用户表，需要新增或扩展方法
|
||
|
||
**注意**: `GetByAsset` 方法只需要 `assetID`，但 JOIN fan_profiles 需要 `star_id`。由于 `AssetLike` 模型包含 `StarID` 字段，查询时应以 `AssetLike.StarID` 作为 JOIN 条件传给 fan_profiles。
|
||
|
||
### 2.3 现有 Service 层
|
||
|
||
`asset_like_service.go` 已有的方法:
|
||
- `GetAssetLikes(ctx, assetID, page, pageSize)` - 分页获取点赞列表
|
||
|
||
**问题**: 只返回 AssetLike 记录，没有返回用户信息
|
||
|
||
### 2.4 现有 Gateway 层
|
||
|
||
`social_controller.go` 已有点赞相关端点:
|
||
- `POST /api/v1/social/assets/:asset_id/like` - 点赞
|
||
- `DELETE /api/v1/social/assets/:asset_id/like` - 取消点赞
|
||
|
||
**缺失**: 没有查询点赞用户的端点
|
||
|
||
### 2.5 Proto 定义 [待确认]
|
||
|
||
需要检查 `pkg/proto/social/` 是否有现成的消息定义。如已有可复用消息（如 `AssetLiker`），直接引用；如无则按 Section 5 新增。
|
||
|
||
---
|
||
|
||
## 3. 架构设计
|
||
|
||
### 3.1 整体架构
|
||
|
||
```
|
||
HTTP Request
|
||
│
|
||
▼
|
||
Gateway (social_controller.go)
|
||
│ GET /api/v1/social/assets/:asset_id/likers
|
||
│
|
||
▼
|
||
Dubbo RPC Call
|
||
│
|
||
▼
|
||
SocialService (Dubbo Provider)
|
||
│
|
||
├──▶ Redis Cache (asset_likers:{asset_id})
|
||
│
|
||
└──▶ SocialRepository ──► asset_likes + users + fan_profiles JOIN
|
||
```
|
||
|
||
### 3.2 数据流
|
||
|
||
1. Gateway 接收请求，验证登录态
|
||
2. 通过 Dubbo 调用 SocialService
|
||
3. SocialService 先查 Redis 缓存
|
||
4. 缓存未命中 → 调用 SocialRepository 查询（直接访问 DB）
|
||
5. 组装用户信息返回，写入 Redis 缓存
|
||
|
||
---
|
||
|
||
## 4. 性能优化设计
|
||
|
||
### 4.1 分页设计（必须）
|
||
|
||
**游标分页 vs OFFSET 分页**：
|
||
|
||
| 方案 | 优点 | 缺点 | 适用场景 |
|
||
|------|------|------|----------|
|
||
| OFFSET | 简单，支持跳页 | 大 OFFSET 性能差 | 数据量小（<1万） |
|
||
| 游标 | 大数据量性能稳定 | 不能跳页 | 数据量大（>1万） |
|
||
|
||
**决策**：**采用游标分页**
|
||
- 理由：藏品点赞列表通常不会很大，但游标分页更健壮
|
||
- 实现：`cursor` =上一页最后一条的 `created_at` 值
|
||
- 首次请求 `cursor=0` 时，查 DB 不带游标条件，返回第一页
|
||
- `cursor=0` **仅表示不需要 `created_at < ?` 条件**，不表示要重新查 DB
|
||
|
||
### 4.2 索引优化
|
||
|
||
**已有索引**：
|
||
```sql
|
||
-- asset_likes 表
|
||
CREATE INDEX idx_asset_likes_asset ON asset_likes(asset_id); -- 仅 asset_id
|
||
CREATE INDEX idx_asset_likes_user_star ON asset_likes(user_id, star_id); -- 覆盖用户+明星查询
|
||
```
|
||
|
||
**缺失索引（必须新增）**：
|
||
```sql
|
||
-- 游标分页查询：WHERE asset_id = ? AND created_at < ? ORDER BY created_at DESC
|
||
-- 注意：asset_likes 表无软删除字段，无需添加 WHERE 条件
|
||
CREATE INDEX idx_asset_likes_asset_created ON asset_likes(asset_id, created_at DESC);
|
||
-- 幂等执行：迁移脚本应检查索引是否已存在，避免重复执行报错
|
||
```
|
||
|
||
**JOIN 查询计划**：
|
||
```
|
||
asset_likes ──(idx_asset_likes_asset_created)──▶ 扫描 asset_id + created_at 排序
|
||
│
|
||
└──▶ users ──(主键 id)──▶ avatar_url
|
||
└──▶ fan_profiles ──(uk_fan_profiles_user_star)──▶ nickname, level
|
||
```
|
||
**注意**：昵称 nickname 来自 fan_profiles 表，不是 users 表
|
||
|
||
### 4.3 Redis 缓存策略（必须）
|
||
|
||
#### 缓存 Key 设计
|
||
```
|
||
asset_likers:{asset_id} → 完整点赞用户列表（JSON）
|
||
```
|
||
|
||
**为什么不按 cursor 分页存储**：
|
||
- 游标分页的 cursor 值是动态的（最后一条的 `liked_at`）
|
||
- 如果缓存每一页的 cursor，key 会很多且难以管理
|
||
- 更好的方案：**缓存完整列表，按 cursor 在内存中切片**
|
||
|
||
#### 缓存数据结构
|
||
```go
|
||
// AssetLikersCache 缓存数据结构
|
||
type AssetLikersCache struct {
|
||
Users []AssetLikerWithTotal `json:"users"` // 完整用户列表（按 liked_at DESC）
|
||
Total int64 `json:"total"` // 总数
|
||
UpdatedAt int64 `json:"updated_at"` // 缓存更新时间
|
||
}
|
||
|
||
// AssetLikerWithTotal 用户+点赞时间
|
||
type AssetLikerWithTotal struct {
|
||
UserID int64 `json:"user_id"`
|
||
Nickname string `json:"nickname"`
|
||
Avatar string `json:"avatar"`
|
||
FanLevel int32 `json:"fan_level"`
|
||
LikedAt int64 `json:"liked_at"`
|
||
StarID int64 `json:"star_id"` // 用于 JOIN fan_profiles，缓存时保留
|
||
}
|
||
```
|
||
|
||
#### 查询流程
|
||
```
|
||
1. GET asset_likers:{asset_id}
|
||
2. 命中 → 从 users 列表中找 liked_at < cursor 的前 page_size 条（cursor=0 时直接取前 page_size 条）
|
||
3. 未命中 → 查 DB，LIMIT 1000（最多缓存1000条），写入 Redis
|
||
4. 返回数据（users, total, has_more, next_cursor）
|
||
```
|
||
|
||
**游标=0 的处理逻辑（缓存命中时）**：
|
||
- 缓存命中时，无论 cursor 是否为 0，直接从缓存的完整列表中按 cursor 切片
|
||
- `cursor=0` 时返回第一页（liked_at 最大的前 page_size 条）
|
||
- 缓存未命中时，`cursor=0` 才查 DB，且不带游标条件
|
||
|
||
#### 缓存失效
|
||
点赞/取消点赞时删除缓存（应在 `LikeAsset` 和 `UnlikeAsset` 方法末尾调用）：
|
||
```go
|
||
// InvalidateAssetLikersCache 删除藏品点赞用户列表缓存
|
||
func InvalidateAssetLikersCache(ctx context.Context, assetID int64) error {
|
||
if database.RedisClient == nil {
|
||
return nil // Redis 未初始化时跳过
|
||
}
|
||
key := fmt.Sprintf("asset_likers:%d", assetID)
|
||
return database.RedisClient.Del(ctx, key).Err()
|
||
}
|
||
```
|
||
|
||
#### TTL 设计
|
||
- TTL = **60 秒**（1分钟）
|
||
- 理由：藏品点赞延迟 1 分钟可接受，且能有效抗住热点压力
|
||
|
||
#### 容量规划
|
||
| 藏品热度 | 点赞数 | 缓存大小（估算） |
|
||
|---------|--------|-----------------|
|
||
| 普通 | 0-500 | ~50KB |
|
||
| 热门 | 500-5000 | ~500KB |
|
||
| 顶流 | 5000+ | ~5MB（截断到1000条）|
|
||
|
||
**截断策略**：最多缓存 1000 条，超出部分不缓存（直接查 DB）
|
||
|
||
**截断边界行为**：
|
||
- 当某藏品点赞数 > 1000 时，缓存只存储前 1000 条
|
||
- 用户翻页 cursor 超出第 1000 条时 → 缓存未命中 → 直接查 DB，不写入缓存
|
||
- 第 1000 条以内的翻页请求均命中缓存，保证热点藏品翻页稳定
|
||
|
||
**缓存雪崩防护**：
|
||
- TTL = 60 秒，保证缓存会自然过期
|
||
- 即使热点藏品频繁更新，最坏情况延迟也只有 60 秒
|
||
|
||
#### 需要修改的文件
|
||
1. `backend/pkg/database/redis.go` - 添加 `GetAssetLikersCache` 和 `SetAssetLikersCache` 方法
|
||
2. `backend/services/socialService/service/asset_like_service.go` - `GetAssetLikers` 方法：查缓存 → 缓存未命中查DB → 写入缓存
|
||
3. `backend/services/socialService/service/asset_like_service.go` - `LikeAsset` / `UnlikeAsset` 方法末尾调用 `InvalidateAssetLikersCache`
|
||
|
||
---
|
||
|
||
## 5. Proto 定义 (pkg/proto/social/)
|
||
|
||
**新增请求消息**:
|
||
```protobuf
|
||
message GetAssetLikersRequest {
|
||
int64 asset_id = 1;
|
||
int32 page_size = 2; // 每页数量（默认20，最大100）
|
||
int64 cursor = 3; // 游标（上一页最后一条的 created_at，首次请求传0）
|
||
}
|
||
|
||
message GetAssetLikersResponse {
|
||
CommonPB base = 1;
|
||
repeated AssetLiker users = 2;
|
||
int64 total = 3;
|
||
bool has_more = 4; // 是否有更多
|
||
int64 next_cursor = 5; // 下一页游标
|
||
}
|
||
|
||
message AssetLiker {
|
||
int64 user_id = 1;
|
||
string nickname = 2;
|
||
string avatar = 3;
|
||
int32 fan_level = 4;
|
||
int64 liked_at = 5;
|
||
}
|
||
```
|
||
|
||
### 5.1 Repository 层
|
||
|
||
```go
|
||
// GetByAssetWithUsers 获取资产的点赞用户列表（带用户信息，游标分页）
|
||
// 注意：JOIN fan_profiles 需要 star_id，查询时从 AssetLike.StarID 获取
|
||
GetByAssetWithUsers(assetID int64, starID int64, cursor int64, limit int) ([]*AssetLikeWithUser, error)
|
||
|
||
// AssetLikeWithUser 点赞记录+用户信息
|
||
type AssetLikeWithUser struct {
|
||
UserID int64
|
||
Nickname string // 来自 fan_profiles.nickname
|
||
Avatar string // 来自 users.avatar_url
|
||
FanLevel int32 // 来自 fan_profiles.level
|
||
LikedAt int64
|
||
StarID int64 // 来自 al.star_id，用于 JOIN fan_profiles
|
||
}
|
||
```
|
||
|
||
**SQL 查询（游标分页）**:
|
||
```sql
|
||
SELECT
|
||
al.user_id,
|
||
al.star_id, -- 用于后续 fan_profiles JOIN，需显式 select
|
||
COALESCE(fp.nickname, '匿名用户') as nickname, -- 昵称来自 fan_profiles
|
||
u.avatar_url, -- 头像来自 users
|
||
COALESCE(fp.level, 1) as fan_level, -- 粉丝等级别名，统一输出为 fan_level
|
||
al.created_at as liked_at
|
||
FROM asset_likes al
|
||
JOIN users u ON al.user_id = u.id
|
||
LEFT JOIN fan_profiles fp ON al.user_id = fp.user_id AND al.star_id = fp.star_id -- star_id 来自 al.star_id
|
||
WHERE al.asset_id = ?
|
||
AND (? = 0 OR al.created_at < ?) -- cursor=0 时跳过游标条件，返回第一页
|
||
ORDER BY al.created_at DESC
|
||
LIMIT ? -- page_size
|
||
```
|
||
**注意**：
|
||
- `users` 表无 nickname 字段，昵称来自 `fan_profiles.nickname`
|
||
- 需要 `COALESCE` 处理用户可能没有 fan_profile 的情况
|
||
|
||
### 5.2 Service 层
|
||
|
||
```go
|
||
func (s *AssetLikeService) GetAssetLikers(ctx context.Context, assetID int64, starID int64, cursor int64, pageSize int32) (*GetAssetLikersResponse, error)
|
||
```
|
||
|
||
**starID 来源**：
|
||
- 从 `Asset` 模型中获取（Asset 与 Star 有关联）
|
||
- 或从请求上下文/缓存中获取（待实现时确认）
|
||
|
||
**校验逻辑**：
|
||
1. 验证资产是否存在（调用 `assetClient.GetAssetForRPC`）
|
||
2. 资产不存在返回错误
|
||
3. 查询缓存 → 命中则直接切片返回
|
||
4. 未命中 → 查 DB（传入 starID 用于 JOIN fan_profiles）→ 写入缓存 → 返回
|
||
|
||
### 5.3 Gateway 层
|
||
|
||
**路由**: `GET /api/v1/social/assets/:asset_id/likers`
|
||
|
||
**请求参数**:
|
||
- `asset_id`: 路径参数
|
||
- `page_size`: 查询参数（默认20，最大100）
|
||
- `cursor`: 查询参数（上一页返回的 next_cursor，首次请求传0）
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"users": [
|
||
{
|
||
"user_id": 123,
|
||
"nickname": "用户昵称", // 来自 fan_profiles.nickname
|
||
"avatar": "https://...", // 来自 users.avatar_url
|
||
"fan_level": 5, // 来自 fan_profiles.level
|
||
"liked_at": 1716200000000
|
||
}
|
||
],
|
||
"total": 100,
|
||
"has_more": true,
|
||
"next_cursor": 1716199999000
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 路由注册
|
||
|
||
在 `router.go` 中添加:
|
||
```go
|
||
social.GET("/assets/:asset_id/likers", socialCtrl.GetAssetLikers)
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 错误处理 [待确认具体错误码]
|
||
|
||
| 错误场景 | HTTP 状态码 | 错误码 | 错误信息 |
|
||
|---------|------------|--------|---------|
|
||
| 未登录 | 401 | `UNAUTHORIZED` | 未授权 |
|
||
| 资产不存在 | 404 | `ASSET_NOT_FOUND` | 资产不存在 |
|
||
| 服务调用失败 | 500 | `INTERNAL_ERROR` | 服务调用失败 |
|
||
|
||
---
|
||
|
||
## 8. 文件清单
|
||
|
||
需要修改的文件:
|
||
1. `backend/scripts/migrate_asset_likes_cursor_pagination.sql` - 新增 `idx_asset_likes_asset_created` 索引
|
||
2. `backend/proto/social.proto` - 新增 GetAssetLikersRequest/GetAssetLikersResponse/AssetLiker 消息
|
||
3. `backend/pkg/proto/social/*.go` - 重新生成（需执行 protoc 编译）
|
||
4. `backend/pkg/database/redis.go` - 新增 GetAssetLikersCache / SetAssetLikersCache / InvalidateAssetLikersCache 方法
|
||
5. `backend/services/socialService/repository/social_repository.go` - 新增 `GetByAssetWithUsers(assetID, starID, cursor, limit)` 接口方法和实现
|
||
6. `backend/services/socialService/service/asset_like_service.go` - 新增 GetAssetLikers 方法（含缓存逻辑），修改 LikeAsset/UnlikeAsset 添加缓存失效
|
||
7. `backend/services/socialService/provider/social_provider.go` - 在 SocialServiceHandler 接口添加 GetAssetLikers 方法注册
|
||
8. `backend/gateway/controller/social_controller.go` - 新增 GetAssetLikers Handler
|
||
9. `backend/gateway/router/router.go` - 注册路由 `GET /assets/:asset_id/likers`
|
||
|
||
---
|
||
|
||
## 9. 实现顺序
|
||
|
||
1. 新增索引（迁移脚本）
|
||
2. Proto 定义（消息结构）
|
||
3. Redis 缓存方法（`backend/pkg/database/redis.go`）
|
||
4. Repository 层（数据查询）
|
||
5. **点赞/取消点赞时触发缓存失效**（在 Service 层修改前先加，确保无竞态）
|
||
6. Service 层（业务逻辑 + 缓存读取）
|
||
7. Provider 层（注册 RPC 方法）
|
||
8. Controller 层（HTTP 处理）
|
||
9. 路由注册
|
||
|
||
---
|
||
|
||
## 10. 数据库迁移
|
||
|
||
```sql
|
||
-- 为游标分页新增索引（幂等）
|
||
CREATE INDEX IF NOT EXISTS idx_asset_likes_asset_created ON asset_likes(asset_id, created_at DESC);
|
||
```
|