zhibo/模块文档/05-好友管理模块.md

好友管理模块接口文档

模块概述

好友管理模块提供好友搜索、添加、删除、拉黑等功能。

---

接口列表

1. 搜索用户

接口路径: GET /api/front/users/search

请求头:

Authorization: Bearer {token}

请求参数:

keyword: 搜索关键词 (昵称或手机号)
page: 页码 (默认1)
pageSize: 每页数量 (默认20)

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 用户ID,
        "nickname": "昵称",
        "phone": "手机号",
        "avatarUrl": "头像URL",
        "friendStatus": 0
      }
    ],
    "total": 总数,
    "page": 当前页,
    "limit": 每页数量
  }
}

friendStatus说明:

• 0: 未添加
• 1: 已是好友
• 2: 已申请

---

2. 发送好友申请

接口路径: POST /api/front/friends/request

请求头:

Authorization: Bearer {token}

请求参数:

{
  "targetUserId": 目标用户ID,
  "message": "申请消息(可选)"
}

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": true
}

---

3. 获取好友申请列表

接口路径: GET /api/front/friends/requests

请求头:

Authorization: Bearer {token}

请求参数:

page: 页码 (默认1)
pageSize: 每页数量 (默认20)

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 请求ID,
        "from_user_id": 发送者ID,
        "nickname": "发送者昵称",
        "avatarUrl": "头像URL",
        "message": "申请消息",
        "create_time": "创建时间"
      }
    ],
    "total": 总数
  }
}

---

4. 处理好友请求

接口路径: POST /api/front/friends/requests/{requestId}/handle

请求头:

Authorization: Bearer {token}

请求参数:

{
  "accept": true
}

accept说明:

• true: 接受
• false: 拒绝

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": true
}

说明: 接受后自动创建双向好友关系和私聊会话

---

5. 获取好友列表

接口路径: GET /api/front/friends

请求头:

Authorization: Bearer {token}

请求参数:

page: 页码 (默认1)
pageSize: 每页数量 (默认20)

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 好友ID,
        "name": "昵称",
        "avatarUrl": "头像URL",
        "phone": "手机号",
        "isOnline": 1,
        "lastOnlineTime": "最后在线时间"
      }
    ],
    "total": 总数
  }
}

isOnline说明:

• 1: 在线
• 0: 离线

---

6. 删除好友

接口路径: DELETE /api/front/friends/{friendId}

请求头:

Authorization: Bearer {token}

请求参数:

friendId: 好友ID (路径参数)

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": true
}

说明: 删除双向好友关系

---

7. 拉黑好友

接口路径: POST /api/front/friends/block/{friendId}

请求头:

Authorization: Bearer {token}

请求参数:

friendId: 好友ID (路径参数)

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": true
}

说明: 拉黑后自动删除好友关系，被拉黑用户无法再发送好友申请

---

8. 取消拉黑

接口路径: POST /api/front/friends/unblock/{friendId}

请求头:

Authorization: Bearer {token}

请求参数:

friendId: 好友ID (路径参数)

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": true
}

---

9. 获取黑名单列表

接口路径: GET /api/front/friends/blocked

请求头:

Authorization: Bearer {token}

请求参数:

page: 页码 (默认1)
pageSize: 每页数量 (默认20)

返回参数:

{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 用户ID,
        "name": "昵称",
        "avatarUrl": "头像URL",
        "phone": "手机号",
        "blockedTime": "拉黑时间"
      }
    ],
    "total": 总数
  }
}