Skip to content

回填用户封禁状态(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 字段 ​

字段类型说明
blockedUserCountuint32forbidden_account 去重后的封禁用户数
scannedBatchesuint32实际分批次数
updatedBlockedUsersuint32本次回刷写入 is_blocked=true 的修改条数
resetModifiedUsersuint32resetOthers=true 时,预清空 is_blocked=false 的修改条数
batchSizeuint32实际批大小
completedbool是否完成
durationMsint64总耗时(毫秒)
messagestring结果说明(如 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 手动回填用户封禁状态接口。