hyapp-server/社交关系接口.md at main

2026-06-16 17:00:06 +08:00

5.2 KiB

Raw Permalink Blame History

本文定义 App 端访问记录、关注、好友申请和好友关系接口。关系事实由 user-service 持久化；腾讯云 IM 只负责把好友申请消息送进聊天窗口，不作为好友关系事实来源。

Core Flow

sequenceDiagram
  participant A as User A App
  participant G as gateway-service
  participant U as user-service
  participant IM as Tencent IM
  participant B as User B App

  A->>G: POST /api/v1/users/{B}/friend-requests
  G->>U: ApplyFriend(A, B)
  U-->>G: pending application
  G-->>A: application=pending
  A->>IM: send custom friend request message to B
  IM-->>B: chat window message
  B->>G: POST /api/v1/users/{A}/friend-requests/accept
  G->>U: AcceptFriendApplication(B, A)
  U-->>G: bidirectional friendship
  G-->>B: friend record

关键边界：

申请接口只创建 pending 申请，不直接发 IM。
同意必须调用 accept 接口，不能只靠 IM 消息状态。
删除好友是双向删除。
自己访问自己、关注自己、加自己好友全部拒绝。
重复访问只增加访问次数，不重复增加 visitors_count。
重复关注、重复取消关注、重复同意、重复删除都按幂等处理。

HTTP Endpoints

所有接口都要求完成资料的登录态，响应统一使用 {code,message,request_id,data} envelope。

Method	Path	Purpose
`POST`	`/api/v1/users/{user_id}/visit`	记录访问用户主页
`GET`	`/api/v1/users/me/visitors?page=1&page_size=20`	我的访问记录
`POST`	`/api/v1/users/{user_id}/follow`	关注用户
`DELETE`	`/api/v1/users/{user_id}/follow`	取消关注
`GET`	`/api/v1/users/me/following?page=1&page_size=20`	我的关注列表
`POST`	`/api/v1/users/{user_id}/friend-requests`	申请添加好友
`POST`	`/api/v1/users/{user_id}/friend-requests/accept`	同意该用户发来的好友申请
`GET`	`/api/v1/users/me/friend-requests?direction=incoming&page=1&page_size=20`	好友申请列表，`direction` 支持 `incoming`/`outgoing`
`GET`	`/api/v1/users/me/friends?page=1&page_size=20`	我的好友列表
`DELETE`	`/api/v1/users/{user_id}/friend`	删除好友

Response Examples

访问资料卡：

{
  "recorded": true,
  "target_stats": {
    "visitors_count": 1,
    "following_count": 0,
    "friends_count": 0,
    "updated_at_ms": 1777996800000
  },
  "target_profile": {
    "user_id": "10002",
    "display_user_id": "163002",
    "username": "Bob",
    "avatar": "https://cdn.example.com/avatar.png",
    "profile_bg_img": "https://cdn.example.com/profile-bg.png"
  }
}

申请好友：

{
  "application": {
    "requester_user_id": "10001",
    "target_user_id": "10002",
    "status": "pending",
    "created_at_ms": 1777996800000,
    "updated_at_ms": 1777996800000
  },
  "already_friends": false
}

同意好友：

{
  "friend": {
    "user_id": "10002",
    "friend_user_id": "10001",
    "friended_at_ms": 1777996810000
  }
}

关注：

{
  "following": true,
  "follower_stats": {
    "visitors_count": 0,
    "following_count": 1,
    "friends_count": 0,
    "updated_at_ms": 1777996800000
  }
}

Storage

Table	Owner	Purpose
`user_profile_stats`	user-service	我的页计数 read model：访问人数、关注数、好友数
`user_profile_visits`	user-service	用户主页访问去重记录，主键 `(app_code,target_user_id,visitor_user_id)`
`user_follows`	user-service	单向关注关系，取消关注只改状态
`user_friend_applications`	user-service	好友申请，pending/accepted
`user_friendships`	user-service	双向好友边，每个好友关系写两行

计数更新和关系边写入必须在同一个 MySQL 事务中完成。user_profile_stats 是首屏计数来源，不能在 /users/me/overview 里实时扫关系表。

Room Feed Integration

GET /api/v1/rooms/feeds?tab=visited 是房间访问历史，只由 JoinRoom 成功后写入 room-service 的房间 feed 索引；不要使用 /users/{user_id}/visit 用户主页访问记录填充。
GET /api/v1/rooms/feeds?tab=following 由 gateway 调用 ListFollowing 读取关注用户，再把关系用户和 followed_at_ms 传给 room-service 查询 active 房间卡片。
GET /api/v1/rooms/feeds?tab=friend 由 gateway 调用 ListFriends 读取好友用户，再把关系用户和 friended_at_ms 传给 room-service 查询 active 房间卡片。
GET /api/v1/rooms/feeds?tab=followed 是房间关注列表，只读取 room-service 的 room_follows 用户-房间关系，再 join active 房间卡片。
好友/用户关注关系事实仍归 user-service；房间关注关系事实归 room-service，不能用 user-service 的用户关注表替代。

App Notes

好友申请成功后，App 发送腾讯 IM 自定义消息给对方；消息里携带 requester_user_id 和申请状态展示参数。
聊天窗口点击同意时调用 /api/v1/users/{requester_user_id}/friend-requests/accept。
如果 accept 返回成功，App 再刷新好友列表或本地会话状态。
如果 IM 消息丢失，pending 申请仍可在 /api/v1/users/me/friend-requests?direction=incoming 找回。

5.2 KiB Raw Permalink Blame History Unescape Escape

Social Relations API