回填用户封禁状态(adminx)
1. 接口定位
- 接口名称: 回填用户封禁状态
- 所属域: admin/user(adminx)
- 业务目标: 将
forbidden_account中的封禁用户同步到attribute.is_blocked,用于高效过滤封禁账号
2. 请求定义
- Method:
POST - Path:
/adminx/user/blocked/backfill - Content-Type: 推荐
application/json - operationID: 必填,请通过 Header
operationID传入 - 鉴权: 必填,管理员 token
- 幂等性: 有条件幂等(同一批次重复回填不会改变最终状态)
3. 请求参数
Header 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| operationID | 是 | string | 链路追踪 ID |
| token | 是 | string | 管理员登录令牌 |
Body 参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| batchSize | 否 | uint32 | 每批处理条数,默认 1000,最大 5000 |
| dryRun | 否 | bool | 是否只统计不写库,默认 false |
| resetOthers | 否 | bool | 是否先将全部用户 is_blocked=false 再回刷封禁用户,默认 false |
4. 响应结构
data 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| blockedUserCount | uint32 | forbidden_account 去重后的封禁用户数 |
| scannedBatches | uint32 | 实际分批次数 |
| updatedBlockedUsers | uint32 | 本次回刷写入 is_blocked=true 的修改条数 |
| resetModifiedUsers | uint32 | resetOthers=true 时,预清空 is_blocked=false 的修改条数 |
| batchSize | uint32 | 实际批大小 |
| completed | bool | 是否完成 |
| durationMs | int64 | 总耗时(毫秒) |
| message | string | 结果说明(如 completed、dry run completed) |
5. 业务规则
- 仅管理员可调用。
- 会先读取
forbidden_account全量 userID,并在内存中去重、去空白。 dryRun=true时不执行任何写库,只返回统计信息。resetOthers=true时,会先执行全量is_blocked=false,再按封禁列表回填true。- 该接口用于手动同步状态,适合上线切换或巡检后修正。
6. 示例
fetch 请求示例
javascript
fetch("http://localhost:10011/adminx/user/blocked/backfill", {
method: "POST",
headers: {
operationID: "adminx-blocked-backfill-001",
token: "eyJhbGciOi...",
"Content-Type": "application/json",
},
body: JSON.stringify({
batchSize: 1000,
dryRun: false,
resetOthers: false,
}),
})
.then((res) => res.json())
.then((data) => console.log(data));请求示例(JSON)
json
{
"batchSize": 1000,
"dryRun": false,
"resetOthers": false
}成功响应示例
json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"blockedUserCount": 3850,
"scannedBatches": 4,
"updatedBlockedUsers": 3850,
"resetModifiedUsers": 0,
"batchSize": 1000,
"completed": true,
"durationMs": 742,
"message": "completed"
}
}dryRun 响应示例
json
{
"errCode": 0,
"errMsg": "",
"errDlt": "",
"data": {
"blockedUserCount": 3850,
"scannedBatches": 0,
"updatedBlockedUsers": 0,
"resetModifiedUsers": 0,
"batchSize": 1000,
"completed": true,
"durationMs": 31,
"message": "dry run completed"
}
}7. 变更记录
- 2026-09-27: 首版发布,新增 adminx 手动回填用户封禁状态接口。