从 .NET 6 / Framework 4.8 杂烩 → .NET 9 + C# 13 + ASP.NET Core 9 + Minimal API + Native AOT + EF Core 9 + Aspire + Orleans 全栈升级 36 天踩坑录:13 反模式 + 14 修法

2026 年 2 月初到 4 月初,我作为 .NET tech lead 带 41 位 C# / .NET 工程师,用 36 天把公司 ".NET 技术栈全栈"从 .NET 6 / Framework 4.8 / EF Core 6 / ASP.NET Core 6 全面升级到 .NET 9 + C# 13 + ASP.NET Core 9 + Minimal API + Native AOT + EF Core 9 + gRPC.NET 2.66 + MassTransit 8.3 + MediatR 12.4 + Aspire 9.1 + Orleans 8.2 + YARP 2.2 + OpenTelemetry 1.10,覆盖 187 个微服务 + 4 个 B2B SaaS 产品 + 9.3 万 QPS + 17 万 daily users。期间踩了 13 个反模式 + 8 次回滚 + 3 次 P0 + 7 次 P1,沉淀 14 套修法 + 30 个 .NET 9 工程化议题。这篇是 36 天踩坑全记录,献给所有从 .NET Framework / .NET 6 迁移的 C# 工程师同行。

一、.NET 9 升级的"4 个核心收益"

从 .NET 6 升级到 .NET 9 的 4 大工程收益:(1) 性能:JIT / GC / Threading 全栈优化,平均吞吐升 23%,p99 降 18%;(2) Native AOT 成熟:启动 < 50ms,内存占用降 47%,适合 Serverless;(3) Minimal API + Open API 原生集成,REST 接口代码量降 60%;(4) ASP.NET Core 9 服务端 Blazor 与 Web Components 互操作。实测:187 服务整体内存降 32%,冷启动从 8s 降到 1.2s。

二、C# 13 的"7 个工程价值特性"

C# 13 在 187 服务中的 7 个工程价值:(1) Primary constructor for class(简化 DI);(2) Collection expressions [.. spread ..];(3) ref readonly parameters;(4) params Span<T>;(5) Lock 对象语言级支持;(6) Implicit index access from end;(7) field-backed property(预览)。4.2 万行老代码用 C# 13 重构后总行数降 18%,可读性显著提升。

三、Minimal API 的"6 个设计要点"

Minimal API 在 187 服务的 6 个设计要点:(1) 路由按 BC 分组到 MapGroup,避免 Program.cs 1000 行;(2) Endpoint filter 替代 Filter Attribute;(3) TypedResults 强类型返回;(4) AsParameters 结构化绑定参数;(5) OpenAPI Document 自动生成;(6) Endpoint metadata 用于 Authz / RateLimit。从 Controller 迁移到 Minimal API 后,代码减少 47%,启动快 60%。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
    o.AddPolicy("admin", p => p.RequireRole("admin")));
builder.Services.AddRateLimiter(o =>
    o.AddFixedWindowLimiter("api", w => {
        w.PermitLimit = 100;
        w.Window = TimeSpan.FromSeconds(10);
    }));
builder.Services.AddScoped<IOrderService, OrderService>();

var app = builder.Build();
app.MapOpenApi();
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

var orders = app.MapGroup("/api/v1/orders")
    .RequireAuthorization()
    .RequireRateLimiting("api")
    .WithOpenApi();

orders.MapGet("/{id:guid}", async (Guid id, IOrderService svc, CancellationToken ct) =>
{
    var order = await svc.GetByIdAsync(id, ct);
    return order is null ? Results.NotFound() : TypedResults.Ok(order);
});

orders.MapPost("/", async ([FromBody] CreateOrderRequest req, IOrderService svc, CancellationToken ct) =>
{
    var created = await svc.CreateAsync(req, ct);
    return TypedResults.Created($"/api/v1/orders/{created.Id}", created);
});

app.Run();

四、Native AOT 的"5 个工程现实"

.NET 9 Native AOT 的 5 个工程现实:(1) 启动 < 50ms,冷启动场景(Lambda / Functions)收益巨大;(2) 内存降 47%,密集多实例场景显著降本;(3) 二进制体积 大约 15-30 MB,docker image 极小;(4) 限制:不能动态加载程序集 / Emit / 部分反射;(5) Trim 触发的运行时异常需 [DynamicallyAccessedMembers] 标注。187 服务中 32 个 AOT,主要是 Lambda / 内部工具 / 静态接口。

五、AOT 兼容性的"5 大坑"

Native AOT 5 大坑:(1) 反射 + serialization:必须用 source generator(System.Text.Json / MessagePack);(2) DI 容器:Microsoft.Extensions.DI 支持 AOT,但部分第三方不行;(3) EF Core:9.0 支持 compiled model + AOT;(4) Trim warnings:全部消除才能 production;(5) Assembly.Load / Activator.CreateInstance 无法用。5 大坑用 source generator + 严格代码审查 + AOT 单元测试解决。

六、EF Core 9 的"6 个工程改进"

EF Core 9 在 187 服务上的 6 个工程改进:(1) Compiled query + Compiled model 配合 AOT;(2) HierarchyId / JSON columns(SQL Server);(3) Cosmos DB 改进:hierarchical partition key;(4) Bulk update / delete:ExecuteUpdate / ExecuteDelete,无需 LINQ-to-SQL;(5) Migration bundle 支持 .NET 9 AOT;(6) Logging 默认结构化。实测:复杂查询 query plan 命中率 + 38%,migration 启动从 5s 降到 600ms。

七、EF Core 的"7 个反模式"

EF Core 在生产 7 大反模式:(1) 不用 AsNoTracking 查只读:Change tracker 浪费内存 + CPU;(2) N+1 查询(忘 Include);(3) DbContext 在 long-lived service 直接注入 → DbContext 线程不安全 OOM;(4) 大事务 / 大 SaveChanges 一次提交 10 万行;(5) 不用 explicit transaction 跨多 SaveChanges;(6) Migration 直接生产跑 → schema 锁表;(7) 不用 Find / FirstOrDefault 区别。修法 7 条:AsNoTracking 默认 + Include 显式 + DbContext IDbContextFactory + 批量分批 + 显式 transaction + Migration bundle 灰度 + 区分单查 / 列表查。

public sealed class OrderRepository(IDbContextFactory<AppDbContext> factory) : IOrderRepository
{
    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct)
    {
        await using var ctx = await factory.CreateDbContextAsync(ct);
        return await ctx.Orders
            .AsNoTracking()
            .Include(o => o.Items)
            .ThenInclude(i => i.Product)
            .AsSplitQuery()
            .FirstOrDefaultAsync(o => o.Id == id, ct);
    }

    public async Task<int> MarkExpiredAsync(DateTime cutoff, CancellationToken ct)
    {
        await using var ctx = await factory.CreateDbContextAsync(ct);
        return await ctx.Orders
            .Where(o => o.Status == OrderStatus.Pending && o.CreatedAt < cutoff)
            .ExecuteUpdateAsync(s =>
                s.SetProperty(o => o.Status, OrderStatus.Expired)
                 .SetProperty(o => o.UpdatedAt, DateTime.UtcNow), ct);
    }
}

八、Async / Await 的"6 条铁律"

C# Async 6 铁律:(1) 永远不要 .Result / .Wait():死锁元凶,生产 P0 来源;(2) 库代码必 ConfigureAwait(false),除非显式需要 context;(3) CancellationToken 必传到底:HTTP / DB / IO 全链路;(4) ValueTask 用于 hot path,但谨慎(读了多次 / 不能 cache 取消);(5) Task.Run 只用于 CPU bound,IO bound 直接 await;(6) await using / await foreach 优先于 using / foreach。187 服务 36 天审计,移除 sync over async 472 处,生产 deadlock 月均 7 → 0。

九、ASP.NET Core 9 的性能优化"5 个杠杆"

ASP.NET Core 9 性能优化 5 杠杆:(1) Kestrel Connection multiplexing / HTTP/3:并发连接降 60%;(2) Response caching + Output cache:静态 / 低频内容降 60%;(3) Streaming JSON(IAsyncEnumerable):大列表内存降 80%;(4) ResponseCompression(Brotli);(5) Pipeline middleware 顺序:RateLimit → Auth → Cache → MVC。实测:187 服务平均 RPS 升 47%,p99 降 35%。

十、MediatR 12.4 的"3 大场景"

MediatR 12.4 在 187 服务中的 3 大场景:(1) CQRS:IRequest<TResponse> 分离 Command / Query;(2) Pipeline behavior:横切关注点(logging / validation / caching / transaction)在 pipeline 中实现;(3) Notification:领域事件 in-process publish。替代了 Controller 直接调 Repository 的混乱,业务代码可测试性大幅提升,单元测试覆盖率从 47% 升到 84%。

十一、Aspire 9.1 的"6 个工程价值"

.NET Aspire 9.1 在 187 服务的 6 个工程价值:(1) Local dev orchestration:一条命令拉起 8-15 个服务 + Redis / Postgres / Kafka;(2) 服务发现 + DI 标准化;(3) Dashboard:Trace / Metric / Log 三件套本地集成;(4) Resource modeling:把基础设施抽象成 C# 代码;(5) Deployment manifest 自动生成 Kustomize / Bicep;(6) OpenTelemetry 默认。新人 onboarding 从 2 周降到 2 天,本地环境一致性 92%。

十二、Orleans 8.2 的"5 个应用场景"

Orleans 8.2(虚拟 Actor 框架)5 应用场景:(1) 实时多人游戏 / 协作编辑(每用户 1 Grain);(2) IoT 设备影子(每设备 1 Grain);(3) 限流 / 频控(每用户 1 Grain 计数);(4) 会话状态管理;(5) 分布式状态机(订单 saga)。我们的 IoT 平台:380 万设备 = 380 万 Grain on 32 silo,平均 RAM 28GB,QPS 12 万,latency p99 8ms。

十三、YARP 2.2 的"4 个工程价值"

YARP(Yet Another Reverse Proxy)2.2 在我们 4 个 SaaS 产品的 4 个工程价值:(1) C# 写配置,与业务代码同栈;(2) 性能优秀:单实例 30 万 RPS;(3) 灰度发布:按 header / weight 切流;(4) Custom transform 简单:加 header / 改 path / 重写 query。替代了 Kong / Nginx 在内部 API gateway 场景,运维成本降 60%。

十四、MassTransit 8.3 的"6 个工程铁律"

MassTransit 8.3 在 187 服务事件驱动的 6 铁律:(1) Saga 状态机用 Automatonymous 模式;(2) Outbox + InMemory + DB outbox 三种选其一(MassTransit 自带);(3) Consumer concurrency 控制 messages-per-consumer;(4) Retry / RedeliveryFilter 区分:Retry 立即重试,Redelivery 延迟重试;(5) ConsumeContext.CancellationToken 必传;(6) Message versioning:[MessageUrn] 显式。替代了直接 RabbitMQ SDK,业务代码降 70%,可观测性自动注入。

十五、gRPC.NET 2.66 的"5 个升级收益"

gRPC.NET 2.66 升级 5 收益:(1) HTTP/3 client / server 支持;(2) Native AOT 完全兼容;(3) JSON transcoding 成熟(gRPC → REST);(4) Server reflection 默认;(5) Interceptor 性能优化。实测:127 个 gRPC 服务 RPS 升 22%,p99 降 15%,Docker image 降 35%。

十六、SignalR 9 的"4 个改进"

ASP.NET Core SignalR 9 的 4 个改进:(1) MessagePack 默认序列化(比 JSON 快 3x);(2) Backplane Redis 改进,跨 region 延迟降 40%;(3) StatefulReconnect:断线 30 秒内重连无感;(4) IAsyncEnumerable streaming 全双工。我们的实时 dashboard 12 万并发连接,SignalR 单服务从 5k 升到 15k 连接。

十七、System.Text.Json 的"5 条最佳实践"

System.Text.Json 在 187 服务 5 条最佳实践:(1) 默认 source generator(AOT 友好 + 性能升 30%);(2) JsonSerializerOptions 全局单例,prepared metadata;(3) PropertyNamingPolicy = CamelCase;(4) WriteIndented = false in production;(5) JsonConverter 自定义对 DateTime / Money / Enum。JSON 序列化 CPU 占用降 47%,内存降 38%。

十八、Dependency Injection 的"5 个反模式"

MS DI 5 反模式:(1) Captive dependency:Singleton 注入 Scoped → Scoped 提升为单例,数据脏;(2) DbContext 注 Singleton → 灾难;(3) Service locator 反模式:从 IServiceProvider GetService;(4) 配置后注册:Configure 后 Configure 覆盖;(5) Open generic 错用:不指定具体类型。5 反模式用 Roslyn analyzer 静态检查 + 启动期 validation 防御,过去 12 个月 DI 故障 0 次。

十九、OpenTelemetry .NET 1.10 的"4 个核心配置"

OpenTelemetry .NET 1.10 的 4 个核心配置:(1) Tracing:AspNetCore / HttpClient / EF Core / gRPC 全自动 instrumentation;(2) Metrics:Process / Runtime / Custom 三套;(3) Logging:ILogger 接 OTel exporter;(4) Resource detection:K8s metadata 自动注入。187 服务 Trace 覆盖率 100%,跨服务 trace 串联 99.7%,排查从 30 分钟降到 5 分钟。

二十、Polly 8.5 的"7 个 Resilience Strategy"

Polly 8.5 在 187 服务的 7 个 strategy:(1) Retry with exponential backoff + jitter;(2) Circuit Breaker;(3) Bulkhead:并发隔离;(4) Timeout:操作级超时;(5) Rate Limiter;(6) Fallback;(7) Hedging:请求复制(对延迟敏感场景)。策略组合写在 ResiliencePipeline,统一注册到 HttpClientFactory,网络调用稳定性显著提升。

二十一、.NET 9 升级路径的"5 阶段方法"

从 .NET 6 / Framework 4.8 升级到 .NET 9 的 5 阶段方法:(1) 第一阶段(第 1-5 天):依赖审计,Roslyn 分析器扫描全部 NuGet 包的兼容性,识别不兼容的反射 / 动态加载 / WCF / Remoting / WebForms 代码;(2) 第二阶段(第 6-12 天):基础设施先行,CI / CD 流水线先升级,Docker base image 切换到 mcr.microsoft.com/dotnet/aspnet:9.0,Roslyn / SDK / Global.json 全部锁定 9.0.x;(3) 第三阶段(第 13-22 天):服务批量迁移,按 BC 分组,先升级无状态服务,再升级有状态服务;(4) 第四阶段(第 23-30 天):性能调优,Native AOT 改造 Lambda / Functions 类服务,EF Core 9 compiled query 改造热点查询;(5) 第五阶段(第 31-36 天):监控验证,OpenTelemetry trace 比对升级前后 p50 / p99 / 内存 / RPS,确认无回归。5 阶段法用于 187 服务,做到了升级期间生产 0 P0,7 个 P1 全部在 4 小时内修复。

二十二、C# 13 Primary Constructor 的"4 个使用边界"

C# 13 Primary Constructor 在 187 服务中的 4 个使用边界:(1) 适用场景:DI 注入服务类、Repository、Handler 这类纯依赖容器类;(2) 不适用场景:含可空状态、复杂初始化逻辑、需要 field-level 校验的领域对象;(3) 序列化注意:Primary Constructor 参数自动成为隐藏字段,不会自动暴露为属性,需要显式声明 public 属性给 System.Text.Json;(4) 继承注意:base class 用 Primary Constructor 时,派生类必须显式调用 base(...)。187 服务重构后,Primary Constructor 让 Service / Handler / Repository 三类共 1.2 万行代码节省了 4500 行样板代码,大约 38% 缩减。

二十三、Collection Expressions 的"5 种典型用法"

C# 13 Collection Expressions [..] 5 种典型用法:(1) 静态集合字面量:int[] x = [1, 2, 3] 替代 new int[] { 1, 2, 3 };(2) Spread 操作:[..a, ..b, 0] 直接展开多个集合;(3) 范型推断:方法参数为 ReadOnlySpan<T> 时直接 [a, b, c] 无需 new;(4) 字典构造:Dictionary<string, int> = [..baseDict, ..overrideDict];(5) ImmutableArray 友好:ImmutableArray<int> = [..items],无需 ToImmutableArray()。Collection Expressions 替代了大量样板代码,加上 params Span<T> 后,API 调用代码可读性提升,GC 分配次数也显著下降。

二十四、Lock 对象语言级支持的"工程影响"

C# 13 的 System.Threading.Lock 对象 + lock 语句语言级支持的工程影响:(1) 比 Monitor.Enter / Exit 性能更好,SQL 锁等待时间降 38%;(2) 编译器直接对 Lock 对象类型生成 Enter / Exit IL,避免 monitor lock 的运行时检查;(3) 与 async / await 配合更安全,但仍不能跨 await(锁仍是线程亲和的);(4) 187 服务中 240 处 lock(object lockObj) 替换为 lock(_lock) 配合 private readonly Lock _lock = new();(5) Roslyn 分析器 CA2002 强制约束 lock 对象类型,防止误用 object。实测:高并发场景下,lock 性能提升 12-20%。

二十五、Minimal API 的"路由组织 4 模式"

Minimal API 在 187 服务的路由组织 4 模式:(1) 按 BC 分文件:每个 Bounded Context 一个 EndpointMap 静态类,内部 MapGroup 注册路由;(2) 按版本分组:MapGroup("/api/v1") / MapGroup("/api/v2") 并行存在,迁移期间双轨;(3) 按权限分组:RequireAuthorization("admin") vs RequireAuthorization("user") 用 MapGroup 标注;(4) 按速率分组:RequireRateLimiting("public-api") vs ("internal-api"),不同 group 不同限流策略。4 模式让 Program.cs 永远不会超过 50 行,所有路由分散到 Endpoint 文件,代码可维护性提升。

二十六、Endpoint Filter 的"3 种典型应用"

Minimal API Endpoint Filter 的 3 种典型应用:(1) Logging filter:记录请求 / 响应 / 耗时,在 endpoint 注册时 .AddEndpointFilter<LoggingFilter>();(2) Validation filter:统一 FluentValidation 校验,失败返回 400 ValidationProblem;(3) Tenant filter:多租户场景从 Header 提取 X-Tenant-Id 注入到 HttpContext.Items,后续 Handler 直接读。Endpoint Filter 替代了 ASP.NET Core 的 ActionFilter,性能更好,组合更灵活。

public sealed class LoggingFilter : IEndpointFilter
{
    private readonly ILogger<LoggingFilter> _logger;
    public LoggingFilter(ILogger<LoggingFilter> logger) => _logger = logger;

    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var sw = System.Diagnostics.Stopwatch.StartNew();
        var endpoint = context.HttpContext.GetEndpoint()?.DisplayName ?? "unknown";
        try
        {
            var result = await next(context);
            _logger.LogInformation("Endpoint {Endpoint} ok in {Elapsed}ms",
                endpoint, sw.ElapsedMilliseconds);
            return result;
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Endpoint {Endpoint} failed in {Elapsed}ms",
                endpoint, sw.ElapsedMilliseconds);
            throw;
        }
    }
}

public static class OrderEndpoints
{
    public static IEndpointRouteBuilder MapOrderEndpoints(this IEndpointRouteBuilder app)
    {
        var grp = app.MapGroup("/api/v1/orders")
            .RequireAuthorization("user")
            .AddEndpointFilter<LoggingFilter>()
            .AddEndpointFilter<ValidationFilter>()
            .WithOpenApi();

        grp.MapGet("/{id:guid}", GetById);
        grp.MapPost("/", Create);
        grp.MapPut("/{id:guid}", Update);
        grp.MapDelete("/{id:guid}", Delete);
        return app;
    }
}

二十七、Native AOT 改造的"7 个步骤"

Native AOT 改造的 7 步骤:(1) 启用 PublishAot:csproj 加 <PublishAot>true</PublishAot>;(2) 修复 Trim warnings:IL2026 / IL2104 / IL3050 全部消除,使用 [DynamicallyAccessedMembers] 标注反射目标;(3) Json 切换:System.Text.Json source generator [JsonSerializable];(4) DI 改造:确保所有第三方 DI 容器 / 拦截器 AOT 兼容;(5) EF Core compiled model:dotnet ef dbcontext optimize 生成静态编译模型;(6) Reflection 替换:Activator.CreateInstance 改为 source-generated factory;(7) Profile-guided optimization(PGO):dotnet publish -p:TieredPgo=true。32 个服务 AOT 改造后,Lambda 冷启动从 8s 降到 1.2s,降本 47%。

二十八、EF Core 9 Compiled Model 的"3 个关键点"

EF Core 9 Compiled Model 的 3 个关键点:(1) 生成命令:dotnet ef dbcontext optimize -o GeneratedModel -n MyApp.GeneratedModel,生成静态模型源代码;(2) 注册:DbContextOptions.UseModel(GeneratedModel.AppDbContextModel.Instance) 替代 model discovery;(3) 收益:启动期 model building 从 5s 降到 200ms,AOT 兼容,适合 Lambda / 微服务高密度部署。187 服务中 60 个引入 compiled model,启动时间整体降 67%。

二十九、EF Core 9 ExecuteUpdate 的"5 个使用边界"

ExecuteUpdate / ExecuteDelete 5 边界:(1) 不触发 Change Tracker:适合大批量更新,但不会发布 Domain Event;(2) 不带 OUTPUT 子句:不能拿到更新后的实体,只能拿影响行数;(3) 不参与 SaveChanges 事务:需要显式 IDbContextTransaction 包起来;(4) 不触发 Interceptor:Audit / SoftDelete 等横切关注点不生效;(5) 性能巨大优势:10 万行更新从 45 秒降到 0.8 秒。使用边界要明确:只用于 Maintenance Job / Batch Job,业务实时操作不用。

三十、EF Core 查询性能优化的"6 个高频杠杆"

EF Core 查询性能 6 杠杆:(1) Compiled query:EF.CompileAsyncQuery<DbContext, params, TResult>,热点查询性能提升 35%;(2) Split query:复杂 Include 用 AsSplitQuery 避免笛卡尔积爆炸;(3) Projection:Select 投影到 DTO,避免加载完整实体;(4) Raw SQL:复杂报表查询 FromSqlInterpolated,绕过 LINQ-to-SQL 翻译;(5) Index hint:配合 SQL Provider 的 hint 函数;(6) DbContext pool:UseDbContextPool 减少 DbContext 创建开销。187 服务热点查询 p99 平均降 47%。

三十一、Async 死锁的"3 大根因"

Async / Await 死锁 3 大根因:(1) SynchronizationContext 死锁:ASP.NET Framework / WinForms / WPF 中 .Result / .Wait() 等待 await 回到原 SC,但 SC 已被 .Wait() 占用;ASP.NET Core 没有 SC,但同步阻塞仍消耗线程池线程,引发线程池饥饿;(2) Thread Pool 饥饿:大量同步阻塞 await Task → 线程池耗尽 → 新请求排队 → 雪崩;(3) Lock 在 async 内持有跨 await:lock 是线程亲和,await 后线程切换,锁状态混乱。修法:严禁 .Result / .Wait();async 方法不持有 lock 跨 await;CancellationToken 全链路传递。

三十二、HttpClientFactory 的"4 个最佳实践"

HttpClientFactory 4 最佳实践:(1) Named client:AddHttpClient("payment", c => c.BaseAddress = ...),避免每个调用方手动配置;(2) Typed client:AddHttpClient<IPaymentApi, PaymentApi>(),DI 自动注入,与 Refit / RestEase 兼容;(3) Polly 集成:AddStandardResilienceHandler() 一次性加 Retry + CircuitBreaker + Timeout + RateLimiter;(4) DelegatingHandler 注入 trace / log / auth header,避免在业务代码重复。187 服务 HTTP 调用稳定性显著提升,故障雪崩月均 4 → 0。

builder.Services.AddHttpClient<IPaymentApi, PaymentApi>(c =>
{
    c.BaseAddress = new Uri(builder.Configuration["Payment:BaseUrl"]!);
    c.Timeout = TimeSpan.FromSeconds(5);
    c.DefaultRequestHeaders.Add("X-Source", "order-svc");
})
.AddStandardResilienceHandler(o =>
{
    o.Retry.MaxRetryAttempts = 3;
    o.Retry.Delay = TimeSpan.FromMilliseconds(200);
    o.Retry.BackoffType = Polly.DelayBackoffType.Exponential;
    o.Retry.UseJitter = true;
    o.CircuitBreaker.FailureRatio = 0.5;
    o.CircuitBreaker.MinimumThroughput = 10;
    o.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(30);
    o.AttemptTimeout.Timeout = TimeSpan.FromSeconds(2);
    o.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(10);
})
.AddHttpMessageHandler<TracingHandler>()
.AddHttpMessageHandler<AuthHandler>();

三十三、MassTransit Saga 的"4 个状态机模式"

MassTransit Saga 4 模式:(1) Choreography:无中心协调,各服务订阅事件触发本地动作,适合简单场景;(2) Orchestration:有中心 Saga,统一推进流程,适合复杂多步骤;(3) Routing Slip:动态路由,每一步携带下一步信息,适合可变流程;(4) Process Manager:长事务 + 持久化状态,Saga state 持久化到 SQL / Redis。187 服务中 18 个 Saga,核心订单流程用 Orchestration,简单通知流程用 Choreography。

三十四、MediatR Pipeline Behavior 的"5 个工程价值"

MediatR Pipeline Behavior 5 价值:(1) Logging behavior:统一记录所有 Command / Query 调用,无需在 Handler 重复;(2) Validation behavior:FluentValidation 统一校验,失败抛 ValidationException;(3) Transaction behavior:对带 [Transactional] 属性的 Command 自动包事务,简化业务代码;(4) Caching behavior:对 Query 自动注入 IMemoryCache / IDistributedCache;(5) Performance behavior:统计 Handler 执行时间,超阈值告警。Pipeline Behavior 让横切关注点完全脱离 Handler 业务逻辑,Handler 代码量降 60%。

三十五、Aspire 9.1 资源建模的"6 个核心 API"

Aspire AppHost 6 核心 API:(1) AddProject:把 .NET 项目作为可启动资源;(2) AddPostgres / AddRedis / AddKafka:基础设施作为资源;(3) WithReference:服务间引用,Aspire 自动注入连接字符串;(4) WithEnvironment:注入环境变量;(5) WithEndpoint:暴露 HTTP / gRPC 端点;(6) WithReplicas:水平扩展副本。本地开发 dotnet run --project AppHost 一条命令拉起 15 个服务 + 5 个基础设施,Dashboard 显示全栈 trace。

三十六、Orleans 8.2 Grain 状态持久化的"4 种方式"

Orleans 8.2 Grain 状态持久化 4 种方式:(1) MemoryStorage:测试用,生产禁用;(2) AzureBlobStorage / TableStorage:Azure 优先,延迟低;(3) AdoNet:SQL Server / PostgreSQL 持久化,适合关系型场景;(4) Redis:低延迟,但需要 Redis Persistence 保证耐久。我们的 IoT 平台 380 万设备 Grain state 用 Redis Cluster + AOF,p99 写延迟 4ms,故障恢复 60s 内。

三十七、Orleans Reminders 的"3 个使用场景"

Orleans Reminders 3 场景:(1) 定时任务:每个用户 24 小时无活动自动登出;(2) 重试机制:Saga 长事务步骤超时重试;(3) 异步通知:设备离线 N 分钟后通知运维。Reminders 替代了 Hangfire / Quartz 的部分场景,但不适合 1 万次/秒以上高频定时,高频用 Timer。

三十八、YARP 配置的"4 个工程模式"

YARP 配置 4 模式:(1) Configuration-based:appsettings.json 中静态配置 Routes / Clusters,适合稳定场景;(2) Code-based:C# Builder API 动态配置,适合需要动态加路由;(3) IProxyConfigProvider:从外部源(DB / Consul / etcd)拉配置,支持热更新;(4) Custom Transform:自定义请求 / 响应转换,如加 X-Trace-Id / 改 path / 重写 body。我们的 SaaS API gateway 用 IProxyConfigProvider + Consul,1.2 万条路由,热更新 < 200ms。

三十九、gRPC.NET 性能调优的"5 个杠杆"

gRPC.NET 性能 5 杠杆:(1) Pooled connections:多路复用减少 HTTP/2 连接数;(2) Streaming:server streaming / client streaming / bidi 适合大量小数据;(3) Compression:GrpcWebText / Gzip,大 payload 带宽降 80%;(4) Deadline:客户端必须设 deadline,避免无限等待;(5) Channel pooling:GrpcChannel 复用,不要每次 new。127 个 gRPC 服务平均 RPS 升 47%,p99 降 35%。

四十、SignalR 9 Scale-out 的"3 个方案"

SignalR 9 横向扩展 3 方案:(1) Redis Backplane:中小规模(< 10 万连接),延迟 5-15ms;(2) Azure SignalR Service:云托管,自动扩展,适合无 ops 团队;(3) 自建分片:大规模(> 10 万连接),按 user-id hash 路由到不同 SignalR 实例。我们的实时 dashboard 12 万连接用 Redis Cluster 5 节点,跨实例消息延迟 p99 18ms。

四十一、System.Text.Json Source Generator 的"4 步落地"

System.Text.Json source generator 4 步:(1) 定义 partial class:[JsonSerializable(typeof(Order))] partial class AppJsonContext : JsonSerializerContext;(2) 序列化:JsonSerializer.Serialize(order, AppJsonContext.Default.Order);(3) 反序列化:JsonSerializer.Deserialize<Order>(json, AppJsonContext.Default.Order);(4) ASP.NET Core 集成:builder.Services.ConfigureHttpJsonOptions(o => o.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default))。187 服务 JSON 序列化 CPU 降 47%,内存降 38%,AOT 完全兼容。

[JsonSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    WriteIndented = false)]
[JsonSerializable(typeof(Order))]
[JsonSerializable(typeof(OrderItem))]
[JsonSerializable(typeof(CreateOrderRequest))]
[JsonSerializable(typeof(IReadOnlyList<Order>))]
[JsonSerializable(typeof(ProblemDetails))]
public sealed partial class AppJsonContext : JsonSerializerContext;

builder.Services.ConfigureHttpJsonOptions(o =>
{
    o.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default);
});

app.MapGet("/api/orders/{id:guid}", async (Guid id, IOrderService svc, CancellationToken ct) =>
{
    var o = await svc.GetByIdAsync(id, ct);
    return o is null
        ? Results.NotFound()
        : Results.Json(o, AppJsonContext.Default.Order);
});

四十二、DI Lifetime 选择的"决策树"

MS DI Lifetime 决策树:(1) 无状态、纯函数式服务 → Singleton;(2) 含 DbContext / HttpContext / 当前用户上下文 → Scoped;(3) 含可变状态、每次需要新实例 → Transient;(4) 含 IDisposable 且生命周期短 → Transient + using;(5) 含 IDisposable 且生命周期长 → Scoped + auto-disposed at scope end。决策树用于 Roslyn 分析器规则,自动检测 lifetime 误用。

四十三、Roslyn 分析器与代码质量的"5 个内置规则集"

5 个核心 Roslyn 分析器:(1) Microsoft.CodeAnalysis.NetAnalyzers:.NET 9 默认启用,涵盖性能 / 安全 / 可靠性;(2) Microsoft.VisualStudio.Threading.Analyzers:async / await 反模式;(3) AsyncFixer:更激进的 async 修复建议;(4) Meziantou.Analyzer:综合性最佳实践;(5) SonarAnalyzer.CSharp:静态代码质量。5 套分析器全部启用,Roslyn warnings as errors,代码 PR 合入门槛大幅提升。

四十四、OpenTelemetry Trace 上下文传播的"3 个场景"

OpenTelemetry Trace 传播 3 场景:(1) HTTP:自动 W3C TraceContext header(traceparent / tracestate)注入;(2) gRPC:自动 metadata 注入;(3) Kafka / MQ:手动通过 ActivitySource.Inject / Extract,把 trace context 放到 message header,消费端 Extract。跨 187 服务 trace 串联率 99.7%,排查从 30 分钟降到 5 分钟。

四十五、Logging 结构化的"4 条规则"

Logging 4 规则:(1) 用 ILogger<T>,不用 Console.WriteLine;(2) 结构化参数:Log("Order {OrderId} created by {UserId}", id, uid),不用字符串拼接;(3) LoggerMessage source generator:高频日志用 [LoggerMessage] 生成静态方法,性能提升 30%;(4) Scopes:Activity.Current.Id 自动加入,跨服务 trace 串联。187 服务统一 ILogger + OTel exporter,日志体积降 47%,搜索效率提升。

四十六、Polly 8.5 ResiliencePipeline 的"3 种组合模式"

Polly 8.5 Pipeline 3 组合模式:(1) Outer-to-Inner 顺序:Timeout → Retry → CircuitBreaker → Bulkhead,Timeout 在最外层捕获总超时;(2) 异步并发隔离:Bulkhead 限制并发到达下游;(3) Hedging 替代 Retry:对延迟敏感场景(LLM / 搜索)用 hedging 并行发送 N 个请求,取最快返回。策略组合写在 ResiliencePipelineBuilder,通过 ResiliencePipelineProvider 全局注册,跨服务统一。

四十七、Kestrel HTTP/3 启用的"3 个工程要点"

Kestrel HTTP/3 启用 3 要点:(1) builder.WebHost.ConfigureKestrel(o => o.ListenAnyIP(443, l => l.Protocols = HttpProtocols.Http1AndHttp2AndHttp3));(2) Alt-Svc header 自动注入,客户端自动升级;(3) 需要 TLS 1.3,证书必须支持。实测:HTTP/3 比 HTTP/2 平均 RPS 升 18%,p99 降 23%,但对短连接收益不大。

四十八、ASP.NET Core Output Cache 的"5 个使用模式"

Output Cache 5 模式:(1) 基础:AddOutputCache() + .CacheOutput(),缓存默认 60 秒;(2) Tag-based invalidation:.CacheOutput(p => p.Tag("orders-list")),Service 中 IOutputCacheStore.EvictByTagAsync 失效;(3) Vary-by:.CacheOutput(p => p.SetVaryByQuery("page", "size")),按参数变体缓存;(4) Conditional:.CacheOutput(p => p.SetCacheKeyPrefix(ctx => ctx.User.Identity?.Name ?? "anon"));(5) Distributed:用 RedisOutputCacheStore 跨实例共享。187 服务接入 Output Cache 后,静态 / 低频接口 RPS 升 8 倍,DB 压力降 70%。

四十九、Streaming JSON IAsyncEnumerable 的"3 个场景"

Streaming JSON 3 场景:(1) 大列表:百万行 SELECT 返回,IAsyncEnumerable 流式发送,内存占用降 80%;(2) 实时事件流:Server-Sent Events 风格,持续推送;(3) 文件下载替代:CSV / 报表数据流。endpoint 直接返回 IAsyncEnumerable<T>,ASP.NET Core 9 自动流式 JSON。

app.MapGet("/api/v1/orders/stream", (
    [FromQuery] DateTime from,
    [FromQuery] DateTime to,
    IOrderService svc,
    CancellationToken ct) =>
{
    return svc.StreamAsync(from, to, ct);
})
.RequireAuthorization("admin")
.WithName("StreamOrders")
.WithOpenApi();

public async IAsyncEnumerable<OrderDto> StreamAsync(
    DateTime from, DateTime to,
    [EnumeratorCancellation] CancellationToken ct)
{
    await using var ctx = await _factory.CreateDbContextAsync(ct);
    var q = ctx.Orders
        .AsNoTracking()
        .Where(o => o.CreatedAt >= from && o.CreatedAt < to)
        .OrderBy(o => o.CreatedAt)
        .Select(o => new OrderDto(o.Id, o.UserId, o.Total, o.Status, o.CreatedAt))
        .AsAsyncEnumerable();
    await foreach (var dto in q.WithCancellation(ct))
        yield return dto;
}

五十、问题复盘:Native AOT 反射切除导致 Newtonsoft.Json 崩溃

第 17 天:32 个 AOT 服务中 6 个上线后立即崩溃,日志显示 "Newtonsoft.Json failed to find constructor for type"。根因:Newtonsoft.Json 依赖运行时反射创建实例,AOT trim 切掉了构造函数元数据。修复:全部切换到 System.Text.Json + source generator;遗留 200 处 JsonConvert.Serialize 用 Roslyn fixer 批量改造;剩余 12 处确实依赖 Newtonsoft 特性(自定义 JsonConverter)的,标注 [DynamicDependency] 保留元数据。耗时 3.5 天,事故等级 P1,影响 6 服务 2 小时。

五十一、问题复盘:EF Core 9 SaveChanges 与 Domain Event 竞态

第 22 天:Outbox + Domain Event 模式中,Event 偶尔丢失。根因:DomainEvent dispatcher 在 SaveChanges 之前发布事件,数据库尚未提交,消费者读不到新数据,引发幻读。修复:重写 SaveChangesInterceptor,捕获 SavedChanges(成功)后再 publish event;DispatchDomainEventsBeforeSaveChanges 用于 in-process pre-commit 事件,DispatchDomainEventsAfterSaveChanges 用于 outbox 写表。修复后丢失率 0,P0 风险消除。

五十二、问题复盘:MassTransit 消费者并发越界打满数据库

第 28 天:某个高峰段 RabbitMQ 队列积压突然消费,数据库连接池耗尽,P1 故障 38 分钟。根因:MassTransit consumer 默认 PrefetchCount 自适应,堆积时一次拉 200+ message,每个 message handler 都需要 DB 连接,瞬时连接需求 500+。修复:显式 ConcurrentMessageLimit = 16,PrefetchCount = 32,匹配数据库连接池 100 上限;HttpClientFactory 也加 IConcurrencyLimiter。事故等级 P1,损失 14 分钟订单。

五十三、问题复盘:Orleans Grain 状态持久化超时引发雪崩

第 32 天:IoT 平台某 silo 触发 OutOfMemoryException,导致 Grain 重启时状态加载超时,雪崩到整个 cluster。根因:某个 Grain 状态在异常情况下累积到 200MB,加载时占用大量内存 + IO;Reminder 触发频率过高,加剧 GC 压力。修复:Grain 状态大小硬上限 512KB,超出抛 InvalidStateException;Reminder 改为按用户活跃度自适应频率;state storage 加分片。事故等级 P0,影响 8 万设备 23 分钟,事后做 chaos test 验证。

五十四、问题复盘:Minimal API 路由冲突导致 404

第 14 天:某次重构后,/api/v1/orders/{id} 和 /api/v1/orders/recent 路由冲突,recent 总是被解析为 id = "recent" 然后 404。根因:Minimal API 路由匹配按注册顺序 + 优先级,但 {id:guid} 不会拒绝非 guid 字符串路径,而是 fallback 到默认。修复:更严格的 constraint 使用 {id:guid:required};或显式 MapGet("/recent") 先于 MapGet("/{id:guid}") 注册;在 Endpoint metadata 中加 RoutePatternFactory.Parse 进行编译期校验。事故等级 P2,但暴露出 Minimal API 路由测试覆盖率不足。

五十五、问题复盘:DI Captive Dependency 引发数据脏

第 9 天:某 Singleton 服务持有了 DbContext,导致跨请求 DbContext 共享,引发幻读 + 内存泄漏。根因:Captive Dependency:Singleton 注入 Scoped → Scoped 实际上变为 Singleton,DbContext 跨请求共享。修复:启用 BuildServiceProvider(new ServiceProviderOptions { ValidateScopes = true, ValidateOnBuild = true }),启动期就报错;改用 IDbContextFactory<T> + await using 手动控制 DbContext 生命周期。事故等级 P1,数据库脏数据 320 条已人工修复。

五十六、性能调优:Profile-Guided Optimization 的"3 个收益"

.NET 9 PGO 3 收益:(1) Tiered PGO 默认开启:运行时基于热路径优化 JIT 代码;(2) Dynamic PGO:运行 5 分钟后重新优化,适合长周期服务;(3) Static PGO(预览):dotnet publish --pgo,基于训练数据生成静态优化。实测:187 服务平均 RPS 升 15%,p99 降 12%,CPU 降 8%。

五十七、性能调优:GC 调优的"4 个杠杆"

.NET 9 GC 4 杠杆:(1) Server GC:多核服务器默认 Server GC,吞吐升 40%;(2) Concurrent GC:后台回收,降低 STW;(3) DATAS(Dynamic Adaptation to Application Sizes,.NET 8+):自适应 heap 大小;(4) Region-based heap:.NET 9 默认,内存碎片降 30%。实测:187 服务 Gen2 GC 频率降 47%,平均 STW 降 60%。

五十八、性能调优:Threading 优化的"4 个要点"

.NET 9 Threading 4 要点:(1) ThreadPool 自适应增长:默认开启 IO completion port;(2) 不要用 Task.Factory.StartNew(longRunning),改用 Task.Run / await;(3) Parallel.ForEachAsync 替代 PLINQ 在 IO bound 场景;(4) Channel<T> 替代 BlockingCollection / ConcurrentQueue 在 producer-consumer 场景。实测:线程池饥饿事件月均 12 → 0。

五十九、安全:JWT + Refresh Token 的"4 个工程要点"

JWT 认证 4 要点:(1) Access token 短(15 分钟);Refresh token 长(7 天)+ rotation;(2) JWT signing key 定期轮换,JwtBearerOptions 配合 IConfigureNamedOptions 热更新;(3) Refresh token 存 Redis,登出 / 异地登录立即吊销;(4) Roslyn analyzer 强制要求 [Authorize] 必显式声明 policy。187 服务统一 JWT,无 session 状态,水平扩展友好。

六十、Health Check 的"4 层架构"

ASP.NET Core Health Check 4 层:(1) /health/live:进程存活,只检查进程不死;(2) /health/ready:依赖就绪,检查 DB / Redis / MQ;(3) /health/startup:Kubernetes startup probe,长启动服务避免被过早 kill;(4) /health/version:返回 build version + commit sha,方便排查。4 层 health check 配合 Kubernetes probe,部署稳定性大幅提升。

六十一、Docker Image 优化的"4 个杠杆"

Docker image 4 杠杆:(1) Multi-stage build:build 阶段 SDK image,运行阶段 runtime image;(2) Native AOT:image 从 220MB 降到 38MB;(3) Distroless / chiseled image:mcr.microsoft.com/dotnet/runtime-deps:9.0-noble-chiseled,无 shell,安全性高;(4) Layer 顺序:csproj restore 先于 source code,缓存命中率提升。187 服务 image size 平均降 67%,push 速度提升 4 倍。

六十二、Kubernetes 部署的"5 个 .NET 9 配置"

K8s 部署 .NET 9 的 5 配置:(1) DOTNET_gcServer=1 启用 Server GC;(2) DOTNET_GCHeapHardLimit 设硬上限,避免 OOM kill;(3) DOTNET_ThreadPool_MinThreads 预热线程池;(4) ASPNETCORE_HTTP_PORTS / ASPNETCORE_HTTPS_PORTS 明确监听端口;(5) HEALTH probes 用 livenessProbe + readinessProbe + startupProbe。实测:cold start 降 47%,稳定性提升。

六十三、CI/CD 流水线的"5 个关键阶段"

.NET 9 CI/CD 5 阶段:(1) restore + build:dotnet restore --locked-mode 强制 packages.lock.json 同步;(2) test:dotnet test --collect:"XPlat Code Coverage" + ReportGenerator;(3) format check:dotnet format --verify-no-changes 强制风格;(4) publish:dotnet publish -c Release + AOT;(5) docker build + push + scan。187 服务 pipeline 平均 6 分钟,失败回滚 < 90 秒。

六十四、监控告警的"5 个核心指标"

5 个核心 .NET 指标:(1) process.runtime.dotnet.gc.collections.count by generation:Gen2 GC 异常高表示内存压力;(2) process.runtime.dotnet.threadpool.queue.length:持续 > 10 表示线程池饥饿;(3) process.runtime.dotnet.exceptions.count:异常爆发是问题先兆;(4) http.server.request.duration p99:核心 SLO;(5) http.server.active_requests:并发请求高表示堆积。5 个指标接入 Prometheus + Grafana,告警 PagerDuty。

六十五、团队规范:Code Review 的"6 条核心标准"

Code Review 6 标准:(1) 必有单元测试,覆盖率不降;(2) async / await 全链路传 CancellationToken;(3) DI lifetime 不能错;(4) 没有 .Result / .Wait();(5) Logging 结构化,不拼字符串;(6) 公共 API 必有 XML doc + ProducesResponseType。6 标准用 Roslyn + Pre-commit hook + PR template 强制,代码质量稳定。

六十六、新人 onboarding 的"7 天计划"

新 .NET 工程师 onboarding 7 天:第 1 天本地环境 + Aspire 启动;第 2 天熟悉 BC 划分 + Minimal API 路由;第 3 天写第一个 Handler + 单元测试;第 4 天 EF Core CRUD + Repository;第 5 天 MassTransit 消费者 + Saga;第 6 天 Native AOT 改造练习;第 7 天 OpenTelemetry trace + Polly 配置。新人 onboarding 从 2 周降到 1 周,P1 率从 23% 降到 4%。

六十七、总结:36 天 .NET 9 升级的"7 条结论"

36 天升级 .NET 9 的 7 条结论:(1) 升级先升 CI / CD,业务代码后跟,容错性最高;(2) Native AOT 不是银弹,只用于 Lambda / Functions / 短生命周期场景;(3) Minimal API 是趋势,但路由组织规范必须先定;(4) EF Core 9 ExecuteUpdate 是性能杀器,但要明确边界;(5) Async / Await 是 .NET 工程师的最低门槛,死锁 0 容忍;(6) OpenTelemetry + Aspire 是可观测性的最优组合;(7) Roslyn 分析器 + Pre-commit hook 是代码质量的最低成本投入。187 服务 36 天升级,沉淀 14 套修法 + 30 个工程化议题,献给所有 .NET 工程师同行。

六十八、彩蛋:.NET 工程师必读的 6 本书 + 6 个仓库

跨 36 天升级期间团队复习的核心资料:(1) 《Pro .NET Memory Management》;(2) 《Concurrency in C# Cookbook》;(3) 《Entity Framework Core in Action》;(4) 《Designing Data-Intensive Applications》;(5) 《Implementing Domain-Driven Design》;(6) 《Microservices Patterns》。核心 GitHub 仓库:dotnet/runtime、dotnet/efcore、dotnet/aspire、MassTransit/MassTransit、jbogard/MediatR、dotnet/orleans。必读 6 本 + 必关注 6 仓库,新工程师 6 个月可成长为骨干。

—— 别看了 · 2026