搜索默认好友

1. 接口定位

• 接口名称: 搜索默认好友
• 所属域: admin/default/user
• 业务目标: 按用户 ID 关键字分页搜索默认好友池，并补充用户公开资料

2. 请求定义

• Method: POST
• Path: /default/user/search
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 幂等

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

字段	必填	类型	说明
keyword	否	string	按 user_id 做不区分大小写模糊匹配；为空时等价于全量搜索
pagination	是	object	分页参数

pagination 字段

字段	必填	类型	说明
pageNumber	是	int32	页码，从 1 开始
showNumber	是	int32	每页条数，大于 0

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	uint32	命中的默认好友总数
users	array<object>	当前页结果

users 元素字段

字段	类型	说明
userID	string	默认好友用户 ID
createTime	int64	加入默认好友池的时间，Unix 毫秒时间戳
user	object	用户公开资料

user 字段

字段	类型	说明
userID	string	用户 ID
account	string	账号
email	string	邮箱
nickname	string	昵称
faceURL	string	头像 URL
gender	int32	性别
level	int32	用户等级

5. 业务规则

• 搜索关键字会对默认好友配置表中的 user_id 做 MongoDB $regex 模糊匹配，忽略大小写。
• 返回的 user 对象不是配置表字段，而是 RPC 层再去 chat 用户服务补查的公开资料。
• 如果补查用户公开资料失败，接口整体失败。

6. 错误码与失败场景

错误码	场景	典型报错
1001	pagination 为空	pagination is empty
1001	pageNumber < 1	pageNumber is invalid
1001	showNumber < 1	showNumber is invalid
-	查询默认好友配置失败	由数据库层返回
-	查询用户公开资料失败	由 chat 用户查询链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/default/user/search", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440304",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "9000",
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "keyword": "9000",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "users": [
      {
        "userID": "9000000001",
        "createTime": 1774905600000,
        "user": {
          "userID": "9000000001",
          "account": "alice001",
          "email": "alice@example.com",
          "nickname": "Alice",
          "faceURL": "https://example.com/alice.png",
          "gender": 2,
          "level": 1
        }
      }
    ]
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "pagination is empty"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 校验分页参数。
3. 按 keyword 在默认好友配置表中分页搜索 user_id。
4. 根据当前页 userID 列表补查用户公开资料。
5. 组装 userID/createTime/user 结果并返回。

9. 变更记录

• 2026-03-31: 首版发布，基于默认好友搜索 RPC 的真实检索和资料拼装逻辑补全文档。