Dapper之所以被称为微ORM，是因为它只做一件事：把SQL查询结果映射成对象，其余的一切都交还给开发者自己控制。这种极简设计让它在性能上几乎与手写ADO.NET持平，同时又省去了大量枯燥的字段赋值代码。当它遇上PostgreSQL这款以稳定和扩展性著称的开源数据库时，如何把查询性能压榨到极致，就成了很多.NET开发者关心的问题。本文将围绕Dapper操作PostgreSQL的实战场景，系统讲解连接管理、SQL优化、参数化查询、批量操作等核心技巧。
一、连接管理与连接池配置
性能优化的第一步往往不在SQL本身，而在连接的创建与销毁上。PostgreSQL的连接建立过程涉及TCP握手、认证、后端进程fork等开销，比MySQL等数据库更重，因此连接池的重要性尤为突出。Npgsql驱动默认就启用了连接池，但默认参数未必适合你的业务场景。
连接字符串中有几个参数值得重点关注：MaxPoolSize决定池中最大连接数，默认100，高并发场景下如果设置过小，会出现排队等待甚至超时异常；MaxAutoPrepare可以开启自动预编译，让频繁执行的SQL在PostgreSQL服务端被预编译成执行计划，减少解析开销，这在Dapper这种手写SQL的场景下收益明显。
var connString = "Host=127.0.0.1;Username=postgres;Password=secret;Database=mydb;MaxPoolSize=200;MaxAutoPrepare=10;AutoPrepareMinUsages=3";
using (var conn = new NpgsqlConnection(connString))
{
conn.Open();
var users = conn.Query<User>("SELECT id, name, email FROM users WHERE id = @id", new { id = 1 });
}
注意上面代码中使用了using语句块，这能确保连接及时归还给连接池而不是真正关闭。一个常见误区是开发者为了复用连接而把单个连接对象做成静态单例长期持有，这在多线程环境下会引发严重问题，因为Npgsql连接不是线程安全的，并发访问同一个连接对象会抛出异常。正确做法是每次操作都新建连接对象，让连接池在底层帮你复用物理连接。
二、参数化查询与SQL注入防范
Dapper操作PostgreSQL时，参数化查询不仅关乎安全，也直接影响性能。PostgreSQL对每一条SQL都会经历解析、重写、规划、执行四个阶段，如果每次都拼接出不同的SQL文本，服务端的执行计划缓存基本失效，而参数化后的SQL文本固定，配合预编译可以大幅减少解析开销。
Dapper的参数写法使用匿名对象，参数占位符在PostgreSQL中使用@前缀，Npgsql驱动会自动将其转换为PostgreSQL原生的$1位置参数形式，开发者无需关心这个转换细节。
// 正确：参数化查询
var order = conn.QueryFirstOrDefault<Order>(
"SELECT * FROM orders WHERE user_id = @userId AND status = @status",
new { userId = 123, status = "paid" });
// 错误：字符串拼接，存在注入风险且无法利用预编译
var bad = conn.Query<Order>(
$"SELECT * FROM orders WHERE name = '{name}'");
还有一种进阶用法是DynamicParameters，它支持显式指定参数类型和方向，特别适合调用存储过程或处理PostgreSQL特有的类型如jsonb、数组类型等。例如插入jsonb字段时，通过::jsonb强转可以避免类型推断失败。
var dp = new DynamicParameters();
dp.Add("data", JsonSerializer.Serialize(payload), DbType.String);
dp.Add("created_at", DateTime.UtcNow);
var id = conn.ExecuteScalar<long>(
"INSERT INTO events(data, created_at) VALUES(@data::jsonb, @created_at) RETURNING id", dp);
顺便一提，PostgreSQL的RETURNING子句是Dapper配合使用时的利器，插入后需要拿到主键时，不需要再发一次查询，直接用ExecuteScalar或Query取回即可，相比MySQL的LAST_INSERT_ID方式更灵活。
三、批量插入的正确姿势
批量写入是性能优化的重灾区。不少开发者循环调用单条INSERT，一千条数据就要往返数据库一千次，网络往返开销远大于SQL执行本身。针对PostgreSQL，Dapper生态下有几种常见方案，性能差距可达数十倍。
第一种方案是利用Dapper对集合参数的自动展开，传入一个List时它会自动生成多条VALUES拼成一条INSERT语句，简单有效，一条SQL插入几百行没问题，但要注意PostgreSQL单条语句最多允许65535个参数，数据量大时需要分批。第二种方案是使用UNNEST配合数组参数，将各列作为数组传入，在服务端展开成行，参数数量与列数相关而与行数无关，适合大批量场景。第三种是Npgsql原生的二进制导入BeginBinaryImport，性能最强，但需要绕过Dapper直接操作NpgsqlConnection。
// 方案一：多条VALUES，Dapper自动展开列表参数
var sql = "INSERT INTO users(name, email) VALUES(@Name, @Email)";
conn.Execute(sql, userList);
// 方案二：UNNEST批量插入，行数不受参数上限制约
var sql2 = @"INSERT INTO users(name, email)
SELECT * FROM UNNEST(@names::text[], @emails::text[])";
conn.Execute(sql2, new
{
names = userList.Select(u => u.Name).ToArray(),
emails = userList.Select(u => u.Email).ToArray()
});
实测下来，一万条数据用循环单条插入可能需要十几秒，多条VALUES方式能压缩到一秒以内，UNNEST或二进制导入则可以进一步降到几百毫秒。选哪种取决于数据规模和团队对代码可读性的要求，一般业务场景下多条VALUES已经够用，报表导入类的场景建议直接上二进制导入。
四、映射性能与异步查询实践
Dapper的对象映射默认通过Emit动态生成IL代码完成，首次生成后会缓存下来，因此同一个类型的重复查询几乎没有反射开销。但有些写法会破坏这个优势，比如把查询结果映射到dynamic再逐字段取值，dynamic路径走的是字典查找，性能明显低于强类型映射，而且丧失了编译期检查，建议仅在临时分析脚本里使用。
多表关联场景下，Dapper的Query重载支持一次SQL返回多个实体并通过splitOn参数切分，避免了ORM中常见的懒加载N+1问题。例如订单和用户的关联查询，一条SQL即可完成主从映射。
var sql = @"SELECT o.id, o.amount, u.id, u.name
FROM orders o JOIN users u ON u.id = o.user_id WHERE o.status = 'paid'";
var orders = conn.Query<Order, User, Order>(sql,
(order, user) => { order.User = user; return order; },
splitOn: "id").ToList();
异步方面，Dapper提供了QueryAsync、ExecuteAsync等完整异步API，Web应用中务必使用异步版本，避免线程池在高并发下被数据库IO阻塞。另外要注意CancellationToken的传递，Npgsql支持通过CommandDefinition接收取消令牌，客户端取消时能及时中断服务端执行，释放数据库资源。
var cmd = new CommandDefinition(
"SELECT * FROM large_table WHERE created_at > @since",
new { since = someDate },
cancellationToken: cts.Token);
var rows = await conn.QueryAsync<Row>(cmd);
最后提醒两个容易踩的坑：一是PostgreSQL的表名和列名默认转小写，如果实体属性是PascalCase，映射时需要用别名或设置DefaultTypeMap.MatchNamesWithUnderscores = true来匹配下划线命名；二是QueryMultiple读取多个结果集时必须按顺序读取，先取的结果集不消费完就不能读下一个。把这些细节处理好，Dapper加PostgreSQL的组合完全能够支撑起高性能的数据访问层。
DapperPostgreSQL微ORM修改时间：2026-09-09 04:22:57