Community编程与开发github.com

架构与CQRS

为分层.NET后端提供整洁架构、基于MediatR的CQRS、精简控制器、管道行为、Mapster映射、模块边界和按资源授权的规范。适用于编辑C#的Application、Api或Core项目中的命令、查询、处理器、验证器、控制器或跨模块代码。

架构与CQRS 是什么?

该技能为.NET后端开发者提供了一整套基于整洁架构和CQRS模式的开发规范。它强制代码遵循严格的分层依赖规则(Web → Application → Core ← Infrastructure),并利用MediatR库实现命令与查询的分离,确保业务逻辑仅存在于Application层的处理器中,控制器仅作为精简的调度器。技能还涵盖了MediatR管道行为(日志、验证)、Mapster对象映射配置、模块化单体架构下的边界管理,以及基于每个资源的授权检查(防止BOLA/IDOR漏洞)。使用此技能可确保生成的代码结构一致、安全,并易于维护和测试。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/19mittal/dotnet-next-toolkit/tree/HEAD/plugins/dotnet-backend/skills/architecture-cqrs

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

架构与CQRS 是做什么的?


0. 项目上下文

每次会话解析一次,从工作目录开始:解决方案文件(*.sln / *.slnx,否则匹配*.csproj——如果有多个匹配则询问)及其按角色划分的项目:<Api>、<Application>、<Core>、<Infrastructure>、<Tests>。这些占位符指代实际的项目名称;以下路径均相对于解决方案根目录。产品名称取自仓库——切勿自行编造。如果解决方案并非按此方式分层,请说明并询问后再施加此结构。


1. 整洁架构 —— 层级规则

解决方案由四个不可变层级构成。依赖流向严格向内: Web → Application → Core ← Infrastructure

层级职责禁止行为
Core实体、枚举、接口(IRepository<T>、IUnitOfWork、服务契约)引用任何其他层级
ApplicationMediatR 命令/查询/处理器、FluentValidation 验证器、DTO、Mapster 配置直接访问数据库、HTTP、Refit
InfrastructureEF Core DbContext、仓储、UoW、Refit 客户端、DelegatingHandler、JWTMediatR、Application DTO
Web控制器、Program.cs、中间件、OpenAPI/Swagger 配置任何形式的业务逻辑

绝不允许发生的违规行为:

  • 控制器中包含除 await _mediator.Send(command) 之外的任何逻辑。
  • Application 的处理器using任何 Infrastructure 命名空间。
  • Core 实体引用 Application 或 Infrastructure 类型。

2. 基于 MediatR 的 CQRS

命令 / 查询命名

Features/
  <BoundedContext>/
    Commands/
      <ActionName>Command/
        <ActionName>Command.cs          ← IRequest<TResult>
        <ActionName>CommandValidator.cs ← AbstractValidator<TCommand>
        <ActionName>CommandHandler.cs   ← IRequestHandler<TCommand, TResult>
    Queries/
      <QueryName>Query/
        <QueryName>Query.cs
        <QueryName>QueryHandler.cs
    DTOs/
      <Entity>Response.cs

处理器规则

  • 所有业务逻辑必须放在处理器的 Handle() 方法内。
  • 处理器仅通过构造函数注入接收依赖。
  • 处理器必须注入 IUnitOfWork(而非直接注入 AppDbContext)。
  • 处理器必须注入 Core 服务接口(例如 IPaymentGatewayService),绝不能注入 Infrastructure 实现。
  • 返回类型始终是 DTO/Result 记录——绝不能是原始实体。

控制器规则

// ✅ 正确 —— 精简调度器
[HttpPost]
public async Task<IActionResult> Create([FromBody] CreateOrderCommand cmd, CancellationToken ct)
    => Ok(await _mediator.Send(cmd, ct));

// ❌ 禁止 —— 控制器中包含逻辑
[HttpPost]
public async Task<IActionResult> Create([FromBody] CreateOrderRequest req)
{
    var order = new Order { ... };  // ← 业务逻辑应属于处理器
    ...
}

3. MediatR 管道行为

两个必需的行为必须按顺序在 Application/DependencyInjection.cs 中注册:

  1. LoggingBehavior<TRequest, TResponse> —— 记录请求类型、执行时间。
  2. ValidationBehavior<TRequest, TResponse> —— 运行 FluentValidation;在处理到达处理器之前抛出 ValidationException。
services.AddTransient(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
services.AddTransient(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));

在 MediatR 12 中,RequestHandlerDelegate<TResponse> 是无参数的 —— 应调用 next(),而不是 next(cancellationToken)。


4. 映射(Mapster)

  • 所有对象转换均使用 IMapper.Adapt<TDestination>()。
  • 映射在 Application/Mapping/MappingConfig.cs 中使用 TypeAdapterConfig 配置。
  • 处理器注入 IMapper —— 绝不能直接调用 TypeAdapter.Adapt<>()。

5. 模块(微服务就绪)

适用于后端为模块化单体的情况 —— 一个可部署单元、一个数据库,每个限界上下文对应一个模块(一个数据库架构加上拥有其表的 Features/* 文件夹)。在模块内部,代码可以自由调用。模块之间: 调用 Core/Interfaces/<Module>/ 中的端口或发布 MediatR 通知 —— 绝不能发送另一个模块的命令、加载其实体、通过导航属性访问其表,或创建循环依赖。

在执行任何跨越模块边界、添加功能文件夹或添加端口的更改之前,请阅读 reference/modular-monolith.md。对于单模块后端,请跳过此步骤。


6. 安全

  • 默认情况下,所有端点都需要 [Authorize]。仅对认证端点使用 [AllowAnonymous] 选择退出。
  • JWT 声明只能通过 ICurrentUserService 访问 —— 绝不在处理器中通过 HttpContext.User 访问。
  • 暴力破解保护(锁定)位于登录处理程序中 —— 而非控制器或中间件中。

按资源授权 —— 处理器的职责,而非特性的职责

[Authorize(Roles="...")] 证明调用者拥有一个角色。它不证明调用者拥有他们刚刚发送的 ID 所对应的数据行。每个接受来自请求的实体 ID 的处理器,在读取或写入之前,必须根据 ICurrentUserService.UserId 验证所有权:

// ❌ BOLA/IDOR —— 任何经过身份验证的调用者都可以通过猜测或枚举 ID 读取任何行
var record = await _unitOfWork.Repository<Order>().GetByIdAsync(request.Id, ct);

// ✅ 所有权是查询谓词的一部分
var record = await _unitOfWork.Repository<Order>().SingleOrDefaultAsync(
    b => b.Id == request.Id && b.OwnerUserId == _currentUser.UserId, ct)
    ?? throw new NotFoundException();

规则:

  • 在查询谓词中按所有者限定范围,而不是在加载后使用 if 进行检查 —— 后来被重构掉的加载后检查会失败并导致漏洞(fails open)。
  • 对于调用者可能看不到的资源,返回 404,而非 403。403 确认了该行存在。
  • 每个角色的范围是其自身的数据:客户看到自己的订单和付款,经理看到其管理的组织的记录。只有 Admin 可以跨越该边界,并且管理员跨账户读取时会写入审计日志条目。
  • 切勿将请求体或查询字符串中的 userId、ownerId 或 organizationId 作为要执行操作的身份标识 —— 应从 ICurrentUserService 派生。请求提供的 ID 是一个需要授权的目标,而不是关于您是谁的声明。
  • 签名链接确认端点是 [AllowAnonymous]:令牌就是授权。它必须是一次性、过期、高熵的,并以恒定时间进行比较 —— 并且它仅授权为其生成的唯一一条记录。
  • 切勿直接将请求 DTO 绑定到实体。角色、状态、价格和资格字段绝不能从网络请求中设置(过度发布 → 权限提升)。

7. 错误处理

抛出项目自有异常(NotFoundException 404、ForbiddenException 403、ConflictException 409;FluentValidation ValidationException 422),并让全局处理程序将它们映射为 ProblemDetails。切勿抛出或映射 BCL 类型,如 InvalidOperationException 或 KeyNotFoundException —— 框架为真实缺陷抛出这些异常,它们必须作为记录的 500 错误暴露出来。处理器中不允许使用捕获所有异常的 catch-all 块。

完整的故障路径 —— 异常基类和 code 词汇表、处理程序实现、网络传输格式、日志级别、持久化和 webhook 故障 —— 参见 [[error-handling-dotnet]]。


完成工作前的检查清单

  • 业务逻辑位于 Application 处理器中,而非控制器或 Infrastructure 中
  • 层级依赖指向内部;Core 没有对外的引用
  • 命令/查询遵循 CQRS;控制器仅通过 MediatR 进行调度
  • 处理器注入 IUnitOfWork 和 Core 接口 —— 而非 AppDbContext 或 Refit
  • 更改尊重模块边界:跨模块调用通过 Core 端口或事件进行,已接受的耦合基线未增加,架构测试通过
  • 新的功能文件夹被分配给一个模块;新表位于其模块架构中
  • 在适用处遵循了管道行为和 Mapster 约定

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能