好友资料（按 ID）

1. 接口定位

• 接口名称: 好友资料（按 ID）
• 所属域: client/friend
• 业务目标: 根据好友 ID 列表获取好友资料，结果只包含当前用户的好友

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userIDs	否	array<string>	目标好友用户 ID 列表

字段约束

• userIDs 未传或传空数组时，直接返回空结果。
• 仅返回当前登录用户的好友信息，非好友会被过滤掉。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
total	uint32	返回的好友数量
users	array<object>	好友资料列表

user 对象

字段	类型	说明
userID	string	用户 ID
password	string	密码字段；当前结构沿用 UserFullInfo
account	string	账户
phoneNumber	string	手机号
areaCode	string	区号
email	string	邮箱
nickname	string	昵称
faceURL	string	头像 URL
gender	int32	性别
level	int32	用户等级
birth	int64	生日时间戳
allowAddFriend	int32	是否允许加好友
allowBeep	int32	是否允许提示音
allowVibration	int32	是否允许震动
globalRecvMsgOpt	int32	全局接收消息选项
registerType	int32	注册类型

5. 业务规则

• 仅允许查询当前登录用户的好友资料。
• 实现逻辑与 /friend/search 类似：
  • 先从 OpenIM 获取当前用户好友 ID 列表
  • 只在好友范围内查询资料
• 若 userIDs 为空，或过滤后没有好友，直接返回空结果。
• 当前返回对象直接复用 UserFullInfo 结构，不再要求分页参数。

6. 错误码与失败场景

错误码	场景	典型报错
1002	token 验证失败	NoPermission
5000+	OpenIM 好友列表获取失败	failed to get friend list
5000+	查询用户资料失败	FindUserFullInfo 调用失败

7. 示例

fetch 请求示例

fetch("http://localhost:10010/chatx/friend/profile", {
  method: "POST",
  headers: {
    operationID: "friend-profile-001",
    token: "user-token",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userIDs: ["u_1001", "u_1002"],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userIDs": ["u_1001", "u_1002"]
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 2,
    "users": [
      {
        "userID": "u_1001",
        "password": "",
        "account": "alice",
        "phoneNumber": "13800138000",
        "areaCode": "+86",
        "email": "alice@example.com",
        "nickname": "Alice",
        "faceURL": "https://cdn.example.com/avatar/a.png",
        "gender": 2,
        "level": 1,
        "birth": 946684800,
        "allowAddFriend": 1,
        "allowBeep": 1,
        "allowVibration": 1,
        "globalRecvMsgOpt": 0,
        "registerType": 1
      },
      {
        "userID": "u_1002",
        "password": "",
        "account": "bob",
        "phoneNumber": "13900139000",
        "areaCode": "+86",
        "email": "bob@example.com",
        "nickname": "Bob",
        "faceURL": "https://cdn.example.com/avatar/b.png",
        "gender": 1,
        "level": 2,
        "birth": 978307200,
        "allowAddFriend": 1,
        "allowBeep": 1,
        "allowVibration": 1,
        "globalRecvMsgOpt": 0,
        "registerType": 1
      }
    ]
  }
}

成功响应示例（无匹配好友）

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

8. 时序流程

1. 校验 operationID 和 token。
2. 解析当前登录用户 ID。
3. 若 userIDs 为空，直接返回空结果。
4. 调用 OpenIM 获取当前用户好友 ID 列表。
5. 过滤 userIDs，只保留好友 ID。
6. 若过滤后为空，直接返回空结果。
7. 调用 FindUserFullInfo 查询好友资料。
8. 将结果包装为 SearchUserInfoResp 返回。

9. 变更记录

• 2026-03-31: 首版发布，chatx 好友资料查询接口。