抛弃臃肿的 Controller！.NET Minimal API 高并发开发最佳实践

一、为什么高并发场景要“抛弃”Controller？

1. 反射开销：MVC 在启动时通过反射扫描 Controller，运行时通过反射匹配 Action，这在极致性能场景下是额外的 CPU 开销。
2. 对象分配：Controller 实例的创建、ActionContext、ModelState 等对象的频繁分配，增加了 GC 压力。
3. 管道深度：MVC 的 Filter 管道比 Minimal API 的 Middleware 链路更长，每一次请求都要经过更多层。

二、性能基石：告别反射，拥抱源码生成

app.MapGet("/users/{id}", (int id, IUserService service) => service.Get(id));

1. 使用 MapGroup 减少路由匹配开销

var userApi = app.MapGroup("/api/users")
    .WithTags("Users")
    .RequireAuthorization(); // 统一鉴权，避免每个 Endpoint 重复检查

userApi.MapGet("/{id:int}", GetUserById);
userApi.MapPost("/", CreateUser);

2. 利用 EndpointFilter 替代 ActionFilter

public static class ValidationFilter
{
    public static RouteHandlerBuilder WithValidation<T>(this RouteHandlerBuilder builder) where T : class
    {
        return builder.AddEndpointFilter(async (context, next) =>
        {
            // 直接从 HttpContext 获取，避免额外的变量声明
            if (context.GetArgument<T>(0) is not { } request)
                return Results.BadRequest("Invalid request body.");

            // 使用 Source Generator 生成的验证器（如 DataAnnotations 或 FluentValidation）
            var validator = context.HttpContext.RequestServices.GetRequiredService<IValidator<T>>();
            var result = await validator.ValidateAsync(request);
            
            if (!result.IsValid)
                return Results.ValidationProblem(result.ToDictionary());
                
            return await next(context);
        });
    }
}

// 使用
app.MapPost("/orders", CreateOrder)
   .WithValidation<CreateOrderRequest>();

三、内存优化：零分配与 IAsyncEnumerable

1. 返回 IAsyncEnumerable<T> 应对大列表

app.MapGet("/logs/stream", async (
    ILogRepository repo,
    CancellationToken ct) =>
{
    // 关键：使用 AsAsyncEnumerable，而不是 ToListAsync
    IAsyncEnumerable<LogEntry> logs = repo.GetRecentLogsAsync(ct);
    return Results.Ok(logs); // Minimal API 原生支持流式 JSON 序列化
});

2. 使用 PooledBuffers 处理字符串

using System.Buffers;

app.MapPost("/sign", (HttpRequest request) =>
{
    var buffer = ArrayPool<char>.Shared.Rent(4096);
    try
    {
        // 使用 buffer 进行字符串操作
        return Results.Ok();
    }
    finally
    {
        ArrayPool<char>.Shared.Return(buffer);
    }
});

四、吞吐利器：NativeAOT 与 ReadyToRun

1. 启用 NativeAOT

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <PublishAot>true</PublishAot>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

2. 使用 JsonSerializerContext 消除反射

[JsonSerializable(typeof(UserDto))]
[JsonSerializable(typeof(List<UserDto>))]
internal partial class AppJsonSerializerContext : JsonSerializerContext
{
}

// 在 Endpoint 中显式指定 Context
app.MapGet("/users", () =>
{
    var users = GetUsers();
    return Results.Json(users, AppJsonSerializerContext.Default.ListUserDto);
});

五、并发控制：Semaphore 与异步队列

场景：限制对下游数据库的并发连接数

// 全局定义信号量（限制并发数为 10）
private static readonly SemaphoreSlim _semaphore = new(10, 10);

app.MapPost("/process", async (HttpRequest request) =>
{
    // 等待信号量，避免压垮数据库
    await _semaphore.WaitAsync();
    try
    {
        // 执行数据库写入或第三方 API 调用
        await ProcessDataAsync();
        return Results.Ok();
    }
    finally
    {
        _semaphore.Release();
    }
});

六、结构化路由与强类型参数

1. 强类型路由参数（C# 14 新特性）

// 使用 Record 作为强类型参数
app.MapGet("/orders/{OrderId:int}", (OrderQuery query) =>
{
    // query.OrderId 直接可用，无需手动解析
    return Results.Ok($"Order {query.OrderId}");
});

public record OrderQuery(int OrderId);

2. 模块化组织（Reusable Routes）

public static class UserEndpoints
{
    public static void MapUserEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/users");

        group.MapGet("/{id:int}", GetUser)
             .WithName("GetUser")
             .CacheOutput(TimeSpan.FromMinutes(1)); // 内置响应缓存
    }

    private static async Task<IResult> GetUser(int id, IUserService service)
    {
        var user = await service.GetAsync(id);
        return user is null ? Results.NotFound() : Results.Ok(user);
    }
}

// Program.cs
app.MapUserEndpoints();

七、实战 Checklist：高并发 Minimal API 避坑指南

1. ✅ 禁用 MVC：在 Program.cs 中确保没有 AddControllers()，减少内存占用。
2. ✅ 使用 IAsyncEnumerable：返回大列表时，永远不要 ToList()。
3. ✅ 启用 AOT：发布时开启 PublishAot，并使用 JsonSerializerContext。
4. ✅ 避免阻塞：严禁在 Endpoint 中使用 .Result 或 .Wait()。
5. ✅ 利用 CancellationToken：所有异步方法传递 CancellationToken，客户端断开时及时释放资源。
6. ✅ 使用 PooledBuffers：高频字符串操作使用 ArrayPool。
7. ✅ 限流：使用内置的 RateLimiter 中间件或 SemaphoreSlim。

总结

• 更少的 GC 压力（更少的对象分配）
• 更低的延迟（更短的管道）
• 更小的内存 footprint（NativeAOT）
• 更高的吞吐（异步流与高效的路由）