Dapper这个名字只要在.NET圈子里混过一两年的人应该都不陌生。我第一次接触它是在一个被EF Core拖到响应迟迟上不去的接口改造项目里老组长丢下一句“换成Dapper试试”然后我就被这个只有几百KB的库深深折服了。它轻、快、直接就像数据库世界的“快递小哥”——不跟你整那些花里胡哨的集装箱调度接一单、跑一趟、货送到手就走。这篇文章我就结合自己这几年在真实项目里的使用经验把Dapper的定位、原理、核心用法以及搜索热词里那个高频报错“ExecuteReader要求已打开且可用的Connection但当前状态为Open”好好拆一拆。这篇文章适合谁看如果你是刚接触.NET的数据访问层新手或者正在EF Core和轻量ORM之间纠结选型的开发亦或是已经被Dapper的某个连接状态报错折磨过的老哥那这篇应该都能给你一些参考。1. “快递小哥”这个比喻恰好说透了Dapper的定位1.1 它是谁生出来的为什么生Dapper是Stack Overflow团队开源的一个轻量级ORM诞生背景其实非常朴素他们发现自家的网站流量巨大EF等重型ORM在性能上不够用但他们又不想退回纯手写ADO.NET那种到处重复的体力活于是干脆在IDbConnection上封装了一套扩展方法把“数据库连接”和“对象映射”这两件事做到极致精简。Dapper的整个核心就一个SqlMapper.cs文件几百KB的体积却能提供绝大多数项目日常需要的CRUD和查询能力。这个“生出来就为了快”的基因决定了它后来的一切设计选择。它不是要在功能上对标完整的ORM全家桶而是要做一个“把SQL执行掉、把数据变成对象、然后立刻走人”的工具人。理解了这个背景你就能明白它为什么不像EF Core那样提供迁移、导航属性、变更追踪这些“五星级酒店式”的服务——因为它压根没打算干那些活。1.2 和EF Core这个“货拉拉”相比它到底强在哪、弱在哪很多人在选型时会纠结Dapper和EF Core纠结的点往往是被网上片面的“谁吊打谁”带偏了。我自己的感受是这两个东西压根不是同一个物种硬要比性能没有意义关键看你的业务场景适合用什么。EF Core更像“货拉拉”帮你规划路线、装卸货物、管理仓库你只管下单剩下它都包了Dapper则是“快递小哥”你告诉它去哪个仓库取哪件货它骑上小电驴就冲出去了但仓库管理和路线规划它不管。维度DapperEF CoreSQL控制力完全手写SQL100%掌控LINQ生成SQL遇坑可写原生SQL性能极快接近手写ADO.NET中等表达式树解析和变更追踪有开销学习成本会SQL就会用要学LINQ、导航属性、迁移、代理等功能覆盖轻量无全自动迁移/导航全功能迁移、追踪、乐观并发、级联适合场景性能敏感、查询复杂、团队熟悉SQL快速CRUD迭代、领域模型复杂1.3 谁最适合用Dapper以我目前参与过的项目来看最合适Dapper的场景有几个报表查询接口、高并发读写的数据中心、需要手写复杂SQL做深度调优的系统以及那些已经被ORM的“黑盒映射”坑过无数次、决定把SQL命脉握回自己手里的团队。相反如果你的项目还在早期快速迭代每天在加表和改字段主力工作就是简单CRUD那EF Core能帮你节省大量时间。说白了Dapper不是一个“到处通用”的银弹而是一个“快准狠”的尖刀。你要清楚自己的项目需要什么再去选型。2. 一包一送的设计哲学Dapper性能神话背后的三个核心机制很多人以为Dapper快是因为它“用了某种黑科技”其实它的优化思路一点都不玄乎。Dapper性能快到接近原生ADO.NET主要靠三个机制绕过表达树翻译、动态IL生成映射、彻底无状态。这三个机制我都逐一验证过实际效果确实立竿见影。2.1 第一步省的是“翻译官”——原生SQL零损耗EF Core要把一句LINQ转换成SQL中间要经过表达式树解析、语义分析、SQL生成、参数化等一系列步骤。这个“翻译官”在简单查询时可能感觉不到开销但一旦查询复杂、调用频繁开销就会积少成多。Dapper直接绕开了整个翻译环节——你传什么SQL字符串它就把什么发给数据库引擎。// EF Core 写法——你需要让它把 LINQ 翻译成 SQL var users await context.Users .Where(u u.Age 18 u.City Shanghai) .OrderByDescending(u u.CreatedAt) .Take(20) .ToListAsync(); // Dapper 写法——你自己把 SQL 写好它只管执行 var users conn.QueryUser( SELECT TOP 20 * FROM Users WHERE Age age AND City city ORDER BY CreatedAt DESC, new { age 18, city Shanghai }).ToList();有人可能会觉得“那Dapper不就是ADO.NET换个皮吗”还真不是它帮你解决的是ADO.NET时代最磨人的那部分工作——DataReader到对象的逐字段赋值。这个才是接下来要说的第二个机制。2.2 第二步省的是“搬运工”——IL动态生成映射手写ADO.NET的典型痛苦是从SqlDataReader里取数据要一个一个字段手写赋值while (reader.Read()) { users.Add(new User { Id reader.GetInt32(0), Name reader.GetString(1), Age reader.GetInt32(2) }); }字段一多这种代码就纯属体力活而且极易写错列索引。Dapper的厉害之处在于它第一次执行某个查询时会动态生成一个专门用于映射该实体类型的IL代码把“从IDataReader取字段值”和“给对象属性赋值”这两个动作编译成高速的委托。之后的同类型查询直接复用这个缓存好的映射器速度堪比手写代码。我第一次知道这个机制的时候下意识觉得“动态IL生成”应该是很高深的魔法后来细想其实就是C#编译器在背后帮我们做了类似AutoMapper的运行时映射优化。但Dapper把这个优化做到了极致小巧没有额外依赖。这也是为什么你在项目中使用它几乎感觉不到性能损耗。2.3 第三步省的是“仓库管理”——无状态、无追踪、用完即走EF Core为了支持变更追踪、延迟加载、工作单元等等会在DbContext里维护一大堆实体状态和缓存信息。每次查询都要检查实体是否已存在、状态是否需要更新、导航属性是否要加载这些逻辑在复杂场景下很有用但在纯查询场景下全是纯开销。Dapper则完全不做这些事情查出来的对象就是普通POCO用完就扔没有任何附加状态需要管理。配合.NET的DI容器和using语句连接开一次、查一次、关一次干净利落。我见过很多团队把Dapper用成“无状态连接工厂”就是因为它不给程序员搞那些“隐形的家务活”。3. 从第一行代码到生产级Dapper核心API的实战拆解3.1 Query查询结果到对象的三种写法先看最简单的场景——把查询结果映射到一个强类型集合using (var conn new SqlConnection(connectionString)) { conn.Open(); // 写法一强类型映射 IEnumerableUser users conn.QueryUser( SELECT Id, Name, Age, City FROM Users WHERE Age age, new { age 18 }); // 写法二动态类型 IEnumerabledynamic rows conn.Query( SELECT Id, Name FROM Users WHERE City city, new { city Shanghai }); }这里要特别注意一个细节Query方法对连接的管理逻辑很聪明。它默认会在查询结束时自动打开连接如果当前是关闭状态并在查询结束后恢复连接原状态但如果调用方传入并打开了的连接它不会多管闲事。这个设计我很喜欢它让你在“快速原型”和“精细控制”之间自由切换。3.2 Execute增删改的正确打开方式查询用Query非查询操作则用Execute。这个方法返回的是受影响行数string sql UPDATE Users SET LastLoginTime now WHERE Id id; int affected conn.Execute(sql, new { now DateTime.Now, id 1001 });当你的参数是动态对象时Dapper会智能匹配SQL里的参数名和匿名对象的属性名。这里我的一个习惯是参数对象一律使用匿名类并且属性名和SQL参数名保持严格一致能少踩很多坑。3.3 ExecuteScalar与ExecuteReader各自的分工与边界ExecuteScalar用于返回单个值的查询比如“统计总记录数”“查询用户名是否存在”。ExecuteReader则适合需要对DataReader进行流式处理的场景比如边读边处理超大结果集。但需要注意的是ExecuteReader对连接的状态有严格要求——这是解开那个热搜报错的关键钥匙我得单独在第4章里细说这里先留个悬念。3.4 多结果集与多映射一次快递送多件货Dapper还提供了两个比较进阶的APIQueryMultiple和QueryT1, T2分别用来处理“一次SQL返回多个结果集”和“表关联映射到多个对象”。// QueryMultiple一次拿多个结果集省去多次往返数据库的损耗 using (var multi conn.QueryMultiple( SELECT * FROM Users; SELECT * FROM Orders;)) { var users multi.ReadUser().ToList(); var orders multi.ReadOrder().ToList(); }这种一次取多包货的能力在高频接口里非常实用。我优化过一个首页聚合接口原先是5次独立查询改成QueryMultiple后一次往返就搞定响应耗时降了一个数量级。4. 热搜词里藏着的那个坑ExecuteReader“要求已打开且可用的Connection”到底怎么回事如果去搜索框里敲“Dapper”最常弹出的关联词之一就是“dapper executereader 要求已打开且可用的 connection。连接的当前状态为打开。”这个报错信息我当年第一次看到时也懵了——因为它的字面意思非常矛盾你告诉我“必须打开连接”但连接状态明明就是Open。这到底是Dapper的bug还是我的代码问题4.1 一个反直觉的报告状态明明是Open却报错要求Open先说结论这大概率不是Dapper的bug而是一个由“执行的时机”和“连接的生存周期”错配引发的异常。为了讲清楚我们要先搞明白ExecuteReader和Query这两者在语义上的本质区别。Query是“一次性查询并映射成对象集合”它会在拿到所有数据后立即关闭连接或归还连接池。而ExecuteReader返回的是一个DataReaderDataReader是流式的、按需读取的也就是说数据库连接必须在整个读取过程中保持打开状态否则没法逐行取数据。所以Dapper在设计ExecuteReader时做了一个相对另类的决定它不像Query那样帮你自动打开连接而是严格要求调用方确保连接处于打开状态。如果连接状态不对它直接抛InvalidOperationException。那“状态明明Open却报错”的骚操作是怎么发生的答案是一个.NET语言特性——延迟执行deferred execution。4.2 最经典的翻车场景迭代器的“延迟交货”看看下面这段代码这就是当初让我排查到深夜的“罪魁祸首”// 这段代码看起来没有任何毛病但实际运行会翻车 public IEnumerableUser GetUsers() { using (var conn new SqlConnection(_connectionString)) { conn.Open(); return conn.QueryUser(SELECT * FROM Users); // 你以为是这里执行查询不是这行的对象还没真正执行SQL } // - 在这里using 块结束了conn 也被 Dispose 了 }问题就出在Query返回的是IEnumerable这是一个惰性集合。当你调用conn.Query ()时它并没有立刻去执行SQL而是返回了一个迭代器对象。这个迭代器直到被foreach或ToList()枚举时才会真正触发数据库查询。但using块的方法一结束conn就立刻被释放了。等调用方真正去遍历返回值时连接已经“死”了Dapper自然抛出一个“要求已打开且可用的Connection”。更诡异的是由于数据库连接池的存在被Dispose的连接对象并不会立刻变成Closed状态它在某些时刻仍可能显示为Open或处于“即将被回收”的中间态于是就有了那句非常具象的报错“连接的当前状态为打开。”那为什么Query报错会比较少而ExecuteReader报这个错特别多因为ExecuteReader要求调用方显式打开连接很多人会在方法里处理好连接生命周期后把reader返回出去结果reader需要在方法外被读取连接在方法结束时被关掉了。同一个逻辑放在ExecuteReader上出错率远高于Query。4.3 第二个经典翻车场景异步方法里using提前“退场”异步场景是另一个高频“翻车点”。尤其是在async / await不熟的人手里极其容易写出下面的代码public async TaskIEnumerableUser GetUsersAsync() { using (var conn new SqlConnection(_connectionString)) { conn.Open(); var result conn.QueryUser(SELECT * FROM Users); // 忘加 await这不是异步方法 return await Task.FromResult(result); // 返回的却是同步集合 } // using 块结束连接被释放 }这里的细节是如果你在异步方法里调用的是同步Dapper APIQuery而不是QueryAsync那连接生命周期很容易被压缩到using块内。当返回集合被实际枚举时连接已经不在可用状态。另一个更隐蔽的坑是Async方法里用了await conn.QueryAsync但没有await直接return了Task 然后方法提前退出了using块连接被释放。等外层await这个Task时连接已经没了。public TaskIEnumerableUser GetUsersAsync() // 注意没有 async 关键字 { using (var conn new SqlConnection(_connectionString)) { conn.Open(); return conn.QueryAsyncUser(SELECT * FROM Users); // 同步方法直接返回异步任务 // 方法立刻返回using 块立刻结束连接立刻被释放 } }这种“异步方法没写成异步”的代码是.NET项目里最常见的线程池饥饿、连接状态错误的来源之一。我之前还专门写过一篇文章讲async/await的隐性陷阱Dapper这个报错就是最典型的下饭菜。4.4 排查策略与修复模板三句话判断问题在哪当你再次遇到这个报错我建议你按下面的顺序做三件事第一在你调用ExecuteReader或者Query/QueryAsync的地方打断点检查conn.State到底是什么状态。如果是Closed问题就在连接管理如果是Open继续第二步。第二检查你返回的集合或reader是否被“延迟使用”。也就是连接释放之后代码才真正去枚举结果。如果是用ToList()或ToArray()在连接释放前直接把数据物化。第三检查是不是异步代码把连接生命周期“带偏”了。最直观的办法是把async关键字和await补齐使用QueryAsync并且确保using块里面就完成了物化。标准的修复模板如下public async TaskListUser GetUsersAsync() { using (var conn new SqlConnection(_connectionString)) { conn.Open(); // 用异步API 在using块内物化绝不把可延迟执行的集合带出连接生命周期 return (await conn.QueryAsyncUser(SELECT * FROM Users)).ToList(); } }一句话总结这个坑用Dapper时连接能开多晚就开多晚能关多早就多早但一定不能在连接关闭后再使用它返回的惰性对象。5. 进阶玩法Dapper在生产环境中的几个高价值用法既然你已经能避开最核心的那个坑了我再分享几个我在生产环境里实测下来非常提升效率的Dapper用法。5.1 DynamicParameters告别字符串拼接式SQL很多人用Dapper时参数还是靠字符串拼接来拼这是很危险的SQL注入隐患。Dapper官方推荐的DynamicParameters可以优雅解决动态查询条件的拼装问题var dp new DynamicParameters(); dp.Add(Name, user.Name, DbType.String, ParameterDirection.Input, 50); dp.Add(Age, user.Age); dp.Add(Id, dbType: DbType.Int32, direction: ParameterDirection.Output); conn.Execute(sp_InsertUser, dp, commandType: CommandType.StoredProcedure); int newId dp.Getint(Id); // 拿到存储过程返回的Output参数这个类尤其在面对动态排序、动态过滤条件时非常好用。你可以在方法里根据业务条件选择性Add参数而不必维护一长串匿名对象的定义。我之前在做一个多条件筛选列表时就是用这个解决了参数数量不稳定、SQL语句拼接脏乱的问题。5.2 批量插入的高效套路Dapper没有内置高性能的批量插入因为它的定位就是一个轻量“快递小哥”。但我们可以用SqlBulkCopy配合快速构建DataTable实现稳定高效的大批量写入using (var conn new SqlConnection(_connectionString)) { conn.Open(); using (var bulk new SqlBulkCopy(conn)) { bulk.DestinationTableName Users; bulk.ColumnMappings.Add(Id, Id); bulk.ColumnMappings.Add(Name, Name); // 用一个DataTable接收内存中的User列表 var dt new DataTable(); dt.Columns.Add(Id, typeof(int)); dt.Columns.Add(Name, typeof(string)); foreach (var u in users) dt.Rows.Add(u.Id, u.Name); bulk.WriteToServer(dt); } }如果你不想引入SqlBulkCopy这种偏底层的API也可以考虑将批量插入写成多值SQL用一条INSERT语句插入多条记录string sql INSERT INTO Users (Name, City) VALUES (Name, City);; conn.Execute(sql, users.Select(u new { Name u.Name, City u.City }));这个方案对千级以下的数据量效果不错超大批量建议还是用SqlBulkCopy。5.3 与存储过程的无缝协作许多传统系统依然大量依赖存储过程Dapper对这个场景的支持非常丝滑。你不需要写任何额外映射代码直接调用并接收结果集即可var user conn.QueryFirstOrDefaultUser( sp_GetUserById, new { id userId }, commandType: CommandType.StoredProcedure);QueryFirstOrDefault是Dapper提供的一个便捷方法专门用于“只取第一行没有则返回null”的场景。其实Query系列还有QuerySingle、QueryFirst等多个变体选哪个完全看你预期结果集的状态预期唯一时用Single系预期可能没有时用FirstOrDefault系。这个选择讲究得很细但也正是Dapper“把控制权交还给你”的体现。5.4 缓存查询结果手工实现的一个小技巧因为Dapper本身不带缓存我在高并发查询项目中习惯自己做一层简单的缓存封装把查询SQL和参数序列化成缓存键命中就直接返回不命中才查库。这个方案看起来笨但实际效果十分稳。用Dapper做数据层时所有优化都得靠我们自己来补这也是它“快递小哥”定位下的必然选择——服务好但别指望它管仓库。我在这几年项目里最大的体会就是框架不是越重越好而是越匹配越好。数据库世界里的“快递小哥”Dapper用最简单的方式帮你把数据传输这件事做到极致但它需要你在连接管理、SQL编写、参数组织等方面更仔细。如果你能掌握它的脾性它会成为数据访问层里最得力的一个工具箱如果只是随手拿来瞎用那些“明明打开了却报没打开”的妖蛾子就会接踵而至。老实说直到现在我每次写Dapper代码心里都会默念一句快递送到手之前别把配送员连接放走。这句话帮我避开了90%的连接状态坑也一并送给你。
Dapper轻量级ORM：连接状态报错排查与性能优化指南
Dapper这个名字只要在.NET圈子里混过一两年的人应该都不陌生。我第一次接触它是在一个被EF Core拖到响应迟迟上不去的接口改造项目里老组长丢下一句“换成Dapper试试”然后我就被这个只有几百KB的库深深折服了。它轻、快、直接就像数据库世界的“快递小哥”——不跟你整那些花里胡哨的集装箱调度接一单、跑一趟、货送到手就走。这篇文章我就结合自己这几年在真实项目里的使用经验把Dapper的定位、原理、核心用法以及搜索热词里那个高频报错“ExecuteReader要求已打开且可用的Connection但当前状态为Open”好好拆一拆。这篇文章适合谁看如果你是刚接触.NET的数据访问层新手或者正在EF Core和轻量ORM之间纠结选型的开发亦或是已经被Dapper的某个连接状态报错折磨过的老哥那这篇应该都能给你一些参考。1. “快递小哥”这个比喻恰好说透了Dapper的定位1.1 它是谁生出来的为什么生Dapper是Stack Overflow团队开源的一个轻量级ORM诞生背景其实非常朴素他们发现自家的网站流量巨大EF等重型ORM在性能上不够用但他们又不想退回纯手写ADO.NET那种到处重复的体力活于是干脆在IDbConnection上封装了一套扩展方法把“数据库连接”和“对象映射”这两件事做到极致精简。Dapper的整个核心就一个SqlMapper.cs文件几百KB的体积却能提供绝大多数项目日常需要的CRUD和查询能力。这个“生出来就为了快”的基因决定了它后来的一切设计选择。它不是要在功能上对标完整的ORM全家桶而是要做一个“把SQL执行掉、把数据变成对象、然后立刻走人”的工具人。理解了这个背景你就能明白它为什么不像EF Core那样提供迁移、导航属性、变更追踪这些“五星级酒店式”的服务——因为它压根没打算干那些活。1.2 和EF Core这个“货拉拉”相比它到底强在哪、弱在哪很多人在选型时会纠结Dapper和EF Core纠结的点往往是被网上片面的“谁吊打谁”带偏了。我自己的感受是这两个东西压根不是同一个物种硬要比性能没有意义关键看你的业务场景适合用什么。EF Core更像“货拉拉”帮你规划路线、装卸货物、管理仓库你只管下单剩下它都包了Dapper则是“快递小哥”你告诉它去哪个仓库取哪件货它骑上小电驴就冲出去了但仓库管理和路线规划它不管。维度DapperEF CoreSQL控制力完全手写SQL100%掌控LINQ生成SQL遇坑可写原生SQL性能极快接近手写ADO.NET中等表达式树解析和变更追踪有开销学习成本会SQL就会用要学LINQ、导航属性、迁移、代理等功能覆盖轻量无全自动迁移/导航全功能迁移、追踪、乐观并发、级联适合场景性能敏感、查询复杂、团队熟悉SQL快速CRUD迭代、领域模型复杂1.3 谁最适合用Dapper以我目前参与过的项目来看最合适Dapper的场景有几个报表查询接口、高并发读写的数据中心、需要手写复杂SQL做深度调优的系统以及那些已经被ORM的“黑盒映射”坑过无数次、决定把SQL命脉握回自己手里的团队。相反如果你的项目还在早期快速迭代每天在加表和改字段主力工作就是简单CRUD那EF Core能帮你节省大量时间。说白了Dapper不是一个“到处通用”的银弹而是一个“快准狠”的尖刀。你要清楚自己的项目需要什么再去选型。2. 一包一送的设计哲学Dapper性能神话背后的三个核心机制很多人以为Dapper快是因为它“用了某种黑科技”其实它的优化思路一点都不玄乎。Dapper性能快到接近原生ADO.NET主要靠三个机制绕过表达树翻译、动态IL生成映射、彻底无状态。这三个机制我都逐一验证过实际效果确实立竿见影。2.1 第一步省的是“翻译官”——原生SQL零损耗EF Core要把一句LINQ转换成SQL中间要经过表达式树解析、语义分析、SQL生成、参数化等一系列步骤。这个“翻译官”在简单查询时可能感觉不到开销但一旦查询复杂、调用频繁开销就会积少成多。Dapper直接绕开了整个翻译环节——你传什么SQL字符串它就把什么发给数据库引擎。// EF Core 写法——你需要让它把 LINQ 翻译成 SQL var users await context.Users .Where(u u.Age 18 u.City Shanghai) .OrderByDescending(u u.CreatedAt) .Take(20) .ToListAsync(); // Dapper 写法——你自己把 SQL 写好它只管执行 var users conn.QueryUser( SELECT TOP 20 * FROM Users WHERE Age age AND City city ORDER BY CreatedAt DESC, new { age 18, city Shanghai }).ToList();有人可能会觉得“那Dapper不就是ADO.NET换个皮吗”还真不是它帮你解决的是ADO.NET时代最磨人的那部分工作——DataReader到对象的逐字段赋值。这个才是接下来要说的第二个机制。2.2 第二步省的是“搬运工”——IL动态生成映射手写ADO.NET的典型痛苦是从SqlDataReader里取数据要一个一个字段手写赋值while (reader.Read()) { users.Add(new User { Id reader.GetInt32(0), Name reader.GetString(1), Age reader.GetInt32(2) }); }字段一多这种代码就纯属体力活而且极易写错列索引。Dapper的厉害之处在于它第一次执行某个查询时会动态生成一个专门用于映射该实体类型的IL代码把“从IDataReader取字段值”和“给对象属性赋值”这两个动作编译成高速的委托。之后的同类型查询直接复用这个缓存好的映射器速度堪比手写代码。我第一次知道这个机制的时候下意识觉得“动态IL生成”应该是很高深的魔法后来细想其实就是C#编译器在背后帮我们做了类似AutoMapper的运行时映射优化。但Dapper把这个优化做到了极致小巧没有额外依赖。这也是为什么你在项目中使用它几乎感觉不到性能损耗。2.3 第三步省的是“仓库管理”——无状态、无追踪、用完即走EF Core为了支持变更追踪、延迟加载、工作单元等等会在DbContext里维护一大堆实体状态和缓存信息。每次查询都要检查实体是否已存在、状态是否需要更新、导航属性是否要加载这些逻辑在复杂场景下很有用但在纯查询场景下全是纯开销。Dapper则完全不做这些事情查出来的对象就是普通POCO用完就扔没有任何附加状态需要管理。配合.NET的DI容器和using语句连接开一次、查一次、关一次干净利落。我见过很多团队把Dapper用成“无状态连接工厂”就是因为它不给程序员搞那些“隐形的家务活”。3. 从第一行代码到生产级Dapper核心API的实战拆解3.1 Query查询结果到对象的三种写法先看最简单的场景——把查询结果映射到一个强类型集合using (var conn new SqlConnection(connectionString)) { conn.Open(); // 写法一强类型映射 IEnumerableUser users conn.QueryUser( SELECT Id, Name, Age, City FROM Users WHERE Age age, new { age 18 }); // 写法二动态类型 IEnumerabledynamic rows conn.Query( SELECT Id, Name FROM Users WHERE City city, new { city Shanghai }); }这里要特别注意一个细节Query方法对连接的管理逻辑很聪明。它默认会在查询结束时自动打开连接如果当前是关闭状态并在查询结束后恢复连接原状态但如果调用方传入并打开了的连接它不会多管闲事。这个设计我很喜欢它让你在“快速原型”和“精细控制”之间自由切换。3.2 Execute增删改的正确打开方式查询用Query非查询操作则用Execute。这个方法返回的是受影响行数string sql UPDATE Users SET LastLoginTime now WHERE Id id; int affected conn.Execute(sql, new { now DateTime.Now, id 1001 });当你的参数是动态对象时Dapper会智能匹配SQL里的参数名和匿名对象的属性名。这里我的一个习惯是参数对象一律使用匿名类并且属性名和SQL参数名保持严格一致能少踩很多坑。3.3 ExecuteScalar与ExecuteReader各自的分工与边界ExecuteScalar用于返回单个值的查询比如“统计总记录数”“查询用户名是否存在”。ExecuteReader则适合需要对DataReader进行流式处理的场景比如边读边处理超大结果集。但需要注意的是ExecuteReader对连接的状态有严格要求——这是解开那个热搜报错的关键钥匙我得单独在第4章里细说这里先留个悬念。3.4 多结果集与多映射一次快递送多件货Dapper还提供了两个比较进阶的APIQueryMultiple和QueryT1, T2分别用来处理“一次SQL返回多个结果集”和“表关联映射到多个对象”。// QueryMultiple一次拿多个结果集省去多次往返数据库的损耗 using (var multi conn.QueryMultiple( SELECT * FROM Users; SELECT * FROM Orders;)) { var users multi.ReadUser().ToList(); var orders multi.ReadOrder().ToList(); }这种一次取多包货的能力在高频接口里非常实用。我优化过一个首页聚合接口原先是5次独立查询改成QueryMultiple后一次往返就搞定响应耗时降了一个数量级。4. 热搜词里藏着的那个坑ExecuteReader“要求已打开且可用的Connection”到底怎么回事如果去搜索框里敲“Dapper”最常弹出的关联词之一就是“dapper executereader 要求已打开且可用的 connection。连接的当前状态为打开。”这个报错信息我当年第一次看到时也懵了——因为它的字面意思非常矛盾你告诉我“必须打开连接”但连接状态明明就是Open。这到底是Dapper的bug还是我的代码问题4.1 一个反直觉的报告状态明明是Open却报错要求Open先说结论这大概率不是Dapper的bug而是一个由“执行的时机”和“连接的生存周期”错配引发的异常。为了讲清楚我们要先搞明白ExecuteReader和Query这两者在语义上的本质区别。Query是“一次性查询并映射成对象集合”它会在拿到所有数据后立即关闭连接或归还连接池。而ExecuteReader返回的是一个DataReaderDataReader是流式的、按需读取的也就是说数据库连接必须在整个读取过程中保持打开状态否则没法逐行取数据。所以Dapper在设计ExecuteReader时做了一个相对另类的决定它不像Query那样帮你自动打开连接而是严格要求调用方确保连接处于打开状态。如果连接状态不对它直接抛InvalidOperationException。那“状态明明Open却报错”的骚操作是怎么发生的答案是一个.NET语言特性——延迟执行deferred execution。4.2 最经典的翻车场景迭代器的“延迟交货”看看下面这段代码这就是当初让我排查到深夜的“罪魁祸首”// 这段代码看起来没有任何毛病但实际运行会翻车 public IEnumerableUser GetUsers() { using (var conn new SqlConnection(_connectionString)) { conn.Open(); return conn.QueryUser(SELECT * FROM Users); // 你以为是这里执行查询不是这行的对象还没真正执行SQL } // - 在这里using 块结束了conn 也被 Dispose 了 }问题就出在Query返回的是IEnumerable这是一个惰性集合。当你调用conn.Query ()时它并没有立刻去执行SQL而是返回了一个迭代器对象。这个迭代器直到被foreach或ToList()枚举时才会真正触发数据库查询。但using块的方法一结束conn就立刻被释放了。等调用方真正去遍历返回值时连接已经“死”了Dapper自然抛出一个“要求已打开且可用的Connection”。更诡异的是由于数据库连接池的存在被Dispose的连接对象并不会立刻变成Closed状态它在某些时刻仍可能显示为Open或处于“即将被回收”的中间态于是就有了那句非常具象的报错“连接的当前状态为打开。”那为什么Query报错会比较少而ExecuteReader报这个错特别多因为ExecuteReader要求调用方显式打开连接很多人会在方法里处理好连接生命周期后把reader返回出去结果reader需要在方法外被读取连接在方法结束时被关掉了。同一个逻辑放在ExecuteReader上出错率远高于Query。4.3 第二个经典翻车场景异步方法里using提前“退场”异步场景是另一个高频“翻车点”。尤其是在async / await不熟的人手里极其容易写出下面的代码public async TaskIEnumerableUser GetUsersAsync() { using (var conn new SqlConnection(_connectionString)) { conn.Open(); var result conn.QueryUser(SELECT * FROM Users); // 忘加 await这不是异步方法 return await Task.FromResult(result); // 返回的却是同步集合 } // using 块结束连接被释放 }这里的细节是如果你在异步方法里调用的是同步Dapper APIQuery而不是QueryAsync那连接生命周期很容易被压缩到using块内。当返回集合被实际枚举时连接已经不在可用状态。另一个更隐蔽的坑是Async方法里用了await conn.QueryAsync但没有await直接return了Task 然后方法提前退出了using块连接被释放。等外层await这个Task时连接已经没了。public TaskIEnumerableUser GetUsersAsync() // 注意没有 async 关键字 { using (var conn new SqlConnection(_connectionString)) { conn.Open(); return conn.QueryAsyncUser(SELECT * FROM Users); // 同步方法直接返回异步任务 // 方法立刻返回using 块立刻结束连接立刻被释放 } }这种“异步方法没写成异步”的代码是.NET项目里最常见的线程池饥饿、连接状态错误的来源之一。我之前还专门写过一篇文章讲async/await的隐性陷阱Dapper这个报错就是最典型的下饭菜。4.4 排查策略与修复模板三句话判断问题在哪当你再次遇到这个报错我建议你按下面的顺序做三件事第一在你调用ExecuteReader或者Query/QueryAsync的地方打断点检查conn.State到底是什么状态。如果是Closed问题就在连接管理如果是Open继续第二步。第二检查你返回的集合或reader是否被“延迟使用”。也就是连接释放之后代码才真正去枚举结果。如果是用ToList()或ToArray()在连接释放前直接把数据物化。第三检查是不是异步代码把连接生命周期“带偏”了。最直观的办法是把async关键字和await补齐使用QueryAsync并且确保using块里面就完成了物化。标准的修复模板如下public async TaskListUser GetUsersAsync() { using (var conn new SqlConnection(_connectionString)) { conn.Open(); // 用异步API 在using块内物化绝不把可延迟执行的集合带出连接生命周期 return (await conn.QueryAsyncUser(SELECT * FROM Users)).ToList(); } }一句话总结这个坑用Dapper时连接能开多晚就开多晚能关多早就多早但一定不能在连接关闭后再使用它返回的惰性对象。5. 进阶玩法Dapper在生产环境中的几个高价值用法既然你已经能避开最核心的那个坑了我再分享几个我在生产环境里实测下来非常提升效率的Dapper用法。5.1 DynamicParameters告别字符串拼接式SQL很多人用Dapper时参数还是靠字符串拼接来拼这是很危险的SQL注入隐患。Dapper官方推荐的DynamicParameters可以优雅解决动态查询条件的拼装问题var dp new DynamicParameters(); dp.Add(Name, user.Name, DbType.String, ParameterDirection.Input, 50); dp.Add(Age, user.Age); dp.Add(Id, dbType: DbType.Int32, direction: ParameterDirection.Output); conn.Execute(sp_InsertUser, dp, commandType: CommandType.StoredProcedure); int newId dp.Getint(Id); // 拿到存储过程返回的Output参数这个类尤其在面对动态排序、动态过滤条件时非常好用。你可以在方法里根据业务条件选择性Add参数而不必维护一长串匿名对象的定义。我之前在做一个多条件筛选列表时就是用这个解决了参数数量不稳定、SQL语句拼接脏乱的问题。5.2 批量插入的高效套路Dapper没有内置高性能的批量插入因为它的定位就是一个轻量“快递小哥”。但我们可以用SqlBulkCopy配合快速构建DataTable实现稳定高效的大批量写入using (var conn new SqlConnection(_connectionString)) { conn.Open(); using (var bulk new SqlBulkCopy(conn)) { bulk.DestinationTableName Users; bulk.ColumnMappings.Add(Id, Id); bulk.ColumnMappings.Add(Name, Name); // 用一个DataTable接收内存中的User列表 var dt new DataTable(); dt.Columns.Add(Id, typeof(int)); dt.Columns.Add(Name, typeof(string)); foreach (var u in users) dt.Rows.Add(u.Id, u.Name); bulk.WriteToServer(dt); } }如果你不想引入SqlBulkCopy这种偏底层的API也可以考虑将批量插入写成多值SQL用一条INSERT语句插入多条记录string sql INSERT INTO Users (Name, City) VALUES (Name, City);; conn.Execute(sql, users.Select(u new { Name u.Name, City u.City }));这个方案对千级以下的数据量效果不错超大批量建议还是用SqlBulkCopy。5.3 与存储过程的无缝协作许多传统系统依然大量依赖存储过程Dapper对这个场景的支持非常丝滑。你不需要写任何额外映射代码直接调用并接收结果集即可var user conn.QueryFirstOrDefaultUser( sp_GetUserById, new { id userId }, commandType: CommandType.StoredProcedure);QueryFirstOrDefault是Dapper提供的一个便捷方法专门用于“只取第一行没有则返回null”的场景。其实Query系列还有QuerySingle、QueryFirst等多个变体选哪个完全看你预期结果集的状态预期唯一时用Single系预期可能没有时用FirstOrDefault系。这个选择讲究得很细但也正是Dapper“把控制权交还给你”的体现。5.4 缓存查询结果手工实现的一个小技巧因为Dapper本身不带缓存我在高并发查询项目中习惯自己做一层简单的缓存封装把查询SQL和参数序列化成缓存键命中就直接返回不命中才查库。这个方案看起来笨但实际效果十分稳。用Dapper做数据层时所有优化都得靠我们自己来补这也是它“快递小哥”定位下的必然选择——服务好但别指望它管仓库。我在这几年项目里最大的体会就是框架不是越重越好而是越匹配越好。数据库世界里的“快递小哥”Dapper用最简单的方式帮你把数据传输这件事做到极致但它需要你在连接管理、SQL编写、参数组织等方面更仔细。如果你能掌握它的脾性它会成为数据访问层里最得力的一个工具箱如果只是随手拿来瞎用那些“明明打开了却报没打开”的妖蛾子就会接踵而至。老实说直到现在我每次写Dapper代码心里都会默念一句快递送到手之前别把配送员连接放走。这句话帮我避开了90%的连接状态坑也一并送给你。
