Skip to content

Batch 批量操作 ​

批量操作把一个命令应用于明确对象集合。设计核心是固定作用范围、选择事务语义、返回逐项账本,并确保重试不会再次处理已完成对象。

批量操作的范围模型 ​

常见选择:

模式请求数据适用规模
显式选择对象 ID 列表少量、用户逐项选择
当前页当前页稳定 ID分页任务
当前查询全部冻结查询 token大集合
全部减排除项查询 token + excluded IDs大集合中的少量排除
导入文件不可变文件快照外部清单

不能只发送 selectAll=true。服务端需要知道“全部”对应哪个筛选、权限主体、时间点和版本。

范围快照 ​

json
{
  "selectionToken": "selection-8841",
  "query": {
    "resource": "invoices",
    "status": [
      "overdue"
    ],
    "owner": "me"
  },
  "snapshotVersion": 31,
  "candidateCount": 312,
  "excludedIds": [
    "invoice-9"
  ],
  "createdAt": "2026-07-18T02:20:00Z",
  "expiresAt": "2026-07-18T02:30:00Z"
}

token 由服务端签发,绑定当前主体和租户。客户端显示查询摘要与 311 个实际候选。筛选改变、token 过期或主体切换后必须重新选择。

选择状态 ​

表头复选框至少区分:

  • 当前页无选择;
  • 当前页部分选择;
  • 当前页全部选择;
  • 已升级为当前查询全部;
  • 查询全部但有排除项;
  • 旧 token 已失效。

“已选择 50 项”与“当前筛选全部 311 项”使用不同文本。复选框视觉混合态不能承担完整范围说明。

原子性选择 ​

语义保证适用
全局原子全部成功或全部回滚同一事务内的强不变量
分组原子组内原子,组间独立按账户、文件或租户分组
尽力执行单项独立提交邮件、标签、独立文件
两阶段审批先预览,再授权执行高风险或巨大范围

批次 API 在执行前声明语义。界面不能在部分失败后才告诉用户“有些已经完成”。

全局原子只在存储和外部副作用确实支持时承诺。跨邮件服务、对象存储和数据库通常无法用一个事务整体回滚。

批次资源 ​

json
{
  "batchId": "invoice-reminder-2048",
  "operation": "invoice.remind",
  "selectionToken": "selection-8841",
  "state": "running",
  "counts": {
    "total": 311,
    "succeeded": 120,
    "failed": 2,
    "skipped": 3,
    "pending": 186
  },
  "resultVersion": 125,
  "canRequestCancellation": true
}

处理中满足:

text
total = succeeded + failed + skipped + pending

结果事件用单项 ID 和序列去重。不能每收到重复事件就增加 succeeded。

逐项账本 ​

json
{
  "batchId": "invoice-reminder-2048",
  "itemId": "invoice-731",
  "observedVersion": 8,
  "outcome": "skipped",
  "code": "already-paid",
  "attempt": 1,
  "processedAt": "2026-07-18T02:20:30Z"
}

账本不可只保存错误项。成功项也是防止重试重复副作用的证据。

observedVersion 说明处理时对象版本。code 是稳定领域分类。attempt 区分关联恢复批次。

分片与背压 ​

24,000 个对象不能一次塞入单个消息或浏览器请求。服务端按批次资源分页读取候选,并将工作切成受控分片。

分片大小取决于:

  • 单项平均耗时;
  • 下游限流;
  • 数据库事务大小;
  • worker 租约时长;
  • 取消响应时间;
  • 单项结果体积;
  • 故障后的重做成本。

分片不是用户可见结果单位。即使一个分片事务失败,也要按契约把每项恢复为 pending 或明确失败,不能丢失 500 项。

背压由执行器限制并发和领取速度。邮件服务返回 429 时,暂停该下游的新领取并遵守等待时间;不要让所有 worker 同时重试。其他不依赖邮件的批次是否继续由资源池隔离决定。

结果存储与分页 ​

逐项账本可能比业务对象更多,需要定义:

  • 结果分区键;
  • 按 outcome/code 的索引;
  • 稳定分页游标;
  • 摘要聚合方式;
  • 下载快照;
  • 保留期限;
  • 原始输入清理;
  • 关联重试查询。

结果页刷新后使用同一 resultVersion。后台归档若改变可见明细,应明确提示,而不是让“失败 4 项”点击后只出现 2 行。

下载文件由服务端从结果账本生成,包含批次 ID、对象 ID、outcome、code、处理时间和观察版本。CSV 公式注入等输出风险需要转义,敏感列按当前权限过滤。

批次 API 的同步与异步边界 ​

少量、快速且同事务的批次可以同步返回。大量或外部副作用操作返回批次资源和查询位置,页面不需要保持长连接。

创建批次成功只表示范围和命令已接受。最终结果来自批次终态。网关超时后先查询是否已有同一领域批次,不能让用户重复创建相同外部通知。

任务中心列出创建时间、作用范围、创建者、状态和结果摘要。用户离开原列表后仍能恢复,不依赖组件内存。

执行管线 ​

mermaid
flowchart LR
    S["冻结选择范围"] --> P["预览数量与影响"]
    P --> C["用户确认"]
    C --> Q["建立批次资源"]
    Q --> W["worker 逐项领取"]
    W --> A["重新授权与读取版本"]
    A --> E["执行领域命令"]
    E --> L["写入逐项账本"]
    L --> G["聚合守恒计数"]
    G --> R["结果页与失败子集"]

worker 领取使用租约,崩溃后其他 worker 可恢复。执行与账本之间需要事务、outbox 或领域去重,避免副作用完成但结果丢失。

预览 ​

高风险批次先返回:

  • 候选总数;
  • 按类别分组;
  • 预计不可处理项;
  • 影响对象;
  • 是否可撤销;
  • 预计耗时;
  • 权限范围;
  • 计费或通知影响。

预览不是保证。执行时对象和权限会变化,最终以逐项结果为准。预览显示快照时间。

确认 ​

确认文本包含操作、范围和不可逆影响:

text
向 311 张逾期发票发送提醒?
范围:我负责 · 状态为逾期 · 排除 invoice-9
已发送的邮件无法撤回。

不要只写“确认批量操作”。若操作可以产生外部通知,明确渠道和收件人数量。

权限 ​

签发 selectionToken 时按当前权限选择候选;执行时每项重新授权。两次检查解决:

  • 权限在批次启动前撤销;
  • 对象移动到其他租户;
  • 用户角色变化;
  • 字段级权限改变;
  • token 被复制到另一会话。

无权对象的结果不能泄露敏感名称。可以返回安全 ID 或计数,取决于披露策略。

并发变化 ​

候选对象可能:

  • 已被删除;
  • 状态已变化;
  • 已由其他批次处理;
  • 版本冲突;
  • 不再满足原查询;
  • 新加入查询集合。

冻结 token 不自动包含新加入对象。已经离开查询的旧候选如何处理由契约决定:按冻结集合继续,或执行前再次要求仍满足条件。界面必须说明。

部分结果 ​

结束摘要:

text
已处理 311 张发票
成功 304 · 失败 4 · 跳过 3
[查看 7 个未完成结果] [下载账本]

不能仅显示 97.7%。失败和跳过含义不同:失败可能恢复,跳过可能已不满足条件。

结果表支持按 outcome/code 筛选,并保留原范围摘要。

重试 ​

恢复批次建立新 batchId:

  1. 从原账本选失败项;
  2. 排除永久错误;
  3. 查询未知结果;
  4. 排除已人工完成;
  5. 读取当前版本;
  6. 重新授权;
  7. 形成新范围;
  8. 执行并关联 parentBatchId。

原批次不可被重写。组合视图按对象展示最终状态,同时可查看每次尝试。

取消 ​

批次取消只停止尚未开始的工作:

  • succeeded 保留;
  • failed 保留;
  • worker 已领取项等待收敛;
  • 未领取项标记 not-started-after-cancel。

直到 pending 为零才能给出最终计数。已经发送的邮件或已删除的对象不能通过取消自动撤回。

页面与焦点 ​

选择工具条在选中至少一项后出现,但不应把焦点自动移走。工具条说明已选范围。

操作开始后,用户可以离开页面;任务中心保留批次入口。完成状态消息只播报摘要,不逐项朗读。

结果表按钮名称包含对象。筛选失败项后说明显示数量。选择失效时焦点保留在工具条并要求重新选择。

案例一:批量移动文件 ​

输入 ​

  • 显式选择 120 个文件;
  • 目标文件夹 version 18;
  • 5 个文件无移动权限;
  • 3 个同名冲突;
  • 2 个在执行前被删除;
  • 其余可独立移动。

处理 ​

  1. 服务端签发显式选择 token;
  2. 预览目标路径和 120 项;
  3. 用户选择同名策略“保留两者并重命名”;
  4. 每项检查源、目标权限和版本;
  5. 110 个文件移动成功;
  6. 5 项返回 forbidden;
  7. 3 项按规则生成唯一名称并成功;
  8. 2 项返回 missing;
  9. 最终 113 成功、5 失败、2 跳过;
  10. 账本记录新路径和文件版本。

验收 ​

  • 120 = 113+5+2;
  • 成功文件只存在于目标位置;
  • 无权限项未泄露目标外敏感路径;
  • 同名命名规则确定且可复算;
  • 源文件执行期间改变时返回版本冲突;
  • 结果页可定位 7 个未正常移动项;
  • 重试不再次移动 113 个成功文件。

失败分支 ​

客户端逐个发 120 个请求,页面关闭后失去结果,用户无法知道哪些移动成功。修正为服务端批次资源和逐项账本。

案例二:当前查询全部添加标签 ​

输入 ​

  • 当前查询匹配 24,380 个客户;
  • 用户排除 12 个;
  • 标签为“2026 夏季活动”;
  • 执行期间 300 个新客户进入查询;
  • 80 个客户已存在相同标签。

处理 ​

  1. selectionToken 冻结 24,380 个候选;
  2. 排除后 total=24,368;
  3. 新加入的 300 个不进入本批次;
  4. worker 按 ID 和当前权限执行;
  5. 已有标签的 80 项标记 skipped/already-present;
  6. 其余成功写入客户-标签关系;
  7. 唯一约束防止重复关系;
  8. 结果摘要区分新添加与已存在;
  9. 用户若要处理新增 300 个,需要创建新批次。

验收 ​

  • token 摘要能重现原查询;
  • 24,368 = succeeded + skipped + failed;
  • 新加入 300 个不被意外处理;
  • 已存在标签不重复创建;
  • token 不能在另一账号使用;
  • 执行期间权限撤销的对象逐项拒绝;
  • 下载账本按当前权限生成。

失败分支 ​

服务端执行时重新跑查询,把新增 300 个也加标签。修正为冻结范围与明确新批次。

对账与调试 ​

批次完成后检查:

text
候选 ID 集合
− succeeded ID
− failed ID
− skipped ID
= 空集合

三个结果集合互不相交。副作用表与 succeeded 逐项对账。账本重复事件不改变计数。

调试记录:

  • selectionToken 与查询摘要;
  • token 主体和期限;
  • 预览版本;
  • worker 租约;
  • 逐项观察版本;
  • outcome/code;
  • 结果事件序列;
  • 关联重试;
  • 最终副作用。

观测 ​

  • 候选数与终态计数不守恒;
  • token 过期和跨主体拒绝;
  • 每种 code;
  • 批次最老 pending;
  • 重试重复处理成功项;
  • 取消后仍领取新项;
  • 结果账本缺失;
  • 用户找不到失败项;
  • 大范围确认后放弃;
  • 辅助技术无法理解范围。

日志记录批次 ID、对象类型和数量,不记录客户名、文件名或邮件内容。

综合练习:批量更改成员角色 ​

为当前筛选的项目成员更改角色:

  • 冻结查询与排除项;
  • 防止移除最后一个管理员;
  • 按项目分组原子;
  • 每项重新授权;
  • 用户角色并发变化;
  • 逐项账本;
  • 失败项目重试;
  • 任务中心恢复;
  • 取消收敛;
  • 结果下载。

验收包含 10,000 个成员、最后管理员约束、权限撤销、worker 崩溃和重复事件。每个项目的管理员不变量必须成立。

来源 ​

从前端走向软件产品工程的长期路线图。