带进度更新的后台任务：有效的 UI 模式

为什么用户在后台任务运行时会卡住

耗时操作不应该阻塞界面。人们会切换标签、断开连接、合上笔记本，或者只是想知道有没有在进行中。当屏幕看起来“卡住”时，用户开始猜测，而猜测会变成反复点击、重复提交和支持工单。

好的后台处理其实是关于“信心”。用户需要三件事：

• 一个清晰的状态（queued、running、done）
• 时间感（即便只是一个粗略估计）
• 明确的下一步（等待、继续工作、取消或稍后再来）

没有这些，即使任务正常运行，体验也会显得糟糕。

一个常见误解是把慢请求当成真正的后台工作。慢请求仍然是一次 web 调用，让用户等待。后台工作不同：你开启一个作业，立即得到确认，繁重处理在别处进行，UI 仍然可用。

举例：用户上传 CSV 导入客户。如果 UI 阻塞，他们可能刷新、重新上传并产生重复。如果导入在后台启动并且 UI 显示带进度且可安全取消的作业卡，他们可以继续工作并稍后看到清晰结果。

核心构件：作业、队列、工作进程和状态

谈到带进度更新的后台任务时，通常指四个协同工作的部分。

一个 作业（job） 是工作单元："导入这个 CSV"、"生成这个报告" 或 "发送 5,000 封邮件"。队列（queue） 是作业等待的队列。工作进程（worker） 从队列中拉取作业并执行（串行或并行）。

对 UI 来说最重要的是作业的 生命周期状态。保持状态少且可预测：

• Queued：已接受，等待 worker
• Running：正在处理
• Done：成功完成
• Failed：因错误停止

每个作业需要一个 作业 ID（唯一引用）。当用户点击按钮时，立即返回该 ID 并在任务面板显示一行“任务已开始”。

你还需要一种方式问 “现在发生了什么？”。这通常是一个 状态端点（或任何读取方法），接收作业 ID 并返回状态和进度细节。UI 用它来显示完成百分比、当前步骤和任何消息。

最后，状态必须保存在 持久化存储 中，而不仅仅是内存。worker 会崩溃、应用会重启、用户会刷新页面。持久化存储让进度和结果可靠。至少要存：

• 当前状态与时间戳
• 进度值（百分比或计数）
• 结果摘要（创建或更改了什么）
• 错误详情（用于调试和对用户友好的说明）

如果你在像 AppMaster 这样的平台上构建，把状态存储当成任意数据模型：UI 按作业 ID 读取，worker 在执行过程中更新它。

根据工作负载选择合适的队列模式

你选择的队列模式会影响应用的“公平性”和可预测性。如果某个任务排在很多工作后面，用户会体验到看似随机的延迟，即便系统健康。这使得队列选择成为 UX 决策，而不仅仅是基础设施问题。

当流量低、作业短且可以容忍偶发重试时，简单的数据库背书队列通常足够。它易于搭建、易于检查，并能把所有东西放在同一处。例子：管理员为小团队运行夜间报告，重试一次也不会导致恐慌。

当吞吐量上升、作业变重或可靠性成为刚需时，通常需要专门的队列系统。导入、大文件处理、大规模通知以及需要跨重启持续运行的工作，受益于更好的隔离、可见性和更安全的重试行为。这会影响用户可见的进度，因为人们会注意到缺失的更新与卡住的状态。

队列结构也影响优先级。单队列更简单，但把快任务和慢任务混在一起会让快操作变慢。分离队列有助于把用户触发的即时工作与可以等待的计划批处理区分开。

有目的地设置并发限制。并发太高会压垮数据库并让进度感觉不连贯；太低则让系统显得迟缓。每个队列从小且可预测的并发数开始，只有在能保持完成时间稳定时才增加并发。

设计一个能在 UI 显示的进度模型

如果你的进度模型模糊，UI 也会显得模糊。决定系统能诚实报告什么、更新频率以及用户如何使用这些信息。

一个大多数作业都能支持的简单状态模式如下：

• state：queued、running、succeeded、failed、canceled
• percent：当可度量时为 0–100
• message：一句用户能理解的短句
• timestamps：created、started、last_updated、finished
• result_summary：处理数、跳过数、错误数等

接着，定义“进度”是什么意思。

当有真实分母时（文件行数、要发送的邮件数），百分比是合适的。遇到不可预期的工作（依赖第三方、计算量可变或昂贵查询）时，百分比会误导。那时基于步骤的进度更可靠，因为它按清晰的块向前推进。

一个实用规则：

• 当能报告 “X of Y” 时使用 percent。
• 当持续时间未知时使用 steps（例如 Validate file、Import、Rebuild indexes、Finalize）。
• 当两者都不可用时使用 不确定（indeterminate） 进度，但要保持信息更新。

在作业运行时保存部分结果，这让 UI 在作业完成前也能展示有用信息，比如实时错误计数或已变更项的预览。对于 CSV 导入，你可以保存 rows_read、rows_created、rows_updated、rows_rejected，以及最近的几条错误信息。

这是让用户信任的后台任务进度更新的基础：UI 保持冷静，数字持续移动，作业结束时有明确的“发生了什么”总结。

进度更新传递：轮询、推送与混合

把后端进度传到屏幕上是许多实现失败的地方。选择与进度变化频率和预计会查看的用户数量相匹配的传递方式。

轮询最简单：UI 每隔 N 秒请求一次状态。一个不错的默认值是在用户主动查看时每 2 到 5 秒一次，然后随着时间推移逐步放慢。如果任务运行超过一分钟，改为 10 到 30 秒。如果标签页在后台，再放慢频率。

推送更新（WebSockets、Server-Sent Events 或移动通知）适合进度变化快或用户需要即时感知的场景。推送即时，但需要在连接断开时有回退方案。

混合方法常常最佳：开始时快速轮询（让 UI 快速看到 queued 到 running），一旦任务稳定就放慢。如果加入推送，保持慢速轮询作为安全网。

当更新停止时，把它当作一种一等状态展示。显示 “最后更新 2 分钟前” 并提供刷新。在后端，如果作业没有心跳，要把它标记为过时（stale）。

让长时任务看起来清晰的 UI 模式

清晰来自两个方面：少量可预测的状态和告诉用户下一步会发生什么的文案。

在 UI 中命名状态，而不仅仅是在后端。作业可能处于 queued（等待）、running（执行中）、waiting for input（需要用户选择）、completed、completed with errors 或 failed。如果用户无法区分这些状态，他们会认为应用卡住了。

在进度指示器旁用简单有用的文案。例如："Importing 3,200 rows (1,140 processed)" 比单纯写 "Processing." 要好得多。再加一句回答：我可以离开吗，会发生什么？例如："You can close this window. We'll keep importing in the background and notify you when it's ready."（你可以关闭此窗口。我们会在后台继续导入并在完成时通知你。）

进度展示位置应符合用户语境：

• 当任务阻塞下一步需要的结果（例如生成发票 PDF）时，使用模态。
• 对于不应打断用户的短任务，用 toast。
• 对于逐项操作，在表格行内显示内联进度。

对任何超过一分钟的任务，增加一个简单的 Jobs 页面（或 Activity 面板），让用户以后能找到工作结果。

一个清晰的长时任务 UI 通常包含：带最后更新时间的状态标签、进度条（或步骤）、一行细节描述、安全的取消行为，以及带摘要和下一步操作的结果区。保持已完成的作业可被发现，这样用户不会被迫在某个屏幕上等待。

在“不完全成功”情况下报告结果而不让用户困惑

“完成”并不总是完全成功。当后台作业处理 9,500 条记录却有 120 条失败时，用户需要在不看日志的情况下理解发生了什么。

把部分成功作为一种一等结果。在主状态行同时展示两方面信息："Imported 9,380 of 9,500. 120 failed." 这能保持信任并确认工作已被保存。

然后展示一个精简的错误摘要，用户可以据此采取行动："Missing required field (63)"、"Invalid date format (41)"。在最终状态展示 "Completed with issues" 往往比直接显示 "Failed" 更清晰，因为它不会暗示所有都没成功。

可导出的错误报告能把困惑变成待办项。保持简单：行或项的标识、错误类别、人类可读的信息以及相关字段名（如适用）。

把下一步动作放在摘要旁边：修复数据并重试失败项、下载错误报告，或在怀疑是系统问题时联系支持并提供作业 ID。

让取消和重试行为让用户信任

取消和重试看起来简单，但当 UI 说一套系统实际做另一套时会迅速破坏信任。为每种作业类型定义取消的含义，然后在界面中诚实反映。

通常有两种有效的取消模式：

• "立即停止"：worker 经常检查取消标志并迅速退出。
• "当前步骤结束后停止"：当前步骤完成后，作业在下一步骤开始前停止。

在 UI 中展示一个中间状态，例如 "Cancel requested"，以免用户重复点击。

通过设计可重跑的工作让取消变得安全。如果作业会写入数据，优先使用幂等操作（重复运行安全）并在必要时做清理。例如 CSV 导入创建记录时，保存作业运行 ID，这样可以查看第 123 次运行改变了哪些内容。

重试需要同样的清晰度。当可以续跑时重试同一作业实例是合理的；若想要干净的运行并保留新时间戳与审计轨迹，创建新的作业实例更安全。无论采用哪种方案，都要解释会发生什么以及不会发生什么。

保持取消与重试可预测的护栏措施：

• 限制重试次数并显示计数。
• 在作业运行时禁用 Retry，避免重复运行。
• 当重试可能产生重复副作用（邮件、付款、导出）时要求确认。
• 在详情面板展示最后一次错误和最后成功的步骤。

逐步流程：从点击到完成的端到端流程

一个好的端到端流程始于一条规则：UI 永远不应等待工作本身完成，它只应等待作业 ID。

流程（从用户点击到最终状态）

1. 用户启动任务，API 快速返回。 当用户点击 Import 或 Generate report，服务器立即创建作业记录并返回唯一作业 ID。

2. 入队并设置初始状态。 将作业 ID 放入队列并把状态设为 queued，进度 0%。即便还没被 worker 抓取，这也给 UI 提供了真实的显示内容。

3. worker 运行并报告进度。 当 worker 开始时，把状态设为 running、记录开始时间，并以小而诚实的步幅更新进度。如果无法测量百分比，就显示步骤如 Parsing、Validating、Saving。

4. UI 保持用户的方向感。 UI 通过轮询或订阅更新并渲染清晰状态。显示一条短消息（当前在做什么）并只呈现当前合适的操作。

5. 以持久化结果收尾。 完成时保存结束时间、输出（下载引用、创建的 ID、摘要计数）和错误详情。把 finished-with-errors 作为独立结果支持，而不是模糊的成功。

取消与重试规则

取消应是明确的：取消作业会请求取消，然后由 worker 确认并标记为 canceled。重试应创建新作业 ID，保留原始记录作为历史，并说明将重新运行什么。

示例场景：带进度与部分失败的 CSV 导入

CSV 导入是后台任务及进度更新常见的场景。想象一个 CRM，销售运维人员上传了包含 8,420 行的 customers.csv。

上传后，UI 应从 “我点了按钮” 切换为 “作业已存在，你可以离开”。在 Imports 页面展示一个简单的作业卡很合适：

• 上传接收："File uploaded. Validating columns..."
• 排队："Waiting for an available worker (2 jobs ahead)."
• 运行中："Importing customers: 3,180 of 8,420 processed (38%)."
• 收尾："Saving results and building a report..."

运行时显示一个用户能信任的进度数字（已处理行数）和一条简短的状态行（当前在做什么）。如果用户离开页面，在 Recent jobs 区保持该作业可见。

加入部分失败：完成时避免使用吓人的 Failed 横幅（当大多数行都成功时）。用 Finished with issues 并清楚分列：

Imported 8,102 customers. Skipped 318 rows.

用简单易懂的语言解释主要失败原因：邮箱格式不合法、缺少公司等必填字段、或重复的外部 ID。让用户下载或查看包含行号、客户名和需要修复字段的错误表。

重试要让人觉得安全和明确。主要操作可以是 Retry failed rows，创建一个新作业，仅重新处理那 318 行（在用户修好 CSV 后）。保持原始作业为只读以保存历史真实性。

最后，让结果以后容易找到。每次导入都应有稳定摘要：谁运行的、何时、文件名、计数（导入、跳过）以及打开错误报告的方式。

导致进度与重试混乱的常见错误

最快失去信任的方式是展示不真实的数字。一个在 0% 卡两分钟然后直接跳到 90% 的进度条会让人觉得在猜测。如果你不知道真实百分比，就显示步骤（Queued、Processing、Finalizing）或 “X of Y items processed”。

另一个常见问题是仅把进度存在内存里。worker 重启时 UI 会“忘记”作业或重置进度。将作业状态保存在持久化存储中，让 UI 从单一可信源读取。

重试体验也会出问题，当用户能多次启动同一作业时。若 Import CSV 按钮在运行时仍然可点，用户就会点两次并制造重复项。此时重试就不清楚应该修哪个运行。

经常出现的问题包括：

• 虚假的百分比进度与真实工作不符
• 向最终用户展示技术性错误堆栈（堆栈跟踪、错误码）
• 未处理超时、重复或幂等性
• 重试会创建新作业却不解释会发生什么
• 取消只改变 UI 而不影响 worker 行为

一个小但重要的细节：把用户消息与开发者细节分开。向用户显示 "12 rows failed validation"，把技术追踪放在日志里。

上线后台作业前的快速检查清单

在发布前，快速检查用户会注意到的部分：清晰度、可信度和恢复能力。

每个作业都应该暴露一个可以在任何地方显示的快照：状态（queued、running、succeeded、failed、canceled）、进度（百分比或步骤）、短消息、时间戳（created、started、finished）以及结果指针（输出或报告的位置）。

让 UI 状态明显且一致。用户需要一个可靠的位置来查找当前和历史作业，并在他们返回时看到清晰标签（"昨天完成"、"仍在运行"）。Recent jobs 面板通常能防止重复点击和重复工作。

用简单语言定义取消与重试规则。决定每种作业取消意味着什么、是否允许重试、以及会复用哪些输入（同一输入或新的作业 ID）。然后测试边界情形，例如在完成前一刻取消。

把部分失败当成真实结果。展示简短摘要（"Imported 97, skipped 3"）并提供可立即使用的错误报告。

为恢复做规划。作业应能在重启后继续，卡住的作业应超时并进入明确状态并给出下一步建议（"重试" 或 "使用作业 ID 联系支持"）。

下一步：先实现一个工作流，再逐步扩展

挑一个用户已经抱怨的工作流开始：CSV 导入、报告导出、大规模邮件发送或图片处理。先做小而稳：作业被创建、运行、报告状态，并且用户能在以后找到它。

一个简单的作业历史页面通常带来最大的质量提升。它给用户一个返回的地点，而不是盯着转圈的加载器。

先选一个进度传递方式。轮询对第一个版本来说很好。把刷新间隔设置得既不至于压垮后端，又足够让人感觉有响应。

避免重写的实用构建顺序：

• 先实现作业状态与状态转换（queued、running、succeeded、failed、finished-with-errors）
• 添加一个带基本筛选的作业历史页面（最近 24 小时、仅我的作业）
• 只有在能保证诚实时才添加进度数字
• 在能保证一致清理后再添加取消
• 在确认作业幂等后再添加重试

如果不写代码也要构建，可以使用像 AppMaster 这样的无代码平台，通过建模作业状态表（PostgreSQL）并从工作流更新它，然后在 Web 和移动端渲染该状态。对于希望在一处构建后端、UI 与后台逻辑的团队，AppMaster（appmaster.io）旨在支持完整应用，而不仅仅是表单或页面。