批量查询用户扩展字段 ex
1. 接口定位
- 接口名称: 批量查询用户扩展字段 ex
- 所属域: chat/user
- 业务目标: 按 userIDs 批量查询 open-im-server 用户
ex,供客户端在好友分页后做手动合并展示
2. 请求定义
- Method:
POST - Path:
/user/find/ex - Content-Type: 推荐
application/json - operationID: 必填,请通过 Header
operationID传入 - 鉴权: 必填,需要通过 Header
token传入有效登录令牌 - 幂等性: 幂等(只读操作)
3. 请求参数
Header 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operationID | 是 | string | 链路追踪 ID |
| token | 是 | string | 登录令牌 |
Body 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| userIDs | 是 | []string | 目标用户 ID 列表 |
字段约束
userIDs不能为空。- 响应中的
ex按 open-im-server 原始字符串返回,不做 JSON 解析与改写。
4. 响应结构
通用响应包裹
| 字段 | 类型 | 说明 |
|---|---|---|
| errCode | int | 错误码,0 表示成功 |
| errMsg | string | 错误简述 |
| errDlt | string | 错误详情 |
| data | any | 业务数据 |
data 字段结构
| 字段 | 类型 | 说明 |
|---|---|---|
| users | array | 用户 ex 列表 |
users 元素字段
| 字段 | 类型 | 说明 |
|---|---|---|
| userID | string | 用户 ID |
| ex | string | open-im-server 用户扩展字段(原样返回) |
5. 业务规则
- 接口按 userIDs 批量读取 open-im-server 用户资料中的
ex。 - 结果仅用于读取与展示,不修改任何数据。
6. 错误码与失败场景
| 错误码 | 场景 | 典型报错 |
|---|---|---|
| 1001 | userIDs 为空或未提供 | userIDs is empty |
7. 示例
fetch 请求示例
javascript
fetch("http://localhost:10008/user/find/ex", {
method: "POST",
headers: {
operationID: "550e8400-e29b-41d4-a716-446655440010",
token: "eyJhbGciOiJIUzI1NiIs...",
"Content-Type": "application/json",
},
body: JSON.stringify({
userIDs: ["user001", "user002"],
}),
})
.then((res) => res.json())
.then((data) => console.log(data));请求示例(JSON)
json
{
"userIDs": ["user001", "user002"]
}成功响应示例
json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"users": [
{
"userID": "user001",
"ex": "{\"isOfficial\":true,\"badge\":\"vip\"}"
},
{
"userID": "user002",
"ex": ""
}
]
}
}8. 时序流程
- 验证登录 token。
- 校验
userIDs。 - 批量读取 open-im-server 用户信息。
- 提取并返回每个用户的
ex。
9. 变更记录
- 2026-09-27: 首版发布,新增按 userIDs 批量查询
ex的能力。