获取官方好友用户 ID 列表(chatx)
1. 接口定位
- 接口名称: 获取官方好友用户 ID 列表(chatx)
- 所属域: chat/friend(chatx)
- 业务目标: 返回指定用户(默认当前登录用户)的好友中,官方标识为 true 的用户 ID 列表
2. 请求定义
- Method:
POST - Path:
/chatx/friend/official_user_ids - Content-Type: 推荐
application/json - operationID: 必填,请通过 Header
operationID传入 - 鉴权: 必填,需要通过 Header
token传入有效登录令牌 - 幂等性: 幂等(只读操作)
3. 请求参数
Header 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operationID | 是 | string | 链路追踪 ID |
| token | 是 | string | 登录令牌 |
Body 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| userID | 否 | string | 目标用户 ID;不传时默认当前登录用户 |
| friendUserIDs | 否 | []string | 好友子集过滤;不传时按全部好友过滤,传值时仅在该子集中返回官方好友 ID |
字段约束
- 普通用户仅允许查询自己(
userID为空或等于当前用户);管理员可查任意用户。 friendUserIDs若传入,会先与真实好友集合求交集,再做官方过滤。
4. 响应结构
通用响应包裹
| 字段 | 类型 | 说明 |
|---|---|---|
| errCode | int | 错误码,0 表示成功 |
| errMsg | string | 错误简述 |
| errDlt | string | 错误详情 |
| data | object | 业务数据 |
data 字段结构
| 字段 | 类型 | 说明 |
|---|---|---|
| userIDs | []string | 官方好友用户 ID 列表 |
5. 业务规则
- 官方标识来源于本地 chat 用户属性表
attribute.is_official。 - 返回顺序按候选好友顺序输出,便于前端直接打标。
- 仅返回好友关系内用户,不会返回非好友用户。
6. 性能说明
- 先调用 OpenIM 获取好友 userID 列表。
- 再使用本地 Mongo 条件
user_id in (...) and is_official=true查询。 - 本地查询仅投影
user_id,避免加载无关字段。
7. 错误码与失败场景
| 错误码 | 场景 | 典型报错 |
|---|---|---|
| 1002 | 普通用户查询他人好友 | NoPermission |
| 5000+ | 上游 OpenIM 调用失败 | 透传上游错误码与错误信息 |
8. 示例
请求示例(查询当前用户全部好友)
json
{}请求示例(查询子集)
json
{
"friendUserIDs": ["u_1001", "u_1002", "u_1003"]
}成功响应示例
json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"userIDs": ["u_1001", "u_1003"]
}
}9. 时序流程
- 中间件校验 token。
- RPC 校验 ownerUserID 权限。
- 拉取好友 userID 列表。
- 可选子集过滤(和好友集合求交集)。
- 本地 attribute 表过滤
is_official=true。 - 返回官方好友 userID 列表。
10. 变更记录
- 2026-09-29: 首版发布,新增 chatx 官方好友用户 ID 列表查询能力。