后端-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+) |
|---|---|---|
| 运行平台 | 仅 Windows | Windows / 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。但只要涉及安全,就应该显式写出顺序,不要依赖自动推断。
推荐顺序与规则:
| 顺序 | 中间件 | 为什么必须在这个位置 |
|---|---|---|
| 1 | UseForwardedHeaders | 反代后必须最先跑,否则后续中间件看到的都是代理的 IP 与 scheme |
| 2 | UseExceptionHandler / UseDeveloperExceptionPage | 必须能在下游任何位置抛出的异常上兜底 |
| 3 | UseHsts | 只加响应头,在发响应前即可 |
| 4 | UseHttpsRedirection | 在用到 URL 的中间件之前 |
| 5 | UseStaticFiles | 尽早短路,避免静态资源也走完整管线(它不做授权检查) |
| 6 | UseRequestLocalization | 必须在任何检查请求区域性的中间件之前 |
| 7 | UseRouting | 先匹配出终结点,后面的中间件才能读到端点元数据 |
| 8 | UseCors | 必须在 UseAuthentication、UseAuthorization、UseResponseCaching 之前 |
| 9 | UseRateLimiter | 用 [EnableRateLimiting] 等按终结点的限流 API 时,必须在 UseRouting 之后;只用全局限流器时可以放在 UseRouting 之前 |
| 10 | UseAuthentication | 必须在 UseAuthorization 之前;放在 UseRouting 之后以便路由信息参与认证决策 |
| 11 | UseAuthorization | 紧接认证之后,依据 HttpContext.User 做判定 |
| 12 | UseSession | 在响应 Cookie 的中间件之前、终结点之前 |
| 13 | UseResponseCaching / UseResponseCompression | UseCors 必须在其之前;压缩与缓存的相对顺序取决于业务 |
| 14 | Map* 终结点 | 管线终点 |
最容易踩的顺序坑
-
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 工厂、无状态服务 |
选择原则(背下来):
- 默认先想 Scoped。
- 有状态且需要跨请求共享 → Singleton,但必须线程安全。
- 无状态且创建廉价 → Transient。
- 绝不能让长生命周期服务持有短生命周期服务(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) | 是 | 单例服务里读最新值 |
四、配置系统
配置是键值对的有序叠加,后加载的覆盖先加载的。默认应用配置源优先级从高到低:
- 命令行参数
- 不带
ASPNETCORE_/DOTNET_前缀的环境变量 - 用户机密(仅
Development环境) appsettings.{Environment}.jsonappsettings.json- 主机配置(
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-publishdotnet 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