Skip to content

好友资料(按 ID) ​

1. 接口定位 ​

  • 接口名称: 好友资料(按 ID)
  • 所属域: chat/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. 响应结构 ​

通用响应包裹 ​

字段类型说明
errCodeint错误码,0 表示成功
errMsgstring错误简述
errDltstring错误详情
dataobject业务数据

data 字段结构 ​

字段类型说明
totaluint32返回的好友数量
usersarray<object>好友资料列表

user 对象 ​

字段类型说明
userIDstring用户 ID
passwordstring密码字段;当前结构沿用 UserFullInfo
accountstring账户
phoneNumberstring手机号
areaCodestring区号
emailstring邮箱
nicknamestring昵称
faceURLstring头像 URL
genderint32性别
levelint32用户等级
birthint64生日时间戳
allowAddFriendint32是否允许加好友
allowBeepint32是否允许提示音
allowVibrationint32是否允许震动
globalRecvMsgOptint32全局接收消息选项
registerTypeint32注册类型

5. 业务规则 ​

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

6. 错误码与失败场景 ​

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

7. 示例 ​

fetch 请求示例 ​

javascript
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) ​

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

成功响应示例 ​

json
{
  "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
      }
    ]
  }
}

成功响应示例(无匹配好友) ​

json
{
  "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 好友资料查询接口。