第 2 篇的项目第一次启动时,控制台里滚过一条建表语句,大意是创建一张 Items 表,带 Id 和 Name 两列。当时觉得挺省事:没写 SQL,表自己就有了,重启一次数据还在。直到我给 Item 加了一个 Description 字段,接口立刻返回 500,日志里说找不到这一列。数据库还是旧的那张表,程序以为它已经有了新列。
这就是 EnsureCreated 的边界:它只在数据库不存在时建一次表,之后不管模型怎么变,它都不会去改结构。演示项目用它没问题,正式项目用它迟早出事。而它背后那个 AppDb,也就是 DbContext(EF Core 里的数据库会话对象),还有另一层容易忽略的规则:它是按请求创建的,不能被单例共享,也不能跨线程同时用。
这篇讲怎么把数据真正存住:DbContext 的生命周期为什么会带来那些坑、EnsureCreated 和迁移(migration,一组带版本号的建表改表脚本)该怎么选、什么时候该用 AsNoTracking、事务边界画在哪、SQLite 和 PostgreSQL 的差别,以及换数据库要改哪几行。启动建表的日志和查询 SQL 都是本机实测,迁移命令和换库后的行为没有跑过,会明确标出。
加一个字段,接口就 500 了
先把依赖和目录摆出来。数据库提供程序是一个单独的包,版本要和 EF Core 对齐:
<Project Sdk="Microsoft.NET.Sdk.Web">
<ItemGroup>
<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="8.0.11" />
</ItemGroup>
</Project>
构建与启动沿用前面两篇的命令:
dotnet build
dotnet run --no-launch-profile --urls "http://127.0.0.1:18082"
数据相关的文件只有这几处,后面换库时改动也集中在这里:
把当时的过程还原一下。模型加字段:
public class Item
{
public long Id { get; set; }
public string Name { get; set; } = "";
public string? Description { get; set; }
}
重新构建、启动,日志里能看到 EF Core 自己生成的建表语句,但只在第一次建库时出现。之后启动就没有了,因为库文件 app.db 已经存在:
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
CREATE TABLE "Items" (...)
关键在这里:EnsureCreated 只判断「库在不在」,不判断「表结构对不对」。第二次启动时库在,它什么都不做,而模型已经多了 Description,查询时 EF 生成的 SQL 会带上这一列,SQLite 找不到列,直接报错。表现是接口 500,日志里是「no such column」这类提示,跟业务代码一点关系都没有。
删掉 app.db 再启动,问题立刻消失。这个「删库大法」很诱人,但它等于每次改模型都清空数据,只能用在本地演示。正式环境必须换成迁移:把每次结构变更写成一个带版本号的脚本,按顺序执行,并且记录哪些已经执行过。
迁移的思路其实是给数据库也做版本控制。每个迁移文件记录「从上一版到这一版改了哪些列、哪些索引」,执行时按时间顺序跑,跑过的记在一张历史表里。这样新机器和老机器都能通过「按顺序执行」到达同一个结构,而不是靠谁记得删库。代价是团队要约定:改模型必须同时提交迁移文件,不能只改 C# 类。
DbContext 为什么是 scoped 的
ASP.NET Core 的依赖注入有三种生命周期,理解这三种,很多坑会自动消失:
DbContext 之所以必须是 scoped,有两个原因。第一,它不是线程安全的,内部维护着一个变更跟踪器和一个连接,两个线程同时用会互相踩状态,典型报错是「上一个操作还没完成就开始新操作」。第二,它实现了 IDisposable,请求结束要释放连接;如果做成单例,连接就一直挂着,事务状态也会串到别的请求上。
所以「把 DbContext 注入到单例里」是明确的错误。开发环境下容器会做作用域校验,直接在启动时报错,提示不能在根作用域解析 scoped 服务;如果关掉了校验,它会在运行时悄悄给你一个长命对象,然后出现各种脏数据和并发异常。正确做法是注入 IServiceScopeFactory,在需要的时候自己开一个 scope,第 5 篇的后台任务就是这么干的。
还有一个常被误解的点:连接池不是 DbContext 管的。DbContext 只是「借用」连接,用完还给 ADO.NET 的连接池;池子的大小、超时由连接字符串和驱动控制。SQLite 是本地文件,没有网络连接池的概念,每次打开就是打开文件;PostgreSQL、SQL Server 这类网络数据库才有真正的连接池。所以「DbContext 太多导致连接耗尽」这个说法不准确,真正耗尽的是底层连接池,而池子大小通常由连接串里的最大池大小决定。
作用域校验默认只在开发环境打开,这是有意的:开发时让错误尽早暴露,生产时为了性能把校验关掉。这也解释了为什么同一个写法在本地启动就报错、到服务器上却「能跑」。它不是能跑,是把问题推迟到了第一次并发请求。别把生产的「能启动」当成通过。
EnsureCreated 和迁移:演示与生产的界线
两者都能建表,差别在「之后怎么办」:
EnsureCreated
库不存在就按当前模型建一套,库存在就什么都不做。没有版本记录,不能增量改表,也不能回滚。适合一次性演示、集成测试里的一次性数据库,代码只有一行,跑起来最省事。
迁移
每次模型变更生成一个带时间戳的脚本,启动或部署时按顺序执行,执行记录写在一张历史表里。能增量改、能审查 SQL、能回退。适合任何需要保住数据的环境,代价是多一套命令和文件要维护。
迁移文件要不要进仓库?要。它是数据库结构的事实来源,和代码一样需要评审。两个人同时加字段时,迁移文件会冲突,解决冲突的过程其实就是确认「最终表结构长什么样」,这个过程必须留下记录。把迁移文件放在 gitignore 里,等于把生产库的结构交给某台机器上的二进制文件,换个人就复现不出来。
迁移文件的命名一般带时间戳,顺序由文件名决定,所以不要手动改文件名。评审时重点看两件事:有没有删列或改类型这种不可逆操作,以及有没有对已有数据做默认值填充。前者回滚时要恢复数据,后者在大表上可能锁表几分钟。这两类改动最好单独发一次,别和其他业务改动混在一起。
迁移的执行时机也有讲究。常见做法是部署时用命令行执行,而不是应用启动时自动跑。原因是启动时自动迁移会让「所有实例同时启动」变成「所有实例同时改表」,多实例部署下容易互相锁住;而且迁移失败会让整个应用起不来,回滚更麻烦。小项目单实例可以在启动时执行,但要清楚这是用简单换风险。
Database.EnsureCreated() 的建表日志。dotnet ef migrations add、dotnet ef database update 的实际输出,以及迁移历史表长什么样,均未在本机实测。上面的描述按框架文档和常见实践写成,命令你在自己项目里跑一次就能确认。
数据层出问题,先看这张表
数据访问的报错往往离根因很远,一个 500 可能是模型、生命周期、SQL、事务四层中的任何一层。按现象倒推能省很多时间:
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 加字段后接口 500,提示找不到列 | EnsureCreated 不会演进表结构 | 看启动时是否只在首次建表,库里是否已有旧表 |
| 启动报「不能在根作用域解析 scoped 服务」 | 单例构造函数里直接注入了 DbContext | 搜单例注册的类,看构造函数参数 |
| 偶发「上一个操作未完成」异常 | 同一个 DbContext 被并发使用,或缓存成了静态字段 | 搜 static 字段和 Task.WhenAll 里的共享实例 |
| 列表接口慢,日志里同一句 SELECT 出现几十次 | N+1 查询,循环里逐条取关联数据 | 数一次请求的 SQL 条数,而不是看总耗时 |
| 只读接口内存持续上涨 | 实体被变更跟踪器记住,请求结束才释放 | 查询是否加了 AsNoTracking |
| 两次 SaveChanges 之间进程退出,数据只写了一半 | 没有显式事务,两次提交各自生效 | 确认是否用了 BeginTransaction 包住 |
| 换库后报表 SQL 报语法错 | 用了提供程序特有的函数或类型 | 搜 FromSqlRaw 和手写 SQL 的位置 |
| 迁移执行了但表没变 | 迁移文件没生成,或执行的是另一套连接串 | 看迁移历史表和当前连接串指向的库 |
表里最值得记住的是第三条。DbContext 被并发使用这件事,本地单请求测试永远测不出来,上线后第一个并发高峰才会暴露,而且报错信息指向 EF 内部,看起来像框架的 bug。根因通常是有人为了「省一次创建」,把 DbContext 存进了静态字段或者单例服务。只要看到「偶发、只在并发时出现、重启就好」,先查共享实例。
第四条也容易被误读成「数据库慢」。N+1 的典型特征是 SQL 条数随数据量线性增长,单条都很快,加起来就慢。优化方向不是加索引,而是把循环里的查询合并成一次。判断方法很简单:打开 EF 的 SQL 日志,数一次请求打了几条,超过五条又都是同一形状的语句,基本就是了。
EF Core 的 SQL 日志是排查数据层最有用的东西,开发环境默认会打印每条命令和执行耗时。看日志时不要只盯单条耗时,要看一次请求的总条数和总时间。单条 1 毫秒、一共一百条,总时间就是一秒,接口慢的锅不在数据库,在查询写法。把日志级别调到 Information 就能看到,调到 Debug 会多出参数值,生产环境注意别把敏感参数打出来。
边界与代价:EF Core、Dapper 和裸 SQL
EF Core 的强项是把「对象」和「表」的映射、变更跟踪、迁移串成一条链,常规增删改查几乎不用写 SQL。代价是它生成的 SQL 不总是最优,复杂查询容易被翻译成一堆嵌套子查询,执行计划难看。判断标准不是「EF 快不快」,而是「这个查询的形状 EF 能不能翻译好」。
N+1 是最典型的例子。写成 _db.Items.ToList() 然后在循环里访问导航属性,如果导航属性是懒加载,每条记录都会再发一条 SQL;一百条数据就是一百零一条。解决办法有两个:查询时用 Include 一次性把关联数据带出来,或者干脆只查需要的字段做投影。投影比 Include 更省,因为它不会把整行都拉回来。
// 差:先取全部,再逐条补数据,容易变成 N+1
var items = await _db.Items.ToListAsync();
foreach (var item in items) { var n = item.Name.Length; }
// 好:一次查询,只取需要的列,且不跟踪
var rows = await _db.Items
.AsNoTracking()
.Select(i => new { i.Id, i.Name })
.ToListAsync();
AsNoTracking 的意思是「这次查询不要记住实体」。默认情况下 EF 会把查出来的实体放进变更跟踪器,为了后面可能的 SaveChanges 能算出差异;只读列表根本不需要这个能力,关掉它既省内存又快一点。经验值:读多写少的接口全部加,单次返回超过一千行的列表一定要加。
事务边界要说清楚。SaveChanges 本身是原子的:一次提交里的多条增删改要么全成要么全败。但两次 SaveChanges 就是两个事务,中间失败会留下半份数据。需要「要么都成」时,用 Database.BeginTransaction 显式包住:
await using var tx = await _db.Database.BeginTransactionAsync();
_db.Items.Add(new Item { Name = "a" });
await _db.SaveChangesAsync();
_db.Items.Add(new Item { Name = "b" });
await _db.SaveChangesAsync();
await tx.CommitAsync();
什么时候该上 Dapper 或裸 SQL?三类场景:复杂报表要五张表关联加窗口函数,EF 翻译不出可接受的执行计划;批量写入十万行,逐条跟踪开销太大;已有系统有一套调优好的存储过程。除此之外的常规 CRUD,用 EF 的收益远大于那点性能损失。规模上的参考:单表百万行以内、查询涉及三张表以内,EF 足够;再复杂就该把那条 SQL 单独拿出来,用 Dapper 映射成对象,而不是硬拧 LINQ。
事务还有两个容易忽略的点。一是事务要尽量短,里面不要放网络调用、不要等用户输入,长事务会持有锁,别的请求只能排队。二是默认隔离级别下,事务里读到的数据可能已经被别人改过,涉及金额、库存这类计算时要在 SQL 里加条件更新,而不是先读再算再写。EF 本身不解决并发竞争,它只保证你提交的这批变更是一个原子操作。
生产该用谁?SQLite 是单文件、写入串行、没有真正的并发写能力,适合开发和单机小工具,不适合多实例服务。PostgreSQL 支持并发写、有丰富索引和 JSON 类型,是这类服务的常规选择。把 Provider 从 Sqlite 换成 Npgsql 要改的地方不多:csproj 里把 Microsoft.EntityFrameworkCore.Sqlite 换成 Npgsql.EntityFrameworkCore.PostgreSQL,UseSqlite 换成 UseNpgsql,连接串换成 PostgreSQL 的格式,迁移文件按新 Provider 重新生成一套。这四步本机没有实测,换库后的类型映射差异要自己验证,尤其是自增主键和时间类型。
换库也不是零成本。SQLite 的整数主键到 PostgreSQL 会变成 bigint,时间列的精度和时区处理也不同,这些差异要在迁移脚本里显式确认,不能指望自动转换。数据量小的时候看不出问题,等到历史数据几百万行,一次类型不匹配的迁移就可能锁表很久。
今天就能自验的五个练习
数据层的坑必须自己踩一次才记得住,下面每条都能在本地做完:
- 给 Item 加一个可空字段,不删库直接启动,请求列表接口,看日志里的错误原文。再删掉 app.db 重启,对比结果。这一步是为了亲眼看到 EnsureCreated 的边界。
- 把 AppDb 注册成 Singleton,启动项目,记录容器给出的报错。然后改回 AddDbContext 的默认注册,确认恢复正常。
- 写一个返回一百条数据的接口,分别在循环里访问导航属性和用 Include 预加载,数日志里 SQL 的条数,而不是看耗时。
- 给只读查询加
AsNoTracking,用日志确认生成的 SQL 没变、但实体不再被跟踪。可以顺手打印变更跟踪器的条目数。 - 写一段两次 SaveChanges 的代码,在第二次之前手动抛异常,重启后查库,看第一条是否留下。再用 BeginTransaction 包住,重复一次,对比结果。
做完这五条,你会对「什么时候该怀疑数据层」有个直觉:单条 SQL 都很快但接口慢,先数条数;重启就好、并发才坏,先查共享实例;改模型后突然报列不存在,先查建表方式。这三个直觉比记住任何一条命令都有用。
小结
下一篇讲鉴权。数据层到这里只是「能存能取」,但接口还全是匿名可访问的,任何人都能读写别人的条目。第 4 篇会在这个项目上加一个登录接口和令牌校验,把「你是谁」这件事确定下来,然后再决定「你能干什么」。到时候你会看到,认证中间件拿到的用户身份,最终还是要落到数据层的查询条件上。
这篇的三句话总结:第一,DbContext 是 scoped 的,一个请求一个实例,不能跨请求共享、不能注入单例、不能并发使用,需要跨请求就用 IServiceScopeFactory 自己开 scope;第二,EnsureCreated 只建一次表,模型变了不会改结构,正式项目用迁移并把迁移文件提交进仓库;第三,N+1 用投影或 Include 解决,只读查询加 AsNoTracking,跨多次 SaveChanges 的一致性要靠显式事务。