基于Dapper打造高性能PostgreSQL异步访问封装（DapperHelper PostgerSQL 版）

原创已于 2025-05-13 15:50:58 修改 · 1.1k 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#postgresql #数据库 #.net #c#

于 2025-04-30 04:11:20 首次发布

.net 专栏收录该内容

139 篇文章

订阅专栏

基于Dapper打造高性能PostgreSQL异步访问封装（DapperHelper PostgerSQL 版）

一、前言

在高富贵性的环境中，我们常常需要处理大量数据，而Dapper作为一款轻量级ORM，充分发挥了性能上的优势。

然而，默认的Dapper没有考虑大量数据流式处理，很容易一次性拉入大量数据到内存，造成OOM。

本文将教你如何封装一个完全支持「异步」「流式」「多结果集」的 DapperHelper，让你充分采用PostgreSQL和Dapper的性能优势！

二、Dapper和PostgreSQL简介

Dapper：定位于极致性能的微型ORM，直接将SQL查询结果映射成实体。
PostgreSQL：一款免费、开源、强大的具有高实时性性能的关系型数据库，特别适合处理大量数据库操作。

三、DapperHelper设计思路

异步打开连接 (OpenAsync)
全部方法完全异步
流式读取 (StreamQueryAsync)
多结果集支持 (QueryMultipleAsync)

四、流式、多结果封装

public static async IAsyncEnumerable<T> StreamQueryAsync<T>(string sql, object? parameters = null)
{
    await using var connection = await CreateConnectionAsync();
    await using var reader = await connection.ExecuteReaderAsync(sql, parameters, commandType: CommandType.Text, commandBehavior: CommandBehavior.SequentialAccess | CommandBehavior.CloseConnection);

    var parser = reader.GetRowParser<T>();

    while (await reader.ReadAsync())
    {
        yield return parser(reader);
    }
}

public static async Task<TResult> QueryMultipleAsync<TResult>(string sql, object? parameters, Func<SqlMapper.GridReader, Task<TResult>> mapFunc)
{
    await using var connection = await CreateConnectionAsync();
    using var multi = await connection.QueryMultipleAsync(sql, parameters);
    return await mapFunc(multi);
}

这样的设计，可以保证日常工作中：

处理大表查询不爆内存
多次SQL处理简单、开放

五、性能比较

方式	内存占用	速度	适用场景
QueryAsync(默认)	高	快	小量数据（<10万条）
StreamQueryAsync	低	较快	大表，流水统计查询

六、DapperHelper完整代码

using System;
using System.Collections.Generic;
using System.Data;
using System.Threading.Tasks;
using Dapper;
using Npgsql;

namespace YourNamespace
{
    /// <summary>
    /// 提供对 PostgreSQL 数据库的 Dapper 异步访问封装，支持常规查询、事务操作、流式查询和多结果集查询。
    /// </summary>
    public static class DapperHelper
    {
        private static readonly string _connectionString = "Host=your_host;Port=5432;Database=your_database;Username=your_user;Password=your_password;Pooling=true;Maximum Pool Size=100;";

        /// <summary>
        /// 创建并打开一个异步 PostgreSQL 数据库连接。
        /// </summary>
        /// <returns>已打开的 NpgsqlConnection 实例</returns>
        private static async Task<NpgsqlConnection> CreateConnectionAsync()
        {
            var connection = new NpgsqlConnection(_connectionString);
            await connection.OpenAsync();
            return connection;
        }

        /// <summary>
        /// 执行异步 SQL 查询并返回结果集。
        /// </summary>
        /// <typeparam name="T">映射的实体类型</typeparam>
        /// <param name="sql">SQL 查询语句</param>
        /// <param name="parameters">参数对象</param>
        /// <returns>实体集合</returns>
        public static async Task<IEnumerable<T>> QueryAsync<T>(string sql, object? parameters = null)
        {
            await using var connection = await CreateConnectionAsync();
            return await connection.QueryAsync<T>(sql, parameters);
        }

        /// <summary>
        /// 执行异步 SQL 查询并返回第一条记录或默认值。
        /// </summary>
        /// <typeparam name="T">映射的实体类型</typeparam>
        /// <param name="sql">SQL 查询语句</param>
        /// <param name="parameters">参数对象</param>
        /// <returns>单个实体或 null</returns>
        public static async Task<T?> QueryFirstOrDefaultAsync<T>(string sql, object? parameters = null)
        {
            await using var connection = await CreateConnectionAsync();
            return await connection.QueryFirstOrDefaultAsync<T>(sql, parameters);
        }

        /// <summary>
        /// 执行 INSERT/UPDATE/DELETE 等命令。
        /// </summary>
        /// <param name="sql">SQL 命令</param>
        /// <param name="parameters">参数对象</param>
        /// <returns>受影响的行数</returns>
        public static async Task<int> ExecuteAsync(string sql, object? parameters = null)
        {
            await using var connection = await CreateConnectionAsync();
            return await connection.ExecuteAsync(sql, parameters);
        }

        /// <summary>
        /// 执行带事务的操作。
        /// </summary>
        /// <param name="action">包含连接与事务的异步操作</param>
        /// <returns>执行结果（返回值由调用者决定）</returns>
        public static async Task<int> ExecuteTransactionAsync(Func<IDbConnection, IDbTransaction, Task<int>> action)
        {
            await using var connection = await CreateConnectionAsync();
            await using var transaction = await connection.BeginTransactionAsync();
            try
            {
                var result = await action(connection, transaction);
                await transaction.CommitAsync();
                return result;
            }
            catch
            {
                await transaction.RollbackAsync();
                throw;
            }
        }

        /// <summary>
        /// 批量执行多条 SQL 命令，并在同一事务中提交。
        /// </summary>
        /// <param name="commands">SQL 命令与参数的集合</param>
        /// <returns>是否成功提交事务</returns>
        public static async Task<bool> ExecuteBatchAsync(IEnumerable<(string Sql, object? Parameters)> commands)
        {
            await using var connection = await CreateConnectionAsync();
            await using var transaction = await connection.BeginTransactionAsync();
            try
            {
                foreach (var (sql, parameters) in commands)
                {
                    await connection.ExecuteAsync(sql, parameters, transaction);
                }
                await transaction.CommitAsync();
                return true;
            }
            catch
            {
                await transaction.RollbackAsync();
                throw;
            }
        }

        /// <summary>
        /// 异步流式读取数据，适用于超大数据集。
        /// </summary>
        /// <typeparam name="T">映射的实体类型</typeparam>
        /// <param name="sql">SQL 查询语句</param>
        /// <param name="parameters">参数对象</param>
        /// <returns>可异步枚举的数据流</returns>
        public static async IAsyncEnumerable<T> StreamQueryAsync<T>(string sql, object? parameters = null)
        {
            await using var connection = await CreateConnectionAsync();
            await using var reader = await connection.ExecuteReaderAsync(sql, parameters, commandType: CommandType.Text, commandBehavior: CommandBehavior.SequentialAccess | CommandBehavior.CloseConnection);

            var parser = reader.GetRowParser<T>();

            while (await reader.ReadAsync())
            {
                yield return parser(reader);
            }
        }

        /// <summary>
        /// 执行 SQL 并读取多个结果集（多表查询）。
        /// </summary>
        /// <typeparam name="TResult">最终组合返回类型</typeparam>
        /// <param name="sql">SQL 查询语句，可包含多个 SELECT</param>
        /// <param name="parameters">参数对象</param>
        /// <param name="mapFunc">结果集处理函数，接收 GridReader 并返回 TResult</param>
        /// <returns>映射后的结果</returns>
        public static async Task<TResult> QueryMultipleAsync<TResult>(
            string sql,
            object? parameters,
            Func<SqlMapper.GridReader, Task<TResult>> mapFunc)
        {
            await using var connection = await CreateConnectionAsync();
            using var multi = await connection.QueryMultipleAsync(sql, parameters);
            return await mapFunc(multi);
        }
    }
}

通过自己封装一套 DapperHelper：

流式处理大表，避免内存爆表
多结果集处理灵活高效，容易扩展

在实际开发中，很推荐将这样的基础封装统一化，有效地拆分合理、降低Bug率，进而提升团队效率！

七、方法使用示例

QueryAsync 示例

var users = await DapperHelper.QueryAsync<User>(
    "SELECT * FROM users WHERE age > @age",
    new { age = 30 });

foreach (var user in users)
{
    Console.WriteLine($"{user.Id} - {user.Name}");
}

QueryFirstOrDefaultAsync 示例

var user = await DapperHelper.QueryFirstOrDefaultAsync<User>(
    "SELECT * FROM users WHERE id = @id",
    new { id = 1 });

Console.WriteLine(user?.Name ?? "未找到用户");

ExecuteAsync 示例

var rowsAffected = await DapperHelper.ExecuteAsync(
    "UPDATE users SET name = @name WHERE id = @id",
    new { id = 1, name = "新名字" });

Console.WriteLine($"更新了 {rowsAffected} 条记录");

ExecuteTransactionAsync 示例

var count = await DapperHelper.ExecuteTransactionAsync(async (conn, tran) =>
{
    var insertSql = "INSERT INTO logs(message) VALUES(@message)";
    var deleteSql = "DELETE FROM users WHERE id = @id";

    await conn.ExecuteAsync(insertSql, new { message = "删除用户前日志" }, tran);
    return await conn.ExecuteAsync(deleteSql, new { id = 5 }, tran);
});

Console.WriteLine($"事务内总计受影响行数：{count}");

ExecuteBatchAsync 示例

var commands = new List<(string Sql, object? Parameters)>
{
    ("INSERT INTO products(name, price) VALUES(@name, @price)", new { name = "商品1", price = 99 }),
    ("INSERT INTO products(name, price) VALUES(@name, @price)", new { name = "商品2", price = 199 })
};

var success = await DapperHelper.ExecuteBatchAsync(commands);

Console.WriteLine(success ? "批量执行成功" : "批量执行失败");

StreamQueryAsync 示例（流式读取）

await foreach (var log in DapperHelper.StreamQueryAsync<LogEntry>(
    "SELECT * FROM logs WHERE created_at > @time",
    new { time = DateTime.UtcNow.AddDays(-1) }))
{
    Console.WriteLine($"{log.Id}: {log.Message}");
}

QueryMultipleAsync 示例（多结果集）

var sql = @"
    SELECT * FROM users WHERE id = @id;
    SELECT * FROM orders WHERE user_id = @id;
";

var result = await DapperHelper.QueryMultipleAsync(sql, new { id = 1 }, async reader =>
{
    var user = await reader.ReadFirstOrDefaultAsync<User>();
    var orders = (await reader.ReadAsync<Order>()).ToList();
    return (user, orders);
});

Console.WriteLine($"用户：{result.user?.Name}");
foreach (var order in result.orders)
{
    Console.WriteLine($"订单号：{order.Id} 金额：{order.Amount}");
}

八、注意事项

✅ 必须安装的包

包名
Dapper
Npgsql

🚀 最低兼容环境要求

.NET Core 3.1+ 或 .NET 5/6/7/8
PostgreSQL 9.6+（一般建议 12及以上）
Dapper 和 Npgsql 最新稳定版兼容良好

📢 小提醒

使用连接字符串，确保格式正确，例如：

Host=localhost;Port=5432;Database=mydb;Username=myuser;Password=mypassword;Pooling=true;Maximum Pool Size=100;

并且在生产环境中注意：

启用连接池（Pooling=true）
设置合理的最大连接数（Maximum Pool Size）

欢迎收藏，点赞，评论与分享！✨

如需要进一步扩展版（含Redis缓存/分表处理/分流分表处理等），可留言或私信我！