告别SQL拼接：Dapper.SqlBuilder让LINQ式优雅查询落地实践-CSDN博客

告别SQL拼接：Dapper.SqlBuilder让LINQ式优雅查询落地实践

【免费下载链接】Dapper 项目地址: https://gitcode.com/gh_mirrors/dapper3/Dapper

你是否还在手写SQL字符串拼接？面对动态条件查询时，既要处理参数化防止注入，又要维护复杂的条件逻辑，代码如同乱麻？本文将带你掌握Dapper.SqlBuilder的实战技巧，用类LINQ的流畅API解决90%的动态查询难题，同时保留Dapper的性能优势。读完你将获得：3种核心场景的实现模板、参数安全处理指南、性能对比数据，以及可直接复用的分页查询组件。

为什么需要SQL构建器？

传统SQL拼接存在三大痛点：参数化繁琐、条件组合混乱、可读性差。Dapper作为.NET生态中性能顶尖的ORM（对象关系映射器），其核心优势在于直接SQL控制与高效映射，但原生API在动态查询场景下仍需手动处理条件拼接。而Dapper.SqlBuilder模块通过声明式API和模板引擎，完美填补了这一空白。

Dapper在ORM性能测试中表现优异，配合SqlBuilder可兼顾开发效率与运行速度

项目核心模块：

基础查询能力：Dapper/
SQL构建器实现：Dapper.SqlBuilder/SqlBuilder.cs
官方使用示例：Dapper.SqlBuilder/Readme.md

核心API与基础用法

SqlBuilder提供18种链式操作方法，覆盖查询构建全场景。最常用的包括Where/OrWhere条件组合、OrderBy排序控制、Join联表查询等。基础使用遵循"构建器+模板"模式：

var builder = new SqlBuilder()
    .Where("UserId = @userId", new { userId = 123 })
    .OrderBy("CreateTime desc");

// 定义SQL模板，使用/**标记**/占位符
var template = builder.AddTemplate(@"
    select * from Posts 
    /**where**/ 
    /**orderby**/
    limit @pageSize offset @offset", 
    new { pageSize = 10, offset = 0 });

// 执行查询
var posts = connection.Query<Post>(template.RawSql, template.Parameters);

模板中的/**where**/会被替换为where UserId = @userId，/**orderby**/替换为order by CreateTime desc。参数自动合并，无需手动管理。

动态条件查询实战

场景1：多条件筛选

用户列表查询通常包含多种可选筛选条件，如用户名模糊搜索、角色筛选、状态过滤等。使用SqlBuilder可清晰组织逻辑：

var builder = new SqlBuilder();
var template = builder.AddTemplate("select * from Users /**where**/ /**orderby**/");

// 动态添加条件
if (!string.IsNullOrEmpty(keyword))
    builder.Where("UserName like @keyword", new { keyword = $"%{keyword}%" });
    
if (roleId.HasValue)
    builder.Where("RoleId = @roleId", new { roleId });
    
if (status != null)
    builder.OrWhere("Status = @status1", new { status1 = Status.Active })
           .OrWhere("Status = @status2", new { status2 = Status.Pending });

// 排序条件
builder.OrderBy("CreateTime desc");

var users = connection.Query<User>(template.RawSql, template.Parameters);

场景2：分页查询组件

结合ROW_NUMBER()实现高效分页，同时支持动态条件与排序：

var builder = new SqlBuilder();
// 分页查询模板
var selectTemplate = builder.AddTemplate(@"
    select * from (
        select *, ROW_NUMBER() OVER (/**orderby**/) as RowNum 
        from Orders /**where**/
    ) t where RowNum between @start and @end",
    new { start = pageIndex * pageSize + 1, end = (pageIndex + 1) * pageSize });

// 总数查询模板
var countTemplate = builder.AddTemplate("select count(*) from Orders /**where**/");

// 动态条件
if (startDate.HasValue)
    builder.Where("CreateTime >= @startDate", new { startDate });
    
// 排序处理
builder.OrderBy(sortBy == "amount" ? "TotalAmount desc" : "CreateTime desc");

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

完整分页组件代码：tests/Dapper.Tests/QueryTests.cs

与LINQ的混合使用策略

虽然SqlBuilder采用SQL优先的设计思路，但可与LINQ实现优势互补。推荐两种组合模式：

模式1：LINQ构建+SQL执行

对简单查询使用LINQ表达式构建条件，复杂场景切换至原生SQL：

// LINQ构建基础条件
var query = dbContext.Products.AsQueryable();
if (minPrice > 0) query = query.Where(p => p.Price >= minPrice);

// 转换为SQL后使用Dapper执行
var sql = query.ToQueryString(); // EF Core 5+特性
var products = connection.Query<Product>(sql, query.Parameters);

模式2：SQL构建+LINQ映射

使用SqlBuilder处理复杂SQL，通过Dapper查询后用LINQ处理内存数据：

var builder = new SqlBuilder()
    .Where("CategoryId = @catId", new { catId = 5 })
    .OrderBy("Sales desc");

var template = builder.AddTemplate("select * from Products /**where**/ /**orderby**/ limit 100");
var products = connection.Query<Product>(template.RawSql, template.Parameters)
    .AsEnumerable() // 切换至LINQ to Objects
    .GroupBy(p => p.Brand)
    .Select(g => new {
        Brand = g.Key,
        TotalSales = g.Sum(p => p.Sales)
    })
    .ToList();

高级技巧与避坑指南

参数安全处理

SqlBuilder自动处理参数命名冲突，当添加同名参数时会自动重命名：

builder.Where("a = @x", new { x = 1 })
       .Where("b = @x", new { x = 2 });
// 生成: where a = @x_0 and b = @x_1

联表查询最佳实践

使用Join方法构建关联查询，配合多映射实现对象嵌套：

var builder = new SqlBuilder()
    .LeftJoin("Categories c on p.CategoryId = c.Id")
    .Where("p.Status = 1");

var template = builder.AddTemplate(@"
    select p.*, c.Name as CategoryName 
    from Products p /**join**/ /**where**/");

var products = connection.Query<Product, Category, Product>(
    template.RawSql,
    (p, c) => { p.Category = c; return p; },
    template.Parameters,
    splitOn: "CategoryName"
);

常见陷阱：OrWhere逻辑

注意OrWhere会被翻译成AND (条件)而非OR，需手动分组：

// 错误写法
builder.Where("a=1").OrWhere("b=2"); // where a=1 and b=2

// 正确写法
builder.Where("(a=1 or b=2)"); // 手动添加括号

性能对比与最佳实践

根据官方基准测试，Dapper配合SqlBuilder的性能仅比原生Dapper低5-8%，但远优于EF Core的LINQ查询：

查询方式	平均耗时	内存分配
手写Dapper	133.7μs	11.6KB
SqlBuilder	142.0μs	12.3KB
EF Core LINQ	317.1μs	11.3KB

数据来源：benchmarks/Dapper.Tests.Performance/最新测试结果

最佳实践总结：

复杂动态查询优先使用SqlBuilder
简单CRUD操作直接用Dapper原生API
超复杂报表查询考虑存储过程+SqlBuilder传参
始终使用参数化查询，避免字符串拼接

总结与扩展学习

Dapper.SqlBuilder通过声明式API和模板引擎，在保留Dapper性能优势的同时，大幅提升了动态查询的开发效率。其类LINQ的链式调用风格降低了学习成本，而原生SQL的直接使用又确保了查询的灵活性与性能可控。

推荐扩展学习资源：

官方文档：README.md
测试用例库：tests/Dapper.Tests/SqlBuilderTests.cs
高级场景示例：Dapper.Rainbow/readme.md

掌握这一工具后，你将告别"SQL字符串地狱"，写出既优雅又高效的数据访问代码。现在就将SqlBuilder集成到你的项目中，体验"手写SQL的自由"与"LINQ式的优雅"的完美结合吧！

【免费下载链接】Dapper 项目地址: https://gitcode.com/gh_mirrors/dapper3/Dapper

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考