Dapper的CommandDefinition结构怎么用 Dapper高级查询构造

CommandDefinition 是 Dapper 中用于精细控制 sql 执行的轻量结构体，核心包含 SQL、参数、超时和标志四要素，适用于需自定义超时、缓存、读取模式或事务等场景。

Dapper 的 CommandDefinition 是一个轻量但关键的结构体，用于显式控制 SQL 执行的全部细节——它不替代直接写 SQL，而是把“怎么查”这件事从方法签名里解耦出来，让高级查询构造更清晰、更可控。

什么时候该用 CommandDefinition 而不是简单传参

当你需要精细调控以下任一行为时，就该跳出 Query(sql, param) 这类快捷方式，改用 CommandDefinition：

• 设置非默认超时（比如报表查询设 90 秒，而列表页固定 5 秒）
• 禁用查询缓存（CommandFlags.NoCache），避免缓存污染或调试时结果不准
• 启用非缓冲读取（CommandFlags.None），处理百万级结果不爆内存
• 混合使用事务、命令类型（CommandType.StoredProcedure）、自定义标志
• 复用同一组配置（如统一加审计参数、日志标记）

CommandDefinition 的核心参数怎么填

它本质是 SQL 执行的“配置包”，构造时最常用的是带命名参数的重载：

var cmd = new CommandDefinition(     sql: "SELECT * FROM Orders WHERE Status = @Status AND CreatedAt > @Since",     param: new { Status = "Shipped", Since = DateTime.Today.AddDays(-7) },     commandTimeout: 45,     commandType: CommandType.Text,     flags: CommandFlags.Buffered // 或 CommandFlags.None / CommandFlags.NoCache );

注意几点：

• param 支持匿名对象、IDictionary、自定义类，Dapper 自动展开为命名参数
• commandTimeout 单位是秒，优先级高于连接字符串里的 Connect Timeout
• flags 是位标志，可组合：比如 CommandFlags.NoCache | CommandFlags.Pipelined
• 不传 commandTimeout 或传 NULL，就走数据库驱动默认值（通常 30 秒）

配合高级 SQL 特性一起用

Dapper 本身不解析 SQL，所以窗口函数、CTE、动态分页这些全靠你写标准 SQL，CommandDefinition 只负责稳稳执行它：

• 用 CTE 做递归组织树：WITH Org AS ( ... ) select * FROM Org，照常传入 CommandDefinition
• 用窗口函数分页：ROW_NUMBER() OVER (ORDER BY Id) AS RowNum，映射到含 RowNum 属性的类即可
• 动态构建 SQL 时（比如用 Dapper.SqlBuilder），最后调用 builder.AddParameters() 得到 Object param，再塞进 CommandDefinition

异步场景下怎么传

所有 *Async 方法（如 QueryAsync）都支持直接传 CommandDefinition，且能同时用 CancellationToken：

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30)); var cmd = new CommandDefinition(sql, param, commandTimeout: 30); var list = await conn.QueryAsync(cmd, cancellationToken: cts.Token);

这样既控了命令超时，又支持用户主动取消，双重保障。

基本上就这些。不用硬记所有字段，抓住“SQL + 参数 + 超时 + 标志”四要素，高级查询构造就稳了。