搜索朋友

1. 接口定位

• 接口名称: 搜索朋友
• 所属域: client/friend
• 业务目标: 在自己已添加的朋友列表中搜索，支持关键字、性别和分页筛选

2. 请求定义

• Method: POST
• Path: /friend/search
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效的登录令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
userID	否	string	目标用户 ID；若不指定则使用当前用户
keyword	是	string	搜索关键字（昵称、账户等）
genders	否	[]int32	性别过滤：1 男，2 女
pagination	否	RequestPagination	分页参数

字段约束

• keyword 不能为空。
• userID 为空时默认搜索当前登录用户的朋友列表。
• 每个用户只能搜索自己的朋友列表，不能搜索他人朋友。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

字段	类型	说明
total	int64	匹配的朋友总数
users	array	朋友完整信息列表
userID	string	用户 ID
nickname	string	昵称
account	string	账户
email	string	邮箱
phoneNumber	string	手机号
areaCode	string	区号
faceURL	string	头像 URL
gender	int32	性别：1 男，2 女
createTime	int64	创建时间（UNIX 时间戳）

5. 业务规则

• 只能在自己已添加的朋友列表中搜索，不能全局搜索用户。
• 朋友列表从 OpenIM 系统实时获取。
• 若用户没有任何朋友（朋友列表为空），直接返回空结果。
• 返回的是朋友的完整信息（包含邮箱、手机号等私密字段）。
• 支持关键字搜索、性别过滤和分页查询。
• 搜索范围限定在朋友 ID 范围内。

6. 错误码与失败场景

错误码	场景	典型报错
1001	keyword 为空	参数验证失败
1001	分页参数错误	参数验证失败
1002	token 验证失败	NoPermission
20101	业务侧 token 不存在	token not exist
5000+	OpenIM 朋友列表获取失败	failed to get friend list
5000+	搜索 服务端 调用失败	search user info failed

7. 示例

fetch 请求示例

fetch("http://localhost:10008/friend/search", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    token: "eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "李",
    genders: [1],
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "keyword": "李",
  "genders": [1],
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 2,
    "users": [
      {
        "userID": "friend001",
        "nickname": "李四",
        "account": "lisi",
        "email": "lisi@example.com",
        "phoneNumber": "13800138000",
        "areaCode": "+86",
        "faceURL": "https://example.com/avatar1.jpg",
        "gender": 1,
        "createTime": 1704067200
      },
      {
        "userID": "friend002",
        "nickname": "老李",
        "account": "laoli",
        "email": "laoli@example.com",
        "phoneNumber": "13900139000",
        "areaCode": "+86",
        "faceURL": "https://example.com/avatar2.jpg",
        "gender": 1,
        "createTime": 1704153600
      }
    ]
  }
}

失败响应示例（朋友列表为空）

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 0,
    "users": []
  }
}

失败响应示例（keyword 为空）

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "keyword cannot be empty"
}

8. 时序流程

1. 验证令牌。
2. 提取操作者用户 ID（若未指定，则使用当前登录用户）。
3. 校验 keyword 参数不为空。
4. 从 OpenIM 系统获取操作者的朋友列表。
5. 若朋友列表为空，返回空结果。
6. 将搜索范围限定在朋友 ID 列表内。
7. 调用服务端 搜索朋友信息（应用关键字、性别和分页筛选）。
8. 返回搜索结果。

9. 变更记录

• 2026-03-31: 首版发布，包含朋友搜索功能的完整定义和示例。