w wyl123ly 的博客
MD

后端-03-ASPNET-Core

48 KB 2026.10.11 原文件

后端-03-ASPNET-Core

这篇笔记讲什么

ASP.NET Core 是 .NET 平台上的跨平台、开源、模块化 Web 框架。本文从「请求管线 + 依赖注入 + 配置」三条主线出发,讲清中间件顺序、三种服务生命周期、EF Core 的跟踪与 N+1 问题,最后给出一个完整可运行的最小 API + EF Core CRUD 示例。

读者本机环境为 .NET SDK 10.0.401(LTS),示例以 .NET 10 为准;涉及版本差异处标注「以官方最新文档为准」。

是什么

ASP.NET Core 是用于构建 Web 应用与 HTTP API 的框架,它把「一个 HTTP 请求如何被处理」抽象成一条请求管线(request pipeline),管线由若干中间件(middleware)首尾相接组成。框架本身几乎不假设你要做什么:路由、认证、序列化、静态文件全都是可插拔的中间件或服务。

它和旧 ASP.NET(.NET Framework 时代的 System.Web)是两套东西:

对比维度旧 ASP.NET(.NET Framework)ASP.NET Core(.NET 5+)
运行平台仅 WindowsWindows / Linux / macOS
托管方式必须寄宿在 IIS 中Kestrel 自托管,IIS/Nginx 只做反向代理
开源否是(MIT 许可)
请求管线HttpModule / HttpHandler中间件(app.Use*)
依赖注入无内置容器内置,全框架可注入
配置web.config多提供程序分层覆盖
版本演进4.8 后停止新功能每年一个主版本,LTS 与 STS 交替

「模块化」的具体含义

用 dotnet new web 建出来的项目只有十几行代码、零个 NuGet 依赖,却能跑起来。你每装一个包(比如 Microsoft.AspNetCore.Authentication.JwtBearer)就获得一组中间件和 DI 扩展方法,不装就没有——这就是模块化。

为什么这样设计

  • 为什么要中间件管线? 旧 ASP.NET 的 HttpModule 顺序由 web.config 间接决定,很难推理。中间件把顺序显式写在 Program.cs 里,从上到下就是请求进入的顺序,从下到上是响应返回的顺序——顺序即配置,可读性和可测性都大幅提升。
  • 为什么要内置依赖注入(DI, Dependency Injection)? 想让「测试时把真实数据库换成内存库」这件事不需要改业务代码,就必须让框架负责创建对象。ASP.NET Core 把 DI 做进内核,ILogger、IConfiguration、DbContext 全部走容器。
  • 为什么要分层配置? 同一份代码要在开发机、CI、生产容器里跑,凭据和连接串必然不同。分层配置让「代码不变、环境决定值」成为可能。
  • 为什么要跨平台? 容器化部署(见 后端-07-Docker与容器化)几乎全在 Linux 上,框架不支持 Linux 就无法进入现代交付流程。

核心内容

一、创建项目与两种 API 风格

dotnet new webapi -n DemoApi          # 最小 API 模板(.NET 8+ 默认)
dotnet new webapi -n DemoApi --use-controllers   # 控制器(Controller)风格
dotnet new web -n DemoEmpty           # 空项目,自己搭管线
dotnet new sln -n Demo && dotnet sln add DemoApi

模板短名与参数以官方最新文档为准(dotnet new webapi --help 查看本机支持项)。

对比项最小 API(Minimal API)控制器(Controller)
写法app.MapGet("/x", handler) 写在 Program.cs类 + [ApiController] + [Route]
代码量极少中等,样板较多
过滤器体系终结点过滤器(AddEndpointFilter)动作过滤器 / 异常过滤器 / 结果过滤器
模型验证自动绑定 + DataAnnotations(.NET 10 原生支持)ModelState + 自动 400
约定式组织需手动分组或拆文件天然按控制器分文件
适合场景微服务、少量端点、BFF、Serverless大型团队、端点很多、需要复杂过滤器

选型建议

端点数在 30 个以内、团队规模小 → 最小 API 更快。端点上百、需要复用复杂过滤器与统一约定 → 控制器。两者可以在同一个应用中共存,不存在二选一。

开发循环用热重载:

dotnet watch run          # 改代码自动重启/热重载
dotnet watch --no-hot-reload run   # 只重启,不热重载(排查热重载引起的怪异行为时用)

二、请求管线与中间件

Program.cs 的启动流程固定是四段式:

var builder = WebApplication.CreateBuilder(args); // 1. 创建构建器,加载配置
builder.Services.AddXxx();                        // 2. 注册服务到 DI 容器
var app = builder.Build();                        // 3. 构建应用(容器冻结)
app.UseXxx(); app.MapXxx();                       // 4. 组装中间件与终结点
app.Run();                                        // 5. 启动并阻塞

中间件是有 next 的委托,终结点是管线的终点。区别如下:

写法是否调用下一个作用
app.Use(async (ctx, next) => { ... await next(); ... })是可以在前后各做一件事(计时、日志)
app.Run(async ctx => { ... })否终端中间件,管线到此结束
app.MapGet(...) / app.MapPost(...)—注册终结点(Endpoint),由路由中间件匹配
app.Map("/path", branch => ...)—按路径前缀分支出一条子管线(注意与 MapGet 同名不同义)
app.UseWhen(cond, branch => ...)条件不成立时继续主管线条件分支,执行完会重新汇合主管线

app.Use 与 app.Map 的本质差别:前者改的是管线结构(所有请求都要穿过),后者注册的是终结点元数据(只有路由匹配的请求才会走到)。

中间件顺序规则

WebApplication 会根据条件自动补上几个中间件:开发环境下补 UseDeveloperExceptionPage;调用过 Map* 且你没显式调 UseRouting 时,在管线开头补 UseRouting、末尾补 UseEndpoints;检测到认证/授权服务时在 UseRouting 之后补 UseAuthentication、UseAuthorization。但只要涉及安全,就应该显式写出顺序,不要依赖自动推断。

推荐顺序与规则:

顺序中间件为什么必须在这个位置
1UseForwardedHeaders反代后必须最先跑,否则后续中间件看到的都是代理的 IP 与 scheme
2UseExceptionHandler / UseDeveloperExceptionPage必须能在下游任何位置抛出的异常上兜底
3UseHsts只加响应头,在发响应前即可
4UseHttpsRedirection在用到 URL 的中间件之前
5UseStaticFiles尽早短路,避免静态资源也走完整管线(它不做授权检查)
6UseRequestLocalization必须在任何检查请求区域性的中间件之前
7UseRouting先匹配出终结点,后面的中间件才能读到端点元数据
8UseCors必须在 UseAuthentication、UseAuthorization、UseResponseCaching 之前
9UseRateLimiter用 [EnableRateLimiting] 等按终结点的限流 API 时,必须在 UseRouting 之后;只用全局限流器时可以放在 UseRouting 之前
10UseAuthentication必须在 UseAuthorization 之前;放在 UseRouting 之后以便路由信息参与认证决策
11UseAuthorization紧接认证之后,依据 HttpContext.User 做判定
12UseSession在响应 Cookie 的中间件之前、终结点之前
13UseResponseCaching / UseResponseCompressionUseCors 必须在其之前;压缩与缓存的相对顺序取决于业务
14Map* 终结点管线终点

最容易踩的顺序坑

- UseAuthorization 写在 UseAuthentication 之前:此时 HttpContext.User 还是匿名的,[Authorize] 一律 401——而且不报错,只是「登录了也没用」。

- UseCors 写在 UseAuthentication 之后:预检请求(OPTIONS)会被认证拦下返回 401,浏览器表现为「跨域失败但后端日志没有任何业务请求」。

- UseStaticFiles 写在 UseAuthorization 之后:以为静态资源受保护,实际上 UseStaticFiles 放在前面时完全不检查授权,wwwroot 下的文件一律公开。

写一个自定义中间件
// 约定式中间件:构造函数注入单例,InvokeAsync 注入 Scoped/Transient
public sealed class RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
{
    // 构造函数注入的作用域服务会被「提升」为单例,所以 Scoped 服务只能注入 InvokeAsync
    public async Task InvokeAsync(HttpContext context)
    {
        var sw = System.Diagnostics.Stopwatch.StartNew();
        try
        {
            await next(context);              // 交给下游
        }
        finally
        {
            sw.Stop();
            // 结构化日志:用占位符而非字符串拼接,值会被单独记录成字段
            logger.LogInformation("完成 {Method} {Path} -> {StatusCode},耗时 {ElapsedMs} ms",
                context.Request.Method, context.Request.Path,
                context.Response.StatusCode, sw.ElapsedMilliseconds);
        }
    }
}

// 注册(在 app.UseRouting() 之前或之后都行,按需要的时机选择)
app.UseMiddleware<RequestTimingMiddleware>();

三、依赖注入

三种生命周期的差别是实例何时被复用:

生命周期注册方法何时创建何时释放适用
Transient(瞬态)AddTransient<T>()每次解析都新建随持有者一起释放无状态、极轻量的工具类
Scoped(作用域)AddScoped<T>()每个 HTTP 请求一次请求结束时DbContext、当前用户上下文、工作单元
Singleton(单例)AddSingleton<T>()首次解析时创建一次应用关闭时配置、缓存、HttpClient 工厂、无状态服务

选择原则(背下来):

  1. 默认先想 Scoped。
  2. 有状态且需要跨请求共享 → Singleton,但必须线程安全。
  3. 无状态且创建廉价 → Transient。
  4. 绝不能让长生命周期服务持有短生命周期服务(Singleton 持 Scoped)——框架的 ValidateScopes 在开发环境会直接抛 InvalidOperationException: Cannot resolve scoped service ... from root provider.,但在 Release 下默认关闭,于是变成只在生产出现的偶发 bug。注意:ValidateScopes / ValidateOnBuild 默认只在开发环境开启,出于性能考虑在非开发环境是关闭的。
经典事故:Singleton 捕获 Scoped 导致 DbContext 被跨请求复用
// ❌ 错误示范:单例里存了 DbContext
public sealed class BadCacheService
{
    private readonly AppDbContext _db;           // Scoped 被提升成 Singleton
    public BadCacheService(AppDbContext db) => _db = db;

    public async Task<int> CountAsync() => await _db.Products.CountAsync();
}
builder.Services.AddScoped<AppDbContext>();
builder.Services.AddSingleton<BadCacheService>();   // 启动即报错(开发环境)

// ✅ 正确做法一:生命周期对齐,改成 Scoped
builder.Services.AddScoped<BadCacheService>();

// ✅ 正确做法二:确有单例需求时,注入 IServiceScopeFactory,手开作用域
public sealed class GoodCacheService(IServiceScopeFactory scopeFactory)
{
    public async Task<int> CountAsync()
    {
        using var scope = scopeFactory.CreateScope();          // 一次独立作用域
        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        return await db.Products.CountAsync();
    }
}

DbContext 不是线程安全的,一旦被单例持有并被多个请求并发调用,症状是随机的 InvalidOperationException: A second operation was started on this context 或数据串请求(用户 A 读到用户 B 的数据)。

解析服务与注册技巧
// GetRequiredService:解析不到就抛异常,业务代码优先用它(fail fast)
var svc = app.Services.GetRequiredService<IMyService>();
// GetService:解析不到返回 null,只有在「可选依赖」时才用
var maybe = app.Services.GetService<IMyService>();

// 泛型开放类型注册:一次注册服务全部 T
builder.Services.AddScoped(typeof(IRepository<>), typeof(EfRepository<>));

// 工厂委托注册:需要在构造时算点什么、或注入非 DI 创建的对象
builder.Services.AddSingleton<IClock>(_ => new SystemClock(TimeProvider.System));
builder.Services.AddSingleton(sp =>
{
    var cfg = sp.GetRequiredService<IConfiguration>();
    return new SmsClient(cfg["Sms:Endpoint"] ?? throw new InvalidOperationException("缺少 Sms:Endpoint"));
});

// 键控服务(Keyed Services,.NET 8+):同一接口按 key 区分多个实现
builder.Services.AddKeyedSingleton<ICache, RedisCache>("redis");
builder.Services.AddKeyedSingleton<ICache, MemoryCache>("memory");
app.MapGet("/cached", ([FromKeyedServices("redis")] ICache cache) => cache.Get("k"));

不要在中间件构造函数里注入 Scoped 服务

中间件是应用启动时构造一次的,构造函数注入的 Scoped 服务等同于单例。正确做法是把 Scoped 依赖放到 InvokeAsync(HttpContext) 的参数里,或改用基于工厂的中间件(IMiddleware)。

IOptions 模式:把配置读成强类型对象
public sealed class JwtOptions
{
    public const string SectionName = "Jwt";
    public string Issuer { get; set; } = string.Empty;
    public string Audience { get; set; } = string.Empty;
    public int ExpiresMinutes { get; set; } = 60;
}

builder.Services.Configure<JwtOptions>(builder.Configuration.GetSection(JwtOptions.SectionName));

public sealed class TokenService(IOptions<JwtOptions> options, IOptionsMonitor<JwtOptions> monitor)
{
    private readonly JwtOptions _opt = options.Value;    // IOptions:启动时快照,之后不随配置变化
    public int ExpiresMinutes => _opt.ExpiresMinutes;

    // IOptionsMonitor:读取「当前值」,配置热重载(appsettings.json 改动)后自动更新
    public string CurrentIssuer => monitor.CurrentValue.Issuer;
}
接口是否随配置变更更新是否支持命名配置典型用途
IOptions<T>否(启动快照)否启动后不变的配置
IOptionsSnapshot<T>是(每请求重新计算)是Scoped 场景下要读最新值
IOptionsMonitor<T>是(变更时回调,可注册 OnChange)是单例服务里读最新值

四、配置系统

配置是键值对的有序叠加,后加载的覆盖先加载的。默认应用配置源优先级从高到低:

  1. 命令行参数
  2. 不带 ASPNETCORE_ / DOTNET_ 前缀的环境变量
  3. 用户机密(仅 Development 环境)
  4. appsettings.{Environment}.json
  5. appsettings.json
  6. 主机配置(DOTNET_、ASPNETCORE_ 前缀的环境变量)
需求做法
分层键用 : 分隔,如 ConnectionStrings:Default
环境变量里的分层键用双下划线 __(所有平台通用),如 ConnectionStrings__Default
覆盖环境名ASPNETCORE_ENVIRONMENT=Production
指定端口ASPNETCORE_URLS=http://+:8080
临时覆盖单个值dotnet run --Jwt:ExpiresMinutes=5
开发期存放机密dotnet user-secrets
# 用户机密:把机密存到项目目录之外的用户配置文件里,避免误提交
dotnet user-secrets init                       # 在 csproj 里写入 UserSecretsId
dotnet user-secrets set "ConnectionStrings:Default" "Host=localhost;Database=demo;Username=app;Password=dev-only"
dotnet user-secrets list
dotnet user-secrets remove "ConnectionStrings:Default"
dotnet user-secrets clear

为什么绝不能把连接字符串提交进仓库

1. Git 历史是不可撤销的:删掉文件后,git log -p 依然能翻出明文;仓库一旦被 fork 或克隆,凭据永久泄露。

2. 生产库的连接串通常含高权限账号,泄露等于直接丢库(见 后端-09-后端安全与性能 中的注入与凭据管理)。

3. 合规审查(等保、SOC 2)会把硬编码凭据列为高危项。

正确做法:本地用 dotnet user-secrets;生产用环境变量或密钥管理服务(Key Vault / Secrets Manager),并让 appsettings.json 里只留占位为空的结构。

五、控制器与模型绑定

using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Mvc;

public sealed record CreateProductRequest(
    [property: Required, StringLength(100, MinimumLength = 1)] string Name,
    [property: Range(0.01, 1_000_000)] decimal Price,
    [property: Range(0, 100_000)] int Stock);

[ApiController]                                  // 开启自动模型验证 400 与推断绑定源
[Route("api/[controller]")]                      // 约定路由:/api/products
public sealed class ProductsController(AppDbContext db) : ControllerBase
{
    // 路由特性:[controller]/[action] 占位符;{id:int} 是路由约束,非 int 直接 404
    [HttpGet("{id:int}")]
    public async Task<ActionResult<ProductDto>> GetById(
        [FromRoute] int id,                      // 从路径取
        [FromQuery] bool includeCategory = false,// 从查询串取
        [FromHeader(Name = "X-Trace-Id")] string? traceId = null, // 从请求头取
        CancellationToken ct = default)
    {
        var dto = await db.Products
            .AsNoTracking()
            .Where(p => p.Id == id)
            .Select(p => new ProductDto(p.Id, p.Name, p.Price))   // 投影,避免过度取数
            .FirstOrDefaultAsync(ct);

        return dto is null
            ? Problem(statusCode: StatusCodes.Status404NotFound, title: "商品不存在", detail: $"id={id}")
            : Ok(dto);
    }

    [HttpPost]
    public async Task<ActionResult<ProductDto>> Create(
        [FromBody] CreateProductRequest req,     // 从 JSON 请求体取
        CancellationToken ct)
    {
        // [ApiController] 会在进入方法体前自动校验 DataAnnotations,失败直接返回 400 + ProblemDetails
        if (!ModelState.IsValid) return ValidationProblem(ModelState);   // 显式写法,便于自定义

        var entity = new Product { Name = req.Name, Price = req.Price, Stock = req.Stock };
        db.Products.Add(entity);
        await db.SaveChangesAsync(ct);
        return CreatedAtAction(nameof(GetById), new { id = entity.Id },
            new ProductDto(entity.Id, entity.Name, entity.Price));
    }
}
绑定源特性取值位置何时可省略(默认推断)
[FromRoute]路由模板中的占位符参数名与路由参数同名时
[FromQuery]?key=value简单类型默认走这里
[FromBody]请求体(JSON)复杂类型默认走这里,一个动作只能有一个
[FromHeader]请求头永不推断,必须显式写
[FromForm]表单 / 文件上传请求 Content-Type 为表单时
[FromServices]DI 容器最小 API 中自动推断
校验与标准错误响应
public sealed record RegisterRequest(
    [property: Required, EmailAddress] string Email,
    [property: Required, MinLength(12)] string Password,
    [property: Range(18, 120)] int Age);

校验失败时,ASP.NET Core 返回 ProblemDetails(RFC 9457 定义的机器可读错误格式):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Age": ["The field Age must be between 18 and 120."],
    "Email": ["The Email field is not a valid e-mail address."]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

统一注册异常处理,让 500 也返回 ProblemDetails:

builder.Services.AddProblemDetails();            // 注册默认的 IProblemDetailsService
app.UseExceptionHandler();                       // 无参重载:自动用 ProblemDetails 输出
app.UseStatusCodePages();                        // 404/405 等无正文响应也补上 ProblemDetails

IActionResult 与 ActionResult<T> 的取舍:

返回类型语义是否需要显式转换是否利于 OpenAPI 推断
IActionResult只表达状态码与响应否弱(需手写 [ProducesResponseType])
ActionResult<T>既能返回 T,也能返回 IActionResult否(有隐式转换)强,框架能推断出 200 的模型
T直接返回数据,恒为 200—强,但无法表达其他状态码

优先用 ActionResult<T>

它兼顾了「返回裸对象」的简洁和「返回错误响应」的灵活性,并且让 Swagger/OpenAPI 能自动生成正确的响应模型。

六、最小 API 写法

var group = app.MapGroup("/api/v1/products")     // 路由组:统一前缀 + 统一约定
               .WithTags("Products")             // OpenAPI 分组
               .RequireAuthorization();          // 组内所有终结点都要认证

group.MapGet("/{id:int}", async (int id, AppDbContext db, CancellationToken ct) =>
{
    var dto = await db.Products.AsNoTracking()
        .Where(p => p.Id == id)
        .Select(p => new ProductDto(p.Id, p.Name, p.Price))
        .FirstOrDefaultAsync(ct);
    // 优先 TypedResults 而非 Results:返回类型是强类型,集成测试可直接断言
    return dto is null ? TypedResults.NotFound() : TypedResults.Ok(dto);
})
.WithName("GetProductById")                      // 命名终结点,可用 LinkGenerator 生成 URL
.Produces<ProductDto>(StatusCodes.Status200OK)
.ProducesProblem(StatusCodes.Status404NotFound);

group.MapPost("/", async (CreateProductRequest req, AppDbContext db, CancellationToken ct) =>
{
    var entity = new Product { Name = req.Name, Price = req.Price, Stock = req.Stock };
    db.Products.Add(entity);
    await db.SaveChangesAsync(ct);
    return TypedResults.Created($"/api/v1/products/{entity.Id}",
        new ProductDto(entity.Id, entity.Name, entity.Price));
})
.AddEndpointFilter(async (ctx, next) =>         // 终结点过滤器:横切逻辑
{
    var logger = ctx.HttpContext.RequestServices.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("调用 {Name}", ctx.HttpContext.GetEndpoint()?.DisplayName);
    var result = await next(ctx);              // 调用实际处理程序
    return result;
});

过滤器顺序

添加到同一个组或同一个终结点上的过滤器按添加顺序执行(next 之前的部分外层先跑);添加到不同组上的过滤器,其相对顺序取决于组的嵌套关系,与外层添加的先后无关。

参数绑定是最小 API 的特色:简单类型默认来自路由/查询串,复杂类型来自 JSON 请求体,DI 中注册的服务自动注入。特殊类型(HttpContext、HttpRequest、CancellationToken、ClaimsPrincipal、Stream)也会自动绑定。

app.MapGet("/{id:int}", (int id,                    // 路由值
                         int page,                  // 查询串
                         [FromHeader(Name = "X-Trace-Id")] string? traceId,  // 请求头
                         IProductService svc) =>     // DI 服务
    svc.Get(id, page));

七、EF Core

EF Core(Entity Framework Core) 是 .NET 的 ORM(Object-Relational Mapping,对象关系映射)。核心对象是 DbContext(工作单元 + 会话)和 DbSet<T>(表)。

public sealed class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public int Stock { get; set; }
    public int CategoryId { get; set; }
    public Category? Category { get; set; }

    [Timestamp]                                   // 并发令牌(SQL Server rowversion)
    public byte[]? RowVersion { get; set; }
}

public sealed class Category
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public List<Product> Products { get; set; } = [];
}

public sealed class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Category> Categories => Set<Category>();

    protected override void OnModelCreating(ModelBuilder b)
    {
        b.Entity<Product>(e =>
        {
            e.Property(p => p.Name).HasMaxLength(100).IsRequired();
            // 金额必须指定精度,否则部分数据库默认会丢小数位
            e.Property(p => p.Price).HasPrecision(18, 2);
            e.HasIndex(p => p.Name);
        });
    }
}

// 注册:默认 Scoped 生命周期,正好对应「一个请求一个上下文」
builder.Services.AddDbContext<AppDbContext>(opt =>
    opt.UseSqlite(builder.Configuration.GetConnectionString("Default")));
    // 生产常用 UseNpgsql / UseSqlServer;SQLite 便于本地起步
迁移
dotnet tool install --global dotnet-ef        # 首次安装 EF 工具
dotnet add package Microsoft.EntityFrameworkCore.Design   # 设计时包,迁移必需
dotnet ef migrations add InitialCreate        # 生成迁移文件
dotnet ef migrations list                     # 查看已生成的迁移
dotnet ef database update                     # 应用到数据库
dotnet ef migrations script -o migrate.sql    # 生成 SQL 脚本(生产发布推荐先审核)
dotnet ef migrations remove                   # 撤销最后一次未应用的迁移

迁移的生产用法

dotnet ef database update 适合本地开发。生产环境应生成 SQL 脚本或迁移捆绑包,经审核后再执行,并且不要在应用启动时偷偷跑迁移——多实例同时启动会竞争执行迁移,造成锁表或半应用状态。

跟踪查询 vs 非跟踪查询
维度跟踪查询(默认)非跟踪 AsNoTracking()
是否记录更改是,SaveChanges 会持久化否,改了也不保存
标识解析(Identity Resolution)是,同一实体只返回同一实例否,同一实体多次出现会返回多个实例
内存与速度较慢、占用更多内存更快、更省内存
适用需要更新的场景只读查询(API 的 GET 绝大多数属于此类)
// 需要更新:用跟踪查询
var p = await db.Products.SingleAsync(x => x.Id == 1);
p.Price = 99.9m;
await db.SaveChangesAsync();                      // 自动生成 UPDATE

// 只读:用非跟踪,避免无谓的变更跟踪开销
var list = await db.Products.AsNoTracking().ToListAsync();

// 非跟踪但仍想保证「同一实体同一实例」时
var withIdentity = await db.Products.AsNoTrackingWithIdentityResolution().ToListAsync();

// 也可以整体改默认(读多写少的 API 常见做法)
// opt.UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking);
// 之后个别写操作查询用 .AsTracking() 显式恢复

投影后还跟踪吗

如果投影结果里不包含实体类型(例如 Select(p => new { p.Id, p.Name })),则不会跟踪任何东西;如果投影里包含实体本身(例如 Select(p => new { Product = p })),那些实体依然会被跟踪。

预加载与 N+1 问题
// ❌ N+1:先查 1 次分类,再为每个分类发 1 次查询 → 1 + N 次往返
var cats = await db.Categories.ToListAsync();
foreach (var c in cats)
{
    var products = await db.Products.Where(p => p.CategoryId == c.Id).ToListAsync();
}

// ✅ 方案一:Include / ThenInclude 预加载,一次 JOIN 取回
var catsWithProducts = await db.Categories
    .Include(c => c.Products)                       // 一级导航
        .ThenInclude(p => p.Category)               // 多级导航(此处演示语法)
    .AsNoTracking()
    .ToListAsync();

// ✅ 方案二(大结果集首选):投影到 DTO,只取需要的列
var dtos = await db.Categories
    .AsNoTracking()
    .Select(c => new CategoryDto(
        c.Id,
        c.Name,
        c.Products.Select(p => new ProductDto(p.Id, p.Name, p.Price)).ToList()))
    .ToListAsync();
方案SQL 形态取数风险
Include一条 JOIN / 多结果集取回实体全部列一对多 JOIN 会产生笛卡尔积膨胀
Select 投影到 DTO一条精简 SQL只取用到的列需维护 DTO 类型
显式 Load() / 手动查询多条可控容易写出 N+1
并发令牌与乐观锁
public sealed class Product
{
    // ... 其他属性
    [ConcurrencyCheck]                       // 通用做法:把某列作为并发令牌
    public Guid Version { get; set; } = Guid.NewGuid();
}

// 保存时 EF Core 会自动加上 WHERE Version = @oldVersion
try
{
    await db.SaveChangesAsync();
}
catch (DbUpdateConcurrencyException ex)
{
    // 冲突说明在你读取之后,别人已经改过 → 返回 409 让客户端重新加载后重试
    var entry = ex.Entries.Single();
    var dbValues = await entry.GetDatabaseValuesAsync();
    return dbValues is null
        ? Results.NotFound("数据已被删除")
        : Results.Conflict("数据已被他人修改,请刷新后重试");
}

乐观锁(optimistic locking)假设冲突很少,靠「版本号比对」在写入时检测;悲观锁(pessimistic locking)靠数据库锁提前阻塞。Web 场景下优先乐观锁,因为它不持有长事务、不占用连接。

连接池与 DbContext 的短生命周期原则
  • DbContext 不是线程安全的,也不该长期存活:它内部缓存所有被跟踪的实体,活得越久内存越大、越容易读到过期数据。
  • 默认 Scoped(一请求一实例)就是正确姿势,不要改成 Singleton,也不要自己 static 缓存它。
  • 数据库连接由 ADO.NET 连接池管理:DbContext 释放时把连接归还池而不是真正关闭,所以「一请求一 DbContext」并不会导致频繁建连。
  • 长耗时任务(导出、批处理)不要挂在请求的 DbContext 上,应新开作用域或改用后台队列。

八、日志与健康检查

// 内置 ILogger 是结构化日志:占位符 {Name} 会被记录为独立字段,而非拼进字符串
logger.LogInformation("订单 {OrderId} 创建成功,金额 {Amount}", order.Id, order.Total);

// 日志级别(从低到高):Trace < Debug < Information < Warning < Error < Critical
// 生产环境通常 Default=Information,框架日志压到 Warning 降低噪音
builder.Logging.AddJsonConsole();                 // 输出 JSON,便于日志系统采集
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Warning"
    }
  }
}

为什么强调结构化日志

把 "订单 " + id + " 创建成功" 写进日志,只能靠正则去捞;用 log.LogInformation("订单 {OrderId} 创建成功", id),OrderId 会成为一个可查询字段,日志平台(ELK/Loki)能直接按它做聚合与告警,见 后端-08-部署与运维基础。

健康检查端点:

builder.Services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>("database");   // 需要 Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

app.MapHealthChecks("/healthz");                     // 存活探针:进程是否活着
app.MapHealthChecks("/readyz", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready") // 就绪探针:依赖是否可用
});
探针语义失败后果
liveness(存活)进程是否需要重启容器被重启
readiness(就绪)是否能接收流量从负载均衡摘除,不重启

九、测试(WebApplicationFactory 集成测试)

思路:用真实的 Program 启动一个内存中的服务器,把外部依赖替换成测试替身,然后用 HttpClient 发真实 HTTP 请求。

using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;

public sealed class ApiFactory : WebApplicationFactory<Program>
{
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.UseEnvironment("Testing");
        builder.ConfigureServices(services =>
        {
            // 移除真实的数据库注册,换成内存库
            services.RemoveAll<DbContextOptions<AppDbContext>>();
            services.RemoveAll<AppDbContext>();
            services.AddDbContext<AppDbContext>(o => o.UseInMemoryDatabase("test-db"));
        });
    }
}

public class ProductsApiTests(ApiFactory factory) : IClassFixture<ApiFactory>
{
    [Fact]
    public async Task 创建商品_应返回201与Location头()
    {
        var client = factory.CreateClient();
        var resp = await client.PostAsJsonAsync("/api/v1/products",
            new { name = "键盘", price = 199.0m, stock = 10 });

        Assert.Equal(HttpStatusCode.Created, resp.StatusCode);
        Assert.NotNull(resp.Headers.Location);
        var dto = await resp.Content.ReadFromJsonAsync<ProductDto>();
        Assert.Equal("键盘", dto!.Name);
    }
}

让 Program 可被测试项目引用

最小 API 的 Program.cs 默认是隐式 internal 的顶级语句类。在 Program.cs 末尾加一行 public partial class Program { },测试项目才能写 WebApplicationFactory<Program>。

十、发布与部署要点

dotnet publish -c Release -o ./publish                      # 框架依赖发布
dotnet publish -c Release -r linux-x64 --self-contained      # 自包含发布(含运行时,镜像更大)
dotnet publish -c Release /p:PublishAot=true                 # AOT 原生编译(启动快、体积小,有反射限制)
dotnet publish -c Release /p:PublishSingleFile=true          # 单文件

反向代理下的 ForwardedHeaders:Nginx / 云负载均衡会终止 TLS 并把真实信息放进 X-Forwarded-For / X-Forwarded-Proto。不处理的话,应用看到的客户端 IP 都是代理 IP、Request.Scheme 永远是 http,于是重定向会退化、限流按代理 IP 计费、审计日志记错人。

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    // 明确只信任已知代理,避免客户端伪造 X-Forwarded-For 绕过限流
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.KnownProxies.Add(System.Net.IPAddress.Parse("10.0.0.10"));
    // 容器/云环境网段常变,可用 KnownNetworks 指定网段;不要图省事 Clear() 掉全部限制
});

app.UseForwardedHeaders();   // 必须是管线里的第一个中间件

容器化与运维的完整内容见 后端-07-Docker与容器化 与 后端-08-部署与运维基础。ASP.NET Core 官方容器镜像、非 root 用户、ASPNETCORE_URLS 与探针配置都在那两篇里展开。

完整可运行示例:最小 API + EF Core CRUD

dotnet new web -n DemoApi && cd DemoApi
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.AspNetCore.OpenApi
dotnet tool install --global dotnet-ef

appsettings.json:

{
  "ConnectionStrings": { "Default": "Data Source=demo.db" },
  "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } },
  "AllowedHosts": "*"
}

Program.cs(完整):

using System.ComponentModel.DataAnnotations;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseSqlite(builder.Configuration.GetConnectionString("Default")));
builder.Services.AddProblemDetails();
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

// 仅在开发环境自动建库,生产走迁移脚本
if (app.Environment.IsDevelopment())
{
    using var scope = app.Services.CreateScope();
    await scope.ServiceProvider.GetRequiredService<AppDbContext>().Database.EnsureCreatedAsync();
    app.MapOpenApi();
}

var v1 = app.MapGroup("/api/v1/products").WithTags("Products");

v1.MapGet("/", async (AppDbContext db, CancellationToken ct) =>
    TypedResults.Ok(await db.Products.AsNoTracking()
        .OrderBy(p => p.Id)
        .Select(p => new ProductDto(p.Id, p.Name, p.Price, p.Stock))
        .ToListAsync(ct)));

v1.MapGet("/{id:int}", async (int id, AppDbContext db, CancellationToken ct) =>
    await db.Products.AsNoTracking().FirstOrDefaultAsync(p => p.Id == id, ct)
        is Product p
        ? TypedResults.Ok(new ProductDto(p.Id, p.Name, p.Price, p.Stock))
        : TypedResults.NotFound());

v1.MapPost("/", async (CreateProductRequest req, AppDbContext db, CancellationToken ct) =>
{
    var entity = new Product { Name = req.Name, Price = req.Price, Stock = req.Stock };
    db.Products.Add(entity);
    await db.SaveChangesAsync(ct);
    return TypedResults.Created($"/api/v1/products/{entity.Id}",
        new ProductDto(entity.Id, entity.Name, entity.Price, entity.Stock));
});

v1.MapPut("/{id:int}", async (int id, CreateProductRequest req, AppDbContext db, CancellationToken ct) =>
{
    // 这里用跟踪查询,因为后面要改它
    var entity = await db.Products.FirstOrDefaultAsync(p => p.Id == id, ct);
    if (entity is null) return TypedResults.NotFound();

    entity.Name = req.Name;
    entity.Price = req.Price;
    entity.Stock = req.Stock;
    await db.SaveChangesAsync(ct);
    return TypedResults.NoContent();
});

v1.MapDelete("/{id:int}", async (int id, AppDbContext db, CancellationToken ct) =>
{
    // 只按主键删除,不必先把整行取回内存
    var affected = await db.Products.Where(p => p.Id == id).ExecuteDeleteAsync(ct);
    return affected == 0 ? TypedResults.NotFound() : TypedResults.NoContent();
});

app.MapHealthChecks("/healthz");
app.Run();

// ---- 模型与 DTO ----
public sealed record ProductDto(int Id, string Name, decimal Price, int Stock);

public sealed record CreateProductRequest(
    [property: Required, StringLength(100, MinimumLength = 1)] string Name,
    [property: Range(0.01, 1_000_000)] decimal Price,
    [property: Range(0, 100_000)] int Stock);

public sealed class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
    public int Stock { get; set; }
}

public sealed class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();

    protected override void OnModelCreating(ModelBuilder b)
    {
        b.Entity<Product>(e =>
        {
            e.Property(p => p.Name).HasMaxLength(100).IsRequired();
            e.Property(p => p.Price).HasPrecision(18, 2);   // 金额精度必须显式指定
        });
    }
}

// 让集成测试能引用 Program
public partial class Program { }

运行与验证:

dotnet run
curl -X POST http://localhost:5000/api/v1/products \
  -H "Content-Type: application/json" \
  -d '{"name":"机械键盘","price":399.00,"stock":25}'
curl http://localhost:5000/api/v1/products

常见坑

1. 中间件顺序错:UseAuthorization 在 UseAuthentication 之前 → 永远 401;UseCors 在认证之后 → 预检被拦。

2. Singleton 持有 Scoped:DbContext 被跨请求复用 → 随机并发异常、数据串请求。开发环境有 ValidateScopes 兜底,生产默认关闭,务必自己在设计上避免。

3. N+1 查询:循环里访问导航属性触发懒加载或逐条查询,本地数据少时看不出来,上线后数据库 QPS 爆掉。一律用 Include 或投影 DTO。

4. GET 用了跟踪查询:白白付出变更跟踪的内存与 CPU 代价。只读一律 AsNoTracking()。

5. AsNoTracking() 后改实体再 SaveChanges:什么都不会发生,而且不报错。这是最隐蔽的一类 bug。

6. 缺 HasPrecision:金额字段在某些数据库上被截断或精度不符,对账时才发现。

7. 连接串提交进仓库:见上文。

8. 未处理 ForwardedHeaders:反代后拿到的是代理 IP,Request.Scheme 恒为 http,导致 HTTPS 重定向死循环或限流失效。

9. EnsureCreated() 用在生产:它绕过迁移、不会更新已有 schema。生产只用 dotnet ef database update 或脚本。

10. 一个动作写两个 [FromBody]:运行时报错,请求体只能被读一次。

练习题

1. 下面这段 Program.cs 的中间件顺序有 3 处安全隐患,请指出并说明各自的症状:

var app = builder.Build();
app.UseStaticFiles();
app.UseAuthorization();
app.UseCors();
app.UseAuthentication();
app.UseExceptionHandler();
app.MapControllers();
app.Run();

2. 某服务注册为 AddSingleton<ReportService>(),ReportService 构造函数注入了 AppDbContext。开发机上一切正常,上线后偶尔报 A second operation was started on this context。请解释原因,并给出两种修法(说明各自的代价)。

3. 有 Category 1 对多 Product。需求是「返回所有分类及其商品名列表」。写出两种实现(Include 与投影),并说明在分类数 1000、每类商品 500 时,你选哪种、为什么。

4. 用最小 API 实现 POST /api/v1/orders:请求体含 customerId 与非空的 items 数组(每项有 productId 与 quantity,quantity 至少为 1),校验失败要返回 ProblemDetails 格式的 400。写出终结点与请求类型的定义。

5. 你需要在 X-Request-Id 请求头缺失时自动生成一个,并在响应头里回填、同时写进该请求的所有日志。用两种方式实现(自定义中间件 / 终结点过滤器),并说明在「只对 /api 下的路由生效」这个额外要求下哪种更合适。

FAQ

最小 API 和控制器能混用吗?

能,而且很常见。同一个应用里 app.MapControllers() 与 app.MapGet(...) 可以共存,它们最终都注册为终结点。混用时注意:控制器的 [Authorize] 和最小 API 的 .RequireAuthorization() 走的是同一套授权中间件,策略与角色体系共享。

为什么我的 appsettings.Development.json 没有生效?

依次检查:① ASPNETCORE_ENVIRONMENT(或 DOTNET_ENVIRONMENT)是否真的等于 Development——用 app.Environment.EnvironmentName 打印确认;② launchSettings.json 里的环境变量会覆盖系统环境变量;③ 文件是否被复制到输出目录(csproj 里应为 CopyToOutputDirectory,模板默认已配置);④ 键名大小写不敏感,但层级分隔符写错(把 : 写成 .)也会读不到。

AsNoTracking() 加了之后查询反而更慢,可能是什么原因?

两种典型情况:① 查询结果里同一实体重复出现多次,非跟踪查询不做标识解析,会为每次出现各建一个实例;数据量大时对象创建成本超过跟踪成本。此时改用 AsNoTrackingWithIdentityResolution()。② 后续代码依赖「EF 返回同一实例」来做引用比较,非跟踪打破了这一点,导致额外去重或重复处理。

迁移文件和数据库状态不一致了怎么办?

先 dotnet ef migrations list 看哪些已应用。若只是本地开发库,最省事的做法是删库重建(dotnet ef database update 0 回滚全部迁移,或直接删掉 SQLite 文件)。若生产库与迁移历史表(__EFMigrationsHistory)不一致,不要手工改历史表,应生成 dotnet ef migrations script <已应用> <目标> 得到幂等脚本,人工审核后执行。

相关笔记

  • 后端-01-HTTP与RESTfulAPI设计 —— 本文示例里的方法语义、状态码与资源命名都遵循那篇的约定。
  • 后端-05-数据库操作与ORM —— 连接池、事务、N+1 的通用原理,与本文 EF Core 部分互为补充。
  • 后端-06-认证与授权 —— 中间件顺序里 UseAuthentication / UseAuthorization 的完整用法。
  • 后端-07-Docker与容器化 —— dotnet publish 产物如何打进镜像。
  • 后端-08-部署与运维基础 —— ForwardedHeaders、健康检查、结构化日志在运维侧的落地。
  • CSharp-05-异步编程 —— async/await、CancellationToken 在请求管线中的传播方式。
  • CSharp-03-集合与LINQ —— EF Core 的查询就是 LINQ 表达式树,延迟执行是理解投影的关键。

参考来源

  • ASP.NET Core 中间件(顺序、Use 与 Map、分支):https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/middleware/?view=aspnetcore-10.0
  • ASP.NET Core 依赖关系注入(生存期、键控服务、IOptions、作用域验证):https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-10.0
  • ASP.NET Core 中的配置(覆盖顺序、环境变量、用户机密):https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/configuration/?view=aspnetcore-10.0
  • 在开发中安全存储应用机密(dotnet user-secrets):https://learn.microsoft.com/zh-cn/aspnet/core/security/app-secrets?view=aspnetcore-10.0
  • ASP.NET Core 中的路由(终结点路由与路由约束):https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/routing?view=aspnetcore-10.0
  • ASP.NET Core MVC 中的模型验证:https://learn.microsoft.com/zh-cn/aspnet/core/mvc/models/validation?view=aspnetcore-10.0
  • 最小 API 快速参考(MapGroup、终结点过滤器、参数绑定、TypedResults、ValidateScopes):https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/minimal-apis?view=aspnetcore-10.0
  • EF Core 迁移概述:https://learn.microsoft.com/zh-cn/ef/core/managing-schemas/migrations/
  • EF Core 跟踪与 No-Tracking 查询(标识解析、投影与跟踪的关系):https://learn.microsoft.com/zh-cn/ef/core/querying/tracking
  • EF Core 预加载相关数据(Include / ThenInclude):https://learn.microsoft.com/zh-cn/ef/core/querying/related-data/eager
  • EF Core 处理并发冲突(乐观锁与并发令牌):https://learn.microsoft.com/zh-cn/ef/core/saving/concurrency
  • EF Core DbContext 配置与生存期:https://learn.microsoft.com/zh-cn/ef/core/dbcontext-configuration/
  • ASP.NET Core 中的日志记录:https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/logging/?view=aspnetcore-10.0
  • ASP.NET Core 中的运行状况检查:https://learn.microsoft.com/zh-cn/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-10.0
  • ASP.NET Core 中的集成测试(WebApplicationFactory):https://learn.microsoft.com/zh-cn/aspnet/core/test/integration-tests?view=aspnetcore-10.0
  • 配置 ASP.NET Core 以使用代理服务器和负载均衡器(ForwardedHeaders):https://learn.microsoft.com/zh-cn/aspnet/core/host-and-deploy/proxy-load-balancer?view=aspnetcore-10.0
  • dotnet publish 命令:https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-publish
  • dotnet watch 命令:https://learn.microsoft.com/zh-cn/dotnet/core/tools/dotnet-watch
  • .NET 10 中的新增功能(配合本机 .NET SDK 10.0.401 查阅):https://learn.microsoft.com/zh-cn/dotnet/core/whats-new/dotnet-10/overview