搜索好友（chatx）

1. 接口定位

• 接口名称: 搜索好友（chatx）
• 所属域: chat/friend（chatx）
• 业务目标: 在指定用户的好友集合内执行关键字搜索，支持分页和性别筛选

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	否	string	目标用户 ID；为空时默认当前登录用户
keyword	否	string	搜索关键字（可匹配 userID/account/nickname 等）
pagination	是	RequestPagination	分页参数
genders	否	[]int32	性别过滤：1 男，2 女

字段约束

• pagination 必填；未传会返回 Pagination is nil。
• pagination.pageNumber >= 1 且 pagination.showNumber >= 1。
• keyword 可为空；为空时表示按筛选条件分页返回好友资料。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
total	uint32	匹配的好友总数
users	array<object>	好友完整信息列表

users 元素（UserFullInfo）

返回结构与 chat.SearchUserInfo 一致，常用字段包括：

• userID / account / nickname / faceURL
• phoneNumber / areaCode / email
• gender / level / birth

5. 权限与业务规则

• 普通用户：仅可查询自己的好友集合。
• 管理员用户：可查询任意 userID 的好友集合。
• 当 userID 为空时，默认使用当前登录用户。
• 搜索范围先由好友关系限定，再应用关键字、性别和分页过滤。
• 关键字匹配字段与 Chat SearchUserInfo 一致：user_id、account、nickname、phone_number、email。
• 若目标用户无好友，返回空结果：total = 0，users = []。

6. 错误码与失败场景

错误码	场景	典型报错
1001	分页参数缺失或非法	Pagination is nil / pageNumber is invalid
1002	token 无效或缺失	NoPermission
1002	越权查询他人好友集合	NoPermission（ownerUserID）
5000+	获取好友列表失败	上游 IM API 调用失败
5000+	用户搜索服务调用失败	SearchUserInfo 调用失败

7. 示例

请求示例（查询当前用户好友）

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

请求示例（管理员查询指定用户好友）

{
  "userID": "u_10001",
  "keyword": "alice",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 10
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "users": [
      {
        "userID": "u_20001",
        "account": "alice",
        "nickname": "Alice",
        "faceURL": "https://cdn.example.com/avatar/a.png",
        "phoneNumber": "13800138000",
        "areaCode": "+86",
        "email": "alice@example.com",
        "gender": 2,
        "level": 1,
        "birth": 946684800
      }
    ]
  }
}

失败响应示例（普通用户跨用户查询）

{
  "errCode": 1002,
  "errMsg": "NoPermission",
  "errDlt": "ownerUserID"
}

8. 时序流程

1. API 层校验 token，并将请求透传到 chatx friend RPC。
2. RPC 层解析调用者身份（普通用户/管理员）。
3. 计算目标 ownerUserID：优先用请求 userID，否则用登录用户。
4. 执行权限校验：仅 owner 本人或管理员可通过。
5. 通过 IM API 获取 owner 的好友 ID 列表。
6. 用好友 ID 列表 + keyword + genders + pagination 调用 Chat 搜索服务。
7. 返回分页结果。

9. 变更记录

• 2026-07-06: 首版发布，新增 chatx 好友关键字搜索接口文档。