Sparkdo.Mediation.Abstractions 1.0.3

Sparkdo.Mediation.Abstractions 参考文档

简介

Sparkdo.Mediation.Abstractions 是 Sparkdo Mediator 中介者模式的核心契约层，定义了整个消息调度系统的基础接口和类型。该包提供了命令（Request）、查询（StreamRequest）、通知（Notification）以及相应处理器的抽象定义，为上层实现提供了清晰、稳定的 API 契约。

作为 Sparkdo 生态系统的一部分，Sparkdo.Mediation.Abstractions 遵循 DDD（领域驱动设计）分层架构原则，不依赖任何第三方包，是构建可扩展、可测试的中介者消息系统的基石。

核心特性

1. CQRS 消息模式支持

• 命令（Request）：IRequest（无返回值）和 IRequest<TResponse>（带返回值）
• 查询（StreamRequest）：IStreamRequest<TResponse> 支持异步流式响应
• 通知（Notification）：INotification 用于事件广播

2. 处理器契约

• IRequestHandler<TRequest> — 处理 void 返回的命令
• IRequestHandler<TRequest, TResponse> — 处理带返回值的命令
• IStreamRequestHandler<TRequest, TResponse> — 处理流式查询
• INotificationHandler<TNotification> — 处理通知事件

3. 统一调度接口

• ISender — 发送命令和查询的统一入口
• IPublisher — 发布通知的统一入口
• IMediator — 组合 ISender 和 IPublisher 的聚合接口

4. 源码生成器支持

• MediatorModuleAttribute — 为源码生成器指定程序集模块名称
• GenericHandlerAttribute — 标记泛型处理器类，支持类型参数约束自动匹配

5. 零依赖设计

纯净的 .NET 实现，无第三方依赖，最大化兼容性和最小化冲突风险。

项目信息

• 包名称: Sparkdo.Mediation.Abstractions
• 描述: Sparkdo Mediator 中介者模式的核心接口和抽象定义
• 标签: mediator, cqrs, abstractions, sparkdo

安装

Package Manager

Install-Package Sparkdo.Mediation.Abstractions

.NET CLI

dotnet add package Sparkdo.Mediation.Abstractions

PackageReference

<PackageReference Include="Sparkdo.Mediation.Abstractions" Version="1.0.0" />

快速入门

定义消息类型

using Sparkdo.Mediation;

// 无返回值的命令
public record CreateUserCommand(string Name, string Email) : IRequest;

// 带返回值的命令
public record GetUserQuery(int UserId) : IRequest<UserDto>;

// 流式查询
public record ExportDataQuery(string Filter) : IStreamRequest<DataRow>;

// 通知事件
public record UserCreatedEvent(int UserId, string Name) : INotification;

实现处理器

using Sparkdo.Mediation;

public class CreateUserHandler : IRequestHandler<CreateUserCommand>
{
    public async ValueTask HandleAsync(CreateUserCommand request, CancellationToken cancellationToken)
    {
        // 在此实现命令处理逻辑
    }
}

public class GetUserHandler : IRequestHandler<GetUserQuery, UserDto>
{
    public async ValueTask<UserDto> HandleAsync(GetUserQuery request, CancellationToken cancellationToken)
    {
        // 在此实现查询处理逻辑
        return new UserDto(request.UserId, "张三", "zhangsan@example.com");
    }
}

public class UserCreatedNotificationHandler : INotificationHandler<UserCreatedEvent>
{
    public ValueTask HandleAsync(UserCreatedEvent notification, CancellationToken cancellationToken)
    {
        // 在此实现通知处理逻辑
        Console.WriteLine($"用户创建成功: {notification.Name}");
        return ValueTask.CompletedTask;
    }
}

API 参考

IMediator 接口

IMediator 是 ISender 和 IPublisher 的组合接口，是使用中介者模式的主要入口点。

public interface IMediator : ISender, IPublisher
{
}

ISender 接口

发送命令和查询的统一接口：

IPublisher 接口

发布通知的统一接口：

消息标记接口

处理器接口

Unit 结构体

Unit 用于表示无返回值的泛型类型参数，因为 Void 不是有效的泛型类型参数。

// 示例：指定 Unit 作为 void 命令的响应类型
public class MyHandler : IRequestHandler<MyCommand, Unit>
{
    public async ValueTask<Unit> HandleAsync(MyCommand request, CancellationToken ct)
    {
        // 业务逻辑
        return Unit.Value;
    }
}

源码生成器特性

MediatorModuleAttribute

指定程序集模块名称，由源码生成器读取以组织生成的 DI 注册代码：

[assembly: Sparkdo.Mediation.MediatorModule("MyApp")]

GenericHandlerAttribute

标记泛型处理器类，使源码生成器自动匹配实现特定标记接口的消息类型：

[GenericHandler]
public class HttpRequestHandler<TRequest, TResponse> : IRequestHandler<TRequest, TResponse>
    where TRequest : IHttpRequest<TResponse>
{
    // 自动匹配所有实现 IHttpRequest<TResponse> 的消息类型
}

测试

该项目作为契约层，不包含直接的单元测试。其接口的设计正确性通过 Sparkdo.Mediation.Tests 和 Sparkdo.Mediation.SourceGeneration.Tests 项目的集成测试进行验证。