Batch 批量操作
批量操作把一个命令应用于明确对象集合。设计核心是固定作用范围、选择事务语义、返回逐项账本,并确保重试不会再次处理已完成对象。
批量操作的范围模型
常见选择:
| 模式 | 请求数据 | 适用规模 |
|---|---|---|
| 显式选择 | 对象 ID 列表 | 少量、用户逐项选择 |
| 当前页 | 当前页稳定 ID | 分页任务 |
| 当前查询全部 | 冻结查询 token | 大集合 |
| 全部减排除项 | 查询 token + excluded IDs | 大集合中的少量排除 |
| 导入文件 | 不可变文件快照 | 外部清单 |
不能只发送 selectAll=true。服务端需要知道“全部”对应哪个筛选、权限主体、时间点和版本。
范围快照
{
"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 在执行前声明语义。界面不能在部分失败后才告诉用户“有些已经完成”。
全局原子只在存储和外部副作用确实支持时承诺。跨邮件服务、对象存储和数据库通常无法用一个事务整体回滚。
批次资源
{
"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
}处理中满足:
total = succeeded + failed + skipped + pending结果事件用单项 ID 和序列去重。不能每收到重复事件就增加 succeeded。
逐项账本
{
"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 的同步与异步边界
少量、快速且同事务的批次可以同步返回。大量或外部副作用操作返回批次资源和查询位置,页面不需要保持长连接。
创建批次成功只表示范围和命令已接受。最终结果来自批次终态。网关超时后先查询是否已有同一领域批次,不能让用户重复创建相同外部通知。
任务中心列出创建时间、作用范围、创建者、状态和结果摘要。用户离开原列表后仍能恢复,不依赖组件内存。
执行管线
flowchart LR
S["冻结选择范围"] --> P["预览数量与影响"]
P --> C["用户确认"]
C --> Q["建立批次资源"]
Q --> W["worker 逐项领取"]
W --> A["重新授权与读取版本"]
A --> E["执行领域命令"]
E --> L["写入逐项账本"]
L --> G["聚合守恒计数"]
G --> R["结果页与失败子集"]worker 领取使用租约,崩溃后其他 worker 可恢复。执行与账本之间需要事务、outbox 或领域去重,避免副作用完成但结果丢失。
预览
高风险批次先返回:
- 候选总数;
- 按类别分组;
- 预计不可处理项;
- 影响对象;
- 是否可撤销;
- 预计耗时;
- 权限范围;
- 计费或通知影响。
预览不是保证。执行时对象和权限会变化,最终以逐项结果为准。预览显示快照时间。
确认
确认文本包含操作、范围和不可逆影响:
向 311 张逾期发票发送提醒?
范围:我负责 · 状态为逾期 · 排除 invoice-9
已发送的邮件无法撤回。不要只写“确认批量操作”。若操作可以产生外部通知,明确渠道和收件人数量。
权限
签发 selectionToken 时按当前权限选择候选;执行时每项重新授权。两次检查解决:
- 权限在批次启动前撤销;
- 对象移动到其他租户;
- 用户角色变化;
- 字段级权限改变;
- token 被复制到另一会话。
无权对象的结果不能泄露敏感名称。可以返回安全 ID 或计数,取决于披露策略。
并发变化
候选对象可能:
- 已被删除;
- 状态已变化;
- 已由其他批次处理;
- 版本冲突;
- 不再满足原查询;
- 新加入查询集合。
冻结 token 不自动包含新加入对象。已经离开查询的旧候选如何处理由契约决定:按冻结集合继续,或执行前再次要求仍满足条件。界面必须说明。
部分结果
结束摘要:
已处理 311 张发票
成功 304 · 失败 4 · 跳过 3
[查看 7 个未完成结果] [下载账本]不能仅显示 97.7%。失败和跳过含义不同:失败可能恢复,跳过可能已不满足条件。
结果表支持按 outcome/code 筛选,并保留原范围摘要。
重试
恢复批次建立新 batchId:
- 从原账本选失败项;
- 排除永久错误;
- 查询未知结果;
- 排除已人工完成;
- 读取当前版本;
- 重新授权;
- 形成新范围;
- 执行并关联 parentBatchId。
原批次不可被重写。组合视图按对象展示最终状态,同时可查看每次尝试。
取消
批次取消只停止尚未开始的工作:
- succeeded 保留;
- failed 保留;
- worker 已领取项等待收敛;
- 未领取项标记 not-started-after-cancel。
直到 pending 为零才能给出最终计数。已经发送的邮件或已删除的对象不能通过取消自动撤回。
页面与焦点
选择工具条在选中至少一项后出现,但不应把焦点自动移走。工具条说明已选范围。
操作开始后,用户可以离开页面;任务中心保留批次入口。完成状态消息只播报摘要,不逐项朗读。
结果表按钮名称包含对象。筛选失败项后说明显示数量。选择失效时焦点保留在工具条并要求重新选择。
案例一:批量移动文件
输入
- 显式选择 120 个文件;
- 目标文件夹 version 18;
- 5 个文件无移动权限;
- 3 个同名冲突;
- 2 个在执行前被删除;
- 其余可独立移动。
处理
- 服务端签发显式选择 token;
- 预览目标路径和 120 项;
- 用户选择同名策略“保留两者并重命名”;
- 每项检查源、目标权限和版本;
- 110 个文件移动成功;
- 5 项返回 forbidden;
- 3 项按规则生成唯一名称并成功;
- 2 项返回 missing;
- 最终 113 成功、5 失败、2 跳过;
- 账本记录新路径和文件版本。
验收
- 120 = 113+5+2;
- 成功文件只存在于目标位置;
- 无权限项未泄露目标外敏感路径;
- 同名命名规则确定且可复算;
- 源文件执行期间改变时返回版本冲突;
- 结果页可定位 7 个未正常移动项;
- 重试不再次移动 113 个成功文件。
失败分支
客户端逐个发 120 个请求,页面关闭后失去结果,用户无法知道哪些移动成功。修正为服务端批次资源和逐项账本。
案例二:当前查询全部添加标签
输入
- 当前查询匹配 24,380 个客户;
- 用户排除 12 个;
- 标签为“2026 夏季活动”;
- 执行期间 300 个新客户进入查询;
- 80 个客户已存在相同标签。
处理
- selectionToken 冻结 24,380 个候选;
- 排除后 total=24,368;
- 新加入的 300 个不进入本批次;
- worker 按 ID 和当前权限执行;
- 已有标签的 80 项标记 skipped/already-present;
- 其余成功写入客户-标签关系;
- 唯一约束防止重复关系;
- 结果摘要区分新添加与已存在;
- 用户若要处理新增 300 个,需要创建新批次。
验收
- token 摘要能重现原查询;
- 24,368 = succeeded + skipped + failed;
- 新加入 300 个不被意外处理;
- 已存在标签不重复创建;
- token 不能在另一账号使用;
- 执行期间权限撤销的对象逐项拒绝;
- 下载账本按当前权限生成。
失败分支
服务端执行时重新跑查询,把新增 300 个也加标签。修正为冻结范围与明确新批次。
对账与调试
批次完成后检查:
候选 ID 集合
− succeeded ID
− failed ID
− skipped ID
= 空集合三个结果集合互不相交。副作用表与 succeeded 逐项对账。账本重复事件不改变计数。
调试记录:
- selectionToken 与查询摘要;
- token 主体和期限;
- 预览版本;
- worker 租约;
- 逐项观察版本;
- outcome/code;
- 结果事件序列;
- 关联重试;
- 最终副作用。
观测
- 候选数与终态计数不守恒;
- token 过期和跨主体拒绝;
- 每种 code;
- 批次最老 pending;
- 重试重复处理成功项;
- 取消后仍领取新项;
- 结果账本缺失;
- 用户找不到失败项;
- 大范围确认后放弃;
- 辅助技术无法理解范围。
日志记录批次 ID、对象类型和数量,不记录客户名、文件名或邮件内容。
综合练习:批量更改成员角色
为当前筛选的项目成员更改角色:
- 冻结查询与排除项;
- 防止移除最后一个管理员;
- 按项目分组原子;
- 每项重新授权;
- 用户角色并发变化;
- 逐项账本;
- 失败项目重试;
- 任务中心恢复;
- 取消收敛;
- 结果下载。
验收包含 10,000 个成员、最后管理员约束、权限撤销、worker 崩溃和重复事件。每个项目的管理员不变量必须成立。
来源
- IETF — RFC 9110:HTTP 方法、幂等与状态(访问日期:2026-07-18)
- IETF — RFC 9457:Problem Details(访问日期:2026-07-18)
- W3C WAI — WCAG 2.2 状态消息(访问日期:2026-07-18)
- W3C WAI — WCAG 2.2 信息与关系(访问日期:2026-07-18)