设置用户官方标识(adminx)
1. 接口定位
- 接口名称: 设置用户官方标识
- 所属域: admin/user(adminx)
- 业务目标: 管理员设置用户是否为官方账号,并双写到 OpenIM Server 的
ex扩展字段
2. 请求定义
- Method:
POST - Path:
/adminx/user/official/set - Content-Type: 推荐
application/json - operationID: 必填,请通过 Header
operationID传入 - 鉴权: 必填,需要通过 Header
token传入有效的管理员登录令牌 - 幂等性: 幂等(同一用户重复设置同一值,结果一致)
3. 请求参数
Header 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operationID | 是 | string | 链路追踪 ID |
| token | 是 | string | 管理员登录令牌 |
Body 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| userID | 是 | string | 用户 ID |
| isOfficial | 是 | bool | 是否官方账号 |
字段约束
userID不能为空。- 写入时会读取用户当前
ex(JSON 字符串),仅增量更新isOfficial字段,不覆盖其他已有字段。 - 若用户
ex不是合法 JSON,则返回参数错误。
4. 响应结构
通用响应包裹
| 字段 | 类型 | 说明 |
|---|---|---|
| errCode | int | 错误码,0 表示成功 |
| errMsg | string | 错误简述 |
| errDlt | string | 错误详情 |
| data | any | 业务数据 |
data 字段结构
| 字段 | 类型 | 说明 |
|---|---|---|
| userID | string | 用户 ID |
| isOfficial | bool | 是否官方账号 |
5. 业务规则
- 先更新 chat 属性表中的
is_official字段。 - 再双写到 OpenIM Server 用户
ex字段(JSON merge 更新isOfficial)。 - 双写失败时会回滚 chat 属性表中的
is_official,并返回失败,避免本地与 OpenIM Server 数据不一致。
6. 错误码与失败场景
| 错误码 | 场景 | 典型报错 |
|---|---|---|
| 1001 | userID 为空 | userID is empty |
| 1001 | 用户 ex 非法 JSON | user ex is not valid json |
| 1004 | 用户不存在 | RecordNotFoundError |
| 500 | OpenIM Server 调用失败 | ServerInternalError(示例) |
7. 示例
fetch 请求示例
javascript
fetch("http://localhost:10009/adminx/user/official/set", {
method: "POST",
headers: {
operationID: "550e8400-e29b-41d4-a716-446655440109",
token: "eyJhbGciOi...",
"Content-Type": "application/json",
},
body: JSON.stringify({
userID: "user001",
isOfficial: true,
}),
})
.then((res) => res.json())
.then((data) => console.log(data));请求示例(JSON)
json
{
"userID": "user001",
"isOfficial": true
}成功响应示例
json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"userID": "user001",
"isOfficial": true
}
}8. 时序流程
- 验证管理员 token。
- 校验
userID。 - 更新 chat 属性表
is_official。 - 读取 OpenIM Server 用户信息并解析
ex。 - 合并写入
ex.isOfficial。 - 若第 5 步失败,回滚第 3 步并返回错误。
9. 变更记录
- 2026-09-27: 新增接口,支持管理员设置用户官方标识并双写
ex。