CommandDefinition 是 Dapper 中用于精细控制 SQL 执行的轻量结构体，核心包含 SQL、参数、超时和标志四要素，适用于需自定义超时、缓存、读取模式或事务等场景。
Dapper 的 CommandDefinition 是一个轻量但关键的结构体，用于显式控制 SQL 执行的全部细节——它不替代直接写 SQL，而是把“怎么查”这件事从方法签名里解耦出来，让高级查询构造更清晰、更可控。
什么时候该用 CommandDefinition 而不是简单传参
当你需要精细调控以下任一行为时，就该跳出 Query 这类快捷方式，改用 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 + 参数 + 超时 + 标志”四要素，高级查询构造就稳了。
