做后端开发的朋友大概率都经历过这个阶段项目刚起步老板或者架构师丢过来一句用 ASP.NET Core WebAPI 搭个服务数据库用 SQL ServerORM 就上 EF Core然后你就得从零把这一整套东西串起来。听起来像是官方文档里十分钟就能跑通的 Demo但真到落地的时候坑一个接一个——连接字符串放哪、DbContext 生命周期怎么管、迁移脚本在生产环境怎么跑、并发冲突怎么处理、查询性能怎么调优每一个都能让你加班到深夜。这篇内容就是把我这些年用ASP.NET Core WebAPI EF Core SQL Server这套组合拳做项目的经验摊开来讲。它适合刚接触这套技术栈、想快速把项目骨架搭起来的新手也适合已经用过但总在某些细节上栽跟头的中级开发者。我不会只给你贴几段能跑的代码就完事而是把每个关键决策背后的为什么讲清楚——为什么 DbContext 要注册成 Scoped、为什么迁移不能在生产环境随手database update、为什么有时候 AsNoTracking 能让接口快一倍。这些才是真正决定你项目能不能稳住的东西。1. 先把技术栈的职责边界划清楚很多人一上来就急着建项目、装包、写实体类结果写到一半发现概念是混的分不清 EF Core 和 SQL Server 各自管什么也搞不明白 WebAPI 在这套组合里扮演什么角色。概念不清后面所有的选型和排错都会变成瞎猜。所以动手之前先把这三者的分工捋顺比什么都重要。1.1 WebAPI、EF Core、SQL Server 各管哪一摊ASP.NET Core WebAPI是门面负责对外暴露 HTTP 接口、处理路由、模型绑定、参数校验、返回 JSON。它不关心数据存在哪、怎么存只关心收到请求、给出响应这件事。你可以把它理解成餐厅的服务员客人点菜请求服务员把单子递给后厨业务逻辑和数据层再把做好的菜端回来响应。EF Core是后厨的采购和配菜环节它是一个 ORM对象关系映射框架负责把 C# 里的对象和数据库里的表对应起来让你用写 C# 的方式去操作数据而不用手写大量 SQL。它管的是实体怎么映射成表、查询怎么翻译成 SQL、变更怎么追踪。SQL Server则是真正的仓库数据最终落在它这里。它管的是存储、索引、事务、并发控制这些底层的事。三者串起来的链路是这样的HTTP 请求进来 → WebAPI 路由到某个 Controller → Controller 调用业务服务 → 业务服务通过 EF Core 的 DbContext 操作数据 → EF Core 把 LINQ 翻译成 T-SQL 发给 SQL Server → 结果原路返回。理解这条链路你才知道出问题时该往哪一层找。1.2 为什么这套组合在中小项目里特别常见选型这件事没有绝对的对错只有合不合适。这套组合之所以在中小型项目和快速交付场景里出现频率极高核心原因有几个。第一是语言统一。从接口到数据访问全是 C#不需要在 C# 和 SQL 之间来回切换思维团队里一个人能从前写到后人力成本低。第二是工具链成熟。Visual Studio 和 VS Code 对这套栈的支持非常到位调试、断点、迁移管理都有现成的工具。第三是SQL Server 与 EF Core 的契合度高。微软自家产品之间的适配通常最顺比如IDENTITY自增、datetimeoffset类型映射、空间数据类型这些EF Core 的 SQL Server Provider 处理得都很自然。但我也得说清楚它的边界如果你的项目是超高并发、对 SQL 有极致性能要求或者需要跨多种数据库灵活切换那纯 EF Core 未必是最优解可能需要 Dapper 混用或者直接上存储过程。选型要看场景别迷信一套打天下。1.3 项目骨架的最小可用结构在动手写代码前我习惯先把目录结构定下来。一个能长期维护的 WebAPI 项目不建议把所有东西塞进一个项目里。我常用的最小结构是这样Solution/ ├── Api/ # WebAPI 入口Controller、中间件、启动配置 ├── Application/ # 业务逻辑、服务接口与实现、DTO ├── Domain/ # 实体类、领域模型、枚举 └── Infrastructure/ # DbContext、迁移、仓储实现、外部依赖这个分层不是教条但它能帮你把数据访问和业务逻辑隔开。最直接的收益是当你想给 DbContext 写单元测试、或者想换掉某个数据访问实现时改动范围是可控的。新手最容易犯的错就是把 DbContext 直接注入到 Controller 里到处用项目小的时候没事一旦业务复杂起来代码会烂得没法看。2. 环境搭建与依赖注入的正确姿势骨架定好了接下来是让项目真正跑起来。这一步看似机械但依赖注入的配置方式直接决定了你后面会不会遇到DbContext 被释放了连接池耗尽这类诡异问题。我见过太多项目在这里埋雷。2.1 安装哪些包版本怎么对齐用 EF Core 操作 SQL Server核心就两个包Microsoft.EntityFrameworkCore和Microsoft.EntityFrameworkCore.SqlServer。如果要用迁移命令还得加上Microsoft.EntityFrameworkCore.Design这个通常装在 Api 项目里因为它是设计时工具。版本对齐是第一个坑。EF Core 的主版本号必须和你的 .NET 运行时主版本匹配比如 .NET 8 就配 EF Core 8。版本错配的典型症状是编译能过、运行时报Method not found或者程序集加载失败。我的习惯是统一用dotnet add package命令安装让它自动解析兼容版本而不是手动去改 csproj 里的版本号。dotnet add package Microsoft.EntityFrameworkCore.SqlServer dotnet add package Microsoft.EntityFrameworkCore.Design装完之后去 csproj 里确认一下版本号是否一致这一步别省。2.2 DbContext 注册成 Scoped 的深层原因在Program.cs里注册 DbContext标准写法是builder.Services.AddDbContextAppDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(Default)));AddDbContext默认把 DbContext 注册为Scoped生命周期也就是每个 HTTP 请求一个实例。这个默认值背后有明确的设计考量DbContext 内部维护着变更追踪器Change Tracker它会记录你从数据库查出来的每个实体的状态。如果 DbContext 是单例Singleton多个请求会共享同一个追踪器导致实体状态互相污染、内存无限增长最终内存泄漏。如果注册成 Transient每个注入点都 new 一个那同一个请求里不同服务拿到的 DbContext 不是同一个事务就没法跨服务共享SaveChanges的原子性也会出问题。所以 Scoped 是唯一合理的选择一个请求内共享同一个 DbContext请求结束就释放。理解这一点你就明白为什么绝对不能在后台线程或定时任务里直接注入并使用 Scoped 的 DbContext——那些场景没有请求上下文得用IServiceScopeFactory手动创建作用域。这是新手踩得最多的坑之一。2.3 连接字符串放哪、怎么加密连接字符串里带着数据库地址和账号密码属于敏感信息。最忌讳的做法是硬编码在代码里然后提交到代码仓库。正确做法是放在appsettings.json的ConnectionStrings节点下本地开发用appsettings.Development.json覆盖生产环境则通过环境变量或密钥管理服务注入。{ ConnectionStrings: { Default: Serverlocalhost;DatabaseAppDb;User Idapp_user;Password***;TrustServerCertificateTrue; } }这里有个细节值得说TrustServerCertificateTrue在本地开发时能省掉证书信任的麻烦但生产环境不应该无脑开应该配置好正规证书。另外连接字符串里建议显式设置MultipleActiveResultSets相关行为、连接超时时间别全用默认值。我一般会加Connect Timeout30避免网络抖动时请求长时间挂起。3. 实体建模与 DbContext 配置的实战细节环境通了接下来是建模。这一步决定了数据库表长什么样、关系怎么连、性能上限在哪。EF Core 的约定优于配置确实省事但省事的地方往往也是埋雷的地方。3.1 实体类与 Fluent API 的分工EF Core 支持两种配置方式数据注解在属性上加[Required]、[MaxLength]这类特性和Fluent API在OnModelCreating里用链式调用配置。我的建议是简单的约束用注解复杂的关系、索引、默认值、级联行为一律用 Fluent API。原因很实际注解会把持久化细节污染到领域实体上而且注解能表达的东西有限比如复合索引、过滤索引、 owned 类型的映射注解根本做不到。Fluent API 集中在OnModelCreating里一眼能看全所有映射规则维护起来清爽。protected override void OnModelCreating(ModelBuilder modelBuilder) { modelBuilder.EntityOrder(entity { entity.HasKey(e e.Id); entity.Property(e e.OrderNo).HasMaxLength(32).IsRequired(); entity.HasIndex(e e.OrderNo).IsUnique(); entity.HasIndex(e new { e.CustomerId, e.CreatedAt }); entity.HasOne(e e.Customer) .WithMany(c c.Orders) .HasForeignKey(e e.CustomerId) .OnDelete(DeleteBehavior.Restrict); }); }注意OnDelete(DeleteBehavior.Restrict)这一行。EF Core 默认对必需关系用级联删除Cascade意味着删一个客户会连带删掉他所有订单。这在很多业务里是灾难性的。我见过真实事故运维误删一条主表记录从表数据全没了。所以涉及业务数据的关联我几乎一律显式设成Restrict删除逻辑交给业务代码显式处理。3.2 主键、并发令牌与软删除的取舍主键选型上自增int简单直观但分布式场景下会有冲突风险Guid全局唯一但索引碎片化严重插入性能差。折中方案是用Guid做主键但配NEWSEQUENTIALID()或者用雪花算法生成有序 ID。中小项目里自增long其实够用别过度设计。并发令牌是很多人忽略的点。两个用户同时改同一条记录后提交的会覆盖先提交的这就是丢失更新。EF Core 支持乐观并发控制做法是给实体加一个RowVersion字段entity.Property(e e.RowVersion).IsRowVersion();对应数据库里是rowversion类型每次更新自动变化。EF Core 在SaveChanges时会把它带进WHERE条件如果版本不匹配就抛DbUpdateConcurrencyException。你需要在业务层捕获这个异常并给用户友好提示而不是让它冒泡成 500 错误。软删除也是常见需求。与其物理删除不如加个IsDeleted标记查询时过滤。EF Core 可以用全局查询过滤器实现modelBuilder.EntityOrder().HasQueryFilter(e !e.IsDeleted);但要提醒一句全局过滤器对导航属性也生效有时候会导致意外的空结果排查起来很费劲。用之前想清楚必要时用IgnoreQueryFilters()显式绕过。3.3 迁移的生成、审查与生产环境落地迁移Migration是 EF Core 管理数据库结构变更的机制。开发时用dotnet ef migrations add 名称生成迁移文件dotnet ef database update应用到数据库。但这里有个必须强调的原则生成的迁移文件一定要人工审查。EF Core 根据模型差异自动生成迁移但它不一定理解你的意图。比如你重命名了一个列它可能识别成删掉旧列 新增新列导致数据丢失。审查迁移文件时重点看Up方法里的DropColumn、DropTable操作确认没有误删。生产环境的落地更要谨慎。直接在线上跑database update风险很高因为迁移是单向的、出问题回滚麻烦。我的做法是用dotnet ef migrations script生成 SQL 脚本交给 DBA 审查后在维护窗口执行并且执行前先备份。这样每一步都可控、可追溯。dotnet ef migrations script --idempotent -o migrate.sql--idempotent参数会生成可重复执行的脚本已经应用过的迁移会自动跳过适合多环境部署。4. 查询性能从能跑到跑得快的分水岭接口能返回数据只是及格线真正拉开水平的是查询性能。EF Core 用起来太顺手顺手到很多人写出了 N1 查询、全表加载、笛卡尔积爆炸却浑然不觉。这一章讲的就是怎么从能跑进化到跑得快。4.1 AsNoTracking 什么时候该开EF Core 默认会追踪查询出来的实体目的是为了后续能检测变更并生成 UPDATE。但如果这个查询只是用来读、读完就返回给前端追踪完全是浪费——它要额外分配内存维护快照、比较状态。这时候加.AsNoTracking()能显著降低开销实测在返回大量数据的列表接口上性能提升经常在 30% 以上。var list await _db.Orders .AsNoTracking() .Where(o o.CreatedAt startDate) .ToListAsync();判断标准很简单这个查询结果会不会被修改并保存。只读就关追踪要改就保留。别一刀切全加或全不加。4.2 识别并消灭 N1 查询N1 是 ORM 最经典的性能杀手。典型场景查出一批订单然后循环里逐个去查每个订单的客户名。1 次主查询 N 次子查询数据量一大直接拖垮数据库。// 错误示范N1 var orders await _db.Orders.ToListAsync(); foreach (var o in orders) { var customer await _db.Customers.FindAsync(o.CustomerId); // 每次循环一次查询 }正确做法是用Include预加载或者用投影一次性取需要的字段// 方案一Include 预加载 var orders await _db.Orders .Include(o o.Customer) .AsNoTracking() .ToListAsync(); // 方案二投影只取需要的字段最省资源 var dtos await _db.Orders .Select(o new OrderDto { Id o.Id, OrderNo o.OrderNo, CustomerName o.Customer.Name }) .AsNoTracking() .ToListAsync();投影方案通常最优因为它生成的 SQL 只 SELECT 需要的列网络传输和内存占用都最小。我一般优先用投影只有在确实需要完整实体图时才用 Include。4.3 分页、索引与执行计划的联动排查分页别用Skip/Take在大偏移量上硬扛。Skip(100000).Take(20)在 SQL Server 里会扫描并丢弃前十万行越翻到后面越慢。优化思路是用键集分页Keyset Pagination基于上一页最后一条记录的 ID 或时间戳做条件var nextPage await _db.Orders .Where(o o.Id lastId) .OrderBy(o o.Id) .Take(20) .AsNoTracking() .ToListAsync();这种方式无论翻到第几页查询代价都稳定。代价是不能随机跳页适合下拉加载更多的场景。索引方面EF Core 生成的 SQL 到底走没走索引光看代码是看不出来的。我的习惯是把慢查询的 SQL 抓出来在 SQL Server Management Studio 里看执行计划重点找 Table Scan、Key Lookup 这些高开销节点。如果发现某个 WHERE 条件列没索引就在OnModelCreating里补上然后生成迁移。索引不是越多越好每个索引都会拖慢写入得在读写之间找平衡。5. 那些文档里不会写的踩坑实录前面讲的都是应该怎么做这一章讲实际会怎么翻车。这些坑我几乎每一个都亲自踩过写出来是希望你能少走点弯路。5.1 DbContext 生命周期错配引发的诡异异常最常见的报错是Cannot access a disposed context instance。根因通常是在某个长生命周期的服务比如单例里注入了 Scoped 的 DbContext或者把 DbContext 存到了静态字段里。请求结束后 DbContext 被释放后续再用就炸。排查链路是这样的先看异常堆栈里 DbContext 是从哪个服务拿到的再检查那个服务的生命周期注册。如果服务是 Singleton 却依赖了 Scoped 的 DbContext就是典型的生命周期错配。修复方案有两种把服务改成 Scoped或者用IServiceScopeFactory在需要时手动开作用域。public class BackgroundWorker { private readonly IServiceScopeFactory _scopeFactory; public BackgroundWorker(IServiceScopeFactory scopeFactory) _scopeFactory scopeFactory; public async Task DoWorkAsync() { using var scope _scopeFactory.CreateScope(); var db scope.ServiceProvider.GetRequiredServiceAppDbContext(); // 在这里安全使用 db } }后台任务、定时任务、事件回调这类没有 HTTP 上下文的场景一律走这个模式。5.2 事务与 SaveChanges 的边界问题有人以为调一次SaveChanges就是一个事务这没错但多个SaveChanges之间就不是原子的了。如果你有一段业务需要扣库存 生成订单 写日志三步都成功或都失败必须显式开事务using var tx await _db.Database.BeginTransactionAsync(); try { // 多步操作 await _db.SaveChangesAsync(); await tx.CommitAsync(); } catch { await tx.RollbackAsync(); throw; }另一个坑是EF Core 的SaveChanges内部本身有事务如果你在外部又开了事务要注意别嵌套出问题。还有事务里别做耗时操作比如调外部 HTTP 接口否则会长时间持有锁拖垮并发。5.3 连接池耗尽与超时排查高并发下偶尔会遇到Timeout expired... The connection pool has been exhausted。根因通常是连接没及时归还——要么是 DbContext 没释放比如手动 new 了却没 using要么是某个查询执行太久占着连接不放。排查思路先看是不是有长事务或慢查询用 SQL Server 的活动监视器看当前连接都在干什么再检查代码里有没有new AppDbContext()这种绕过 DI 的写法。连接池大小可以在连接字符串里用Max Pool Size调但那是治标真正的解法是保证连接快速归还。我一般会把默认的 100 调到和预期并发匹配的值同时确保所有 DbContext 都走 DI 管理。5.4 常见问题速查对照表现象可能根因排查方向修复方案Cannot access a disposed context生命周期错配检查服务注册生命周期改 Scoped 或用 ScopeFactory接口返回数据慢N1 或全表加载抓 SQL 看执行计划Include/投影/加索引并发更新丢数据无并发令牌检查实体是否有 RowVersion加 IsRowVersion 并处理异常连接池耗尽连接未归还查慢查询与手动 new走 DI、优化慢查询迁移误删列自动生成未审查看 Up 方法 DropColumn人工修正迁移脚本生产迁移失败直接 database update看迁移历史表改用幂等脚本 备份6. 让这套栈在生产环境站得稳的收尾配置代码写对只是第一步能不能在生产环境稳定运行还取决于一些容易被忽略的配置。这些配置平时不显眼出事的时候却是救命的。6.1 日志、健康检查与慢查询监控EF Core 内置了日志能力可以在AddDbContext时配置敏感数据日志和命令日志。开发环境我一般开LogLevel.Information看生成的 SQL生产环境则只记录 Warning 以上避免日志爆炸。关键是把慢查询记下来options.UseSqlServer(conn, sql sql.CommandTimeout(30)) .LogTo(Console.WriteLine, new[] { DbLoggerCategory.Database.Command.Name }, LogLevel.Information);配合健康检查端点能快速判断数据库连通性。ASP.NET Core 自带AddHealthChecks().AddDbContextCheckAppDbContext()挂到/health上运维监控直接对接。6.2 连接 resiliency 与重试策略网络抖动、数据库短暂不可用是常态。EF Core 的 SQL Server Provider 支持执行策略Execution Strategy能自动重试瞬时故障options.UseSqlServer(conn, sql sql.EnableRetryOnFailure(maxRetryCount: 3, maxRetryDelay: TimeSpan.FromSeconds(5), null));但要注意开了重试策略后手动事务必须用strategy.ExecuteAsync包裹否则会报配置了执行策略就不能直接开事务的错。这是很多人开了重试之后突然报错的根因。6.3 版本升级时的兼容性检查清单EF Core 大版本升级比如 7 升 8通常有破坏性变更。升级前我会过一遍清单检查所有用到的 API 是否被标记过时、跑一遍完整迁移脚本看有没有语法不兼容、在预发环境压测一轮。特别留意 LINQ 翻译行为的变化——某些以前能翻译成 SQL 的写法新版本可能改成客户端求值性能会断崖式下跌。升级后务必抓几条核心查询的 SQL 对比一下。我个人在实际项目里的体会是这套栈真正的门槛不在会不会写而在知不知道边界在哪。EF Core 让你写数据访问像写普通 C# 一样舒服但舒服的代价是它把 SQL 藏起来了你得主动去把它挖出来看。每次上线前抓几条核心接口的 SQL 过一遍执行计划这个习惯帮我挡掉了至少一半的性能事故。另外再分享一个小技巧给 DbContext 的OnConfiguring或全局日志加一个开关只在需要排查时打开 SQL 输出平时关掉既不影响性能又能在关键时刻拿到第一手线索。
