aspnet-core

ASP.NET Core

适用场景

• 开发 ASP.NET Core 应用、服务或中间件
• 修改身份验证、路由、配置、托管或部署行为
• 在 Blazor、Minimal APIs 或控制器 API 等 ASP.NET Core 子技术栈之间做出选择
• 调试请求管道问题
• 将旧版 ASP.NET 现代化为 ASP.NET Core

文档

• ASP.NET Core 概述
• ASP.NET Core 中间件
• ASP.NET Core 最佳实践
• ASP.NET Core 中的配置
• 身份验证与授权

参考资料

• patterns.md - 详细介绍中间件、安全、配置、DI、错误处理和日志记录模式
• anti-patterns.md - 常见的 ASP.NET Core 错误，包括误用 HttpClient、异步反模式、配置错误、DI 问题、中间件顺序问题和安全漏洞

工作流

1. 首先确认实际的托管结构：

   • 顶级 Program.cs 结构
   • 中间件顺序和注册
   • 身份验证模型（Identity、JWT、OAuth、Cookie）
   • 端点注册和路由

2. 遵循正确的中间件顺序：

   ExceptionHandler → HttpsRedirection → Static Files → Routing
   → CORS → Authentication → Authorization → Rate Limiting
   → Response Caching → Custom Middleware → Endpoints
   

3. 正确使用内置模式：

   • 配置优先使用 IOptions<T> / IOptionsSnapshot<T>
   • 使用 ILogger<T> 进行结构化日志记录
   • 使用 IHttpClientFactory 创建 HTTP 客户端（切勿使用 new HttpClient()）
   • 使用 IHostedService / BackgroundService 执行后台工作

4. 将专门的工作交由特定技能处理：

   • UI 和组件 → blazor
   • 实时通信 → signalr
   • RPC → grpc
   • 新建 HTTP API → minimal-apis（除非需要控制器，否则优先使用）
   • 控制器 API → web-api

5. 使用构建、测试和针对性端点检查进行验证。

当前上游说明

• ASP.NET Core v10.0.11 是维护版本，而非新的编程模型。它将 OpenAPI 更新至 2.7.5，修复了已过期客户端持久化 Blazor circuit 状态的恢复问题，并更新了维护依赖项。保留现有的中间件和端点架构，然后重新运行针对 OpenAPI、交互式呈现、身份验证和启动的测试。
• 2026 年 8 月的 Microsoft Learn aspnetcore-10.0 概述仍是选择 Blazor、Minimal APIs、控制器 API、SignalR 和 gRPC 的路由入口；仅凭此次更新本身，并不足以成为更改现有应用模型的理由。

中间件模式

顺序至关重要

var app = builder.Build();

app.UseExceptionHandler("/error");      // 1. Catch all exceptions
app.UseHsts();                          // 2. Security headers
app.UseHttpsRedirection();              // 3. HTTPS redirect
app.UseStaticFiles();                   // 4. Serve static files
app.UseRouting();                       // 5. Route matching
app.UseCors();                          // 6. CORS policy
app.UseAuthentication();                // 7. Who are you?
app.UseAuthorization();                 // 8. Can you access?
app.UseRateLimiter();                   // 9. Rate limiting
app.UseResponseCaching();               // 10. Response cache
app.MapControllers();                   // 11. Endpoints

自定义中间件模式

public class RequestTimingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<RequestTimingMiddleware> _logger;

    public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var sw = Stopwatch.StartNew();
        await _next(context);
        _logger.LogInformation("Request {Path} completed in {Elapsed}ms",
            context.Request.Path, sw.ElapsedMilliseconds);
    }
}

配置模式

强类型选项

// appsettings.json
{
  "EmailSettings": {
    "SmtpServer": "smtp.example.com",
    "Port": 587
  }
}

// Registration
builder.Services.Configure<EmailSettings>(
    builder.Configuration.GetSection("EmailSettings"));

// Usage
public class EmailService(IOptions<EmailSettings> options)
{
    private readonly EmailSettings _settings = options.Value;
}

基于环境的配置

builder.Configuration
    .AddJsonFile("appsettings.json", optional: false)
    .AddJsonFile($"appsettings.{builder.Environment.EnvironmentName}.json", optional: true)
    .AddEnvironmentVariables()
    .AddUserSecrets<Program>(optional: true);

安全模式

身份验证设置

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!))
        };
    });

授权策略

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AdminOnly", policy =>
        policy.RequireRole("Admin"));
    options.AddPolicy("MinAge18", policy =>
        policy.RequireClaim("Age", "18", "19", "20")); // simplified
});

应避免的反模式

反模式	问题所在	更好的做法
new HttpClient()	套接字耗尽	IHttpClientFactory
同步等待异步任务（Task.Result）	线程池耗尽	正确使用 await
在 appsettings.json 中存储密钥	安全风险	User Secrets、Key Vault
静默捕获所有异常	隐藏缺陷	使用 IExceptionHandler
在中间件中使用 async void	导致进程崩溃	async Task
缺少 HTTPS 重定向	安全风险	UseHttpsRedirection()

性能最佳实践

1. 到处使用 async/await — 避免同步阻塞调用
2. 正确使用 DbContext 池 — 使用作用域生命周期
3. 启用响应压缩 — UseResponseCompression()
4. 使用输出缓存 — .NET 7+ 使用 UseOutputCache()
5. 使用诊断工具进行性能分析 — Visual Studio Diagnostic Tools、PerfView
6. 避免在热点路径中分配内存 — 使用 Span<T>、对象池

交付

• 生产环境可信的 ASP.NET Core 代码和配置
• 清晰的请求管道和托管方案
• 与受影响的端点和中间件相匹配的验证
• 正确配置的安全标头和 HTTPS

验证

• 中间件顺序经过有意安排并有文档说明
• 安全和配置变更明确
• 端点行为通过测试或冒烟检查覆盖
• 异步上下文中没有阻塞调用
• 未将密钥提交到源代码管理
• 已实现满足生产就绪要求的运行状况检查