写后台任务的第一版,我用主构造函数把依赖直接写在类名后面,还顺手把计数器声明成 private readonly long _seed,然后在任务里 Interlocked.Increment(ref _seed)。构建直接失败,编译器说的是:
error CS0192: 无法将只读字段用作 ref 或 out 值(构造函数中除外)
原因很朴素:Interlocked 要修改这个字段,而 readonly 只允许在构造函数里赋值。把声明改成普通字段 private long _seed = 0; 才通过。这类错误不会骗人,编译器当场就拦住了;麻烦的是后面那些不会拦的:任务没跑、队列满了接口卡住、重启后任务消失、关停时任务被腰斩。
这篇讲怎么让任务在请求之外稳定地跑:BackgroundService 和 IHostedService 该选谁、为什么不能在启动时同步等、Channel 有界队列满了会发生什么、单例里拿不到 scoped 的 DbContext 怎么办、优雅停机会打断什么,以及「重启丢任务」这层为什么绕不过去。任务的日志和 202 返回都是本机实测,Hangfire 和消息队列没有跑过,会明确标出。
先让任务跑起来:202 返回与执行日志
目标很简单:调用一个接口,接口立刻返回「已受理」,真正的活在后台做。用一个有界队列连接两边,接口只管入队,后台服务只管消费。队列用 Channel,它是框架自带的线程安全队列,不需要额外装包:
依赖同样没有变化,Channel 就在框架里:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
</Project>
构建和启动命令与前面一致:
dotnet build
dotnet run --no-launch-profile --urls "http://127.0.0.1:18082"
任务相关的文件分成三处,职责清楚,出问题好定位:
using System.Threading.Channels;
public class ReportQueue
{
private readonly Channel<long> _channel;
public ReportQueue()
{
_channel = Channel.CreateBounded<long>(new BoundedChannelOptions(100)
{
FullMode = BoundedChannelFullMode.Wait
});
}
public ValueTask EnqueueAsync(long id, CancellationToken ct) =>
_channel.Writer.WriteAsync(id, ct);
public IAsyncEnumerable<long> ReadAllAsync(CancellationToken ct) =>
_channel.Reader.ReadAllAsync(ct);
}
后台服务继承 BackgroundService,重写 ExecuteAsync。注意它没有在构造函数里注入 AppDb,而是注入 IServiceScopeFactory,每一轮自己开一个作用域去拿。原因第 3 篇讲过:后台服务是单例,DbContext 是 scoped,单例直接拿 scoped 服务会在启动时报错:
public class ReportWorker : BackgroundService
{
private readonly ReportQueue _queue;
private readonly IServiceScopeFactory _scopes;
private readonly ILogger<ReportWorker> _log;
private long _seed = 0;
public ReportWorker(ReportQueue queue, IServiceScopeFactory scopes,
ILogger<ReportWorker> log)
{
_queue = queue;
_scopes = scopes;
_log = log;
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
await foreach (var id in _queue.ReadAllAsync(stoppingToken))
{
using var scope = _scopes.CreateScope();
var db = scope.ServiceProvider.GetRequiredService<AppDb>();
var count = await db.Items.CountAsync(stoppingToken);
var jobNo = Interlocked.Increment(ref _seed);
_log.LogInformation("job {Job} finished, items={Count}", jobNo, count);
}
}
}
注册和接口一起看。队列是单例,后台服务用 AddHostedService,接口只负责把 id 写进队列,写完立刻返回 202(已受理,不代表已完成):
builder.Services.AddSingleton<ReportQueue>();
builder.Services.AddHostedService<ReportWorker>();
app.MapPost("/api/jobs/report", async (ReportQueue q, CancellationToken ct) =>
{
await q.EnqueueAsync(1, ct);
return Results.Json(new { job_id = 1 }, statusCode: 202);
});
启动后发一次请求,再等一两秒看日志:
curl.exe -s -i -X POST 127.0.0.1:18082/api/jobs/report
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Server: Kestrel
Transfer-Encoding: chunked
{"job_id":1}
202 说明请求被受理,不说明活干完了。真正的执行痕迹在日志里,两行挨着出现,第一行是 EF 生成的 SQL,第二行是任务自己的日志:
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
Executed DbCommand (0ms) [Parameters=[], CommandType='Text', CommandTimeout='30']
SELECT COUNT(*) FROM "Items" AS "i"
info: ReportWorker[0]
job 1 finished, items=1
ReportWorker[0] 里的方括号是日志分类的一部分,来自 ILogger<ReportWorker>,数字是事件编号。看到这一行,说明消费确实发生了,而不是接口返回了就算完。
202 的语义是「已受理」,不是「已完成」。客户端拿到 202 之后,要么轮询另一个查询接口看结果,要么等服务端推送通知。直接把 202 当成成功,会让用户以为报表已经生成,实际还在队列里排队。接口文档里要把这一点写清楚,别让调用方猜。
BackgroundService 和 IHostedService 差在哪
两者是继承关系,理解层次比记名字有用:
StartAsync 和 StopAsync。宿主启动时调用前者,关停时调用后者。需要自己管理任务的生命周期。ExecuteAsync,它负责启动、停止、传递取消令牌。绝大多数场景选它。await 之前的代码是同步执行的,写长了会直接拖慢整个应用启动。为什么第一个 await 之前的代码会拖慢启动?因为宿主在启动阶段会等所有 IHostedService.StartAsync 完成。BackgroundService 的 StartAsync 会在后台启动 ExecuteAsync,但紧接着会执行到第一个真正让出线程的 await。如果前面有一段同步的耗时操作,比如读大文件、开数据库连接并同步查询、循环里 Thread.Sleep,这部分就发生在启动路径上,整个应用会卡在那里。
实测里没有这个问题,因为 ExecuteAsync 第一行就是 await foreach。但这是一个很容易踩的坑:有人在任务开头写一段初始化,看起来是「后台」的,其实阻塞了启动。判断标准很简单:启动日志里 Now listening on 出现得晚,而任务日志还没开始,就该怀疑这里。
那什么时候直接写 IHostedService?当你要控制启动顺序,比如「必须等这个服务初始化完成,应用才算启动成功」时。用 BackgroundService 的话,任务在后台跑,宿主不等它,启动立刻完成。两者语义不同,别为了少写几行选错。
BackgroundService 还有一个容易忽略的行为:ExecuteAsync 抛出的异常默认会让整个宿主停止。这是较新版本的设计,目的是让「后台任务挂了」尽早暴露,而不是留着一个静默死掉的线程。如果你希望单条任务失败不影响后续,必须在循环内部捕获异常并记录,让异常停在单条任务边界。
有界队列满了,请求会被拖住
Channel.CreateBounded 的意思是「最多装一百个,多了要按规则处理」。规则由 FullMode 决定,这里选的是 Wait:队列满时写入方等待,直到有消费者取走一个。放在接口里,就是请求被挂起,直到队列腾出位置才返回 202。
这个设计的代价要说清楚。队列满意味着消费速度跟不上生产速度,Wait 会把压力反推给调用方:请求一直挂着,占着连接,客户端可能先超时。短时间看这是「背压」,能让上游慢下来;时间一长,它会把 Web 服务器的连接数吃掉,最后连健康检查都进不来。所以有界队列必须配合两样东西:客户端超时,以及服务端的兜底策略。
兜底有几种选法。第一种是丢:用 DropOldest 或 DropWrite,队列满时丢弃,接口立刻返回,代价是任务静默丢失,必须记指标。第二种是拒绝:接口先 TryWrite,失败就返回 503 并带 Retry-After,让调用方自己重试,语义清晰。第三种是落库:把任务写进一张待处理表,后台轮询,队列只做加速,重启也不丢。
// 不等待的写法:满了就明确拒绝,而不是挂起请求
if (!queue.TryWrite(id))
return Results.Json(new { error = "busy" }, statusCode: 503);
TryWrite 和 WriteAsync 的区别就在这:前者不等待、立即返回真假,后者会等。用哪个取决于你希望「压力由调用方承担」还是「服务端自己承担」。默认情况下,对外接口选拒绝更安全,内部批处理选等待更省事。
容量定多少也值得想。一百这个数字是演示用的,实际要按「消费速度乘可接受延迟」估算:每秒消费十条、能接受积压十秒,容量就是一百。容量太小会频繁拒绝,太大则内存上涨、重启丢失的更多。
队列长度还是可观测性的入口。至少记录三个数:入队总数、拒绝或等待次数、当前积压。只有入队数,看不出消费是否跟得上;只有日志,看不出趋势。这三个数用计数器打出来,出问题时一眼就能判断是生产太快还是消费太慢。
作用域、取消令牌与关停
后台服务里拿 DbContext 这件事,只有一条正确路径:注入 IServiceScopeFactory,每次处理开一个 CreateScope(),用完释放。为什么不能在构造函数里存一个 DbContext?因为后台服务是单例,构造时创建的那个 DbContext 会活到进程结束,变更跟踪器越积越大,还会在多个任务之间共享,迟早报「上一个操作未完成」。
还有一个细节:scope 要在每轮任务内部创建,不能提到循环外面。如果写成「进方法开一个 scope,然后循环处理所有任务」,那个 DbContext 又会活很久,变更跟踪器越积越大,等于把单例的问题换了个位置。正确的位置是循环体内部,处理完就释放。
取消令牌是第二个必须处理的点。ExecuteAsync 的参数 stoppingToken 会在宿主关停时被触发,ReadAllAsync 和 CountAsync 都应该带上它。不带的结果是:关停信号来了,任务还在跑一个很长的查询,宿主等超时后强行结束进程,那一轮的工作可能只写了一半。
但「带上令牌」不等于「处理了取消」。正确的写法是让取消异常向上冒泡,或者在任务边界捕获 OperationCanceledException 后干净退出:
try
{
await foreach (var id in _queue.ReadAllAsync(stoppingToken))
{
// 单条任务本身也要能被打断
}
}
catch (OperationCanceledException)
{
_log.LogInformation("worker stopped before finishing");
}
这里有个取舍:正在处理的那一条,是「尽量做完再退出」还是「立刻放弃」?做完可能超出宿主给的关停窗口,照样被强杀;立刻放弃则保证快速退出,但任务半途而废。如果任务有副作用,正确做法是把它做成幂等,配合「执行前标记、成功后确认」的两阶段,这样无论在哪一步被打断,重跑都不会重复写入。
判断任务是否幂等,有个简单办法:把它连续执行两次,看结果是否和一次相同。写入、扣款、发通知这类操作,默认都不幂等,需要业务键去重,否则关停重试就会变成重复扣款。
后台任务出问题,先看这张表
后台任务的故障大多没有异常堆栈,只有「该发生的没发生」。下面这些现象和原因对应着查最省时间:
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 接口返回 202,但后台一次都没执行 | 忘了 AddHostedService,或 ExecuteAsync 里异常被吞 | 启动日志里有没有 ReportWorker 的报错,注册代码是否成对 |
| 启动明显变慢,任务日志迟迟不出现 | ExecuteAsync 在第一个 await 前有同步耗时操作 | 看 ExecuteAsync 开头几行有没有同步查询或等待 |
| 队列一满,接口跟着超时 | 有界队列用了 Wait,写入方被挂起 | 看 FullMode 与接口用的是 WriteAsync 还是 TryWrite |
| 启动报「不能在根作用域解析 scoped 服务」 | 单例的 worker 直接注入了 DbContext | 看 worker 构造函数参数,改成 IServiceScopeFactory |
| 关停时任务被腰斩,数据写了一半 | 没有传递或没有处理 CancellationToken | 看 ReadAllAsync 和查询是否都带了令牌 |
| 重启后积压的任务全没了 | 任务只存在内存队列里 | 确认入队前有没有落库或发消息 |
| 编译报 CS0192,无法把只读字段用作 ref | 计数器声明成了 readonly,又被 Interlocked 修改 | 把字段改成普通字段,只读只用于真正不变的依赖 |
| 任务越跑越慢,队列持续积压 | 单消费者串行处理,每轮耗时大于生产速度 | 统计每轮耗时与入队速率,再决定加消费者还是换队列 |
第一行和第四行是最常见的两个「静默失败」。注册漏了不会有任何提示,接口照样返回 202,看起来一切正常;scoped 服务那个错误则只在开发环境启动时暴露,生产关掉作用域校验后,会变成一个长命 DbContext 慢慢积累脏数据。这两种都不是靠读业务代码能发现的,得看启动日志和注册处。
第三行要结合业务判断。队列满本身是保护,不是故障;真正的问题是「满了之后接口无限等待」。如果调用方是浏览器,用户会看到转圈直到超时;如果调用方是另一个服务,可能触发它自己的重试,把压力放大。看到这种链条,先给接口加超时和明确的 503,再谈扩容。
边界与代价:什么时候该上 Hangfire 或消息队列
BackgroundService 加 Channel 的组合,适合「单进程、任务量不大、丢了能接受或已落库」的场景。它的优点是零依赖、启动快、代码全在眼前;缺点是所有持久化、重试、并发控制都要自己写,而且只能在当前进程内调度。和成熟方案对比一下更清楚:
BackgroundService + Channel
进程内调度,零外部依赖,代码完全可控。适合单服务、每分钟几十到几百条、能接受重启丢任务或已落库的场景。重试、定时、可视化都得自己实现。
Hangfire 或消息队列
任务持久化到数据库或中间件,天然支持重试、延迟、多消费者和重启恢复。Hangfire 适合单服务加可视化面板;消息队列适合跨服务、每秒上千、需要削峰。代价是依赖和运维成本。
什么时候该换 Hangfire?需要这些能力时:任务失败自动重试、延迟执行、定时任务用 cron 表达式、有可视化面板看成功失败、任务状态要持久化。Hangfire 默认把任务存进数据库,重启不丢,单机或小集群够用。代价是多一套表、多一个依赖,任务参数要能序列化。任务量在每分钟几百以内、团队不想自己造调度,它是划算的。
什么时候该上消息队列?跨服务、要削峰、每秒上千条、需要多个消费者并行、需要死信队列。RabbitMQ 或 Kafka 这类方案把「任务」变成消息,生产者和消费者彻底解耦,重启、扩容都不影响。代价是运维成本明显上升,本地开发也要起一个中间件。规模上的经验值:单服务每分钟几十到几百条,BackgroundService 足够;需要重试和可视化,Hangfire;跨服务或每秒上千,消息队列。
还有一层容易被忽略的成本:并发控制。单消费者串行处理最简单,但慢任务会堵住后面的;开多个消费者能提速,但同一个任务可能被重复消费,需要幂等键。Channel 支持多个读者,但「谁拿到哪条」不确定,涉及顺序的任务不能这么干。顺序、幂等、重试这三件事,只要开始考虑,就说明该上成熟队列了,自己写往往会在半年后付出更大代价。
还有一点是观测。Hangfire 自带面板,消息队列有积压指标,自己写的 Channel 什么都没有。上线前至少要有任务开始、结束、失败三条日志,加上处理条数和耗时;否则出问题时你只能看到「接口 202 了」,无法回答「任务到底跑没跑」。这也是自研方案最常见的欠账。
本机只实测了 BackgroundService 加有界 Channel 这一条路径:202 返回、worker 日志、EF 的 COUNT 查询。Hangfire、RabbitMQ、Kafka 均未实测,上面的判断是按它们的定位和常见用法写的,具体配置和性能数字要看你自己的环境。
今天就能自验的五个练习
后台任务的坑必须在运行态看,静态读代码看不出来:
- 把
private long _seed改回readonly,构建一次,确认 CS0192 的报错原文;再改回来。这一步是为了记住「只读字段不能被 Interlocked 修改」。 - 把队列容量改成 1,然后在接口里连续发五次请求,观察第几次开始变慢或超时。把
WriteAsync换成TryWrite,再发五次,对比行为。 - 在
ExecuteAsync第一行加一个Thread.Sleep(3000),启动应用,对比加之前和加之后Now listening on出现的时间。 - 把
IServiceScopeFactory换成直接注入AppDb,启动项目,记录容器报错;然后改回去。这一步能让你看清 scoped 与单例的冲突。 - 入队十条任务后立刻按 Ctrl+C 停掉进程,重新启动,确认这十条都没有被执行。再把任务改成「先写进数据库再入队」,重复一次,对比结果。
小结
下一篇讲上线。任务在本地跑通只是开始,真正上线会遇到另一批问题:配置从哪读、日志往哪写、健康检查该查进程还是查数据库、反向代理后面拿不到真实客户端地址、Kestrel 的默认超时够不够。第 6 篇会把这些按「上线前必须确认」的顺序列出来,也会把第 1 篇那个端口被 launchSettings 抢走的坑收尾。
这篇的三句话总结:第一,BackgroundService 是 IHostedService 的封装,写业务用前者,需要控制启动顺序才用后者,ExecuteAsync 第一个 await 之前不要写耗时逻辑;第二,有界 Channel 满了会等,等待会把请求拖住,要么明确拒绝返回 503,要么先把任务落库,别让内存队列承担持久化;第三,worker 是单例,拿 scoped 的 DbContext 必须每轮开 scope,关停时要处理取消令牌,否则任务会被腰斩。这三件事都得自己写,别指望框架替你做。