架构与CQRS 是做什么的?
0. 项目上下文
每次会话解析一次,从工作目录开始:解决方案文件(*.sln / *.slnx,否则匹配*.csproj——如果有多个匹配则询问)及其按角色划分的项目:<Api>、<Application>、<Core>、<Infrastructure>、<Tests>。这些占位符指代实际的项目名称;以下路径均相对于解决方案根目录。产品名称取自仓库——切勿自行编造。如果解决方案并非按此方式分层,请说明并询问后再施加此结构。
1. 整洁架构 —— 层级规则
解决方案由四个不可变层级构成。依赖流向严格向内:
Web → Application → Core ← Infrastructure
| 层级 | 职责 | 禁止行为 |
|---|---|---|
| Core | 实体、枚举、接口(IRepository<T>、IUnitOfWork、服务契约) | 引用任何其他层级 |
| Application | MediatR 命令/查询/处理器、FluentValidation 验证器、DTO、Mapster 配置 | 直接访问数据库、HTTP、Refit |
| Infrastructure | EF Core DbContext、仓储、UoW、Refit 客户端、DelegatingHandler、JWT | MediatR、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 中注册:
LoggingBehavior<TRequest, TResponse>—— 记录请求类型、执行时间。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 约定