写后台任务的第一版,我用主构造函数把依赖直接写在类名后面,还顺手把计数器声明成 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"

任务相关的文件分成三处,职责清楚,出问题好定位:

Program.cs注册队列与后台服务,提供入队接口
ReportQueue.cs有界 Channel,连接接口和后台服务
ReportWorker.cs继承 BackgroundService,负责消费
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 差在哪

两者是继承关系,理解层次比记名字有用:

IHostedService最底层接口,只有 StartAsync 和 StopAsync。宿主启动时调用前者,关停时调用后者。需要自己管理任务的生命周期。
BackgroundService对上面的封装,你只写一个 ExecuteAsync,它负责启动、停止、传递取消令牌。绝大多数场景选它。
ExecuteAsync 的约定它是一段长跑的异步方法。第一个 await 之前的代码是同步执行的,写长了会直接拖慢整个应用启动。
StopAsync 的约定宿主关停时给出一个超时窗口,超时没停下来的任务会被强行放弃,正在做的事可能只做了一半。

为什么第一个 await 之前的代码会拖慢启动?因为宿主在启动阶段会等所有 IHostedService.StartAsync 完成。BackgroundService 的 StartAsync 会在后台启动 ExecuteAsync,但紧接着会执行到第一个真正让出线程的 await。如果前面有一段同步的耗时操作,比如读大文件、开数据库连接并同步查询、循环里 Thread.Sleep,这部分就发生在启动路径上,整个应用会卡在那里。

实测里没有这个问题,因为 ExecuteAsync 第一行就是 await foreach。但这是一个很容易踩的坑:有人在任务开头写一段初始化,看起来是「后台」的,其实阻塞了启动。判断标准很简单:启动日志里 Now listening on 出现得晚,而任务日志还没开始,就该怀疑这里。

那什么时候直接写 IHostedService?当你要控制启动顺序,比如「必须等这个服务初始化完成,应用才算启动成功」时。用 BackgroundService 的话,任务在后台跑,宿主不等它,启动立刻完成。两者语义不同,别为了少写几行选错。

BackgroundService 还有一个容易忽略的行为:ExecuteAsync 抛出的异常默认会让整个宿主停止。这是较新版本的设计,目的是让「后台任务挂了」尽早暴露,而不是留着一个静默死掉的线程。如果你希望单条任务失败不影响后续,必须在循环内部捕获异常并记录,让异常停在单条任务边界。

有界队列满了,请求会被拖住

Channel.CreateBounded 的意思是「最多装一百个,多了要按规则处理」。规则由 FullMode 决定,这里选的是 Wait:队列满时写入方等待,直到有消费者取走一个。放在接口里,就是请求被挂起,直到队列腾出位置才返回 202。

请求入队到任务完成
接口入队队列有空位,写入立刻成功
返回 202只表示已受理,不代表执行完
后台消费逐条读出,每轮开一个 scope
写日志记录任务号与实际处理条数

这个设计的代价要说清楚。队列满意味着消费速度跟不上生产速度,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");
}

这里有个取舍:正在处理的那一条,是「尽量做完再退出」还是「立刻放弃」?做完可能超出宿主给的关停窗口,照样被强杀;立刻放弃则保证快速退出,但任务半途而废。如果任务有副作用,正确做法是把它做成幂等,配合「执行前标记、成功后确认」的两阶段,这样无论在哪一步被打断,重跑都不会重复写入。

判断任务是否幂等,有个简单办法:把它连续执行两次,看结果是否和一次相同。写入、扣款、发通知这类操作,默认都不幂等,需要业务键去重,否则关停重试就会变成重复扣款。

内存队列里的任务在进程重启时全部消失,这是设计如此,不是 bug。只要任务不能丢,就必须在入队前先落库(待处理表加状态字段),或者直接发到消息队列。Channel 只能做「同一进程内的缓冲」,不能当持久化存储。

后台任务出问题,先看这张表

后台任务的故障大多没有异常堆栈,只有「该发生的没发生」。下面这些现象和原因对应着查最省时间:

现象真实原因第一步查什么
接口返回 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 均未实测,上面的判断是按它们的定位和常见用法写的,具体配置和性能数字要看你自己的环境。

今天就能自验的五个练习

后台任务的坑必须在运行态看,静态读代码看不出来:

  1. 把 private long _seed 改回 readonly,构建一次,确认 CS0192 的报错原文;再改回来。这一步是为了记住「只读字段不能被 Interlocked 修改」。
  2. 把队列容量改成 1,然后在接口里连续发五次请求,观察第几次开始变慢或超时。把 WriteAsync 换成 TryWrite,再发五次,对比行为。
  3. 在 ExecuteAsync 第一行加一个 Thread.Sleep(3000),启动应用,对比加之前和加之后 Now listening on 出现的时间。
  4. 把 IServiceScopeFactory 换成直接注入 AppDb,启动项目,记录容器报错;然后改回去。这一步能让你看清 scoped 与单例的冲突。
  5. 入队十条任务后立刻按 Ctrl+C 停掉进程,重新启动,确认这十条都没有被执行。再把任务改成「先写进数据库再入队」,重复一次,对比结果。

小结

下一篇讲上线。任务在本地跑通只是开始,真正上线会遇到另一批问题:配置从哪读、日志往哪写、健康检查该查进程还是查数据库、反向代理后面拿不到真实客户端地址、Kestrel 的默认超时够不够。第 6 篇会把这些按「上线前必须确认」的顺序列出来,也会把第 1 篇那个端口被 launchSettings 抢走的坑收尾。

这篇的三句话总结:第一,BackgroundService 是 IHostedService 的封装,写业务用前者,需要控制启动顺序才用后者,ExecuteAsync 第一个 await 之前不要写耗时逻辑;第二,有界 Channel 满了会等,等待会把请求拖住,要么明确拒绝返回 503,要么先把任务落库,别让内存队列承担持久化;第三,worker 是单例,拿 scoped 的 DbContext 必须每轮开 scope,关停时要处理取消令牌,否则任务会被腰斩。这三件事都得自己写,别指望框架替你做。