架构模式与实践

// 表现层：只做 HTTP 协议转换
[ApiController]
[Route("api/orders")]
public class OrdersController(IOrderAppService app) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create(CreateOrderRequest req)
        => Ok(await app.CreateAsync(req.ToCommand()));
}

// 应用层：用例编排，不写业务规则
public class OrderAppService(IOrderRepository repo, IUnitOfWork uow)
{
    public async Task<OrderDto> CreateAsync(CreateOrderCommand cmd)
    {
        var order = Order.Create(cmd.CustomerName, cmd.Total); // 领域规则在领域层
        await repo.AddAsync(order);
        await uow.SaveChangesAsync();
        return OrderDto.From(order);
    }
}

// 领域层：业务规则的家
public class Order
{
    public int Id { get; private set; }
    public string Customer { get; private set; }
    public OrderStatus Status { get; private set; }

    public static Order Create(string customer, decimal total)
    {
        if (total <= 0) throw new DomainException("金额必须大于 0");
        return new Order { Customer = customer, Status = OrderStatus.New };
    }

    public void Confirm()
    {
        if (Status != OrderStatus.New) throw new DomainException("只有新订单可确认");
        Status = OrderStatus.Confirmed;
    }
}

public class Order
{
    private readonly List<OrderLine> _lines = [];

    public IReadOnlyList<OrderLine> Lines => _lines.AsReadOnly();
    public decimal Total => _lines.Sum(l => l.Quantity * l.UnitPrice);

    public OrderLine AddLine(int productId, int quantity, decimal unitPrice)
    {
        if (quantity <= 0) throw new DomainException("数量必须为正");
        var line = new OrderLine(productId, quantity, unitPrice);
        _lines.Add(line);
        return line;
    }

    public void RemoveLine(int productId)
    {
        var line = _lines.FirstOrDefault(l => l.ProductId == productId)
                   ?? throw new DomainException("订单项不存在");
        if (Status != OrderStatus.New) throw new DomainException("已确认订单不可改项");
        _lines.Remove(line);
    }
}

public record OrderLine(int ProductId, int Quantity, decimal UnitPrice);

// 命令侧：领域模型 + 事务
public class OrderAppService(IOrderRepository repo, IUnitOfWork uow)
{
    public async Task CreateAsync(CreateOrderCommand cmd)
    {
        var order = Order.Create(cmd.CustomerName, cmd.Total);
        await repo.AddAsync(order);
        await uow.SaveChangesAsync();
    }
}

// 查询侧：专用读模型，按需投影
public class OrderQueryService(IDbConnection db)
{
    public async Task<IEnumerable<OrderSummaryDto>> ListAsync(string customer)
    {
        // 直接 SQL/Dapper，绕过领域约束，为查询而生
        return await db.QueryAsync<OrderSummaryDto>(
            "SELECT Id, Customer, Total, Status FROM Orders WHERE Customer = @customer",
            new { customer });
    }
}

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

// 请求：应用层用例的定义
public record CreateOrderCommand(string CustomerName, decimal Total) : IRequest<int>;

// 处理器：用例实现
public class CreateOrderHandler(IOrderRepository repo, IUnitOfWork uow)
    : IRequestHandler<CreateOrderCommand, int>
{
    public async Task<int> Handle(CreateOrderCommand cmd, CancellationToken ct)
    {
        var order = Order.Create(cmd.CustomerName, cmd.Total);
        await repo.AddAsync(order);
        await uow.SaveChangesAsync(ct);
        return order.Id;
    }
}

// 管道行为：统一事务边界
public class TransactionBehavior<TReq, TResp>(IUnitOfWork uow)
    : IPipelineBehavior<TReq, TResp> where TReq : notnull
{
    public async Task<TResp> Handle(TReq request,
        RequestHandlerDelegate<TResp> next, CancellationToken ct)
    {
        await uow.BeginTransactionAsync(ct);
        var response = await next();
        await uow.CommitAsync(ct);
        return response;
    }
}

// Controller 使用
[HttpPost]
public async Task<IActionResult> Create(CreateOrderCommand cmd)
    => Ok(await _mediator.Send(cmd));

public record Result<T>(T? Value, Error? Error)
{
    public bool IsSuccess => Error is null;

    public static Result<T> Ok(T value) => new(value, null);
    public static Result<T> Fail(Error error) => new(default, error);

    public TValue Match<TValue>(
        Func<T, TValue> onSuccess,
        Func<Error, TValue> onFailure)
        => IsSuccess ? onSuccess(Value!) : onFailure(Error!);
}

public record Error(string Code, string Message);

// 领域方法返回结果而非抛异常
public Result<Order> Confirm()
{
    if (Status != OrderStatus.New)
        return Result<Order>.Fail(new Error("ORDER.NOT_CONFIRMABLE", "只有新订单可确认"));
    Status = OrderStatus.Confirmed;
    return Result<Order>.Ok(this);
}

// 调用方显式处理
var result = order.Confirm();
return result.Match(
    success => Ok(success),
    error => Problem(error.Message, statusCode: 409));

// 领域事件：已发生的过去时
public record OrderConfirmed(int OrderId, string Customer) : INotification;

// 聚合内发布事件
public class Order
{
    private readonly List<INotification> _events = [];

    public IReadOnlyList<INotification> Events => _events;

    public void Confirm()
    {
        if (Status != OrderStatus.New) throw new DomainException("订单状态不允许确认");
        Status = OrderStatus.Confirmed;
        _events.Add(new OrderConfirmed(Id, Customer));
    }

    public void ClearEvents() => _events.Clear();
}

// 事件处理器：副作用在这里
public class OrderConfirmedHandler(INotificationService notify)
    : INotificationHandler<OrderConfirmed>
{
    public async Task Handle(OrderConfirmed evt, CancellationToken ct)
    {
        await notify.SendEmailAsync(evt.Customer, "订单已确认", evt.OrderId, ct);
    }
}

// 模块化单体：按领域划项目/程序集
// src/
//   Orders.Domain/       领域模型、聚合
//   Orders.Application/  用例、MediatR Handler
//   Orders.Infrastructure/ EF、仓储实现
//   Orders.Api/          表现层、DI 组装
//   Shared.Kernel/       通用基座（结果类型、领域事件基类）

// DI 组装：把模块的依赖集中注册，避免循环引用
builder.Services.AddOrdersModule(builder.Configuration);
builder.Services.AddPaymentsModule(builder.Configuration);