彻底掌握动态查询构建：Dapper.SqlBuilder实战指南与5大进阶技巧

在现代数据访问层开发中，动态SQL构建是处理复杂业务逻辑的核心需求。无论是多条件筛选、动态排序还是权限控制，传统字符串拼接不仅代码臃肿，更隐藏着SQL注入风险和维护噩梦。Dapper.SqlBuilder作为Dapper生态中的重要组件，通过创新的模板替换机制，让动态查询构建变得直观而安全。本文将从核心价值到实战技巧，全面解析如何利用这一工具提升开发效率，解决90%的动态查询场景问题。

一、核心价值：为什么选择Dapper.SqlBuilder？

1.1 告别字符串拼接的3大痛点

传统动态SQL构建通常面临三大挑战：逻辑判断复杂（需要处理大量if-else和AND/OR拼接）、参数管理混乱（手动维护参数集合易出错）、安全隐患（字符串拼接导致SQL注入风险）。Dapper.SqlBuilder通过声明式API和自动参数合并，从根本上解决了这些问题。

以电商平台的商品筛选功能为例，假设需要根据价格区间、分类、库存状态等动态条件查询商品：

// 传统方式
var sql = "SELECT * FROM Products WHERE 1=1";
var parameters = new DynamicParameters();

if (minPrice.HasValue)
{
    sql += " AND Price >= @minPrice";
    parameters.Add("minPrice", minPrice);
}
if (categoryId.HasValue)
{
    sql += " AND CategoryId = @categoryId";
    parameters.Add("categoryId", categoryId);
}
// ...更多条件判断

使用SqlBuilder后，代码变得简洁直观：

var builder = new SqlBuilder();
var template = builder.AddTemplate("SELECT * FROM Products /**where**/");

if (minPrice.HasValue)
    builder.Where("Price >= @minPrice", new { minPrice });
if (categoryId.HasValue)
    builder.Where("CategoryId = @categoryId", new { categoryId });

1.2 模板替换机制的工作原理

SqlBuilder的核心创新在于模板标记系统，通过/**标记名**/占位符定义SQL片段的插入位置。其内部维护着不同类型的查询子句（Where/OrderBy等），最终根据规则自动拼接。关键实现位于Dapper.SqlBuilder/SqlBuilder.cs，核心逻辑如下：

// 简化版核心代码
public class SqlBuilder {
    private Dictionary<string, List<string>> _clauses = new();
    
    public SqlBuilder Where(string sql, object parameters = null) {
        AddClause("where", sql, parameters);
        return this;
    }
    
    private void AddClause(string key, string sql, object parameters) {
        if (!_clauses.ContainsKey(key)) _clauses[key] = new();
        _clauses[key].Add(sql);
        // 参数自动合并逻辑...
    }
}

当渲染模板时，SqlBuilder会将/**where**/替换为所有Where子句的组合，并自动处理AND连接符，无需手动管理。

二、基础实践：从零开始构建动态查询

2.1 环境准备与基本用法

首先通过NuGet安装Dapper.SqlBuilder包，然后创建第一个动态查询：

// 1. 创建构建器实例
var builder = new SqlBuilder();

// 2. 定义SQL模板
var template = builder.AddTemplate(
    "SELECT Id, Name, Price FROM Products /**where**/ /**orderby**/"
);

// 3. 添加查询条件
builder.Where("IsActive = @isActive", new { isActive = true })
       .OrderBy("Price ASC");

// 4. 执行查询
using (var connection = new SqlConnection("Your_Connection_String")) {
    var products = connection.Query<Product>(
        template.RawSql,  // 生成的SQL
        template.Parameters  // 合并后的参数
    );
}

2.2 动态参数化查询实现

参数安全是动态查询的关键。SqlBuilder会自动合并所有添加的参数，避免手动管理参数集合的麻烦：

var searchParams = new {
    MinPrice = 100,
    MaxPrice = 500,
    Category = "Electronics"
};

var builder = new SqlBuilder()
    .Where("Price BETWEEN @MinPrice AND @MaxPrice", searchParams)
    .Where("Category = @Category", searchParams);

var template = builder.AddTemplate("SELECT * FROM Products /**where**/");
// 最终参数包含：MinPrice, MaxPrice, Category

2.3 条件筛选的3种实用模式

根据业务场景不同，动态筛选可分为以下模式：

模式1：可选条件（存在即添加）

适用于搜索表单中的非必填字段：

if (!string.IsNullOrEmpty(keyword)) {
    builder.Where("Name LIKE @keyword OR Description LIKE @keyword", 
        new { keyword = $"%{keyword}%" });
}

模式2：多选条件（IN查询）

处理标签、分类等多选筛选：

if (tagIds?.Any() == true) {
    builder.Where("TagId IN @tagIds", new { tagIds });
}

模式3：范围条件（BETWEEN/比较）

价格、日期等范围查询：

if (startDate.HasValue) {
    builder.Where("CreateTime >= @startDate", new { startDate });
}
if (endDate.HasValue) {
    builder.Where("CreateTime <= @endDate", new { endDate });
}

三、进阶技巧：复杂场景的解决方案

3.1 多模板共享查询条件

在分页查询中，列表查询和总数查询通常共享相同的筛选条件。SqlBuilder支持多模板复用同一套条件：

// 创建基础构建器并添加共享条件
var baseBuilder = new SqlBuilder()
    .Where("IsDeleted = 0")
    .Where("TenantId = @tenantId", new { tenantId = 123 });

// 列表查询模板（带分页）
var listTemplate = baseBuilder.AddTemplate(@"
    SELECT * FROM (
        SELECT *, ROW_NUMBER() OVER (/**orderby**/) AS RowNum
        FROM Orders /**where**/
    ) t WHERE RowNum BETWEEN @pageStart AND @pageEnd", 
    new { pageStart = 1, pageEnd = 20 }
);

// 总数查询模板
var countTemplate = baseBuilder.AddTemplate(
    "SELECT COUNT(*) FROM Orders /**where**/"
);

// 动态添加排序条件
baseBuilder.OrderBy("OrderDate DESC");

// 执行查询
var orders = connection.Query<Order>(listTemplate.RawSql, listTemplate.Parameters);
var totalCount = connection.ExecuteScalar<int>(countTemplate.RawSql, countTemplate.Parameters);

3.2 复杂逻辑组合：AND与OR的灵活运用

通过Where和OrWhere方法组合复杂条件：

// 场景：查询VIP用户或消费满1000的普通用户
builder.Where("UserType = 'VIP'")
       .OrWhere("(UserType = 'Regular' AND TotalSpent >= @minSpent)", 
           new { minSpent = 1000 });

生成的WHERE子句为： WHERE UserType = 'VIP' AND (UserType = 'Regular' AND TotalSpent >= @minSpent)

3.3 自定义SQL片段与模板扩展

对于复杂查询需求，可通过AddClause方法添加自定义SQL片段：

// 添加自定义HAVING子句
builder.AddClause("having", "SUM(Amount) > @minTotal", 
    new { minTotal = 1000 }, " HAVING ");

var template = builder.AddTemplate(@"
    SELECT CustomerId, SUM(Amount) AS Total
    FROM Orders /**where**/
    GROUP BY CustomerId /**having**/
");

四、避坑指南：常见问题与解决方案

4.1 参数名冲突问题

当不同条件使用相同参数名时，SqlBuilder会自动覆盖之前的参数值。解决方案：使用唯一参数名或集中管理参数：

// 错误示例：参数名冲突
builder.Where("Price > @value", new { value = 100 })
       .Where("Quantity > @value", new { value = 5 });  // 覆盖前一个@value

// 正确示例：使用唯一参数名
builder.Where("Price > @minPrice", new { minPrice = 100 })
       .Where("Quantity > @minQuantity", new { minQuantity = 5 });

4.2 OrWhere的逻辑陷阱

所有OrWhere条件会被合并为一组用OR连接的条件，与普通Where条件用AND连接：

builder.Where("A = 1")
       .OrWhere("B = 2")
       .OrWhere("C = 3");

生成的WHERE子句为： WHERE A = 1 AND (B = 2 OR C = 3)

如需实现(A=1 OR B=2) AND C=3，需嵌套使用SqlBuilder：

var innerBuilder = new SqlBuilder()
    .Where("A = 1")
    .OrWhere("B = 2");
    
var outerBuilder = new SqlBuilder()
    .Where(innerBuilder.AddTemplate("/**where**/").RawSql)
    .Where("C = 3");

4.3 模板标记命名规范

避免使用SQL关键字作为标记名，建议添加前缀区分不同类型的子句：

// 推荐：使用明确的标记名
var template = builder.AddTemplate(@"
    SELECT * FROM Products 
    /**filter_where**/ 
    /**sort_orderby**/
");

builder.AddClause("filter_where", "Price > @minPrice", new { minPrice = 100 }, " AND ");
builder.AddClause("sort_orderby", "CreateTime DESC", null, " ORDER BY ");

五、资源推荐：从入门到精通

5.1 官方文档与源码

• 核心文档：docs/index.md
• API参考：Dapper.SqlBuilder/PublicAPI.Shipped.txt
• 测试案例：tests/Dapper.Tests/SqlBuilderTests.cs

5.2 进阶学习路径

1. 基础掌握：完成官方示例中的5个核心场景
2. 源码研究：分析Dapper.SqlBuilder/SqlBuilder.cs中的模板渲染逻辑
3. 性能优化：结合benchmarks/Dapper.Tests.Performance/Benchmarks.Dapper.cs学习查询缓存策略
4. 扩展开发：尝试继承SqlBuilder实现自定义子句类型

5.3 项目获取与贡献

通过以下命令获取完整项目代码：

git clone https://gitcode.com/gh_mirrors/dapper3/Dapper

Dapper.SqlBuilder作为Dapper生态的重要组成部分，持续接受社区贡献。如需提交PR，请遵循项目的贡献指南和代码规范。

---

通过本文的学习，你已经掌握了Dapper.SqlBuilder的核心原理和实战技巧。无论是简单的条件筛选还是复杂的多模板查询，这一工具都能帮助你写出更安全、更易维护的动态SQL代码。记住，优秀的动态查询构建不仅是技术实现，更是业务逻辑与数据访问层的优雅衔接。

祝你的数据访问层开发之旅更加高效愉快！