.NET工程实践：轻量级CAT架构设计与落地-CSDN博客

1. 项目概述：这不是一只真猫，而是一套面向 .NET 开发者的“猫系”工程实践体系

“Cat in dotNET”——看到这个标题，很多刚接触 .NET 的开发者第一反应是：“这是个宠物识别项目？还是某个萌系 UI 库？”其实都不是。它是我过去三年在多个中大型企业级 .NET 项目中沉淀下来的一套 轻量级、可组合、强约定、低侵入 的工程实践方法论，核心目标只有一个：让 .NET 项目从“能跑起来”走向“好维护、易扩展、敢重构”。之所以叫“Cat”，不是因为卖萌，而是取其英文单词中隐含的四个关键特质： C onvention（约定）、 A gility（敏捷性）、 T estability（可测试性）——合起来就是 CAT，一个在复杂系统里依然能保持优雅姿态、快速转身、自主呼吸的生命体。

这套实践不依赖任何第三方框架强行绑定，也不要求你推翻现有架构重写；它完全基于 .NET 原生能力（.NET 6+ 推荐，但 .NET 5 亦可平滑适配），通过 目录结构约束、接口契约前置、依赖注入粒度控制、测试桩标准化、配置分层治理 这五根支柱，把原本散落在 Startup.cs、Program.cs、各种 ServiceCollection 扩展方法、以及无数“临时加个逻辑”的代码块中的隐性规则，显性化、模板化、工具化。它适合三类人：一是正在带团队做 .NET 技术选型的 Tech Lead，需要一套能快速对齐开发节奏的“最小公约数”；二是接手遗留系统的中级开发者，面对满屏 new Service() 和静态方法调用时急需一套“解耦手术刀”；三是准备跳槽面试的候选人，掌握这套实践，能在系统设计题中自然带出“我如何让模块边界清晰、如何保障变更不破测试、如何让新同事三天内看懂主干流程”。

它不解决“高并发”或“超低延迟”这类性能专项问题，但它能让你在解决这些问题时，不再被“改一处崩十处”“测完功能不敢上线”“查 Bug 要翻遍三个项目”所拖累。换句话说，“Cat in dotNET”不是给系统加功能，而是给团队加“工程免疫力”。

2. 整体设计思路与方案选型逻辑：为什么是这五根支柱，而不是其他？

2.1 不选“大框架”，而选“小约定”：对抗技术债的源头策略

很多团队一上来就想引入 MediatR + CQRS + Event Sourcing 这套“黄金组合”，结果半年后发现：90% 的业务场景根本用不到事件溯源，MediatR 的 IRequestHandler 泛型嵌套三层后连自己都看不懂，CQRS 的读写分离反而让简单查询变得绕路。我试过两次，一次在金融风控后台，一次在物流调度平台，最后都回归到了更朴素的路径： 先统一接口形状，再约束调用关系，最后才考虑消息解耦 。

所以“Cat”体系的第一选择，是放弃“框架驱动”，转向“约定驱动”。我们定义了最简接口契约：

public interface IUseCase<in TRequest, TResponse>
    where TRequest : class
    where TResponse : class
{
    Task<TResponse> ExecuteAsync(TRequest request, CancellationToken ct = default);
}

注意，这里没有 IRequest<TResponse> 或 IRequestHandler<TRequest, TResponse> 那种深度泛型嵌套，也没有强制要求继承某个基类。它就是一个干净的、语义明确的“用例”抽象——输入一个请求对象，输出一个响应对象，全程异步。所有业务逻辑入口，必须实现这个接口。好处是什么？

可测试性直线上升 ：Mock 一个接口比 Mock 一个继承自 BaseHandler 的类简单十倍；
IDE 友好 ：VS 或 Rider 点击“查找所有引用”，立刻看到所有业务入口点，不用在 Handlers/ 、 Commands/ 、 UseCases/ 多个文件夹里翻找；
无学习成本 ：新人第一天就能看懂 CreateOrderUseCase 是干什么的，不需要先学 CQRS 概念。

这个选择背后的计算很实际：一个中型项目平均有 80–120 个核心业务用例。如果每个用例的接入成本（理解+编写+测试）从 45 分钟降到 12 分钟，一年节省的工时就是 300+ 小时——这笔账，比争论“DDD 是否过重”实在得多。

2.2 目录结构即架构图：用物理隔离代替逻辑注释

.NET 项目最常见的混乱，不是代码写得差，而是 模块边界在文件系统里不存在 。你看到 Controllers/ 下混着订单、用户、支付的 API； Services/ 里既有 IEmailService 又有 IInventoryCheckService ，但没人知道它们属于哪个业务域； Models/ 文件夹塞满了 DTO、Entity、ViewModel，命名还带 Dto 、 Vm 、 Model 后缀，光靠名字根本分不清职责。

“Cat”体系强制采用垂直切片（Vertical Slice）目录结构，但做了关键简化： 不按“领域”分，而按“能力”分 。例如：

src/
├── Cat.Core/              # 公共基础设施（非业务）
├── Cat.Application/       # 所有用例实现 + 请求/响应 DTO
│   ├── Orders/
│   │   ├── CreateOrderUseCase.cs
│   │   ├── CreateOrderRequest.cs
│   │   └── CreateOrderResponse.cs
│   ├── Users/
│   │   ├── RegisterUserUseCase.cs
│   │   └── ...
├── Cat.Domain/            # 纯领域模型（Entity、ValueObject、DomainException）
│   ├── Orders/
│   │   ├── Order.cs
│   │   ├── OrderItem.cs
│   │   └── OrderStatus.cs
├── Cat.Infrastructure/    # 外部依赖实现（EF Core Context、Redis Cache、SMTP Mailer）
│   ├── Persistence/
│   │   └── AppDbContext.cs
│   ├── External/
│   │   └── SmtpEmailSender.cs
└── Cat.Presentation/      # API 层（Controller、Minimal API Endpoint）
    └── Orders/
        └── OrderEndpoints.cs

为什么这样设计？因为“领域”这个词太抽象，不同人理解差异极大；而“能力”是具象的——“创建订单”这件事，必然涉及订单实体、创建请求、库存校验、邮件通知、数据库写入。把所有相关代码放在 Orders/ 下，意味着：

新增一个“取消订单”功能，只需在 Orders/ 下新增三个文件，不会污染 Users/ 或 Payments/ ；
删除“订单”模块？直接删掉整个 Orders/ 文件夹，编译器立刻报错，绝无遗漏；
Code Review 时，Reviewer 只需打开 Orders/ 文件夹，5 分钟内就能判断逻辑是否完整、是否有外部依赖泄露。

我曾在一个电商项目中推行此结构，上线前做了一次“模块隔离测试”：随机挑出 3 个业务模块，让三位不同开发者分别只看对应文件夹代码，独立写出该模块的单元测试。结果三人覆盖的测试用例重合度仅 37%，说明原有结构下，大家对模块边界的认知是严重碎片化的。而采用新结构后，重合度提升到 89%——物理结构真的会重塑思维结构。

2.3 依赖注入：不是“注册一切”，而是“暴露最小契约”

.NET 的 IServiceCollection 像个黑洞，很多项目习惯性地把所有 I*Service 全部 AddScoped ，甚至 AddSingleton 一堆状态管理类。结果就是：

单元测试时，要 Mock 十几个接口，构造函数参数长得要滚动屏幕；
某个 IReportGenerator 修改了内部缓存策略，导致所有依赖它的用例行为突变；
Startup.cs 超过 500 行，没人敢动第 327 行的 AddTransient<ICacheManager>() 。

“Cat”体系规定：只有 UseCase 接口和 Domain Entity 的仓储接口（ IRepository<T> ）允许被直接注入；所有具体实现类、工具类、配置类，必须通过 UseCase 内部自行解析或构造。例如：

// ✅ 正确：UseCase 只依赖抽象，不依赖具体实现
public class CreateOrderUseCase : IUseCase<CreateOrderRequest, CreateOrderResponse>
{
    private readonly IOrderRepository _orderRepo;
    private readonly IInventoryService _inventorySvc; // 注意：这是领域服务接口，非基础设施
    private readonly ILogger<CreateOrderUseCase> _logger;

    public CreateOrderUseCase(
        IOrderRepository orderRepo,
        IInventoryService inventorySvc,
        ILogger<CreateOrderUseCase> logger)
    {
        _orderRepo = orderRepo;
        _inventorySvc = inventorySvc;
        _logger = logger;
    }

    public async Task<CreateOrderResponse> ExecuteAsync(CreateOrderRequest req, CancellationToken ct)
    {
        // 业务逻辑...
        var order = new Order(...);
        await _orderRepo.AddAsync(order, ct);
        await _inventorySvc.ReserveStock(req.Items, ct); // 领域服务协调多个仓储
        return new CreateOrderResponse { Id = order.Id };
    }
}

而 IInventoryService 的具体实现（比如调用 Redis 或调用库存微服务）则放在 Cat.Infrastructure.External 下，并 不在 DI 容器中注册为 IInventoryService ，而是由 CreateOrderUseCase 在构造时通过工厂或配置动态选择：

// 在 Program.cs 中
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();
builder.Services.AddScoped<IInventoryService, StubInventoryService>(); // 默认用 Stub，便于测试

// 生产环境启动时替换
if (builder.Environment.IsProduction())
{
    builder.Services.Replace(new ServiceDescriptor(
        typeof(IInventoryService),
        typeof(RedisInventoryService),
        ServiceLifetime.Scoped));
}

这种设计牺牲了一点“自动注册”的便利，但换来的是：

测试极简 ：单元测试只需传入 StubInventoryService ，无需关心 Redis 连接字符串；
演进自由 ：明天想把库存服务换成 gRPC，只需新增 GrpcInventoryService 并替换注册，UseCase 代码零修改；
故障隔离 ： RedisInventoryService 抛异常，不会影响 CreateOrderUseCase 的单元测试通过率。

实测下来，在一个 12 人团队的项目中，DI 相关的集成问题从每月平均 4.2 次降至 0.3 次——因为大部分问题，根本没机会发生。

2.4 配置治理：拒绝“appsettings.json 一锅炖”

.NET 的配置系统强大，但也容易滥用。常见反模式：

把数据库连接字符串、Redis 地址、第三方 API Key 全塞进 appsettings.Development.json ；
用 IConfiguration.GetSection("Features").GetValue<bool>("EnablePromotion") 这种硬编码键名的方式读取开关；
微服务间配置格式不统一，A 服务用 Cache:TimeoutSeconds ，B 服务用 cache.timeout_in_seconds 。

“Cat”体系引入 配置契约（Configuration Contract） 概念：每个模块（如 Orders 、 Users ）定义自己的配置类，且必须实现 IConfigurationSection 绑定：

// Cat.Application.Orders/OrdersOptions.cs
public class OrdersOptions
{
    public int MaxItemsPerOrder { get; set; } = 100;
    public TimeSpan ReservationTimeout { get; set; } = TimeSpan.FromMinutes(30);
    public bool EnableAutoCancel { get; set; } = true;
}

// 在 Program.cs 中绑定
builder.Services.Configure<OrdersOptions>(builder.Configuration.GetSection("Orders"));

对应 appsettings.json ：

{
  "Orders": {
    "MaxItemsPerOrder": 200,
    "ReservationTimeout": "00:15:00",
    "EnableAutoCancel": false
  }
}

关键点在于： 配置类即文档 。当你看到 OrdersOptions ，就知道订单模块有哪些可配项；当 OrdersOptions 缺少某个属性，编译器直接报错，而不是运行时报 NullReferenceException 。我们还配套了一个小工具 Cat.ConfigValidator ，在 CI 流程中自动扫描所有 IConfigureOptions<T> 注册，检查 appsettings.*.json 中是否存在对应 Section，缺失项标红告警——把配置错误消灭在构建阶段。

这套机制在一次灰度发布中救了大命：运维同学漏配了 Users:PasswordMinLength ，旧版代码用 Configuration["Users:PasswordMinLength"] 返回 null，导致密码校验逻辑崩溃。而采用新契约后， UsersOptions.PasswordMinLength 是 int 类型，未配置时绑定失败，应用启动直接失败，CI 流水线卡住，问题在 2 分钟内被发现并修复。

2.5 测试策略：用“测试桩”代替“全量 Mock”

.NET 单元测试生态里，Moq 是事实标准，但过度使用会导致测试脆弱。比如：

// ❌ 脆弱测试：Mock 了太多细节
var mockRepo = new Mock<IOrderRepository>();
mockRepo.Setup(x => x.AddAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()))
        .Returns(Task.CompletedTask);
mockRepo.Setup(x => x.GetByIdAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
        .ReturnsAsync(new Order { Status = OrderStatus.Created });

var useCase = new CreateOrderUseCase(mockRepo.Object, ...);
var result = await useCase.ExecuteAsync(req);
// 然后还要 Assert mockRepo.Verify(...) —— 这是在测 Moq，不是测业务！

“Cat”体系推广 Test Double（测试替身） 思维，为每个外部依赖提供轻量级内存实现：

// Cat.Tests.Stubs/InMemoryOrderRepository.cs
public class InMemoryOrderRepository : IOrderRepository
{
    private readonly List<Order> _orders = new();

    public Task AddAsync(Order order, CancellationToken ct) 
        => Task.Run(() => _orders.Add(order), ct);

    public Task<Order?> GetByIdAsync(Guid id, CancellationToken ct) 
        => Task.Run(() => _orders.FirstOrDefault(x => x.Id == id), ct);

    public void Clear() => _orders.Clear(); // 方便测试重置
}

测试时直接 new 出来：

// ✅ 稳健测试：关注行为，不关注实现细节
[Fact]
public async Task Should_Create_Order_With_Valid_Items()
{
    // Arrange
    var repo = new InMemoryOrderRepository();
    var useCase = new CreateOrderUseCase(repo, new StubInventoryService(), ...);

    var request = new CreateOrderRequest { Items = new[] { new OrderItem { ProductId = Guid.NewGuid(), Quantity = 2 } } };

    // Act
    var response = await useCase.ExecuteAsync(request);

    // Assert
    Assert.NotNull(response.Id);
    Assert.Equal(1, await repo.CountAsync()); // 直接查内存仓库
}

优势非常明显：

零反射开销 ： InMemoryOrderRepository 是真实类型，执行速度比 Moq 快 3–5 倍；
调试友好 ：断点打进去，变量值一目了然，不用看 Moq 的内部 _interceptors ；
契约自检 ：如果 IOrderRepository 新增了 UpdateStatusAsync 方法， InMemoryOrderRepository 编译失败，强迫你同步更新测试桩——这本身就是一种设计反馈。

我们在一个包含 420 个单元测试的项目中切换此策略后，测试执行时间从 18.4 秒降至 11.2 秒，更重要的是，测试失败时的错误信息从 “Moq.MockException: Expected invocation on the mock at least once...” 变成 “Assert.Equal() Failure”，新人能 5 秒内定位问题。

3. 核心环节实现与实操步骤：从零搭建一个“Cat”项目

3.1 初始化项目结构：5 分钟完成骨架搭建

不要从 dotnet new webapi 开始。正确起点是创建一个干净的解决方案容器，然后按“Cat”约定逐层添加：

# 1. 创建空解决方案
dotnet new sln -n CatDemo

# 2. 创建核心类库（不引用任何业务代码）
dotnet new classlib -n Cat.Core
dotnet sln add Cat.Core

# 3. 创建应用层（UseCase + DTO）
dotnet new classlib -n Cat.Application
dotnet sln add Cat.Application
dotnet add Cat.Application reference Cat.Core

# 4. 创建领域层（Entity + ValueObject）
dotnet new classlib -n Cat.Domain
dotnet sln add Cat.Domain
dotnet add Cat.Domain reference Cat.Core

# 5. 创建基础设施层（EF Core + 外部服务）
dotnet new classlib -n Cat.Infrastructure
dotnet sln add Cat.Infrastructure
dotnet add Cat.Infrastructure reference Cat.Domain Cat.Core

# 6. 创建表现层（API）
dotnet new webapi -n Cat.Presentation
dotnet sln add Cat.Presentation
dotnet add Cat.Presentation reference Cat.Application Cat.Infrastructure

此时解决方案结构已具备“Cat”骨架。接下来是关键一步： 删除所有默认生成的 Startup.cs / Program.cs 中的冗余代码 。只保留最简启动逻辑：

// Cat.Presentation/Program.cs
var builder = WebApplication.CreateBuilder(args);

// 注册核心服务（仅限契约）
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// 注册 Cat 体系服务
builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();
builder.Services.AddScoped<IInventoryService, StubInventoryService>();
builder.Services.Configure<OrdersOptions>(builder.Configuration.GetSection("Orders"));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

提示：此时 Cat.Application 项目里还没有任何 UseCase，但编译已通过。这就是“契约先行”的力量——接口定义好了，实现可以晚点写，但结构已经稳固。

3.2 实现第一个 UseCase：创建订单（含完整错误处理）

以 CreateOrderUseCase 为例，展示“Cat”风格的完整实现链路：

Step 1：定义请求与响应 DTO（在 Cat.Application.Orders/ 下）

// CreateOrderRequest.cs
public record CreateOrderRequest
{
    public required Guid UserId { get; init; }
    public required List<OrderItemRequest> Items { get; init; } = new();
    public string? CouponCode { get; init; }
}

public record OrderItemRequest
{
    public required Guid ProductId { get; init; }
    public int Quantity { get; init; }
}

// CreateOrderResponse.cs
public record CreateOrderResponse
{
    public required Guid Id { get; init; }
    public required DateTime CreatedAt { get; init; }
    public required decimal TotalAmount { get; init; }
}

Step 2：定义领域实体（在 Cat.Domain.Orders/ 下）

// Order.cs
public class Order : AggregateRoot
{
    public Guid Id { get; private set; }
    public Guid UserId { get; private set; }
    public List<OrderItem> Items { get; private set; } = new();
    public OrderStatus Status { get; private set; } = OrderStatus.Pending;
    public DateTime CreatedAt { get; private set; } = DateTime.UtcNow;

    // 领域逻辑：校验库存、计算总价
    public void Confirm()
    {
        if (Items.All(i => i.Status == ItemStatus.Confirmed))
        {
            Status = OrderStatus.Confirmed;
        }
    }

    public decimal CalculateTotal() => Items.Sum(i => i.UnitPrice * i.Quantity);
}

// OrderItem.cs
public class OrderItem : Entity
{
    public Guid ProductId { get; private set; }
    public int Quantity { get; private set; }
    public decimal UnitPrice { get; private set; }
    public ItemStatus Status { get; private set; } = ItemStatus.Pending;
}

Step 3：实现 UseCase（在 Cat.Application.Orders/ 下）

// CreateOrderUseCase.cs
public class CreateOrderUseCase : IUseCase<CreateOrderRequest, CreateOrderResponse>
{
    private readonly IOrderRepository _orderRepo;
    private readonly IInventoryService _inventorySvc;
    private readonly IOptions<OrdersOptions> _options;
    private readonly ILogger<CreateOrderUseCase> _logger;

    public CreateOrderUseCase(
        IOrderRepository orderRepo,
        IInventoryService inventorySvc,
        IOptions<OrdersOptions> options,
        ILogger<CreateOrderUseCase> logger)
    {
        _orderRepo = orderRepo;
        _inventorySvc = inventorySvc;
        _options = options;
        _logger = logger;
    }

    public async Task<CreateOrderResponse> ExecuteAsync(CreateOrderRequest request, CancellationToken ct)
    {
        // 1. 输入验证（UseCase 自己负责，不依赖 MVC ModelBinding）
        if (request.Items.Count == 0)
            throw new ValidationException("至少需要一个商品");

        if (request.Items.Count > _options.Value.MaxItemsPerOrder)
            throw new ValidationException($"最多允许 {_options.Value.MaxItemsPerOrder} 个商品");

        // 2. 领域对象构建
        var order = new Order
        {
            Id = Guid.NewGuid(),
            UserId = request.UserId,
        };

        foreach (var itemReq in request.Items)
        {
            // 3. 库存预占（外部服务调用）
            var reserved = await _inventorySvc.ReserveStock(itemReq.ProductId, itemReq.Quantity, ct);
            if (!reserved)
                throw new BusinessRuleException($"商品 {itemReq.ProductId} 库存不足");

            order.Items.Add(new OrderItem
            {
                ProductId = itemReq.ProductId,
                Quantity = itemReq.Quantity,
                UnitPrice = await GetProductPriceAsync(itemReq.ProductId, ct) // 假设调用产品服务
            });
        }

        // 4. 持久化
        await _orderRepo.AddAsync(order, ct);

        _logger.LogInformation("订单 {OrderId} 创建成功", order.Id);

        return new CreateOrderResponse
        {
            Id = order.Id,
            CreatedAt = order.CreatedAt,
            TotalAmount = order.CalculateTotal()
        };
    }

    private async Task<decimal> GetProductPriceAsync(Guid productId, CancellationToken ct)
    {
        // 实际调用产品服务，此处简化
        return 99.9m;
    }
}

注意：这里没有 try-catch 包裹所有逻辑，而是让 ValidationException 和 BusinessRuleException 向上冒泡。这是“Cat”体系的错误处理哲学—— 异常即契约 。上层（如 Controller）统一捕获这些特定异常，转换为 HTTP 状态码和友好的错误消息，避免业务逻辑里充斥 if (result.IsSuccess) 判断。

3.3 构建表现层：Minimal API + 统一错误处理

在 Cat.Presentation/Orders/OrderEndpoints.cs 中，用 Minimal API 实现端点：

// OrderEndpoints.cs
public static class OrderEndpoints
{
    public static void MapOrderEndpoints(this IEndpointRouteBuilder endpoints)
    {
        var group = endpoints.MapGroup("/api/orders").WithTags("Orders");

        group.MapPost("/", async (HttpContext ctx, 
            [FromBody] CreateOrderRequest request,
            IUseCase<CreateOrderRequest, CreateOrderResponse> useCase) =>
        {
            try
            {
                var response = await useCase.ExecuteAsync(request, ctx.RequestAborted);
                return Results.Ok(response);
            }
            catch (ValidationException ex)
            {
                return Results.BadRequest(new ProblemDetails
                {
                    Title = "参数验证失败",
                    Detail = ex.Message,
                    Status = StatusCodes.Status400BadRequest
                });
            }
            catch (BusinessRuleException ex)
            {
                return Results.Conflict(new ProblemDetails
                {
                    Title = "业务规则冲突",
                    Detail = ex.Message,
                    Status = StatusCodes.Status409Conflict
                });
            }
            catch (Exception ex)
            {
                // 记录日志，返回通用错误
                ctx.RequestServices.GetRequiredService<ILogger<OrderEndpoints>>()
                    .LogError(ex, "创建订单时发生未预期错误");
                return Results.StatusCode(StatusCodes.Status500InternalServerError);
            }
        });
    }
}

并在 Program.cs 中注册：

// Program.cs
app.MapOrderEndpoints(); // 调用扩展方法

这套错误处理机制的好处是：

Controller 极简 ：没有一行业务逻辑，全是路由和异常转换；
可测试性高 ： MapOrderEndpoints 方法本身可单元测试，验证不同异常是否映射到正确状态码；
前端友好 ：返回的 ProblemDetails 是 RFC 7807 标准，前端可统一解析 title 和 detail 展示提示。

3.4 编写单元测试：用 InMemory 仓库跑通全流程

在 Cat.Tests/ 项目中，为 CreateOrderUseCase 编写测试：

// CreateOrderUseCaseTests.cs
public class CreateOrderUseCaseTests
{
    [Fact]
    public async Task Should_Create_Order_With_Single_Item()
    {
        // Arrange
        var repo = new InMemoryOrderRepository();
        var inventorySvc = new StubInventoryService(); // 总是返回 true
        var options = Options.Create(new OrdersOptions { MaxItemsPerOrder = 10 });
        var logger = new TestLogger<CreateOrderUseCase>();

        var useCase = new CreateOrderUseCase(repo, inventorySvc, options, logger);

        var request = new CreateOrderRequest
        {
            UserId = Guid.NewGuid(),
            Items = new List<OrderItemRequest>
            {
                new() { ProductId = Guid.NewGuid(), Quantity = 1 }
            }
        };

        // Act
        var response = await useCase.ExecuteAsync(request);

        // Assert
        Assert.NotNull(response.Id);
        Assert.Equal(1, await repo.CountAsync());
        var savedOrder = await repo.GetByIdAsync(response.Id);
        Assert.NotNull(savedOrder);
        Assert.Equal(1, savedOrder.Items.Count);
    }

    [Fact]
    public async Task Should_Throw_ValidationException_When_No_Items()
    {
        // Arrange
        var useCase = CreateUseCase(); // 工厂方法，复用 setup
        var request = new CreateOrderRequest { UserId = Guid.NewGuid() };

        // Act & Assert
        var ex = await Assert.ThrowsAsync<ValidationException>(() => 
            useCase.ExecuteAsync(request));
        Assert.Equal("至少需要一个商品", ex.Message);
    }
}

实操心得：我们为每个 I*Repository 都提供了 InMemory*Repository ，并封装了 TestLogger<T> （一个不输出日志、只记录日志级别的内存 Logger），确保测试不依赖任何外部系统。一个典型的 UseCase 测试，从 Arrange 到 Assert 平均耗时 8–12ms，整个测试项目 200+ 用例可在 3 秒内跑完。

3.5 CI/CD 集成：用 GitHub Actions 实现自动化验证

在 .github/workflows/dotnet.yml 中，加入“Cat”专属检查：

name: Cat Build & Test

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '7.0.x'

    - name: Restore dependencies
      run: dotnet restore

    - name: Build
      run: dotnet build --no-restore

    - name: Run unit tests
      run: dotnet test --no-build --verbosity normal

    - name: Validate Configuration Contracts
      run: |
        dotnet tool install -g Cat.ConfigValidator
        dotnet cat-config-validate --project Cat.Presentation/Cat.Presentation.csproj

Cat.ConfigValidator 是我们自研的 CLI 工具，它会：

扫描项目中所有 IConfigureOptions<T> 注册；
解析 appsettings.*.json 中的所有 Section；
对比两者，输出缺失配置项报告；
若存在未绑定的 Section，则视为警告（允许存在，但需人工确认）。

这个检查在 PR 提交时自动触发，确保每次合并都不会带入配置漂移。

4. 常见问题与排查技巧实录：那些踩过的坑，现在都成了 checklist

4.1 “UseCase 里调用另一个 UseCase？是不是违反了单一职责？”

这是初学者最常问的问题。答案是： 不推荐，但不禁止；关键看调用动机 。

❌ 错误场景 ： CreateOrderUseCase 直接 new SendEmailUseCase() 发送订单确认邮件。
问题：邮件发送是副作用，不应阻塞主流程；且 SendEmailUseCase 的失败会导致订单创建失败，违背“订单创建成功即终态”的业务语义。
✅ 正确场景 ： CreateOrderUseCase 执行成功后，发布 OrderCreatedDomainEvent ，由独立的 OrderCreatedEventHandler 处理邮件发送。
但如果你的项目规模小、无事件总线，也可以接受 CreateOrderUseCase 内部调用 IEmailService.SendAsync(...) —— 因为 IEmailService 是领域服务接口，其具体实现（如 SmtpEmailSender ）已在基础设施层解耦。

我的实操原则：UseCase 之间绝不直接调用；UseCase 可以调用领域服务（ I*Service ），领域服务再调用基础设施。这样既保证了 UseCase 的纯净，又避免了过度分层。

4.2 “领域模型里放业务逻辑，但 EF Core 的导航属性加载太慢，怎么办？”

典型矛盾： Order 实体需要 Items 导航属性来计算总价，但 Include(o => o.Items) 会 N+1 查询； Select 投影又破坏了领域模型的完整性。

“Cat”体系的解法是： 领域模型只负责逻辑，数据获取交给仓储 。

// IOrderRepository.cs
public interface IOrderRepository
{
    Task<Order> GetByIdWithItemsAsync(Guid id, CancellationToken ct);
    Task AddAsync(Order order, CancellationToken ct);
}

// EfOrderRepository.cs
public class EfOrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public async Task<Order> GetByIdWithItemsAsync(Guid id, CancellationToken ct)
    {
        return await _context.Orders
            .Include(o => o.Items) // 显式加载
            .FirstOrDefaultAsync(o => o.Id == id, ct);
    }
}

UseCase 中直接调用 GetByIdWithItemsAsync ，拿到完整的 Order 对象后再调用 order.CalculateTotal() 。这样：

领域模型保持纯粹，不耦合 ORM；
数据获取策略（Eager Load vs Explicit Load）由仓储实现决定，UseCase 无感知；
性能问题集中在仓储层优化，不影响业务逻辑。

我们曾用此方式将一个报表页面的查询耗时从 2.3s 降至 380ms——通过在仓储中改用 AsNoTracking() 和 Select 投影，UseCase 代码一行未改。

4.3 “配置项越来越多，appsettings.json 膨胀，怎么管理？”

当 appsettings.json 超过 500 行，维护就成了噩梦。“Cat”体系的实践是： 按环境拆分 + 按模块拆分 + 使用 JSON 引用 。

// appsettings.json
{
  "Logging": { ... },
  "Serilog": { ... },
  "Orders": {
    "$ref": "orders.options.json"
  },
  "Users": {
    "$ref": "users.options.json"
  }
}

// orders.options.json
{
  "MaxItemsPerOrder": 200,
  "ReservationTimeout": "00:15:00"
}

.NET 本身不支持 $ref ，但我们用一个简单的 MSBuild Target 在构建时自动合并：

<!-- 在 Cat.Presentation.csproj 中 -->
<Target Name="MergeConfigFiles" BeforeTargets="Build">
  <Exec Command="dotnet tool install -g Cat.ConfigMerger" />
  <Exec Command="dotnet cat-config-merge --input $(MSBuildThisFileDirectory)appsettings.json --output $(MSBuildThisFileDirectory)appsettings.merged.json" />
</Target>

Cat.ConfigMerger 工具会递归解析 $ref ，生成最终的 appsettings.merged.json ，并在 Program.cs 中加载它。这样，每个模块的配置完全独立，新人只需关注 orders.options.json ，无需在千行配置中大海捞针。

4.4 “测试覆盖率怎么算？是不是要追求 100%？”

“Cat”体系不设覆盖率硬指标，但有明确的 测试分层指南 ：

层级	目标覆盖率	测试重点	示例
UseCase	≥ 95%	主路径 + 所有异常分支	`CreateOrderUseCase` 的成功创建、库存不足、参数为空等
领域模型	≥ 80%	核心领域逻辑	`Order.Confirm()` 的状态流转、 `CalculateTotal()` 的精度计算
仓储实现	≥ 70%	CRUD 边界条件	`EfOrderRepository.AddAsync` 的并发插入、 `GetByIdAsync` 的 null 处理
表现层	≥ 50%	端点路由 + 异常映射	`OrderEndpoints` 的 200/400/409 状态码验证

关键原则： 不测胶水代码 。比如 Program.cs 中的 builder.Services.Add... 注册语句，不写测试； MapOrderEndpoints 中的 group.MapPost 路由声明，也不测——因为它们是声明式代码，错误会在编译或启动时立即暴露，无需运行时测试。

我们用 dotnet test --collect:"XPlat Code Coverage" 生成报告，但团队晨会只看“UseCase 层覆盖率下降趋势”，不纠结单个数字。有一次， CreateOrderUseCase 覆盖率从 96% 降到 92%，我们立刻回溯，发现是新增了一个 if (coupon.IsValid()) 分支但没写对应测试，当天就补上了——这才是覆盖率该起的作用。