报表接口原本是同步的,生成一次要十几秒,用户点一下要等很久。改成「先返回 202,再后台跑」之后,本地测试很顺:请求立刻返回,日志里能看到任务开始和结束。但上线第一周出了三次问题:发布重启时正在跑的任务直接消失;某个任务 panic 了,请求方完全不知道;还有人把一个「等第三方回调」的逻辑写成了 std::thread::sleep,那几分钟里整个服务的接口都变慢了。
这三个问题的根源,都是把「进程内的一个异步任务」当成了「可靠的后台队列」。tokio::spawn 确实能让你立刻返回,但它不负责持久化、不负责重试、也不负责隔离阻塞。它只是把工作交给当前运行时,进程一停,任务就没了。
这篇在上一篇的鉴权和数据层之上加任务接口:先用 tokio::spawn 跑通最短链路,再讲清楚它的三个边界,然后用有界队列解决「任务无限堆积」,最后给出「什么时候必须上独立 worker 加消息队列」的判断条件。CPU 密集、阻塞调用、进程重启这些坑会逐个拆开。
先看现象:后台任务的九个典型故障
后台任务的故障往往不在任务代码本身,而在「任务和请求的关系」上。请求返回之后发生的事,用户看不到,监控也容易漏。下面这张表按现象排,前三条是最常见的。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 接口返回 202,任务却没执行 | spawn 之后的运行时被关闭,或 worker 没启动 | 看任务开始日志和运行时生命周期 |
| 进程重启后任务丢失 | 任务只在内存里,没有持久化 | 是否有任务表或消息队列 |
| 任务 panic,请求方毫无感知 | JoinHandle 被丢弃,panic 不会传回请求 | 是否保留并 await 句柄,或装 panic hook |
| 一个任务让所有接口变慢 | 任务里调用了阻塞函数,占住运行时 worker 线程 | 搜代码里的 std::thread::sleep、同步 IO |
| CPU 密集任务拖垮延迟 | 计算跑在 async worker 上,不让出执行权 | 是否用 spawn_blocking 或独立进程 |
| 并发一高内存就涨 | 每个请求都 spawn,没有上限 | 是否有有界队列或并发信号量 |
| 队列满了,请求一直卡住 | 用 send().await 无限等待 | 是否用 try_send 并返回 503 或 429 |
| 同一任务被执行两次 | 队列至少投递一次,任务没有幂等键 | 是否有唯一约束或幂等表 |
| 失败后没有重试 | 任务错误被吞掉,没有状态记录 | 是否有重试次数和下次执行时间 |
这张表里最容易被低估的是第四条。阻塞调用不会报错,也不会留下明显痕迹,它只是让线程闲着等,表现为「接口偶尔变慢、并发上不去」。在本地单人测试时几乎复现不了,一上压力就暴露。第 3 节会把这个机制讲透。
job_id 之后,应该通过另一个接口查询状态,而不是认为事情已经完成。如果任务可能失败,状态接口要能返回失败原因和重试次数。tokio::spawn 与 JoinHandle 的边界
这一篇不需要新的依赖,tokio 的 full 特性已经包含 spawn、time 和 sync:
[dependencies]
tokio = { version = "1", features = ["full"] }
cargo run
tokio::spawn 把一个 future 交给运行时,立刻返回一个 JoinHandle。future 会在某个 worker 线程上被轮询执行,和当前请求并发。JoinHandle 是用来等待结果和获取返回值的句柄;如果你不保存它,任务仍然会跑,但你失去了和它的联系:不知道它何时结束、是否 panic、返回值是什么。
下面是最短的任务接口。NEXT_JOB 用原子计数器生成 id,spawn 里的闭包移动一份 id,睡眠 800 毫秒模拟报表生成,开始和结束各打一条日志:
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;
use axum::{extract::State, http::StatusCode, routing::post, Json, Router};
use serde::Serialize;
static NEXT_JOB: AtomicU64 = AtomicU64::new(1);
#[derive(Serialize)]
struct JobAck {
job_id: u64,
}
async fn start_report(State(_state): State<AppState>) -> (StatusCode, Json<JobAck>) {
let job_id = NEXT_JOB.fetch_add(1, Ordering::Relaxed);
tokio::spawn(async move {
tracing::info!(job = job_id, "report job started");
tokio::time::sleep(Duration::from_millis(800)).await;
tracing::info!(job = job_id, "report job finished");
});
(StatusCode::ACCEPTED, Json(JobAck { job_id }))
}
let app = Router::new()
.route("/api/jobs/report", post(start_report))
.with_state(state);
请求和实测返回:
curl -s -i -X POST 127.0.0.1:18080/api/jobs/report
HTTP/1.1 202 Accepted
content-type: application/json
{"job_id":1}
后台日志实测如下。两条日志的时间戳相差约 838 毫秒,和代码里的 800 毫秒睡眠加调度开销吻合:
23:52:14.203 INFO rustdemo: report job started job=1
23:52:15.041 INFO rustdemo: report job finished job=1
注意请求返回时任务才刚开始,日志里的 started 和 finished 都在响应之后。这就是 202 的意义:请求线程不等待任务。现在把 JoinHandle 丢掉,任务仍然会跑,但出现下面三种情况时你没有任何手段感知。
第一,panic。任务里的 panic 会被运行时捕获,不会让进程崩溃,也不会传给请求方;如果句柄被丢弃,通常只剩一条 panic 日志。请求方看到的是 202,以为任务成功了。第二,取消。进程退出或运行时关闭时,未完成的任务会被丢弃,没有补偿。第三,结果。任务返回的值和错误都留在句柄里,丢掉句柄就等于丢掉这些信息。
需要感知结果时,保留句柄并 await:
let handle = tokio::spawn(async move {
// 任务
42
});
match handle.await {
Ok(value) => tracing::info!(value, "job ok"),
Err(error) => tracing::error!(error = %error, "job failed or panicked"),
}
但 await 会让当前请求等待任务完成,这又回到了同步。正确的位置是「请求只负责提交,另一个长期运行的 worker 负责 await 并在失败时更新任务状态」;句柄要么交给监控任务,要么在任务内部用 catch_unwind 或 panic hook 记录。对于真正需要可靠性的任务,这些都不够,应该直接落库或进队列。
阻塞调用的代价:std::thread::sleep 为什么会卡住整个 worker
tokio 的运行时由若干个 worker 线程组成,每个线程跑一个事件循环,轮询分配给它的任务。一个任务在 .await 处让出执行权,线程才能去跑别的任务。异步的价值就在这个「让出」上:等待网络或定时器时,线程不闲着。
std::thread::sleep 是操作系统级的睡眠,它让当前线程整体停下来,不会让出执行权,也不会通知 tokio 的调度器。你在 async 任务里调用它,就等于把一个 worker 线程按住了。如果运行时只有几个 worker,连续几个这样的任务就能把线程全部占住,其他请求即使只差一个 await 也无法推进。表现是「服务没死,但所有接口都卡住」。
tokio::time::sleep
异步定时器,返回一个 future,在 .await 时注册到运行时并让出线程。睡眠期间 worker 可以去处理别的任务,适合在 async 代码里做延迟、退避、超时。它不会阻塞线程,但会让当前任务暂停。
std::thread::sleep
同步睡眠,直接阻塞操作系统线程,不让出执行权。只适合在普通线程或 spawn_blocking 的闭包里使用;在 async 任务里调用会占住 worker,任务越多、worker 越少,延迟越容易被打爆。
判断一段代码能不能放进 async,看它是不是「等待型」:网络请求要用异步客户端,文件读写可以用 tokio 的异步接口,数据库用 sqlx 的异步接口,定时用 tokio::time。反过来,同步的文件 API、CPU 密集计算、调用只提供阻塞接口的第三方库,都不该直接跑在 async worker 上。
tokio 的 worker 线程数量默认与 CPU 核数相关,可用环境变量或构建器调整。这个数量通常是个位到十几,所以只要有几个阻塞任务同时发生,线程就可能被全部占住。这也解释了一个反直觉的现象:一个看起来只影响单个请求的 std::thread::sleep,可以让整个服务在这段时间里像假死一样,连健康检查都变慢。
CPU 密集任务的正确处理是 tokio::spawn_blocking:它把闭包交给运行时的阻塞线程池,不占 async worker。下面的例子把一段计算移出去,等它完成再继续:
let result = tokio::task::spawn_blocking(move || {
let mut total = 0u64;
for i in 0..50_000_000u64 {
total = total.wrapping_add(i);
}
total
})
.await
.expect("blocking task panicked");
tracing::info!(result, "cpu job done");
spawn_blocking 的线程池有上限,不能把它当成无限并发的万能药。大量 CPU 任务同时提交,会把阻塞线程占满,后面的任务排队。数量再大、耗时再长,就该考虑独立 worker 进程,甚至单独的机器,而不是继续在 Web 进程里挤。
std::thread::sleep、同步 reqwest::blocking、同步文件读写或长事务查询。这些调用不会报错,但会让 worker 线程停下来;本地单请求看不出问题,线上并发时表现为延迟整体抬升。排查时先全局搜 sleep( 和 blocking 关键字。有界队列:任务堆积时该怎么办
每个请求都 spawn 一个任务,等于没有上限。流量突增时,任务在内存里越堆越多,每个任务都持有数据,内存会一直涨;同时 CPU 和数据库被这些任务争抢,延迟进一步恶化。解决办法是给任务加一个有界队列:请求只负责把任务放进去,队列满了就明确拒绝,而不是无限接收。
tokio::sync::mpsc 是 tokio 提供的多生产者单消费者通道,创建时可以指定容量。try_send 不等待,队列满时立刻返回错误,这让我们可以把「系统忙」翻译成 503 或 429。下面的队列容量是 8,一个长期运行的 worker 串行消费:
use tokio::sync::mpsc;
struct Job {
id: u64,
}
let (tx, mut rx) = mpsc::channel::<Job>(8);
tokio::spawn(async move {
while let Some(job) = rx.recv().await {
tracing::info!(job = job.id, "worker picked");
tokio::time::sleep(Duration::from_millis(800)).await;
tracing::info!(job = job.id, "worker finished");
}
});
#[derive(Clone)]
struct AppState {
pool: sqlx::SqlitePool,
tx: mpsc::Sender<Job>,
}
入队接口用 try_send,满和关闭分别映射成不同状态码:
use axum::http::StatusCode;
use axum::Json;
use serde_json::json;
enum EnqueueError {
Full,
Closed,
}
async fn enqueue(
State(state): State<AppState>,
) -> Result<(StatusCode, Json<JobAck>), (StatusCode, Json<serde_json::Value>)> {
let job_id = NEXT_JOB.fetch_add(1, Ordering::Relaxed);
match state.tx.try_send(Job { id: job_id }) {
Ok(()) => Ok((StatusCode::ACCEPTED, Json(JobAck { job_id }))),
Err(mpsc::error::TrySendError::Full(_)) => Err((
StatusCode::SERVICE_UNAVAILABLE,
Json(json!({ "error": "queue full" })),
)),
Err(mpsc::error::TrySendError::Closed(_)) => Err((
StatusCode::SERVICE_UNAVAILABLE,
Json(json!({ "error": "worker down" })),
)),
}
}
这里选 503 而不是 202,是因为「没有接收」和「已经接收」必须区分。返回 202 之后客户端会认为任务在跑,实际却丢了,这是最坏的语义。队列满时返回 503 加 Retry-After,让客户端知道可以稍后重试;如果你更希望限制单个客户端的提交频率,用 429 也合理,关键是把「忙」和「已接受」分开。
队列满不是靠调大容量解决的。容量大只能推迟问题,内存和延迟还是会到顶。正确的顺序是:先看任务能不能更快完成、能不能合并、能不能降级;再看 worker 数量是否合理;最后才考虑扩容。队列是缓冲,不是无限仓库。
还有一个细节:队列容量和 worker 数量要匹配。容量 8、worker 1 个、每个任务 800 毫秒,那么第 9 个请求就会被拒绝,吞吐上限是每秒一个多。这个算术要写进容量规划,不能凭感觉设一个 1000。
什么时候必须上独立 worker 与消息队列
进程内的 spawn 加有界队列,适合「可以丢、可以重来、几十秒内完成」的任务,比如发一封通知邮件、刷新一个缓存、生成一张小缩略图。它的优点是零依赖、调试简单;缺点是进程重启即丢、不能跨实例共享、失败没有重试、无法单独扩容。
出现下面任意一条,就该考虑独立 worker 加消息队列:任务不能丢(订单、账单、对账);任务要跑几分钟以上或占用大量 CPU 和内存;需要重试、退避、死信;需要多个实例共享任务;需要按任务类型独立扩容;需要审计「谁在什么时候提交了什么」。这些条件不是「规模大了才考虑」,而是「业务语义要求可靠」时就该考虑。
消息队列的选型可以按现有基础设施来。已经在用 Redis,Redis Stream 的消费者组能提供「读取、确认、待处理列表」,上手成本低;需要复杂的路由、优先级、死信策略,RabbitMQ 更成熟。两者我没有在本机实测,这里只给判断方向,不给具体命令和版本。
不上消息队列也能做到不丢:在数据库里建一张任务表,字段包含 id、类型、载荷、状态、重试次数、下次执行时间。请求在同一个事务里写业务数据和任务记录,提交后返回 202;后台 worker 轮询 status = pending 且 next_run_at 到期的行,执行成功后改状态,失败则增加重试次数并延后。这个方案就是常说的「事务性发件箱」,它用数据库换掉了消息队列,适合任务量不大、已有数据库的场景。
无论用哪种队列,任务都要幂等。消息队列通常保证「至少一次」,网络抖动、worker 崩溃都可能导致同一任务被执行两次。幂等键可以是一个业务唯一 id,写入时加唯一约束;或者建一张已处理表,执行前先插入,冲突就跳过。没有幂等,重试就是把错误放大。
重试也要有边界。每次失败都立刻重试,会把下游打得更惨;常见的做法是指数退避,比如 1 秒、2 秒、4 秒逐次拉长,并设置最大尝试次数。超过上限后转入死信,留下任务载荷和最后一次错误,等人处理。重试次数和下次执行时间都要落库,否则进程一重启,计数就归零,任务会无限重来。
边界与代价
先讲进程内方案的天花板。单进程的任务队列和 Web 请求共享同一个运行时、同一份内存、同一台机器的 CPU。任务一重,Web 延迟就被拖;任务一多,内存就涨;进程一重启,任务就丢。它适合作为起点,但不适合作为长期方案。判断是否到天花板,看三个信号:任务开始出现丢失、任务耗时开始影响接口延迟、需要多实例部署。
再讲 spawn_blocking 的边界。它解决的是「不阻塞 async worker」,不解决「任务可靠」和「任务可观测」。阻塞线程池满了之后,任务会排队;进程退出时,排队和执行中的任务照样丢。它可以和队列组合使用,但不能替代队列。
消息队列也有代价。多一个组件就多一个故障点,消息积压、消费者断开、重复投递都要处理;部署和监控的成本比进程内任务高一个量级。任务量很小的时候上队列,往往是「为了可靠而增加了更多不可靠」。先估算任务量和失败代价,再决定要不要付这笔成本。
最后是观测。后台任务最大的问题是「用户看不到」。至少要有三个指标:提交数、成功数、失败数;加上任务耗时分布和队列深度。日志里带 job_id 和任务类型,失败时记录错误原因和重试次数。没有这些,任务丢了也不会有人发现,直到用户投诉。
提交任务的请求日志和执行任务的 worker 日志要能串起来。最省事的办法是提交时生成 job_id,响应里返回,日志里统一带这个字段;排查时用 job_id 搜两边,就能看到「谁在什么时间提交、worker 什么时候开始、失败在哪一步」。这比在十几个服务里猜时间线有效得多。
当天能自己验证的练习
- 按第 2 节的代码跑通
POST /api/jobs/report,确认返回 202 和job_id,并在日志里找到开始和结束两条记录,算出时间差。 - 在任务闭包里
panic!,请求仍然返回 202;再把JoinHandle保留并await,观察JoinError和日志差异,理解「panic 不传给请求方」。 - 把任务里的
tokio::time::sleep换成std::thread::sleep,同时发几个请求,观察其他接口的延迟变化;再换回来,对比两次结果。 - 把
mpsc::channel的容量设为 2,连续提交 5 个任务,确认第 3 个之后返回queue full和 503,而不是一直挂起。 - 写一个模拟重启的测试:任务开始后立刻结束进程,确认内存里的任务丢失;再把任务 id 写进一张 SQLite 表,重启后手动扫表重跑,理解持久化的最小做法。
任务跑通之后,最后一篇处理「怎么把它放到线上」。配置怎么从环境变量来、日志怎么结构化、健康检查为什么要查数据库、优雅停机怎么接、容器里 SQLite 为什么需要一个可写目录,以及 Nginx 后面的真实 IP 怎么拿。那一篇也会把本机没实测的部署项逐条标出来。
小结
三句话收束:tokio::spawn 只负责并发,不负责持久化、重试和结果回传,JoinHandle 丢了就失去感知;async 里不能调阻塞函数,定时用 tokio::time::sleep,CPU 密集用 spawn_blocking,再重就上独立 worker;进程内队列要有界,满了返回 503 或 429,任务不能丢时用消息队列或数据库任务表,并保证幂等。
这篇的任务接口和队列代码可以留着当基线,下一篇会把它放进一个真正可部署的进程:同样的接口,加上配置、日志、健康检查和优雅停机。