dotnet-10-csharp-14

.NET 10 和 C# 14 最佳实践

.NET 10（LTS，2025 年 11 月）和 C# 14。涵盖最小 API，不包括 MVC。

官方文档： .NET 10 | C# 14 | ASP.NET Core 10

详细文件

文件	主题
csharp-14.md	扩展块、field 关键字、空条件赋值
minimal-apis.md	验证、TypedResults、筛选器、模块化单体、垂直切片
security.md	JWT 身份验证、CORS、速率限制、OpenAPI 安全性、中间件顺序
infrastructure.md	Options、弹性、通道、运行状况检查、缓存、Serilog、EF Core、键控服务
testing.md	WebApplicationFactory、集成测试、身份验证测试
anti-patterns.md	HttpClient、DI 生命周期捕获、阻塞异步操作、N+1 查询
libraries.md	MediatR、FluentValidation、Mapster、ErrorOr、Polly、Aspire

---

快速入门

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>14</LangVersion>
    <Nullable>enable</Nullable>
  </PropertyGroup>
</Project>

var builder = WebApplication.CreateBuilder(args);

// Core services
builder.Services.AddValidation();
builder.Services.AddProblemDetails();
builder.Services.AddOpenApi();

// Security
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
builder.Services.AddRateLimiter(opts => { /* see security.md */ });

// Infrastructure
builder.Services.AddHealthChecks();
builder.Services.AddOutputCache();

// Modules
builder.Services.AddUsersModule();

var app = builder.Build();

// Middleware (ORDER MATTERS - see security.md)
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseCors();
app.UseRateLimiter();
app.UseAuthentication();
app.UseAuthorization();
app.UseOutputCache();

app.MapOpenApi();
app.MapHealthChecks("/health");
app.MapUsersEndpoints();
app.Run();

---

决策流程图

Result 与 Exception

digraph {
    "Error type?" [shape=diamond];
    "Expected?" [shape=diamond];
    "Result<T>/ErrorOr" [shape=box];
    "Exception" [shape=box];
    "Error type?" -> "Expected?" [label="domain"];
    "Error type?" -> "Exception" [label="infrastructure"];
    "Expected?" -> "Result<T>/ErrorOr" [label="yes"];
    "Expected?" -> "Exception" [label="no"];
}

IOptions 选择

digraph {
    "Runtime changes?" [shape=diamond];
    "Per-request?" [shape=diamond];
    "IOptions<T>" [shape=box];
    "IOptionsSnapshot<T>" [shape=box];
    "IOptionsMonitor<T>" [shape=box];
    "Runtime changes?" -> "IOptions<T>" [label="no"];
    "Runtime changes?" -> "Per-request?" [label="yes"];
    "Per-request?" -> "IOptionsSnapshot<T>" [label="yes"];
    "Per-request?" -> "IOptionsMonitor<T>" [label="no"];
}

Channel 类型

digraph {
    "Trust producer?" [shape=diamond];
    "Can drop?" [shape=diamond];
    "Bounded+Wait" [shape=box,style=filled,fillcolor=lightgreen];
    "Bounded+Drop" [shape=box];
    "Unbounded" [shape=box];
    "Trust producer?" -> "Unbounded" [label="yes"];
    "Trust producer?" -> "Can drop?" [label="no"];
    "Can drop?" -> "Bounded+Drop" [label="yes"];
    "Can drop?" -> "Bounded+Wait" [label="no"];
}

---

关键模式摘要

C# 14 扩展块

extension<T>(IEnumerable<T> source)
{
    public bool IsEmpty => !source.Any();
}

.NET 10 内置验证

builder.Services.AddValidation();
app.MapPost("/users", (UserDto dto) => TypedResults.Ok(dto));

TypedResults（始终使用）

app.MapGet("/users/{id}", async (int id, IUserService svc) =>
    await svc.GetAsync(id) is { } user
        ? TypedResults.Ok(user)
        : TypedResults.NotFound());

模块模式

public static class UsersModule
{
    public static IServiceCollection AddUsersModule(this IServiceCollection s) => s
        .AddScoped<IUserService, UserService>();

    public static IEndpointRouteBuilder MapUsersEndpoints(this IEndpointRouteBuilder app)
    {
        var g = app.MapGroup("/api/users").WithTags("Users");
        g.MapGet("/{id}", GetUser.Handle);
        return app;
    }
}

HTTP 弹性

builder.Services.AddHttpClient<IApi, ApiClient>()
    .AddStandardResilienceHandler();

错误处理（RFC 9457）

builder.Services.AddProblemDetails();
app.UseExceptionHandler();
app.UseStatusCodePages();

---

必须遵循的模式（始终使用）

任务	✅ 始终使用	❌ 绝不使用
扩展成员	C# 14 extension<T>() 块	传统的 this 扩展方法
属性验证	C# 14 field 关键字	手动后备字段
空值赋值	obj?.Prop = value	if (obj != null) obj.Prop = value
API 返回值	TypedResults.Ok()	Results.Ok()
Options 验证	.ValidateOnStart()	缺少验证
HTTP 弹性	AddStandardResilienceHandler()	手动配置 Polly
时间戳	DateTime.UtcNow	DateTime.Now

---

快速参考卡

┌─────────────────────────────────────────────────────────────────┐
│                    .NET 10 / C# 14 PATTERNS                      │
├─────────────────────────────────────────────────────────────────┤
│ EXTENSION PROPERTY:  extension<T>(IEnumerable<T> s) {           │
│                        public bool IsEmpty => !s.Any();         │
│                      }                                          │
├─────────────────────────────────────────────────────────────────┤
│ FIELD KEYWORD:       public string Name {                       │
│                        get => field;                            │
│                        set => field = value?.Trim();            │
│                      }                                          │
├─────────────────────────────────────────────────────────────────┤
│ OPTIONS VALIDATION:  .BindConfiguration(Section)                │
│                      .ValidateDataAnnotations()                 │
│                      .ValidateOnStart();   // CRITICAL!         │
├─────────────────────────────────────────────────────────────────┤
│ HTTP RESILIENCE:     .AddStandardResilienceHandler();           │
├─────────────────────────────────────────────────────────────────┤
│ TYPED RESULTS:       TypedResults.Ok(data)                      │
│                      TypedResults.NotFound()                    │
│                      TypedResults.Created(uri, data)            │
├─────────────────────────────────────────────────────────────────┤
│ ERROR PATTERN:       ErrorOr<User> or user?.Match(...)          │
├─────────────────────────────────────────────────────────────────┤
│ IOPTIONS:            IOptions<T>        → startup, no reload    │
│                      IOptionsSnapshot<T> → per-request reload   │
│                      IOptionsMonitor<T>  → live + OnChange()    │
└─────────────────────────────────────────────────────────────────┘

---

反模式快速参考

反模式	修复方法
new HttpClient()	注入 HttpClient 或 IHttpClientFactory
Results.Ok()	TypedResults.Ok()
手动配置 Polly	AddStandardResilienceHandler()
Singleton → Scoped	使用 IServiceScopeFactory
GetAsync().Result	await GetAsync()
用异常控制流程	使用 ErrorOr<T> Result 模式
DateTime.Now	DateTime.UtcNow
缺少 .ValidateOnStart()	始终在 Options 注册时添加

完整列表请参见 anti-patterns.md。

---

库快速参考

库	包	用途
MediatR	MediatR	CQRS
FluentValidation	FluentValidation.DependencyInjectionExtensions	验证
Mapster	Mapster.DependencyInjection	映射
ErrorOr	ErrorOr	Result 模式
Polly	Microsoft.Extensions.Http.Resilience	弹性
Serilog	Serilog.AspNetCore	日志记录

用法示例请参见 libraries.md。