1. 项目概述为什么我们需要Dapper在.NET开发的世界里数据访问层DAL的构建一直是个绕不开的话题。从早期的ADO.NET手写SqlConnection、SqlCommand到后来重量级的Entity FrameworkEF全家桶开发者们总是在“灵活性”和“开发效率”之间反复权衡。手写ADO.NET代码繁琐且容易出错而EF虽然功能强大但学习曲线陡峭在某些高性能、复杂SQL的场景下其生成的SQL语句又可能不尽如人意性能损耗也让人头疼。这时Dapper就登场了。它不是什么全新的ORM对象关系映射框架而是一个轻量级的“对象映射器”。你可以把它理解为你和ADO.NET之间的一层“智能胶水”。它接管了最枯燥、最容易出错的那部分工作——将数据库查询返回的DataReader数据自动、高效地映射到你定义的C#实体类对象上。你依然需要自己编写SQL这保证了你对数据库操作的绝对控制权和灵活性但后续繁琐的“行数据到对象属性”的赋值循环Dapper帮你一键搞定。简单来说如果你怀念手写SQL的精准与高效但又厌倦了随之而来的重复性编码和潜在错误Dapper就是你一直在找的那个工具。它特别适合对性能有要求、需要执行复杂查询、或者项目架构倾向于“微服务”、“简洁仓储”模式的场景。接下来我们就深入拆解Dapper的核心使用让你能快速上手并应用到实际项目中。2. Dapper核心设计与思路拆解2.1 轻量级哲学微内核与扩展性Dapper的设计哲学非常明确做最少的事并做到极致。它的核心库Dapper.dll非常小只专注于一件事——高效地执行参数化SQL并将结果映射到对象。它没有DbContext没有迁移Migration没有复杂的配置约定也没有延迟加载Lazy Loading或变更跟踪Change Tracking。这种“微内核”设计带来了几个直接好处性能卓越因为没有额外的运行时开销如EF的变更跟踪上下文Dapper在数据查询和映射上的速度极快 benchmarks 显示其性能非常接近原生ADO.NET。透明可控你写的SQL就是最终发往数据库的SQL参数化后没有“魔法”便于调试和性能优化。学习成本低API极其简洁主要就是几个扩展方法半小时就能掌握核心用法。那么复杂的多表关联、事务、存储过程调用怎么办Dapper通过扩展方法和灵活的映射机制来应对。它提供了一系列方法如Query,Execute,QueryMultiple来处理常见场景更复杂的逻辑则需要你组合这些基础方法或者编写一点辅助代码。这赋予了开发者极大的自由度但也要求你对SQL和数据库操作有基本的了解。2.2 核心接口IDbConnection的扩展Dapper的所有功能都是通过为System.Data.IDbConnection接口添加扩展方法来实现的。这意味着只要你有一个实现了IDbConnection的数据库连接对象如SqlConnection,MySqlConnection,NpgsqlConnection等你就能立即使用Dapper。这种设计非常巧妙无侵入性它不要求你继承某个特定的基类或实现某个接口可以轻松集成到任何现有项目中。数据库无关性理论上支持所有ADO.NET提供程序。虽然Dapper内部对某些数据库如SQL Server有特别的优化但核心API是通用的。符合习惯.NET开发者对IDbConnection再熟悉不过使用Dapper的感觉就像在使用一个“增强版”的ADO.NET。2.3 映射策略约定、配置与自定义Dapper的默认对象映射基于简单的名称匹配不区分大小写。数据库查询返回的列名会自动匹配到对象属性名。例如查询返回的UserId列会自动映射到实体类的UserId属性。但现实世界的数据库和对象模型往往不是一一对应的。Dapper为此提供了多种映射策略自定义映射通过SetTypeMap或实现SqlMapper.ITypeMap接口可以定义复杂的映射规则。多映射Multi Mapping用于将单行数据映射到多个关联对象是处理一对一、一对多关联查询的利器。动态类型与匿名对象对于临时性、结构不固定的查询结果可以直接使用dynamic或匿名类型来接收提供了额外的灵活性。这种“默认简单高级可配”的策略确保了在80%的简单场景下开箱即用同时在20%的复杂场景下也有路可走。3. 核心细节解析与实操要点3.1 基础CRUD操作详解Dapper的CRUD操作主要通过Query查、Execute增删改两大系列方法完成。查询单条记录QueryFirst/QuerySingleusing var connection new SqlConnection(connectionString); var sql SELECT * FROM Users WHERE UserId UserId; var user connection.QueryFirstOrDefaultUser(sql, new { UserId 1 });QueryFirst返回序列中的第一个元素。如果查询结果为空则抛出异常。QueryFirstOrDefault返回序列中的第一个元素如果序列为空则返回默认值对于引用类型是null。这是查询单条记录最常用、最安全的方法。QuerySingle期望查询结果只有一行。如果结果为多行或为空都会抛出异常。适用于确知只有一条记录的场景如按主键查询。参数化UserId是参数占位符通过匿名对象new { UserId 1 }传递参数。Dapper会自动处理参数化有效防止SQL注入。查询多条记录Queryvar sql SELECT * FROM Users WHERE IsActive IsActive; var activeUsers connection.QueryUser(sql, new { IsActive true }).ToList();返回一个IEnumerableUser可以方便地使用LINQ进行后续处理。注意Dapper默认延迟执行调用.ToList()会立即执行查询并将结果物化到内存中。执行增删改Executevar insertSql INSERT INTO Users (UserName, Email) VALUES (UserName, Email); SELECT CAST(SCOPE_IDENTITY() AS INT); var newUserId connection.ExecuteScalarint(insertSql, new { UserName John, Email johnexample.com }); var updateSql UPDATE Users SET Email Email WHERE UserId UserId; var rowsAffected connection.Execute(updateSql, new { Email newjohnexample.com, UserId newUserId });Execute执行命令返回受影响的行数。ExecuteScalar执行命令并返回结果集中第一行第一列的值。常用于获取插入后生成的自增ID如示例中的SCOPE_IDENTITY()。注意Execute方法执行INSERT/UPDATE/DELETE但它不返回新插入的ID。如果需要ID必须像示例一样在SQL语句中显式查询并配合ExecuteScalar使用或者使用Query方法执行插入语句。3.2 参数传递与防注入机制Dapper强制使用参数化查询这是其安全性的基石。它支持多种参数传递方式匿名对象最常用如new { Id 1, Name test }。动态对象ExpandoObject或DynamicParameters。后者更强大可以指定参数方向输入/输出、类型、大小等。字典Dictionarystring, object。实体对象可以直接将实体对象作为参数其属性名与SQL参数名匹配即可。重要技巧使用DynamicParameters处理复杂参数var parameters new DynamicParameters(); parameters.Add(UserId, 1, DbType.Int32, ParameterDirection.Input); parameters.Add(TotalCount, dbType: DbType.Int32, direction: ParameterDirection.Output); connection.Execute(usp_GetUserDetails, parameters, commandType: CommandType.StoredProcedure); var totalCount parameters.Getint(TotalCount);当需要调用存储过程、处理输出参数、或者参数类型需要精确控制时DynamicParameters是你的最佳选择。3.3 多结果集与复杂映射处理多个结果集QueryMultiple当存储过程或复杂查询返回多个结果集时QueryMultiple非常高效。var sql SELECT * FROM Users WHERE UserId id; SELECT * FROM Orders WHERE UserId id; ; using var multi connection.QueryMultiple(sql, new { id 1 }); var user multi.ReadFirstOrDefaultUser(); var orders multi.ReadOrder().ToList();它只与数据库进行一次往返依次读取各个结果集。多映射Multi Mapping用于关联查询将单行数据拆分到多个对象。var sql SELECT * FROM Users u INNER JOIN Orders o ON u.UserId o.UserId WHERE u.UserId id; var data connection.QueryUser, Order, User( sql, (user, order) { // 此委托定义了如何将行数据组合成对象 // 例如可以将order关联到user if (user.Orders null) user.Orders new ListOrder(); user.Orders.Add(order); return user; }, new { id 1 }, splitOn: OrderId // 告诉Dapper从哪个列开始是第二个对象Order的数据 ).Distinct().ToList();splitOn参数至关重要它告诉Dapper数据库列在何处“分割”以映射到不同的对象。默认是“Id”如果表中有多个“Id”列或主键列名不同必须显式指定。4. 实操过程与核心环节实现4.1 环境准备与基础封装首先通过NuGet安装DapperInstall-Package Dapper在实际项目中我们不会在每个地方都散落着using var connection new ...的代码。一个常见的做法是进行简单的封装管理连接生命周期和提供便捷方法。基础仓储层示例public class DapperRepository { private readonly string _connectionString; public DapperRepository(IConfiguration configuration) { _connectionString configuration.GetConnectionString(DefaultConnection); } // 获取一个打开的连接 private async TaskIDbConnection CreateConnectionAsync() { var connection new SqlConnection(_connectionString); await connection.OpenAsync(); return connection; } // 封装查询方法异步 public async TaskT QueryFirstOrDefaultAsyncT(string sql, object parameters null) { using var connection await CreateConnectionAsync(); return await connection.QueryFirstOrDefaultAsyncT(sql, parameters); } // 封装执行方法异步 public async Taskint ExecuteAsync(string sql, object parameters null) { using var connection await CreateConnectionAsync(); return await connection.ExecuteAsync(sql, parameters); } // 更多封装方法... }实操心得连接对象IDbConnection实现了IDisposable。虽然Dapper方法内部会在必要时打开连接但最佳实践是显式管理连接生命周期。使用using语句或在依赖注入DI容器中将其注册为Scoped生命周期确保连接被及时关闭。上面的封装在方法内部创建和释放连接适用于轻量级操作。对于需要跨多个方法使用同一连接和事务的场景需要在更高层级如业务逻辑单元管理连接。4.2 事务处理实战Dapper的事务处理非常直观与ADO.NET一脉相承。public async Taskbool TransferFundsAsync(int fromAccountId, int toAccountId, decimal amount) { // 注意连接需要在外部创建以便在同一个连接上开启事务 using var connection new SqlConnection(_connectionString); await connection.OpenAsync(); // 开始事务 using var transaction await connection.BeginTransactionAsync(); try { var deductSql UPDATE Accounts SET Balance Balance - Amount WHERE AccountId AccountId AND Balance Amount; var addSql UPDATE Accounts SET Balance Balance Amount WHERE AccountId AccountId; // 执行扣款 var rowsDeducted await connection.ExecuteAsync(deductSql, new { Amount amount, AccountId fromAccountId }, transaction); if (rowsDeducted ! 1) { // 扣款失败余额不足或账户不存在 await transaction.RollbackAsync(); return false; } // 执行加款 var rowsAdded await connection.ExecuteAsync(addSql, new { Amount amount, AccountId toAccountId }, transaction); if (rowsAdded ! 1) { // 加款失败账户不存在 await transaction.RollbackAsync(); return false; } // 全部成功提交事务 await transaction.CommitAsync(); return true; } catch (Exception ex) { // 发生异常回滚事务 await transaction.RollbackAsync(); // 记录日志或重新抛出异常 throw; } }关键点事务IDbTransaction必须在同一个打开的连接上创建。所有在事务内的Dapper操作都必须将transaction对象作为参数传入对应的方法。务必使用try-catch块在异常发生时回滚事务避免连接池中的连接持有未完成的事务。检查受影响行数是确保业务逻辑正确性的重要手段。4.3 性能优化技巧使用异步方法Dapper为所有主要方法提供了Async后缀的异步版本如QueryAsync,ExecuteAsync。在ASP.NET Core等现代框架中应优先使用异步方法以避免阻塞线程池线程提高应用吞吐量。合理使用缓存Dapper会对SQL语句的解析将SQL文本和参数转换为具体的命令进行缓存。这意味着同一条SQL语句文本完全相同第二次执行时会更快。因此尽量避免动态拼接SQL尤其是字符串拼接而是使用参数化查询这既能防注入又能最大化缓存收益。批量操作对于大量数据的插入或更新虽然Dapper本身没有像EF Core的AddRange那样的批量操作但你可以利用以下方式优化表值参数TVP对于SQL Server可以将数据集合作为表值参数传递给存储过程在数据库端进行高效批量处理。使用Execute方法传入对象集合Dapper的Execute方法支持传入IEnumerableT参数它会自动将其转换为多组参数执行。但这本质上是生成一条带有多组参数的SQL语句如INSERT ... VALUES (p0, p1), (p2, p3), ...并非真正的批量操作数据量极大时如数万行可能超出SQL语句长度限制或性能不佳。var users new ListUser { /* 大量用户对象 */ }; var sql INSERT INTO Users (Name, Email) VALUES (Name, Email); var rowsAffected connection.Execute(sql, users); // Dapper会遍历集合执行专门的批量操作库对于极大规模的批量操作应考虑使用如SqlBulkCopySQL Server或第三方库如Dapper.Extensions或Dapper.Contrib的批量插入功能但需注意其局限性。选择正确的数据获取方法Query返回多个实体。QueryFirstOrDefault期望最多一个结果。QuerySingle确信只有一个结果。ExecuteScalar只需要一个标量值。ExecuteReader对于流式读取超大型结果集不一次性加载到内存时使用Dapper内部即基于此。5. 常见问题与排查技巧实录5.1 映射失败列名与属性名不匹配这是新手最常遇到的问题。数据库返回的列名为user_id但C#类属性为UserId默认映射会失败。解决方案使用别名最直接在SQL查询中为列指定别名。SELECT user_id AS UserId, user_name AS UserName FROM users自定义类型映射全局或局部指定映射规则。局部使用匿名类型接收对于简单查询可以直接用SELECT ...映射到匿名类型。全局使用SetTypeMap不推荐频繁修改全局映射可能影响其他代码。使用Dapper.Contrib的[Column]特性如果使用该扩展库using Dapper.Contrib.Extensions; [Table(users)] // 指定表名 public class User { [Key] // 指定主键 public int Id { get; set; } [Column(user_name)] // 指定列名 public string UserName { get; set; } }5.2 查询结果为空或为nullQueryFirstOrDefault返回null这是预期行为表示没找到记录。调用方需做好空值检查。QuerySingle抛出InvalidOperationException要么没找到记录序列为空要么找到了多条记录。确保你的查询条件能唯一确定一条记录。集合查询Query返回空集合Query方法永远不会返回null只会返回一个空的集合。调用.Any()或检查.Count()即可。5.3 性能瓶颈排查SQL本身是瓶颈Dapper只是执行SQL。首先使用数据库管理工具如SSMS的“包括实际执行计划”分析你执行的SQL语句性能。确保索引合理没有表扫描。N1查询问题在循环中执行查询导致多次数据库往返。// 错误示例N1问题 var users connection.QueryUser(SELECT * FROM Users); foreach (var user in users) { user.Orders connection.QueryOrder(SELECT * FROM Orders WHERE UserId Id, new { user.Id }).ToList(); }解决方案使用QueryMultiple一次性获取所有数据或者在单条SQL中使用JOIN结合多映射Multi Mapping或自定义结果处理。// 解决方案使用JOIN和Multi Mapping一对多需在映射委托中手动聚合 var sql SELECT u.*, o.* FROM Users u LEFT JOIN Orders o ON u.UserId o.UserId ORDER BY u.UserId ; var userDict new Dictionaryint, User(); var data connection.QueryUser, Order, User( sql, (user, order) { if (!userDict.TryGetValue(user.UserId, out var existingUser)) { existingUser user; existingUser.Orders new ListOrder(); userDict.Add(existingUser.UserId, existingUser); } if (order ! null) existingUser.Orders.Add(order); return existingUser; }, splitOn: OrderId ).Distinct().ToList();连接池问题确保连接被正确关闭使用using或依赖注入框架管理。连接泄露会导致连接池耗尽出现超时错误。5.4 与依赖注入DI框架集成在ASP.NET Core中推荐将数据库连接注册为Scoped生命周期并在Repository或Service中注入IDbConnection工厂。Startup.cs 或 Program.cs 中配置builder.Services.AddScopedIDbConnection(sp { var configuration sp.GetRequiredServiceIConfiguration(); var connectionString configuration.GetConnectionString(DefaultConnection); // 注意这里创建连接但不打开。由Dapper或使用者在需要时打开。 var connection new SqlConnection(connectionString); return connection; }); // 注册自定义仓储 builder.Services.AddScopedIUserRepository, DapperUserRepository();Repository实现public class DapperUserRepository : IUserRepository { private readonly IDbConnection _dbConnection; public DapperUserRepository(IDbConnection dbConnection) { _dbConnection dbConnection; } public async TaskUser GetByIdAsync(int id) { // Dapper会在必要时自动打开连接但显式打开是更佳实践 if (_dbConnection.State ! ConnectionState.Open) await _dbConnection.OpenAsync(); var sql SELECT * FROM Users WHERE UserId id; return await _dbConnection.QueryFirstOrDefaultAsyncUser(sql, new { id }); } // ... 其他方法 }重要提示在Scoped生命周期中一个HTTP请求内共享同一个连接实例。这天然支持了事务范围在同一个连接上开启事务多个Repository操作可以参与同一事务。请求结束时依赖注入容器会自动处理连接的释放如果实现了IDisposable。这种方式比在每个方法内部创建连接更高效连接池管理更好。5.5 关于Dapper.Contrib的取舍Dapper.Contrib是Dapper的一个官方扩展提供了简单的CRUD方法Get,Insert,Update,Delete通过特性Attribute来标注实体类。优点对于非常简单的、表结构一对一的CRUD它能进一步减少代码量。缺点与限制功能有限复杂查询、连接查询、存储过程等仍需回退到原生Dapper。默认基于特性配置可能侵入你的实体类。批量操作、复杂条件更新支持较弱。某些高级映射场景可能不灵活。个人建议在中小型项目或快速原型中可以酌情使用Contrib来简化基础CRUD。但在大型、复杂的项目中我更倾向于坚持使用核心Dapper因为它提供了最根本的透明度和控制力所有SQL都清晰可见便于团队协作和后期维护。将简单的CRUD SQL语句写出来并不比使用Contrib的方法调用麻烦多少却能带来长期的理解和维护优势。
