EchoChat/docs/api/frontend/contact.md

联系人模块 API (Contact)

通用规范（认证方式、响应格式、错误码）见 README.md

---

接口列表

方法	路径	权限	说明
GET	/api/v1/contacts	需认证	获取好友列表
POST	/api/v1/contacts/request	需认证	发送好友申请
POST	/api/v1/contacts/accept	需认证	接受好友申请
POST	/api/v1/contacts/reject	需认证	拒绝好友申请
GET	/api/v1/contacts/requests	需认证	获取待处理的好友申请列表
DELETE	/api/v1/contacts/:id	需认证	删除好友
PUT	/api/v1/contacts/:id/remark	需认证	修改好友备注
PUT	/api/v1/contacts/:id/group	需认证	移动好友到分组
POST	/api/v1/contacts/block	需认证	拉黑用户
DELETE	/api/v1/contacts/block/:id	需认证	取消拉黑
GET	/api/v1/contacts/block	需认证	获取黑名单
GET	/api/v1/contacts/groups	需认证	获取好友分组列表
POST	/api/v1/contacts/groups	需认证	创建好友分组
PUT	/api/v1/contacts/groups/:id	需认证	修改好友分组
DELETE	/api/v1/contacts/groups/:id	需认证	删除好友分组
GET	/api/v1/contacts/recommend	需认证	好友推荐
GET	/api/v1/users/search	需认证	搜索用户

---

1. 获取好友列表

GET /api/v1/contacts

查询参数：

参数	类型	必填	说明
group_id	int	否	按分组筛选，不传则返回全部

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": [
        {
            "user_id": 2,
            "username": "lisi",
            "nickname": "李四",
            "avatar": "",
            "remark": "我的同事",
            "group_id": 1,
            "is_online": true
        }
    ]
}

---

2. 发送好友申请

POST /api/v1/contacts/request

请求参数：

字段	类型	必填	说明
target_id	int	是	目标用户 ID
message	string	否	申请附言

错误场景：

• 400: 不能添加自己为好友
• 400: 已是好友
• 400: 已有待处理的申请
• 403: 对方已将你拉黑

---

3. 接受好友申请

POST /api/v1/contacts/accept

请求参数：

字段	类型	必填	说明
request_id	int	是	好友申请记录 ID

说明： 接受后系统自动创建双向好友关系，并通过 WebSocket 推送 contact.request.accepted 事件给对方。

---

4. 拒绝好友申请

POST /api/v1/contacts/reject

请求参数：

字段	类型	必填	说明
request_id	int	是	好友申请记录 ID

---

5. 获取待处理的好友申请

GET /api/v1/contacts/requests

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": [
        {
            "id": 5,
            "user_id": 3,
            "username": "wangwu",
            "nickname": "王五",
            "avatar": "",
            "message": "我是你的同学",
            "created_at": "2026-03-01T10:30:00Z"
        }
    ]
}

---

6. 删除好友

DELETE /api/v1/contacts/:id

路径参数： id — 好友的用户 ID

说明： 删除后双向关系均解除。

---

7. 修改好友备注

PUT /api/v1/contacts/:id/remark

路径参数： id — 好友的用户 ID

请求参数：

字段	类型	必填	说明
remark	string	是	新备注名，最多 50 字符

---

8. 移动好友到分组

PUT /api/v1/contacts/:id/group

路径参数： id — 好友的用户 ID

请求参数：

字段	类型	必填	说明
group_id	int	是	目标分组 ID，0 为默认分组

---

9. 拉黑用户

POST /api/v1/contacts/block

请求参数：

字段	类型	必填	说明
target_id	int	是	目标用户 ID

说明： 拉黑后自动解除好友关系（如果存在），对方无法向你发送好友申请和消息。

---

10. 取消拉黑

DELETE /api/v1/contacts/block/:id

路径参数： id — 被拉黑用户的 ID

---

11. 获取黑名单

GET /api/v1/contacts/block

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": [
        {
            "user_id": 5,
            "username": "blocked_user",
            "nickname": "某用户",
            "avatar": ""
        }
    ]
}

---

12. 获取好友分组列表

GET /api/v1/contacts/groups

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": [
        { "id": 1, "name": "同事", "sort_order": 0, "friend_count": 15 },
        { "id": 2, "name": "朋友", "sort_order": 1, "friend_count": 8 }
    ]
}

---

13. 创建好友分组

POST /api/v1/contacts/groups

请求参数：

字段	类型	必填	说明
name	string	是	分组名称，最多 50 字符

---

14. 修改好友分组

PUT /api/v1/contacts/groups/:id

路径参数： id — 分组 ID

请求参数：

字段	类型	必填	说明
name	string	是	新分组名称
sort_order	int	否	排序序号

---

15. 删除好友分组

DELETE /api/v1/contacts/groups/:id

路径参数： id — 分组 ID

说明： 删除分组后，该分组内的好友自动移至默认分组（group_id = 0）。

---

16. 好友推荐

GET /api/v1/contacts/recommend

说明： 基于共同好友算法推荐可能认识的人。

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": [
        {
            "user_id": 8,
            "username": "zhaoliu",
            "nickname": "赵六",
            "avatar": "",
            "common_count": 3
        }
    ]
}

---

17. 搜索用户

GET /api/v1/users/search

查询参数：

参数	类型	必填	说明
keyword	string	是	搜索关键词（用户名/昵称模糊匹配）
page	int	否	页码，默认 1
page_size	int	否	每页数量，默认 20

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": [
        {
            "user_id": 10,
            "username": "newuser",
            "nickname": "新用户",
            "avatar": "",
            "is_friend": false
        }
    ]
}