1. 为什么这套组合拳至今仍是企业级接口开发的主力方案做后端接口开发的朋友大概率都绕不开一个经典命题怎么用最短的路径把数据库里的数据安全、高效地暴露成 HTTP 接口。我这些年接手过不少项目有从零起步的也有半路接手别人代码的但凡涉及关系型数据存储和接口服务ASP.NET Core WebAPI EF Core SQL Server这套组合出现的频率高得惊人。它不是最新潮的方案甚至有人觉得它老派但真到了要交付、要维护、要扩展的场景里这套组合的稳定性和开发效率依然很难被替代。先把话说清楚这篇内容讲的是如何在一个 ASP.NET Core WebAPI 项目里用 Entity Framework Core 作为数据访问层对接 SQL Server 数据库完成从建模、配置、迁移到接口落地的完整链路。它解决的核心问题是——让开发者不用手写大量 ADO.NET 样板代码就能把数据库操作变成强类型的 C# 对象操作同时保留对 SQL 性能的可控性。适合谁看刚接触 .NET 后端的新手可以照着走一遍完整流程有一定经验但一直靠抄配置过日子的开发者可以在这里补齐对迁移机制、DbContext 生命周期、查询性能这些关键点的理解带团队的技术负责人也能从中找到一些规范层面的参考。我见过太多项目在这套组合上翻车问题往往不在技术本身而在于几个关键决策没想清楚DbContext 该注册成什么生命周期、实体关系怎么配、迁移脚本谁来管、查询什么时候该用原生 SQL。这些细节在官方文档里都有但文档不会告诉你在真实项目里踩过什么坑。下面我按实际落地的顺序把整套流程拆开讲中间穿插我自己踩过的坑和验证过的做法。2. 整体架构设计与技术选型思路2.1 分层结构怎么切才不别扭很多人一上来就纠结要不要搞 DDD 那一套我的建议是先别想那么远。对于一个中等规模的 WebAPI 项目我通常采用三层结构接口层Controllers、业务层Services、数据访问层DbContext 实体。这个切法的好处是职责清晰Controller 只负责接收请求和返回响应Service 承载业务逻辑数据访问层专注和数据库打交道。为什么不把 EF Core 的查询直接写在 Controller 里小项目确实可以但一旦业务复杂起来Controller 会迅速膨胀成几百行的上帝类测试也没法写。把数据访问收敛到 Service 层之后Controller 变得很薄单元测试时可以用接口 mock 掉数据层这是实打实的收益。具体到目录结构我习惯这样组织/Controllers 接口定义 /Services 业务逻辑 /Data DbContext、实体配置 /Models 实体类、DTO /Migrations EF Core 迁移文件这里有个细节值得说实体类Entity和传输对象DTO一定要分开。我见过太多项目直接把 Entity 当接口返回值结果数据库字段一改前端就崩了更别提把导航属性序列化出去导致的循环引用问题。DTO 的存在就是为了隔离数据库结构和接口契约这个隔离层不能省。2.2 为什么选 EF Core 而不是 Dapper 或纯 ADO.NET这是个老生常谈的选型问题。Dapper 性能更好、SQL 完全可控纯 ADO.NET 最底层最灵活那为什么还选 EF Core我的判断标准是看项目的查询复杂度和团队规模。EF Core 的核心优势在于强类型查询、自动迁移、关系映射、变更追踪。对于以 CRUD 为主、查询条件相对规整的业务系统EF Core 能把开发效率拉高一大截。你写context.Users.Where(u u.Age 18)编译器帮你检查字段名重构时改属性名会自动同步这是字符串拼接 SQL 永远给不了的体验。但 EF Core 不是银弹。复杂报表查询、多表聚合、性能敏感的大数据量场景我依然会用 Dapper 或原生 SQL 兜底。EF Core 从 3.0 开始支持FromSqlRaw和ExecuteSqlRaw混合使用完全没问题。我的实际做法是常规 CRUD 走 LINQ复杂查询走原生 SQL两者在同一个 DbContext 里共存互不干扰。至于 SQL Server选它的理由更实际和 .NET 生态天然亲和EF Core 对它的支持最成熟迁移工具、连接池、事务处理都是一等公民待遇。如果项目没有明确的国产化或跨平台数据库要求SQL Server 是省心的选择。2.3 DbContext 生命周期一个决定性能与正确性的关键参数这是我最想强调的一点。ASP.NET Core 的依赖注入容器里DbContext 默认注册方式是Scoped也就是每个 HTTP 请求一个实例。这个默认值是有道理的但很多人不清楚背后的逻辑随手改成Singleton或Transient结果踩坑。Scoped推荐每个请求一个 DbContext请求结束自动释放。变更追踪在单次请求内有效事务边界清晰连接池利用率合理。这是绝大多数 WebAPI 场景的正确选择。Transient每次注入都创建新实例。听起来很干净但同一个请求里如果多个 Service 都注入了 DbContext会创建多个实例变更追踪各自为政保存时容易出现部分实体没被追踪到的诡异问题。Singleton绝对不能用。DbContext 不是线程安全的多个请求并发访问同一个实例会导致数据错乱甚至崩溃。注册代码就一行但含义要清楚builder.Services.AddDbContextAppDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(Default)));AddDbContext默认就是 Scoped不用额外指定。如果你确实需要在后台任务里用 DbContext那就用IDbContextFactoryT手动创建用完即弃别想着复用。3. 核心配置与实体建模的实操细节3.1 连接字符串与 DbContext 的初始化配置连接字符串放在appsettings.json里是标准做法但有几个细节新手容易忽略。首先是连接字符串的写法SQL Server 的典型格式{ ConnectionStrings: { Default: Serverlocalhost;DatabaseAppDb;User Idsa;PasswordYourPassword;TrustServerCertificateTrue; } }TrustServerCertificateTrue这个参数在本地开发环境几乎必加否则新版驱动会因为证书问题连不上。生产环境则应该配置正规证书而不是简单粗暴地信任所有证书。然后是 DbContext 的配置。除了指定连接我通常还会配几个选项builder.Services.AddDbContextAppDbContext(options { options.UseSqlServer( builder.Configuration.GetConnectionString(Default), sqlOptions sqlOptions.EnableRetryOnFailure( maxRetryCount: 3, maxRetryDelay: TimeSpan.FromSeconds(5), errorNumbersToAdd: null)); options.EnableSensitiveDataLogging( builder.Environment.IsDevelopment()); });EnableRetryOnFailure是应对瞬时数据库故障的利器网络抖动、数据库短暂不可用时自动重试避免接口直接报错。EnableSensitiveDataLogging只在开发环境开它会把参数值打进日志方便调试但生产环境开着有泄露敏感数据的风险务必用环境判断包起来。3.2 实体类设计与 Fluent API 配置的取舍实体类就是普通的 POCO 类但怎么配映射关系有两种方式数据注解Attribute和 Fluent API。我的经验是——简单约束用注解复杂关系用 Fluent API两者可以混用。数据注解适合字段级的简单规则比如public class Product { public int Id { get; set; } [Required] [MaxLength(100)] public string Name { get; set; } string.Empty; [Column(TypeName decimal(18,2))] public decimal Price { get; set; } public int CategoryId { get; set; } public Category? Category { get; set; } }但涉及外键行为、索引、复合键、多对多这些Fluent API 更清晰。在OnModelCreating里集中配置protected override void OnModelCreating(ModelBuilder modelBuilder) { modelBuilder.EntityProduct(entity { entity.HasKey(e e.Id); entity.Property(e e.Name).IsRequired().HasMaxLength(100); entity.HasIndex(e e.Name).IsUnique(); entity.HasOne(e e.Category) .WithMany(c c.Products) .HasForeignKey(e e.CategoryId) .OnDelete(DeleteBehavior.Restrict); }); }这里OnDelete(DeleteBehavior.Restrict)是个关键决策。默认行为是Cascade删分类会连带删掉所有产品这在很多业务里是灾难。改成Restrict后有产品关联的分类删不掉数据库层面就挡住了误操作。这个坑我见过不止一次线上误删数据往往就是级联删除没配好。3.3 迁移机制让数据库结构跟着代码走EF Core 的迁移Migration是它最实用的功能之一。核心逻辑是你改实体类生成迁移文件应用到数据库三步走。命令不复杂dotnet ef migrations add InitialCreate dotnet ef database update但真实项目里迁移的管理策略比命令本身重要得多。我的做法是开发阶段每个功能分支的实体变更都生成独立迁移命名要能看懂比如AddProductIndex、AlterOrderStatusColumn别用默认的Migration1、Migration2。测试/生产环境不在应用启动时自动Migrate()而是生成 SQL 脚本由运维审核后执行。自动迁移在生产环境是危险操作一旦迁移出错回滚很麻烦。生成脚本的命令dotnet ef migrations script --idempotent -o migrate.sql--idempotent参数会生成可重复执行的脚本已经应用过的迁移会跳过适合多环境部署。注意迁移文件一定要纳入版本控制。我见过有人把 Migrations 目录加进 .gitignore结果换台机器就不知道数据库结构是怎么演变的这是给自己挖坑。4. 接口实现全流程从查询到写入的落地代码4.1 一个完整的 CRUD 接口长什么样光说不练假把式这里给一个产品管理的完整示例。先看 Service 层它封装了数据访问逻辑public class ProductService : IProductService { private readonly AppDbContext _context; public ProductService(AppDbContext context) { _context context; } public async TaskListProductDto GetAllAsync(int page, int size) { return await _context.Products .AsNoTracking() .OrderBy(p p.Id) .Skip((page - 1) * size) .Take(size) .Select(p new ProductDto { Id p.Id, Name p.Name, Price p.Price, CategoryName p.Category!.Name }) .ToListAsync(); } public async Taskint CreateAsync(CreateProductDto dto) { var product new Product { Name dto.Name, Price dto.Price, CategoryId dto.CategoryId }; _context.Products.Add(product); await _context.SaveChangesAsync(); return product.Id; } }这段代码里有几个值得展开的点。AsNoTracking()用于只读查询跳过变更追踪性能提升明显尤其是返回大量数据时。Select投影到 DTO 是在数据库端完成的只查需要的列不会把整张表的字段都拉回来。分页用Skip/Take注意页码从 1 开始时要减 1这个边界新手常错。Controller 层就很薄了[ApiController] [Route(api/[controller])] public class ProductsController : ControllerBase { private readonly IProductService _service; public ProductsController(IProductService service) { _service service; } [HttpGet] public async TaskActionResultListProductDto Get( [FromQuery] int page 1, [FromQuery] int size 20) { if (size 100) size 100; return Ok(await _service.GetAllAsync(page, size)); } [HttpPost] public async TaskActionResultint Create([FromBody] CreateProductDto dto) { var id await _service.CreateAsync(dto); return CreatedAtAction(nameof(Get), new { id }, id); } }size 100的兜底限制是必须的否则有人传size100000直接把数据库拖垮。这种防御性代码在真实项目里比什么架构都重要。4.2 查询性能优化什么时候该怀疑 EF CoreEF Core 生成的 SQL 大部分时候够用但有几类场景要特别警惕。第一是 N1 查询问题循环里访问导航属性每次触发一次数据库查询。解决办法是用Include预加载var categories await _context.Categories .Include(c c.Products) .ToListAsync();但Include也不能滥用多层嵌套 Include 会生成巨大的 JOIN数据量一大就慢。我的经验是需要关联数据时优先考虑投影Select 到 DTO而不是无脑 Include。第二是客户端求值。EF Core 3.0 之后无法翻译成 SQL 的表达式会直接抛异常这是好事逼你把逻辑挪到能翻译的位置。但有些写法虽然能翻译效率很差比如在 Where 里对字段做函数运算// 慢无法用索引 _context.Products.Where(p p.Name.ToLower() abc) // 快可以用索引假设排序规则不区分大小写 _context.Products.Where(p p.Name abc)第三是批量操作。EF Core 7 之前批量更新/删除要逐条加载再改性能很差。EF Core 7 引入了ExecuteUpdate和ExecuteDelete直接生成批量 SQLawait _context.Products .Where(p p.Price 10) .ExecuteUpdateAsync(s s.SetProperty(p p.Price, p p.Price * 1.1m));这个 API 不走变更追踪直接发 SQL大批量操作时性能差距是数量级的。4.3 事务处理单库操作的边界控制EF Core 的SaveChanges本身是事务性的一次保存里的所有变更要么全成功要么全失败。但跨多次SaveChanges的操作就需要显式事务using var transaction await _context.Database.BeginTransactionAsync(); try { _context.Orders.Add(order); await _context.SaveChangesAsync(); _context.OrderItems.AddRange(items); await _context.SaveChangesAsync(); await transaction.CommitAsync(); } catch { await transaction.RollbackAsync(); throw; }这里有个容易忽略的点BeginTransactionAsync开启的事务和SaveChanges内部的事务是嵌套关系外层事务提交前内层不会真正落库。另外事务要尽量短别在事务里做 HTTP 调用或耗时计算否则会长时间持有锁拖垮并发。5. 常见问题排查与避坑经验实录5.1 连接与迁移类问题速查这类问题占了新手求助的一大半我整理成表格方便对照现象可能原因解决方向启动报证书错误未信任开发证书连接串加TrustServerCertificateTrue或配置正规证书迁移命令找不到未安装 EF 工具执行dotnet tool install --global dotnet-ef数据库已存在但表没建迁移未应用检查database update是否执行或脚本是否跑过修改实体后查询报列不存在迁移未生成或未应用生成新迁移并更新数据库并发时偶发数据错乱DbContext 被注册成 Singleton改回 Scoped检查是否有静态字段持有上下文迁移这块我踩过最深的坑是多人协作时两个人各自生成了迁移合并分支后迁移顺序错乱导致database update报迁移已存在或找不到前序迁移。解决办法是合并前先沟通或者用dotnet ef migrations remove撤掉本地未提交的迁移拉取最新代码后重新生成。5.2 性能与并发问题的排查思路接口突然变慢排查顺序我一般是这样的先看日志里 EF Core 生成的 SQL用LogTo(Console.WriteLine)或日志级别调到Information就能看到。如果 SQL 本身慢看执行计划有没有走索引如果 SQL 快但接口慢看是不是 N1 查询或者序列化开销。序列化这块有个隐蔽的坑返回大对象图时JSON 序列化可能比数据库查询还耗时。解决办法是投影到精简的 DTO别把整个实体图扔出去。另外循环引用会导致序列化直接抛异常这也是为什么实体和 DTO 要分开的又一个理由。并发写入冲突是另一个高频问题。EF Core 默认用最后写入获胜策略两个请求同时改同一条记录后提交的会覆盖先提交的。要检测冲突可以用并发令牌RowVersionpublic class Order { public int Id { get; set; } [Timestamp] public byte[] RowVersion { get; set; } Array.Emptybyte(); }配置后如果保存时版本号不匹配会抛DbUpdateConcurrencyException业务层捕获后提示用户数据已被他人修改请刷新重试。这个机制在订单、库存这类场景几乎是必需的。5.3 几个只有踩过才知道的实操心得第一个心得别在 DbContext 上做长生命周期缓存。有人为了优化性能把查询结果缓存在 DbContext 的字段里结果数据永远不更新。缓存要用专门的缓存组件如内存缓存或分布式缓存DbContext 用完就该释放。第二个心得日志里别开敏感数据。EnableSensitiveDataLogging在开发环境很方便但一旦误开到生产密码、身份证号这些会明文进日志。我的做法是用环境变量严格控制代码里写死IsDevelopment()判断。第三个心得迁移脚本要能回滚。EF Core 生成的迁移默认只有 Up 没有 Down 的完整回滚逻辑复杂变更比如删列回滚会丢数据。生产环境的破坏性变更我习惯先备份或者写一个补偿脚本别指望database update能一键还原。第四个心得连接池参数要调。SQL Server 连接池默认最大 100 个连接高并发下容易耗尽。可以在连接串里加Max Pool Size200;Min Pool Size5;但别盲目调大连接数超过数据库承载能力反而更糟。压测之后再定参数别拍脑袋。6. 项目演进中的扩展方向与个人体会这套基础架构搭好之后后续扩展其实很自然。比如要加缓存在 Service 层包一层IMemoryCache或分布式缓存即可数据访问逻辑不用动。要加审计日志可以重写SaveChangesAsync在保存前遍历变更追踪器把修改记录写进审计表。要做读写分离EF Core 支持配置多个连接读走从库、写走主库虽然配置稍复杂但架构上是可行的。我个人在实际操作中的体会是这套组合真正的价值不在于能跑起来而在于它给了你一个清晰的演进路径。一开始可以很简单一个 DbContext、几个实体、几个接口就能交付随着业务增长你可以逐步引入仓储模式、CQRS、领域事件每一步都有落脚点不用推倒重来。反倒是那些一开始就追求终极架构的项目往往在过度设计中耗尽了精力。最后分享一个小技巧新项目初始化时我会先写一个最小的健康检查接口里面执行一次context.Database.CanConnectAsync()部署后第一件事就是调这个接口确认数据库连通性。这个习惯帮我省去了无数次接口 500 但不知道是代码问题还是数据库问题的排查时间。数据库连接、迁移状态、连接池健康这些基础设施层面的东西越早暴露越好别等业务逻辑堆上去之后再来找根因。 
长河君 · 2026/10/26 4:30:08 · 阅读 1.2k ASP.NET Core WebAPI + EF Core + SQL Server 企业级接口开发实战指南
1. 为什么这套组合拳至今仍是企业级接口开发的主力方案做后端接口开发的朋友大概率都绕不开一个经典命题怎么用最短的路径把数据库里的数据安全、高效地暴露成 HTTP 接口。我这些年接手过不少项目有从零起步的也有半路接手别人代码的但凡涉及关系型数据存储和接口服务ASP.NET Core WebAPI EF Core SQL Server这套组合出现的频率高得惊人。它不是最新潮的方案甚至有人觉得它老派但真到了要交付、要维护、要扩展的场景里这套组合的稳定性和开发效率依然很难被替代。先把话说清楚这篇内容讲的是如何在一个 ASP.NET Core WebAPI 项目里用 Entity Framework Core 作为数据访问层对接 SQL Server 数据库完成从建模、配置、迁移到接口落地的完整链路。它解决的核心问题是——让开发者不用手写大量 ADO.NET 样板代码就能把数据库操作变成强类型的 C# 对象操作同时保留对 SQL 性能的可控性。适合谁看刚接触 .NET 后端的新手可以照着走一遍完整流程有一定经验但一直靠抄配置过日子的开发者可以在这里补齐对迁移机制、DbContext 生命周期、查询性能这些关键点的理解带团队的技术负责人也能从中找到一些规范层面的参考。我见过太多项目在这套组合上翻车问题往往不在技术本身而在于几个关键决策没想清楚DbContext 该注册成什么生命周期、实体关系怎么配、迁移脚本谁来管、查询什么时候该用原生 SQL。这些细节在官方文档里都有但文档不会告诉你在真实项目里踩过什么坑。下面我按实际落地的顺序把整套流程拆开讲中间穿插我自己踩过的坑和验证过的做法。2. 整体架构设计与技术选型思路2.1 分层结构怎么切才不别扭很多人一上来就纠结要不要搞 DDD 那一套我的建议是先别想那么远。对于一个中等规模的 WebAPI 项目我通常采用三层结构接口层Controllers、业务层Services、数据访问层DbContext 实体。这个切法的好处是职责清晰Controller 只负责接收请求和返回响应Service 承载业务逻辑数据访问层专注和数据库打交道。为什么不把 EF Core 的查询直接写在 Controller 里小项目确实可以但一旦业务复杂起来Controller 会迅速膨胀成几百行的上帝类测试也没法写。把数据访问收敛到 Service 层之后Controller 变得很薄单元测试时可以用接口 mock 掉数据层这是实打实的收益。具体到目录结构我习惯这样组织/Controllers 接口定义 /Services 业务逻辑 /Data DbContext、实体配置 /Models 实体类、DTO /Migrations EF Core 迁移文件这里有个细节值得说实体类Entity和传输对象DTO一定要分开。我见过太多项目直接把 Entity 当接口返回值结果数据库字段一改前端就崩了更别提把导航属性序列化出去导致的循环引用问题。DTO 的存在就是为了隔离数据库结构和接口契约这个隔离层不能省。2.2 为什么选 EF Core 而不是 Dapper 或纯 ADO.NET这是个老生常谈的选型问题。Dapper 性能更好、SQL 完全可控纯 ADO.NET 最底层最灵活那为什么还选 EF Core我的判断标准是看项目的查询复杂度和团队规模。EF Core 的核心优势在于强类型查询、自动迁移、关系映射、变更追踪。对于以 CRUD 为主、查询条件相对规整的业务系统EF Core 能把开发效率拉高一大截。你写context.Users.Where(u u.Age 18)编译器帮你检查字段名重构时改属性名会自动同步这是字符串拼接 SQL 永远给不了的体验。但 EF Core 不是银弹。复杂报表查询、多表聚合、性能敏感的大数据量场景我依然会用 Dapper 或原生 SQL 兜底。EF Core 从 3.0 开始支持FromSqlRaw和ExecuteSqlRaw混合使用完全没问题。我的实际做法是常规 CRUD 走 LINQ复杂查询走原生 SQL两者在同一个 DbContext 里共存互不干扰。至于 SQL Server选它的理由更实际和 .NET 生态天然亲和EF Core 对它的支持最成熟迁移工具、连接池、事务处理都是一等公民待遇。如果项目没有明确的国产化或跨平台数据库要求SQL Server 是省心的选择。2.3 DbContext 生命周期一个决定性能与正确性的关键参数这是我最想强调的一点。ASP.NET Core 的依赖注入容器里DbContext 默认注册方式是Scoped也就是每个 HTTP 请求一个实例。这个默认值是有道理的但很多人不清楚背后的逻辑随手改成Singleton或Transient结果踩坑。Scoped推荐每个请求一个 DbContext请求结束自动释放。变更追踪在单次请求内有效事务边界清晰连接池利用率合理。这是绝大多数 WebAPI 场景的正确选择。Transient每次注入都创建新实例。听起来很干净但同一个请求里如果多个 Service 都注入了 DbContext会创建多个实例变更追踪各自为政保存时容易出现部分实体没被追踪到的诡异问题。Singleton绝对不能用。DbContext 不是线程安全的多个请求并发访问同一个实例会导致数据错乱甚至崩溃。注册代码就一行但含义要清楚builder.Services.AddDbContextAppDbContext(options options.UseSqlServer(builder.Configuration.GetConnectionString(Default)));AddDbContext默认就是 Scoped不用额外指定。如果你确实需要在后台任务里用 DbContext那就用IDbContextFactoryT手动创建用完即弃别想着复用。3. 核心配置与实体建模的实操细节3.1 连接字符串与 DbContext 的初始化配置连接字符串放在appsettings.json里是标准做法但有几个细节新手容易忽略。首先是连接字符串的写法SQL Server 的典型格式{ ConnectionStrings: { Default: Serverlocalhost;DatabaseAppDb;User Idsa;PasswordYourPassword;TrustServerCertificateTrue; } }TrustServerCertificateTrue这个参数在本地开发环境几乎必加否则新版驱动会因为证书问题连不上。生产环境则应该配置正规证书而不是简单粗暴地信任所有证书。然后是 DbContext 的配置。除了指定连接我通常还会配几个选项builder.Services.AddDbContextAppDbContext(options { options.UseSqlServer( builder.Configuration.GetConnectionString(Default), sqlOptions sqlOptions.EnableRetryOnFailure( maxRetryCount: 3, maxRetryDelay: TimeSpan.FromSeconds(5), errorNumbersToAdd: null)); options.EnableSensitiveDataLogging( builder.Environment.IsDevelopment()); });EnableRetryOnFailure是应对瞬时数据库故障的利器网络抖动、数据库短暂不可用时自动重试避免接口直接报错。EnableSensitiveDataLogging只在开发环境开它会把参数值打进日志方便调试但生产环境开着有泄露敏感数据的风险务必用环境判断包起来。3.2 实体类设计与 Fluent API 配置的取舍实体类就是普通的 POCO 类但怎么配映射关系有两种方式数据注解Attribute和 Fluent API。我的经验是——简单约束用注解复杂关系用 Fluent API两者可以混用。数据注解适合字段级的简单规则比如public class Product { public int Id { get; set; } [Required] [MaxLength(100)] public string Name { get; set; } string.Empty; [Column(TypeName decimal(18,2))] public decimal Price { get; set; } public int CategoryId { get; set; } public Category? Category { get; set; } }但涉及外键行为、索引、复合键、多对多这些Fluent API 更清晰。在OnModelCreating里集中配置protected override void OnModelCreating(ModelBuilder modelBuilder) { modelBuilder.EntityProduct(entity { entity.HasKey(e e.Id); entity.Property(e e.Name).IsRequired().HasMaxLength(100); entity.HasIndex(e e.Name).IsUnique(); entity.HasOne(e e.Category) .WithMany(c c.Products) .HasForeignKey(e e.CategoryId) .OnDelete(DeleteBehavior.Restrict); }); }这里OnDelete(DeleteBehavior.Restrict)是个关键决策。默认行为是Cascade删分类会连带删掉所有产品这在很多业务里是灾难。改成Restrict后有产品关联的分类删不掉数据库层面就挡住了误操作。这个坑我见过不止一次线上误删数据往往就是级联删除没配好。3.3 迁移机制让数据库结构跟着代码走EF Core 的迁移Migration是它最实用的功能之一。核心逻辑是你改实体类生成迁移文件应用到数据库三步走。命令不复杂dotnet ef migrations add InitialCreate dotnet ef database update但真实项目里迁移的管理策略比命令本身重要得多。我的做法是开发阶段每个功能分支的实体变更都生成独立迁移命名要能看懂比如AddProductIndex、AlterOrderStatusColumn别用默认的Migration1、Migration2。测试/生产环境不在应用启动时自动Migrate()而是生成 SQL 脚本由运维审核后执行。自动迁移在生产环境是危险操作一旦迁移出错回滚很麻烦。生成脚本的命令dotnet ef migrations script --idempotent -o migrate.sql--idempotent参数会生成可重复执行的脚本已经应用过的迁移会跳过适合多环境部署。注意迁移文件一定要纳入版本控制。我见过有人把 Migrations 目录加进 .gitignore结果换台机器就不知道数据库结构是怎么演变的这是给自己挖坑。4. 接口实现全流程从查询到写入的落地代码4.1 一个完整的 CRUD 接口长什么样光说不练假把式这里给一个产品管理的完整示例。先看 Service 层它封装了数据访问逻辑public class ProductService : IProductService { private readonly AppDbContext _context; public ProductService(AppDbContext context) { _context context; } public async TaskListProductDto GetAllAsync(int page, int size) { return await _context.Products .AsNoTracking() .OrderBy(p p.Id) .Skip((page - 1) * size) .Take(size) .Select(p new ProductDto { Id p.Id, Name p.Name, Price p.Price, CategoryName p.Category!.Name }) .ToListAsync(); } public async Taskint CreateAsync(CreateProductDto dto) { var product new Product { Name dto.Name, Price dto.Price, CategoryId dto.CategoryId }; _context.Products.Add(product); await _context.SaveChangesAsync(); return product.Id; } }这段代码里有几个值得展开的点。AsNoTracking()用于只读查询跳过变更追踪性能提升明显尤其是返回大量数据时。Select投影到 DTO 是在数据库端完成的只查需要的列不会把整张表的字段都拉回来。分页用Skip/Take注意页码从 1 开始时要减 1这个边界新手常错。Controller 层就很薄了[ApiController] [Route(api/[controller])] public class ProductsController : ControllerBase { private readonly IProductService _service; public ProductsController(IProductService service) { _service service; } [HttpGet] public async TaskActionResultListProductDto Get( [FromQuery] int page 1, [FromQuery] int size 20) { if (size 100) size 100; return Ok(await _service.GetAllAsync(page, size)); } [HttpPost] public async TaskActionResultint Create([FromBody] CreateProductDto dto) { var id await _service.CreateAsync(dto); return CreatedAtAction(nameof(Get), new { id }, id); } }size 100的兜底限制是必须的否则有人传size100000直接把数据库拖垮。这种防御性代码在真实项目里比什么架构都重要。4.2 查询性能优化什么时候该怀疑 EF CoreEF Core 生成的 SQL 大部分时候够用但有几类场景要特别警惕。第一是 N1 查询问题循环里访问导航属性每次触发一次数据库查询。解决办法是用Include预加载var categories await _context.Categories .Include(c c.Products) .ToListAsync();但Include也不能滥用多层嵌套 Include 会生成巨大的 JOIN数据量一大就慢。我的经验是需要关联数据时优先考虑投影Select 到 DTO而不是无脑 Include。第二是客户端求值。EF Core 3.0 之后无法翻译成 SQL 的表达式会直接抛异常这是好事逼你把逻辑挪到能翻译的位置。但有些写法虽然能翻译效率很差比如在 Where 里对字段做函数运算// 慢无法用索引 _context.Products.Where(p p.Name.ToLower() abc) // 快可以用索引假设排序规则不区分大小写 _context.Products.Where(p p.Name abc)第三是批量操作。EF Core 7 之前批量更新/删除要逐条加载再改性能很差。EF Core 7 引入了ExecuteUpdate和ExecuteDelete直接生成批量 SQLawait _context.Products .Where(p p.Price 10) .ExecuteUpdateAsync(s s.SetProperty(p p.Price, p p.Price * 1.1m));这个 API 不走变更追踪直接发 SQL大批量操作时性能差距是数量级的。4.3 事务处理单库操作的边界控制EF Core 的SaveChanges本身是事务性的一次保存里的所有变更要么全成功要么全失败。但跨多次SaveChanges的操作就需要显式事务using var transaction await _context.Database.BeginTransactionAsync(); try { _context.Orders.Add(order); await _context.SaveChangesAsync(); _context.OrderItems.AddRange(items); await _context.SaveChangesAsync(); await transaction.CommitAsync(); } catch { await transaction.RollbackAsync(); throw; }这里有个容易忽略的点BeginTransactionAsync开启的事务和SaveChanges内部的事务是嵌套关系外层事务提交前内层不会真正落库。另外事务要尽量短别在事务里做 HTTP 调用或耗时计算否则会长时间持有锁拖垮并发。5. 常见问题排查与避坑经验实录5.1 连接与迁移类问题速查这类问题占了新手求助的一大半我整理成表格方便对照现象可能原因解决方向启动报证书错误未信任开发证书连接串加TrustServerCertificateTrue或配置正规证书迁移命令找不到未安装 EF 工具执行dotnet tool install --global dotnet-ef数据库已存在但表没建迁移未应用检查database update是否执行或脚本是否跑过修改实体后查询报列不存在迁移未生成或未应用生成新迁移并更新数据库并发时偶发数据错乱DbContext 被注册成 Singleton改回 Scoped检查是否有静态字段持有上下文迁移这块我踩过最深的坑是多人协作时两个人各自生成了迁移合并分支后迁移顺序错乱导致database update报迁移已存在或找不到前序迁移。解决办法是合并前先沟通或者用dotnet ef migrations remove撤掉本地未提交的迁移拉取最新代码后重新生成。5.2 性能与并发问题的排查思路接口突然变慢排查顺序我一般是这样的先看日志里 EF Core 生成的 SQL用LogTo(Console.WriteLine)或日志级别调到Information就能看到。如果 SQL 本身慢看执行计划有没有走索引如果 SQL 快但接口慢看是不是 N1 查询或者序列化开销。序列化这块有个隐蔽的坑返回大对象图时JSON 序列化可能比数据库查询还耗时。解决办法是投影到精简的 DTO别把整个实体图扔出去。另外循环引用会导致序列化直接抛异常这也是为什么实体和 DTO 要分开的又一个理由。并发写入冲突是另一个高频问题。EF Core 默认用最后写入获胜策略两个请求同时改同一条记录后提交的会覆盖先提交的。要检测冲突可以用并发令牌RowVersionpublic class Order { public int Id { get; set; } [Timestamp] public byte[] RowVersion { get; set; } Array.Emptybyte(); }配置后如果保存时版本号不匹配会抛DbUpdateConcurrencyException业务层捕获后提示用户数据已被他人修改请刷新重试。这个机制在订单、库存这类场景几乎是必需的。5.3 几个只有踩过才知道的实操心得第一个心得别在 DbContext 上做长生命周期缓存。有人为了优化性能把查询结果缓存在 DbContext 的字段里结果数据永远不更新。缓存要用专门的缓存组件如内存缓存或分布式缓存DbContext 用完就该释放。第二个心得日志里别开敏感数据。EnableSensitiveDataLogging在开发环境很方便但一旦误开到生产密码、身份证号这些会明文进日志。我的做法是用环境变量严格控制代码里写死IsDevelopment()判断。第三个心得迁移脚本要能回滚。EF Core 生成的迁移默认只有 Up 没有 Down 的完整回滚逻辑复杂变更比如删列回滚会丢数据。生产环境的破坏性变更我习惯先备份或者写一个补偿脚本别指望database update能一键还原。第四个心得连接池参数要调。SQL Server 连接池默认最大 100 个连接高并发下容易耗尽。可以在连接串里加Max Pool Size200;Min Pool Size5;但别盲目调大连接数超过数据库承载能力反而更糟。压测之后再定参数别拍脑袋。6. 项目演进中的扩展方向与个人体会这套基础架构搭好之后后续扩展其实很自然。比如要加缓存在 Service 层包一层IMemoryCache或分布式缓存即可数据访问逻辑不用动。要加审计日志可以重写SaveChangesAsync在保存前遍历变更追踪器把修改记录写进审计表。要做读写分离EF Core 支持配置多个连接读走从库、写走主库虽然配置稍复杂但架构上是可行的。我个人在实际操作中的体会是这套组合真正的价值不在于能跑起来而在于它给了你一个清晰的演进路径。一开始可以很简单一个 DbContext、几个实体、几个接口就能交付随着业务增长你可以逐步引入仓储模式、CQRS、领域事件每一步都有落脚点不用推倒重来。反倒是那些一开始就追求终极架构的项目往往在过度设计中耗尽了精力。最后分享一个小技巧新项目初始化时我会先写一个最小的健康检查接口里面执行一次context.Database.CanConnectAsync()部署后第一件事就是调这个接口确认数据库连通性。这个习惯帮我省去了无数次接口 500 但不知道是代码问题还是数据库问题的排查时间。数据库连接、迁移状态、连接池健康这些基础设施层面的东西越早暴露越好别等业务逻辑堆上去之后再来找根因。