C#.NET MediatR 深入解析：进程内消息分发、CQRS、通知事件与管道行为实战

简介

MediatR 是 .NET 里很常见的进程内消息分发库。

它做的事情不复杂：

调用方发出一个请求，MediatR 找到对应的处理器执行。

这听起来像“多绕了一层”，但在业务代码越来越复杂时，这一层很有用。

没有 MediatR 时，控制器、服务类里经常会堆很多依赖：

public class OrdersController : ControllerBase
{
    private readonly IOrderRepository _orders;
    private readonly IInventoryService _inventory;
    private readonly IPaymentService _payment;
    private readonly IEmailService _email;
    private readonly ILogger _logger;
}

一开始还好，后面新增库存、支付、优惠券、消息通知、审计日志，控制器和服务层就会越来越重。

MediatR 的思路是把这些操作拆成一条条消息：

await sender.Send(new CreateOrderCommand(...));

控制器只表达“要创建订单”，真正的处理逻辑放到对应的 Handler 里。

一句话概括：

MediatR 不是消息队列，也不是分布式事件总线，它是应用进程内部的请求分发器。

这篇文章主要讲清楚：

• MediatR 到底解决什么问题；
• Send、Publish 分别适合什么场景；
• Command、Query、Notification 怎么写；
• Pipeline Beha vior 怎么处理日志、验证、事务；
• 在 ASP.NET Core 里怎么注册和使用；
• 实际项目里容易踩哪些坑。

先把定位说清楚

MediatR 实现的是中介者模式。

中介者模式的核心不是“高级”，而是减少直接依赖。

普通调用是这样：

Controller -> Service -> Repository / OtherService / Logger / MessageSender

使用 MediatR 后变成：

Controller -> MediatR -> Handler -> Repository / OtherService

也就是说：

• 调用方不直接依赖具体业务处理类；
• 请求和处理器通过类型匹配；
• 横切逻辑可以放进管道；
• 每个业务动作可以拆成一个独立处理单元。

但这不代表所有项目都要上 MediatR。

如果项目很小，业务逻辑也简单，直接写服务类更清楚。

MediatR 更适合这些场景：

• 控制器越来越薄，业务逻辑想拆到独立用例里；
• 项目采用 CQRS，读写操作希望分开组织；
• 需要统一加日志、验证、权限、事务、性能监控；
• 有领域事件或进程内通知；
• 业务动作很多，按 feature / use case 组织更清晰。

它不是消息队列

这个点很重要。

MediatR 是进程内分发。

也就是说：

• 不跨进程；
• 不跨服务；
• 不负责持久化消息；
• 不负责失败重试；
• 不负责削峰；
• 不负责最终一致性。

下面这些事情不是 MediatR 的职责：

• 服务 A 给服务 B 发消息；
• 消息失败后自动重试；
• 消息落库防丢；
• 多个消费者分布式消费。

这些场景要看：

• RabbitMQ
• Kafka
• Redis Stream
• Azure Service Bus
• CAP
• MassTransit

MediatR 解决的是同一个应用内部的调用组织问题。

核心接口

MediatR 常用接口不多。

接口	作用	常见场景
IRequest	有返回值请求	查询、创建后返回 ID
IRequest	无返回值请求	命令、执行动作
IRequestHandler	处理有返回值请求	Command / Query Handler
IRequestHandler	处理无返回值请求	Command Handler
INotification	通知事件	订单已创建、用户已注册
INotificationHandler	通知处理器	发邮件、写日志、同步缓存
IPipelineBeha vior	请求管道	日志、验证、事务、性能统计
ISender	发送 Request	Send
IPublisher	发布 Notification	Publish
IMediator	同时包含发送和发布能力	兼容常见写法

现在更推荐按职责注入：

private readonly ISender _sender;
private readonly IPublisher _publisher;

如果只需要发送命令或查询，用 ISender 就够了。
如果只需要发布通知，用 IPublisher 就够了。

IMediator 也能用，只是能力更宽。

安装和注册

安装：

dotnet add package MediatR

在现代版本当中，MediatR已经直接对Microsoft.Extensions.DependencyInjection注册予以支持。

Program.cs：

using MediatR;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
});

如果 Handler 在其他程序集里，就注册对应程序集：

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(CreateOrderCommand).Assembly);
});

或者注册多个程序集：

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssemblies(
        typeof(Program).Assembly,
        typeof(CreateOrderCommand).Assembly);
});

老资料里经常出现：

dotnet add package MediatR.Extensions.Microsoft.DependencyInjection

这是旧版本常见写法。新项目通常先看当前 MediatR 包本身的注册方式，不要直接照搬旧教程。

关于 License Key

较新的 MediatR 版本引入了 license key 配置。

注册时可以这样设置：

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.LicenseKey = builder.Configuration["MediatR:LicenseKey"];
});

如果没有配置，可能会看到 license 相关日志。

这类日志并非意味着功能无法使用，但在生产环境中，需要按照实际的许可要求进行处理。客户端应用切勿将license key嵌入前端或桌面客户端包中。

如果只是想屏蔽客户端缺失 license 的日志，可以按日志分类过滤：

builder.Logging.AddFilter("LuckyPennySoftware.MediatR.License", LogLevel.None);

这部分属于版本和许可策略问题，实际项目里要以当前包版本和团队许可为准。

Command：处理写操作

Command 通常表示“执行一个会改变系统状态的动作”。

比如创建订单、取消订单、修改用户资料。

先定义请求：

using MediatR;

public sealed record CreateOrderCommand(
    long UserId,
    IReadOnlyList Items) : IRequestlong>;

public sealed record CreateOrderItem(
    long ProductId,
    int Quantity);

这里 CreateOrderCommand 返回 long，表示创建后的订单 ID。

再写处理器：

using MediatR;

public sealed class CreateOrderCommandHandler
    : IRequestHandlerCreateOrderCommand, long>
{
    private readonly IOrderRepository _orders;
    private readonly IProductRepository _products;
    private readonly IUnitOfWork _unitOfWork;

    public CreateOrderCommandHandler(
        IOrderRepository orders,
        IProductRepository products,
        IUnitOfWork unitOfWork)
    {
        _orders = orders;
        _products = products;
        _unitOfWork = unitOfWork;
    }

    public async Tasklong> Handle(
        CreateOrderCommand request,
        CancellationToken cancellationToken)
    {
        if (request.Items.Count == 0)
        {
            throw new InvalidOperationException("订单明细不能为空。");
        }

        var order = new Order(request.UserId);

        foreach (CreateOrderItem item in request.Items)
        {
            Product product = await _products.GetByIdAsync(
                item.ProductId,
                cancellationToken);

            order.AddItem(product.Id, product.Price, item.Quantity);
        }

        await _orders.AddAsync(order, cancellationToken);
        await _unitOfWork.Sa veChangesAsync(cancellationToken);

        return order.Id;
    }
}

控制器只负责接收请求、发送命令：

[ApiController]
[Route("api/orders")]
public sealed class OrdersController : ControllerBase
{
    private readonly ISender _sender;

    public OrdersController(ISender sender)
    {
        _sender = sender;
    }

    [HttpPost]
    public async Tasklong>> Create(
        CreateOrderRequest request,
        CancellationToken cancellationToken)
    {
        var command = new CreateOrderCommand(
            request.UserId,
            request.Items
                .Select(x => new CreateOrderItem(x.ProductId, x.Quantity))
                .ToArray());

        long orderId = await _sender.Send(command, cancellationToken);

        return Ok(orderId);
    }
}

这样控制器不再关心：

• 怎么查商品；
• 怎么组装订单；
• 怎么保存；
• 怎么提交事务。

这些都在对应的 Handler 里。

Query：处理读操作

Query 通常表示“查询数据，不改变系统状态”。

定义查询：

public sealed record GetOrderDetailQuery(long OrderId)
    : IRequest;

public sealed record OrderDetailDto(
    long Id,
    long UserId,
    decimal TotalAmount,
    IReadOnlyList Items);

public sealed record OrderItemDto(
    long ProductId,
    string ProductName,
    int Quantity,
    decimal Price);

处理器：

public sealed class GetOrderDetailQueryHandler
    : IRequestHandlerGetOrderDetailQuery, OrderDetailDto?>
{
    private readonly IOrderReadRepository _orders;

    public GetOrderDetailQueryHandler(IOrderReadRepository orders)
    {
        _orders = orders;
    }

    public Task Handle(
        GetOrderDetailQuery request,
        CancellationToken cancellationToken)
    {
        return _orders.GetDetailAsync(request.OrderId, cancellationToken);
    }
}

控制器：

[HttpGet("{id:long}")]
public async Task> GetById(
    long id,
    CancellationToken cancellationToken)
{
    OrderDetailDto? order = await _sender.Send(
        new GetOrderDetailQuery(id),
        cancellationToken);

    if (order is null)
    {
        return NotFound();
    }

    return Ok(order);
}

Command 和 Query 分开以后，代码结构会更清楚：

• 写操作关注业务规则和状态变化；
• 读操作关注查询效率和返回模型；
• 两边不必强行共用同一个服务方法。

这就是 CQRS 的基本味道。

Notification：处理一对多事件

Send 是一对一。

一个请求对应一个处理器。

Publish 是一对多。

一个通知可以有多个处理器。

比如订单创建后：

• 写订单日志；
• 发站内信；
• 清理购物车；
• 推送统计事件。

定义通知：

public sealed record OrderCreatedNotification(
    long OrderId,
    long UserId,
    decimal TotalAmount) : INotification;

发布通知：

public sealed class CreateOrderCommandHandler
    : IRequestHandlerCreateOrderCommand, long>
{
    private readonly IOrderRepository _orders;
    private readonly IUnitOfWork _unitOfWork;
    private readonly IPublisher _publisher;

    public CreateOrderCommandHandler(
        IOrderRepository orders,
        IUnitOfWork unitOfWork,
        IPublisher publisher)
    {
        _orders = orders;
        _unitOfWork = unitOfWork;
        _publisher = publisher;
    }

    public async Tasklong> Handle(
        CreateOrderCommand request,
        CancellationToken cancellationToken)
    {
        var order = Order.Create(request.UserId);

        await _orders.AddAsync(order, cancellationToken);
        await _unitOfWork.Sa veChangesAsync(cancellationToken);

        await _publisher.Publish(
            new OrderCreatedNotification(
                order.Id,
                order.UserId,
                order.TotalAmount),
            cancellationToken);

        return order.Id;
    }
}

第一个通知处理器：

public sealed class ClearCartWhenOrderCreatedHandler
    : INotificationHandlerOrderCreatedNotification>
{
    private readonly ICartService _cart;

    public ClearCartWhenOrderCreatedHandler(ICartService cart)
    {
        _cart = cart;
    }

    public Task Handle(
        OrderCreatedNotification notification,
        CancellationToken cancellationToken)
    {
        return _cart.ClearAsync(notification.UserId, cancellationToken);
    }
}

第二个通知处理器：

public sealed class WriteOrderAuditLogHandler
    : INotificationHandlerOrderCreatedNotification>
{
    private readonly IAuditLogRepository _logs;

    public WriteOrderAuditLogHandler(IAuditLogRepository logs)
    {
        _logs = logs;
    }

    public Task Handle(
        OrderCreatedNotification notification,
        CancellationToken cancellationToken)
    {
        return _logs.AddAsync(
            $"订单已创建：{notification.OrderId}",
            cancellationToken);
    }
}

这里的重点是：

• 创建订单的主流程不用知道有几个后续动作；
• 新增一个通知处理器，不需要改发布方；
• 通知不适合返回业务结果。

Publish 不等于可靠事件

Publish 很容易被误用成“事件总线”。

但它仍然是进程内执行。

如果通知处理器失败，行为取决于发布策略和异常处理方式。它没有自动持久化、自动重试、死信队列这些能力。

所以这类事情不要只靠 INotification：

• 扣款成功后必须发送出库消息；
• 订单创建事件必须可靠投递到其他服务；
• 外部系统失败后要重试；
• 消息丢失会造成数据不一致。

这类场景更适合：

• 事务内写业务数据和 Outbox 表；
• 后台任务扫描 Outbox；
• 通过消息队列投递到外部系统。

MediatR 的 Notification 更适合进程内副作用：

• 清理缓存；
• 写审计日志；
• 触发本地领域事件处理；
• 发送非关键通知；
• 拆分本地模块之间的后续动作。

Pipeline Beha vior：把横切逻辑放进管道

Pipeline Beha vior 是 MediatR 很重要的能力。

它类似 ASP.NET Core 中间件。

请求进入 Handler 前后，可以统一加一些逻辑：

• 日志；
• 参数验证；
• 权限检查；
• 性能统计；
• 事务；
• 缓存。

基本结构如下：

public sealed class LoggingBeha viorTRequest, TResponse>
    : IPipelineBeha viorTRequest, TResponse>
{
    private readonly ILogger> _logger;

    public LoggingBeha vior(
        ILogger> logger)
    {
        _logger = logger;
    }

    public async TaskHandle(
        TRequest request,
        RequestHandlerDelegate next,
        CancellationToken cancellationToken)
    {
        string requestName = typeof(TRequest).Name;

        _logger.LogInformation("开始处理 {RequestName}", requestName);

        TResponse response = await next();

        _logger.LogInformation("完成处理 {RequestName}", requestName);

        return response;
    }
}

注册：

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddOpenBeha vior(typeof(LoggingBeha vior));
});

这样所有 Send 请求都会经过这个行为。

实际示例：FluentValidation 验证管道

MediatR 经常和 FluentValidation 搭配。

需要额外安装：

dotnet add package FluentValidation
dotnet add package FluentValidation.DependencyInjectionExtensions

先定义验证器：

using FluentValidation;

public sealed class CreateOrderCommandValidator
    : AbstractValidatorCreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.UserId)
            .GreaterThan(0)
            .WithMessage("用户 ID 不合法。");

        RuleFor(x => x.Items)
            .NotEmpty()
            .WithMessage("订单明细不能为空。");

        RuleForEach(x => x.Items)
            .ChildRules(item =>
            {
                item.RuleFor(x => x.ProductId).GreaterThan(0);
                item.RuleFor(x => x.Quantity).GreaterThan(0);
            });
    }
}

验证管道：

using FluentValidation;

public sealed class ValidationBeha viorTRequest, TResponse>
    : IPipelineBeha viorTRequest, TResponse>
{
    private readonly IEnumerable> _validators;

    public ValidationBeha vior(IEnumerable> validators)
    {
        _validators = validators;
    }

    public async TaskHandle(
        TRequest request,
        RequestHandlerDelegate next,
        CancellationToken cancellationToken)
    {
        if (!_validators.Any())
        {
            return await next();
        }

        var context = new ValidationContext(request);

        var errors = _validators
            .Select(x => x.Validate(context))
            .SelectMany(x => x.Errors)
            .Where(x => x is not null)
            .ToList();

        if (errors.Count > 0)
        {
            throw new ValidationException(errors);
        }

        return await next();
    }
}

注册：

builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddOpenBeha vior(typeof(ValidationBeha vior));
});

这样 Handler 里就不用堆一堆基础参数校验。

Handler 更专注业务规则：

• 用户是否存在；
• 商品是否可售；
• 库存是否足够；
• 价格是否需要重新计算。

实际示例：事务管道

事务也适合放进管道。

不过不是所有请求都需要事务。

可以定义一个标记接口：

public interface ITransactionalRequest
{
}

让需要事务的命令实现它：

public sealed record CreateOrderCommand(
    long UserId,
    IReadOnlyList Items)
    : IRequestlong>, ITransactionalRequest;

事务管道：

public sealed class TransactionBeha viorTRequest, TResponse>
    : IPipelineBeha viorTRequest, TResponse>
{
    private readonly AppDbContext _dbContext;

    public TransactionBeha vior(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async TaskHandle(
        TRequest request,
        RequestHandlerDelegate next,
        CancellationToken cancellationToken)
    {
        if (request is not ITransactionalRequest)
        {
            return await next();
        }

        await using var transaction = await _dbContext.Database
            .BeginTransactionAsync(cancellationToken);

        TResponse response = await next();

        await _dbContext.Sa veChangesAsync(cancellationToken);
        await transaction.CommitAsync(cancellationToken);

        return response;
    }
}

注册顺序要留意。

例如：

builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.AddOpenBeha vior(typeof(LoggingBeha vior));
    cfg.AddOpenBeha vior(typeof(ValidationBeha vior));
    cfg.AddOpenBeha vior(typeof(TransactionBeha vior));
});

通常希望：

• 日志最外层；
• 验证在事务之前；
• 事务包住真正的业务处理。

如果验证失败，不需要打开事务。

如果采用这种事务管道，Handler 里就不要再对同一个 DbContext 重复提交。

也就是说，下面两种方式选一种：

• Handler 自己调用 Sa veChangesAsync；
• 事务管道统一调用 Sa veChangesAsync。

两边都提交，代码语义会变乱。

Minimal API 里的写法

MediatR 不只适用于控制器。

Minimal API 里也可以直接注入 ISender：

app.MapPost("/orders", async (
    CreateOrderRequest request,
    ISender sender,
    CancellationToken cancellationToken) =>
{
    var command = new CreateOrderCommand(
        request.UserId,
        request.Items
            .Select(x => new CreateOrderItem(x.ProductId, x.Quantity))
            .ToArray());

    long orderId = await sender.Send(command, cancellationToken);

    return Results.Ok(new { orderId });
});

查询接口：

app.MapGet("/orders/{id:long}", async (
    long id,
    ISender sender,
    CancellationToken cancellationToken) =>
{
    OrderDetailDto? order = await sender.Send(
        new GetOrderDetailQuery(id),
        cancellationToken);

    return order is null
        ? Results.NotFound()
        : Results.Ok(order);
});

文件组织方式

MediatR 代码如果放得乱，很快会变成另一种混乱。

比较常见的组织方式是按功能分目录：

Features/
  Orders/
    CreateOrder/
      CreateOrderCommand.cs
      CreateOrderCommandHandler.cs
      CreateOrderCommandValidator.cs
    GetOrderDetail/
      GetOrderDetailQuery.cs
      GetOrderDetailQueryHandler.cs
      OrderDetailDto.cs

这种方式的好处是：

• 一个用例相关的请求、处理器、验证器放在一起；
• 改创建订单时，不用到处找文件；
• 比按 Controllers、Services、Repositories 横向分层更贴近业务动作。

当然，项目如果已经有成熟分层方式，也没必要为了 MediatR 强行重排目录。

执行流程

一次 Send 大概是这样：

flowchart LR
    A["Controller / Minimal API"] --> B["ISender.Send"]
    B --> C["Pipeline Beha viors"]
    C --> D["Request Handler"]
    D --> E["Repository / DbContext / External Service"]
    D --> C
    C --> B
    B --> A

一次 Publish 大概是这样：

flowchart LR
    A["Handler / Domain Service"] --> B["IPublisher.Publish"]
    B --> C["Notification Handler A"]
    B --> D["Notification Handler B"]
    B --> E["Notification Handler C"]

这两张图的区别很关键：

• Send 是一对一，有返回值；
• Publish 是一对多，不适合拿返回值；
• Pipeline Beha vior 主要包在 Send 的请求处理链路上。

常见坑 1：把所有方法都改成 MediatR

MediatR 是组织业务用例的工具，不是替代所有方法调用的工具。

下面这些代码没必要硬套：

• 简单工具方法；
• 实体内部行为；
• 私有领域计算；
• 很短的纯函数；
• 一个类内部的普通协作。

如果一个操作只是同一个类内部拆方法，直接调用方法更清楚。

MediatR 更适合表达“一个应用层用例”。

常见坑 2：Handler 变成大杂烩

用了 MediatR，并不自动等于架构清晰。

如果 Handler 里塞满：

• 参数校验；
• 权限判断；
• 事务；
• 日志；
• 复杂查询；
• 外部接口调用；
• 各种 if-else；

那只是把胖控制器换成了胖 Handler。

更合适的拆法是：

• 基础校验放验证器；
• 日志、事务、性能统计放管道；
• 复杂领域规则放领域对象或领域服务；
• 数据访问细节放仓储或查询对象；
• Handler 负责组织这个用例。

常见坑 3：在 Handler 里互相 Send

一个 Handler 里再调用 _sender.Send(...)，有时可以用，但要克制。

如果大量 Handler 互相发送请求，调用链会变得不直观：

AHandler -> Send(BCommand) -> BHandler -> Send(CCommand)

结果是：

• 调试困难；
• 事务边界不清楚；
• 重复经过管道；
• 容易形成隐式依赖。

更稳的做法是把公共业务能力抽成服务，两个 Handler 都调用这个服务。

常见坑 4：滥用 Notification 做关键业务

Notification 适合解耦本地副作用。

但关键业务不要轻易放进“谁订阅谁执行”的隐式流程里。

例如：

• 创建订单必须扣库存；
• 支付成功必须生成流水；
• 审核通过必须变更主状态。

这些动作如果是主流程的一部分，最好明确写在命令处理逻辑里，或者放在明确的领域服务里。

Notification 更适合“主流程完成后顺带发生”的动作。

常见坑 5：忽略 CancellationToken

Handle 方法自带 CancellationToken。

数据库、HTTP、缓存、消息发送等异步调用，都要尽量传下去：

await _orders.AddAsync(order, cancellationToken);
await _unitOfWork.Sa veChangesAsync(cancellationToken);

如果每一层都丢掉 CancellationToken，上游请求取消后，后台工作仍然可能继续执行。

常见坑 6：异常处理边界不清楚

MediatR 不会让异常自动变成统一响应。

Handler 抛出的异常，最终还是要被 ASP.NET Core 的异常处理中间件、过滤器或自定义异常映射处理。

常见做法是：

• 参数错误抛验证异常；
• 找不到资源返回 null 或领域结果对象；
• 业务冲突抛业务异常或返回错误结果；
• 最外层统一转成 HTTP 响应。

不要把所有异常处理都塞进每个 Handler。

什么时候不适合用 MediatR？

这些情况可以先不上：

• 项目很小，控制器和服务类已经足够清楚；
• 团队不熟悉这种用例拆分方式；
• 业务逻辑非常简单，主要是 CRUD；
• 引入后只是多了一堆空壳 Command / Handler；
• 调用链可读性比原来更差。

MediatR 的收益来自“拆分复杂度”。

如果本来没有复杂度，引入它只会增加文件数量和跳转成本。

总结

MediatR 的核心价值不是“让代码看起来高级”，而是：

把应用内部的业务动作，拆成清晰的请求、处理器、通知和管道。

它最常用的几类能力是：

• Send：命令和查询，一对一处理；
• Publish：通知事件，一对多处理；
• Pipeline Beha vior：日志、验证、事务、性能统计等横切逻辑；
• ISender / IPublisher：按职责暴露发送和发布能力；
• 程序集扫描：自动注册请求处理器和通知处理器。

真正需要记住的是边界：

• 它是进程内分发，不是消息队列；
• 它能让控制器变薄，但不能自动让业务变清楚；
• Notification 不适合承载必须成功的关键业务；
• Handler 也需要保持单一职责；
• 简单项目没必要为了模式而引入。

用在合适的位置，MediatR 会让应用层更像一组清晰的用例。

用得过度，就只是把直接调用换成绕路调用。