Cat in dotNET：面向.NET开发者的轻量工程实践方法论

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

“Cat in dotNET”——看到这个标题，很多刚接触的开发者第一反应是：“这是个宠物识别AI项目？还是某个用猫图做UI皮肤的玩具库？”其实都不是。我在一线带团队、做架构评审、帮客户做技术选型的十年里，见过太多团队在 .NET 生态中踩坑：有人把 ASP.NET Core Web API 当成“万能胶”硬塞进高并发物联网网关；有人用 Entity Framework Core 直接查百万级订单表却没加任何查询拦截和缓存策略；还有人把 .NET 8 的 AOT 编译当成“一键加速按钮”，结果编译失败十几次后直接放弃。而“Cat in dotNET”正是我从这些真实战场中提炼出的一套 轻量、可验证、有呼吸感的 .NET 工程实践方法论 ——它不追求“全栈覆盖”，也不堆砌最新特性，而是像养猫一样，强调 边界感、响应性、可观察性与适度干预 。核心关键词是： dotNET、Cat、工程实践、轻量架构、可验证性 。它适合三类人：刚从 .NET Framework 迁移过来、对 Core/5/6/7/8 版本演进感到混乱的中年开发者；带 3–5 人小团队、需要快速交付又怕后期失控的技术负责人；以及正在准备高级 .NET 面试、想展示“不止会写代码”的求职者。它不是框架，不是 SDK，更不是开源项目名，而是一组经过 27 个真实生产项目反复锤炼的 设计约束集（Design Constraints）与配套验证脚手架 。比如，“猫不主动扑人”对应“API 不主动推送数据，所有通信必须由客户端发起并携带明确上下文”；“猫会自己舔毛”对应“每个微服务必须内置健康检查、指标采集与日志结构化能力，不依赖外部注入”；“猫只在固定猫砂盆排泄”对应“所有异常必须归一为 IResult 或 ProblemDetails 格式，禁止裸 throw Exception”。这套体系的名字之所以叫“Cat”，是因为它拒绝“狗式服从”（dogma-driven development）——不强制你用某套 DDD 模板、不规定你必须分六层、不推销某种 ORM 哲学，而是给你一套“猫科动物行为守则”，让你在 .NET 的广阔草原上，既保持野性，又不迷失方向。

2. 内容整体设计与思路拆解：为什么是“猫”，而不是“狼”或“鹰”？

2.1 “Cat”不是拟人化修辞，而是工程隐喻的精准锚点

很多人误以为“Cat in dotNET”是个营销噱头，但实际设计时，每一个“猫行为”都严格映射到一个可落地的技术约束。我们先看三个典型对比：

• 狼（Wolf）隐喻 ：强调群体协作、层级指挥、统一战线。这对应的是传统企业级 SOA 架构——ESB 中心化路由、统一认证网关、强契约的 WCF 服务。但现实是，.NET 生态早已转向去中心化：gRPC 双向流、Minimal APIs 的极简路由、OpenTelemetry 的分布式追踪。狼群模式在云原生时代反而成了性能瓶颈和故障放大器。我曾帮一家保险科技公司重构理赔系统，他们坚持用“狼式”架构——所有服务必须通过中央 API 网关鉴权、限流、日志，结果单点网关在大促期间 CPU 持续 98%，排查三天才发现是网关自身 JSON 解析逻辑存在反序列化漏洞。而“猫式”方案直接让每个服务自带 JWT 验证中间件 + 本地速率限制（基于 MemoryCache 实现），网关退化为纯 DNS 路由器，故障率下降 76%。

• 鹰（Eagle）隐喻 ：强调高空俯瞰、全局掌控、抽象建模。这对应的是过度设计的 DDD 战术模式——动辄划分 12 个限界上下文、为每个实体配 Value Object 和 Domain Service。但在中小项目中，这种抽象成本远超收益。我们做过统计：在 15 个平均 3 人团队维护的内部系统中，采用“鹰式 DDD”的项目，需求变更平均响应时间比“猫式”长 4.2 倍，因为每次改一个字段都要穿越 ApplicationService → DomainService → AggregateRoot → Entity 多层封装。而“猫式”只要求： 领域模型必须能被单元测试 100% 覆盖，且所有业务规则必须显式写在模型方法内（不允许在 Controller 或 Repository 中写 if-else 业务逻辑） 。一句话：你可以用一个 class，但这个 class 必须自洽、可测、无副作用。

• 猫（Cat）隐喻 ：强调个体主权、环境适应、低侵入响应。这正是 .NET 8+ 的核心气质：AOT 编译让你控制二进制输出，Source Generators 让你在编译期生成代码而非运行时反射，Minimal Hosting Model 剥离了 Startup.cs 的仪式感。我们设计“Cat”体系时，所有约束都遵循“最小必要原则”。例如，“猫只喝干净水”对应“所有配置必须来自 IConfiguration，且禁止在代码中硬编码 ConnectionString 或 Secret”；“猫会抓老鼠但不杀鸡”对应“Repository 层可以调用 Dapper 执行复杂查询，但绝不允许在仓储方法中调用 HttpClient 或发邮件”——边界清晰，责任单一。

提示：不要试图把“Cat”当成新框架去学。它是一张检查清单，是你每次写完一个 Controller Action、定义一个 DTO、配置一个中间件时，心里默念的三句话：“它是否尊重了猫的边界？它是否具备猫的自检能力？它是否留下了猫的爪印（可观测痕迹）？”

2.2 为什么选择 .NET 作为唯一载体？跨平台不是伪命题

有人问：“Java 也有 Spring Boot Actuator，Go 也有 Prometheus Client，为什么非得绑定 .NET？”这个问题直击本质。答案是： .NET 的类型系统、编译期元数据与运行时反射能力，在‘约束即代码’这件事上，拥有不可替代的精度优势 。举个具体例子：在“Cat”体系中，我们要求“所有 HTTP 接口必须声明其幂等性语义”。在 Java/Spring 中，你只能靠 @Idempotent 注解 + AOP 切面拦截，但切面无法保证开发者一定在方法上加了注解，也无法在编译期报错。而在 .NET 中，我们用 Source Generator 实现：当编译器扫描到 [HttpPost] 方法时，自动检查其是否标注 [Idempotent] 或 [NonIdempotent]，如果未标注，则生成编译错误 CS9999：“HTTP POST 方法必须显式声明幂等性语义”。这个能力，源于 C# 9+ 的源生成器与 Roslyn 编译器深度集成——它不是运行时魔法，而是编译期铁律。同样，我们用 Analyzer 强制“所有 DTO 必须实现 IValidatableObject”，用 .NET 8 的 AOT 兼容性检查确保“所有泛型约束必须支持 NativeAOT”。这些不是“最佳实践建议”，而是编译器强制执行的契约。其他语言生态要么靠文档约定（易失效），要么靠运行时代理（有性能损耗），唯独 .NET 能把工程纪律刻进编译流水线。这也是为什么“Cat in dotNET”不叫“Cat in Backend”——它的根，深扎在 .NET 的编译模型与类型哲学里。

2.3 整体架构分层：四层“猫科解剖图”，拒绝“洋葱”或“六边形”幻觉

“Cat in dotNET”不画标准分层图，而是按猫的生理结构划分四层，每层有明确职责与禁令：

• 表皮层（Skin Layer） ：对应 Minimal Hosting Model 下的 Program.cs。只允许三件事：注册服务（builder.Services.AddXXX）、配置中间件（app.UseXXX）、设置终结点（app.MapXXX）。禁令：禁止在此层写任何业务逻辑、禁止调用 await、禁止 new 任何业务对象。理由：表皮是猫与外界接触的第一道屏障，必须薄、透、快。我见过最离谱的案例是某团队在 Program.cs 里写了一段 async Task 初始化 Redis 连接池的代码，结果应用启动耗时从 800ms 暴涨到 12s，因为 .NET 默认 Host 启动是同步阻塞的，async 方法被包装成 Task.Run 导致线程饥饿。

• 肌肉层（Muscle Layer） ：对应 Application Services 与 Domain Models。这是唯一允许包含业务逻辑的地方。所有 UseCase 必须封装为独立类（如 CreateOrderService），且构造函数参数必须全部为接口（IOrderRepository, IPaymentGateway）。禁令：禁止此层引用 Microsoft.AspNetCore.* 命名空间（即不能依赖 HTTP 相关类型），禁止访问 HttpContext。理由：肌肉决定猫的行动力，但肌肉不负责感知世界——感知交给表皮层，决策交给神经层。

• 神经层（Nerve Layer） ：对应 MediatR 请求管道与 CQRS 模式。所有跨用例协调（如“下单成功后发短信+扣库存+更新推荐”）必须通过 INotification 发布，由独立 Handler 处理。禁令：Handler 中禁止抛出业务异常（只能 throw new InvalidOperationException），所有业务校验失败必须返回 Result 。理由：神经传递信号，但不参与判断对错——判断是肌肉的事，神经只负责广播。

• 骨骼层（Bone Layer） ：对应 Infrastructure 实现，包括 EF Core DbContext、Dapper Repository、第三方 SDK 封装。禁令：此层代码不得包含任何 if-else 业务分支，所有 SQL 查询必须预编译（EF Core 的 CompiledQuery 或 Dapper 的 SqlMapper.AddTypeMap），所有外部调用必须包裹重试策略（Polly）与熔断器（CircuitBreaker）。理由：骨骼支撑身体，但不思考——它只提供稳定、可预测的物理支撑。

这四层不是垂直堆叠，而是像猫的脊柱一样贯穿始终：一个 HTTP 请求进来，表皮层接收（MapPost），神经层分发（Send ），肌肉层执行（CreateOrderService.Handle），骨骼层落实（OrderRepository.Create）。每一层都像猫的某个器官，各司其职，互不越界。

3. 核心细节解析与实操要点：从“猫砂盆”到“猫抓板”的完整配置

3.1 “猫砂盆”：统一异常处理与问题响应的底层协议

在“Cat in dotNET”中，“猫砂盆”指代整个系统的错误归一化机制。它不是简单的 try-catch 全局过滤器，而是一套编译期+运行时双保险的响应协议。核心目标： 让每个 HTTP 错误响应，都像猫在固定位置排泄一样可预测、可审计、可追溯 。

首先，定义基础响应契约：

public record ProblemDetailsResponse(
    string Type,
    string Title,
    int Status,
    string Detail,
    string Instance,
    Dictionary<string, string[]>? Errors = null);

注意：这里不用 ASP.NET Core 内置的 ProblemDetails 类，而是自定义 record。原因有三：一是内置类有无参构造函数，容易被反序列化攻击；二是它继承自 Object，无法强制泛型约束；三是 record 的不可变性天然契合“错误不可篡改”原则。我们用 Source Generator 在编译期检查：所有返回 ProblemDetailsResponse 的 Action，其 StatusCode 必须与 Status 字段值一致（如 return Results.Problem(...) 时，Status 必须等于 500）。

其次，实现“砂盆守卫”中间件：

public class CatLitterBoxMiddleware
{
    private readonly RequestDelegate _next;
    
    public CatLitterBoxMiddleware(RequestDelegate next) => _next = next;

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
            
            // 检查 4xx/5xx 响应是否已按协议格式化
            if (context.Response.StatusCode >= 400 && 
                !context.Response.HasStarted &&
                context.Response.ContentType?.Contains("application/problem+json") == true)
            {
                // 已合规，放行
                return;
            }
        }
        catch (Exception ex)
        {
            // 统一捕获未处理异常
            var problem = ex switch
            {
                ValidationException v => ToValidationProblem(v),
                BusinessException b => ToBusinessProblem(b),
                _ => ToUnknownProblem(ex)
            };
            
            context.Response.StatusCode = problem.Status;
            context.Response.ContentType = "application/problem+json";
            await JsonSerializer.SerializeAsync(context.Response.Body, problem);
            return;
        }

        // 对于非 Problem 响应的 4xx/5xx，强制重写
        if (context.Response.StatusCode >= 400 && !context.Response.HasStarted)
        {
            var fallback = new ProblemDetailsResponse(
                "https://catindotnet.dev/errors/fallback",
                "Unexpected Error",
                context.Response.StatusCode,
                "An error occurred. Please check logs.",
                context.TraceIdentifier);
            
            context.Response.StatusCode = fallback.Status;
            context.Response.ContentType = "application/problem+json";
            await JsonSerializer.SerializeAsync(context.Response.Body, fallback);
        }
    }
}

关键细节在于 context.Response.HasStarted 的判断——这是防止“猫在半路乱拉”的关键。ASP.NET Core 的响应流一旦开始写入（Headers 已发送），就无法再修改 StatusCode 或 Body。我们通过这个检查，确保所有错误都在响应真正发出前完成格式化。

注意：这个中间件必须注册在 app.UseRouting() 之后、 app.UseEndpoints() 之前，且绝对不能放在 UseExceptionHandler 之后——因为后者会吞掉原始异常堆栈。我们宁可多一层中间件，也要保留原始异常的完整 CallStack。

最后，配套的“砂盆清洁工”——日志结构化。我们禁用所有 Console.WriteLine，强制使用 ILogger ，并通过 Serilog 配置：

Log.Logger = new LoggerConfiguration()
    .Enrich.FromLogContext()
    .Enrich.WithProperty("Application", "CatInDotNet")
    .WriteTo.Console(outputTemplate: 
        "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}")
    .CreateLogger();

重点是 {Properties:j} ——它将所有日志属性（如 OrderId、UserId）以 JSON 格式输出，方便 ELK 或 Grafana 直接解析。一次线上支付失败，运维同事只需在 Kibana 输入 Properties.OrderId: "ORD-2024-XXXX" ，就能秒级定位到完整链路日志，无需翻十几份不同格式的日志文件。

3.2 “猫抓板”：领域事件发布与最终一致性的轻量实现

“猫抓板”解决的是分布式事务难题。在“Cat in dotNET”中，我们彻底放弃 Saga 模式和两阶段提交（2PC），转而拥抱“事件溯源 + 最终一致性”——但做了关键简化： 不存储事件流，不重建状态，只用事件作通知信使 。

核心组件只有两个：

• EventPublisher ：一个轻量接口，只定义 PublishAsync<TEvent>(TEvent @event) 方法。
• EventSubscriber ：一个抽象基类，定义 HandleAsync(TEvent @event) 抽象方法。

实现上，我们默认使用 Redis Streams（非 Pub/Sub）作为事件总线。为什么选 Redis Streams？因为它天然支持：

• 消息持久化（猫抓过的痕迹不会消失）
• 消费组（Consumer Group）实现多实例负载均衡（多只猫共享一块抓板）
• Pending List 追踪未确认消息（防止猫抓完忘记埋）

具体代码：

public class RedisEventPublisher : IEventPublisher
{
    private readonly IConnectionMultiplexer _redis;
    private readonly ILogger<RedisEventPublisher> _logger;

    public RedisEventPublisher(IConnectionMultiplexer redis, ILogger<RedisEventPublisher> logger)
    {
        _redis = redis;
        _logger = logger;
    }

    public async Task PublishAsync<TEvent>(TEvent @event) where TEvent : class
    {
        var db = _redis.GetDatabase();
        var streamKey = $"event:{typeof(TEvent).Name}";
        
        // 序列化事件（用 System.Text.Json，避免 Newtonsoft.Json 的循环引用陷阱）
        var json = JsonSerializer.Serialize(@event, new JsonSerializerOptions 
        { 
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase 
        });
        
        // 写入 Redis Stream，ID 设为 * 表示自动生成
        await db.StreamAddAsync(streamKey, "data", json);
        
        _logger.LogInformation("Published event {@Event}", @event);
    }
}

// 订阅端：后台服务监听
public class OrderCreatedSubscriber : BackgroundService
{
    private readonly IConnectionMultiplexer _redis;
    private readonly IServiceProvider _serviceProvider;
    private readonly ILogger<OrderCreatedSubscriber> _logger;

    public OrderCreatedSubscriber(IConnectionMultiplexer redis, 
        IServiceProvider serviceProvider, 
        ILogger<OrderCreatedSubscriber> logger)
    {
        _redis = redis;
        _serviceProvider = serviceProvider;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var db = _redis.GetDatabase();
        var streamKey = "event:OrderCreated";
        var groupName = "order-processor";
        var consumerName = $"consumer-{Environment.MachineName}";

        // 创建消费者组（仅首次执行）
        try
        {
            await db.StreamCreateConsumerGroupAsync(streamKey, groupName, "$");
        }
        catch (RedisServerException ex) when (ex.Message.Contains("BUSYGROUP"))
        {
            // 组已存在，忽略
        }

        while (!stoppingToken.IsCancellationRequested)
        {
            // 从消费者组读取最多 1 条消息
            var messages = await db.StreamReadGroupAsync(
                streamKey, 
                groupName, 
                consumerName, 
                count: 1, 
                noAck: false); // noAck=false 表示需手动确认

            foreach (var msg in messages)
            {
                try
                {
                    var json = msg["data"].ToString();
                    var @event = JsonSerializer.Deserialize<OrderCreated>(json);
                    
                    using var scope = _serviceProvider.CreateScope();
                    var handler = scope.ServiceProvider.GetRequiredService<IEventHandler<OrderCreated>>();
                    await handler.HandleAsync(@event);

                    // 处理成功，确认消息
                    await db.StreamAcknowledgeAsync(streamKey, groupName, msg.Id);
                }
                catch (Exception ex)
                {
                    _logger.LogError(ex, "Failed to process event {@Event}", msg);
                    // 失败不确认，消息会留在 Pending List，稍后重试
                }
            }

            await Task.Delay(100, stoppingToken); // 避免空轮询
        }
    }
}

这个实现的关键“猫式”设计点：

• 不保证一次处理 ：Redis Streams 的 Pending List 机制天然支持失败重试，但重试次数无上限——这符合猫的习性：抓不成功就再抓，直到满意为止。我们不设“最大重试 3 次”这种武断规则，而是靠监控告警（如 Pending List 长度 > 1000 时触发 PagerDuty）来人工介入。
• 事件即事实 ：OrderCreated 事件只包含 OrderId , CustomerId , TotalAmount 等不可变字段，不包含任何计算逻辑（如“折扣后金额”）。计算留给订阅方根据当前上下文实时算——这保证了最终一致性，也避免了事件版本升级的噩梦。
• 零依赖框架 ：整个事件总线不依赖 MassTransit、NServiceBus 等重型框架，仅用 StackExchange.Redis 一个 NuGet 包。部署时，你只需要一个 Redis 实例，无需额外安装 RabbitMQ 或 Kafka 集群。

实操心得：上线前务必做“断网测试”。我们曾在一个电商项目中，故意拔掉 Redis 服务器网线，观察应用行为——预期是事件发布失败，但应用必须继续接受用户下单（因为 Publisher 是 fire-and-forget 模式）。结果发现有个开发在 PublishAsync 里写了 await db.StreamAddAsync(...).ConfigureAwait(false) 却没包 try-catch，导致主线程卡死。后来我们强制规定：所有 Publisher 方法必须返回 ValueTask ，且内部异常必须吞掉并记录 Warn 日志，绝不能影响主流程。

3.3 “猫耳”：可观察性三件套的极简集成

“猫耳”代表系统的感知能力——不是堆砌 Grafana + Prometheus + Jaeger 的豪华套装，而是用 .NET 原生能力实现的“三件套”： 健康检查、指标采集、分布式追踪 。每一件都遵循“最小侵入”原则。

健康检查（Health Check） ：
我们不用 AddHealthChecks() 的默认内存检查，而是强制每个服务实现 ICatHealthCheck 接口：

public interface ICatHealthCheck
{
    string Name { get; }
    Task<(bool IsHealthy, string? Description)> CheckAsync(CancellationToken cancellationToken);
}

// 示例：数据库健康检查
public class SqlServerHealthCheck : ICatHealthCheck
{
    private readonly IDbConnection _connection;

    public SqlServerHealthCheck(IDbConnection connection) => _connection = connection;

    public string Name => "sql-server";

    public async Task<(bool IsHealthy, string? Description)> CheckAsync(CancellationToken cancellationToken)
    {
        try
        {
            await _connection.ExecuteScalarAsync("SELECT 1", cancellationToken);
            return (true, null);
        }
        catch (Exception ex)
        {
            return (false, $"Connection failed: {ex.Message}");
        }
    }
}

注册时，用反射自动扫描程序集中所有 ICatHealthCheck 实现：

// 在 Program.cs 中
builder.Services.Scan(scan => scan
    .FromAssembliesOf(typeof(ICatHealthCheck))
    .AddClasses(classes => classes.AssignableTo<ICatHealthCheck>())
    .AsImplementedInterfaces()
    .WithScopedLifetime());

这样，新增一个健康检查，只需写一个类，无需手动调用 AddCheck ——猫自己会竖起耳朵听。

指标采集（Metrics） ：
放弃 Prometheus 的 pull 模型，采用 OpenTelemetry 的 push 模型，但只启用最核心的三个指标：

• http.server.request.duration （HTTP 请求耗时直方图）
• process.runtime.dotnet.gc.heap.size （GC 堆大小）
• system.memory.usage （系统内存占用）

配置代码精简到 10 行：

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddRuntimeInstrumentation()
        .AddOtlpExporter(opt => opt.Endpoint = new Uri("http://otel-collector:4318/v1/metrics")));

关键技巧：我们禁用所有 AddHttpClientInstrumentation() ，因为 .NET 8 的 HttpClient 默认已集成 OpenTelemetry，手动添加会导致重复采样。这个细节，是我在调试一个内存泄漏问题时，通过 dotMemory 抓取 GC Root 才发现的——重复 Instrumentation 会创建大量 Activity 对象，长期驻留内存。

分布式追踪（Tracing） ：
不追求全链路 100% 覆盖，而是聚焦“黄金路径”：从 HTTP 入口到数据库查询。我们用 ActivitySource 手动创建关键 Span：

public class OrderService
{
    private static readonly ActivitySource Source = new("CatInDotNet.Order");

    public async Task<Order> CreateOrderAsync(CreateOrderRequest request)
    {
        using var activity = Source.StartActivity("CreateOrder", ActivityKind.Server);
        activity?.SetTag("order.amount", request.TotalAmount);
        activity?.SetTag("customer.id", request.CustomerId);

        // ... 业务逻辑

        using var dbActivity = Source.StartActivity("SaveToDatabase", ActivityKind.Client);
        dbActivity?.SetTag("db.statement", "INSERT INTO Orders ...");
        await _repository.CreateAsync(order);
        dbActivity?.Stop();

        return order;
    }
}

注意： ActivitySource 必须是 static readonly，否则会因频繁创建导致内存碎片。这个教训，是我用 dotMemory 分析一个高并发服务时，发现 40% 的内存分配来自 ActivitySource 构造函数，才痛定思痛改掉的。

4. 实操过程与核心环节实现：从零搭建一个“猫系”订单服务

4.1 初始化项目：Minimal Hosting 的正确打开方式

我们不用 dotnet new webapi ，而是从最干净的 dotnet new web 开始，手动组装“猫系”骨架。原因：WebAPI 模板自带 Controllers、Startup.cs 兼容层等冗余代码，违背“猫的简洁性”。

步骤详解：

1. 创建项目 ：

   dotnet new web -n CatOrderService --framework net8.0
   cd CatOrderService
   

2. 添加核心 NuGet 包 （严格限定，不多不少）：

   dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 8.0.4
   dotnet add package Microsoft.EntityFrameworkCore.Tools --version 8.0.4
   dotnet add package Serilog.AspNetCore --version 8.0.1
   dotnet add package StackExchange.Redis --version 7.3.1
   dotnet add package MediatR --version 12.2.0
   dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks.Redis --version 8.0.4
   

   注意：所有包版本必须与 .NET 8.0 主版本对齐。我们曾因混用 EF Core 7.x 和 .NET 8，导致 AOT 编译时出现 System.NotSupportedException: Dynamic code generation is not supported 错误，排查两天才发现是包版本不匹配。

3. Program.cs 的“猫式”初始化 （共 37 行，无业务逻辑）：

   var builder = WebApplication.CreateBuilder(args);
   
   // 【表皮层】注册服务
   builder.Services.AddControllers();
   builder.Services.AddEndpointsApiExplorer();
   builder.Services.AddSwaggerGen();
   
   // 【骨骼层】基础设施
   builder.Services.AddDbContext<OrderDbContext>(opt => 
       opt.UseSqlServer(builder.Configuration.GetConnectionString("Default")));
   
   builder.Services.AddSingleton<IRedisConnection, RedisConnection>();
   builder.Services.AddScoped<IOrderRepository, OrderRepository>();
   
   // 【神经层】MediatR
   builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));
   
   // 【肌肉层】应用服务
   builder.Services.AddScoped<CreateOrderService>();
   builder.Services.AddScoped<GetOrderService>();
   
   // 【猫耳】可观察性
   builder.Host.UseSerilog((ctx, lc) => lc
       .WriteTo.Console()
       .ReadFrom.Configuration(ctx.Configuration));
   
   var app = builder.Build();
   
   // 【表皮层】配置中间件
   if (app.Environment.IsDevelopment())
   {
       app.UseSwagger();
       app.UseSwaggerUI();
   }
   
   app.UseHttpsRedirection();
   app.UseAuthorization();
   app.MapControllers();
   
   // 【猫砂盆】异常守卫必须在此处注册
   app.UseMiddleware<CatLitterBoxMiddleware>();
   
   app.Run();
   

   关键点： AddControllers() 后立即 MapControllers() ，不加任何 .ConfigureServices() 的扩展方法——那些方法往往偷偷注入了你不想要的服务（如 AddMvcCore() 会注入 ViewEngine，而我们是纯 API 服务）。

4.2 领域模型设计：用 record 和 init-only 实现“猫的纯粹性”

订单领域模型，拒绝贫血模型，也拒绝过度封装。我们只用 C# 12 的 record 和 init 修饰符：

public record Order(
    Guid Id,
    Guid CustomerId,
    decimal TotalAmount,
    OrderStatus Status,
    DateTime CreatedAt,
    IReadOnlyList<OrderItem> Items)
{
    public Order WithStatus(OrderStatus newStatus) => this with { Status = newStatus };
    public Order WithItems(IReadOnlyList<OrderItem> newItems) => this with { Items = newItems };
}

public record OrderItem(
    string ProductCode,
    int Quantity,
    decimal UnitPrice)
{
    public decimal TotalPrice => Quantity * UnitPrice;
}

public enum OrderStatus
{
    Draft = 0,
    Confirmed = 1,
    Shipped = 2,
    Completed = 3,
    Cancelled = 4
}

为什么用 record ？因为：

• with 表达式天然支持状态转换（Draft → Confirmed），无需写 Builder 模式；
• ToString() 自动生成结构化字符串，方便日志输出；
• 编译器保证 Equals() 和 GetHashCode() 正确性，避免手写 bug。

为什么用 init ？我们在构造函数中加入业务规则：

public record Order(
    Guid Id,
    Guid CustomerId,
    decimal TotalAmount,
    OrderStatus Status,
    DateTime CreatedAt,
    IReadOnlyList<OrderItem> Items)
{
    public Order
    (
        Guid id,
        Guid customerId,
        decimal totalAmount,
        OrderStatus status,
        DateTime createdAt,
        IReadOnlyList<OrderItem> items
    )
    {
        // 【猫的爪印】在构造时留下验证痕迹
        if (totalAmount <= 0) throw new ArgumentException("TotalAmount must be greater than zero.");
        if (!items.Any()) throw new ArgumentException("Order must contain at least one item.");
        if (items.Any(i => i.Quantity <= 0)) throw new ArgumentException("All items must have positive quantity.");

        Id = id;
        CustomerId = customerId;
        TotalAmount = totalAmount;
        Status = status;
        CreatedAt = createdAt;
        Items = items;
    }
}

这个构造函数会在 new Order(...) 时立即执行，而不是等到 Controller 的 [FromBody] 绑定后。它把验证提前到对象创建瞬间，符合“猫只在安全环境进食”的原则——错误数据，绝不让它进入内存。

4.3 创建订单用例：从 Controller 到 Repository 的全链路

Controller 层（肌肉层入口）：

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IMediator _mediator;

    public OrdersController(IMediator mediator) => _mediator = mediator;

    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<Order>> CreateOrder([FromBody] CreateOrderRequest request)
    {
        // 【猫砂盆】此处不处理异常，交给中间件
        var result = await _mediator.Send(new CreateOrderCommand(request));
        return CreatedAtAction(nameof(GetOrder), new { id = result.Id }, result);
    }

    [HttpGet("{id:guid}")]
    public async Task<ActionResult<Order>> GetOrder(Guid id)
    {
        var result = await _mediator.Send(new GetOrderQuery(id));
        return result is null ? NotFound() : Ok(result);
    }
}

注意： CreateOrderCommand 是一个简单的 DTO，不继承任何基类：

public record CreateOrderCommand(CreateOrderRequest Request) : IRequest<Order>;

Application Service 层（肌肉层核心）：

public class CreateOrderService : IRequestHandler<CreateOrderCommand, Order>
{
    private readonly IOrderRepository _repository;
    private readonly ILogger<CreateOrderService> _logger;

    public CreateOrderService(IOrderRepository repository, ILogger<CreateOrderService> logger)
    {
        _repository = repository;
        _logger = logger;
    }

    public async Task<Order> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
    {
        // 【猫的爪印】记录关键业务日志
        _logger.LogInformation("Creating order for customer {@CustomerId}", request.Request.CustomerId);

        // 1. 构建领域对象（触发构造函数验证）
        var order = new Order(
            Id: Guid.NewGuid(),
            CustomerId: request.Request.CustomerId,
            TotalAmount: request.Request.Items.Sum(i => i.Quantity * i.UnitPrice),
            Status: OrderStatus.Draft,
            CreatedAt: DateTime.UtcNow,
            Items: request.Request.Items.Select(i => new OrderItem(i.ProductCode, i.Quantity, i.UnitPrice)).ToList());

        // 2. 保存到数据库
        await _repository.CreateAsync(order, cancellationToken);

        // 3. 发布领域事件（猫抓板）
        await _publisher.PublishAsync(new OrderCreated(order.Id, order.CustomerId, order.TotalAmount));

        _logger.LogInformation("Order {@OrderId} created successfully", order.Id);
        return order;
    }
}

Repository 层（骨骼层实现）：

public class OrderRepository : IOrderRepository
{
    private readonly OrderDbContext _context;

    public OrderRepository(OrderDbContext context) => _context = context;

    public async Task CreateAsync(Order order, CancellationToken cancellationToken)
    {
        // 【猫的爪印】SQL 日志
        _context.Orders.Add(new OrderEntity
        {
            Id = order.Id,
            CustomerId = order.CustomerId,
            TotalAmount = order.TotalAmount,
            Status = (int)order.Status,
            CreatedAt = order.CreatedAt,
            ItemsJson = JsonSerializer.Serialize(order.Items)
        });

        await _context.SaveChangesAsync(cancellationToken);
    }
}

关键点： ItemsJson 字段用 string 存储 JSON，而非关系型展开。这是“猫式”权衡——订单项极少更新，JSON 存储省去了 3 张关联表的 JOIN 开销，且查询时用 JsonDocument.Parse() 解析，性能损失可忽略。我们在压测中对比过：1000 QPS 下，JSON 方案平均延迟 12ms，而关系型方案因 JOIN 导致 28ms。

4.4 本地验证与 CI/CD 流水线：让“猫的习性”自动化

“Cat in dotNET”要求所有约束必须在 CI 流水线中自动验证，不能依赖人工 Code Review。我们用 GitHub Actions 实现：

name: Cat Verification Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '8.0.x'
    
    - name: Restore
      run: dotnet restore
    
    - name: Build
      run: dotnet build --no-restore --configuration Release
    
    - name: Run Unit Tests
      run: dotnet test --no-build --configuration Release --logger "trx;LogFileName=test-results.trx"
    
    - name: Verify Cat Constraints
      run: |
        # 检查 Program.cs 是否包含禁止的代码
        if grep -r "Console.WriteLine\|throw new Exception" . --include="*.cs" | grep -v "Tests"; then
          echo "❌ Forbidden patterns found in production code!"
          exit 1
        fi
        
        # 检查所有 HTTP POST 方法是否标注幂等性
        if ! dotnet tool run dotnet-cat-analyzer