Npgsql/EFCore.PG 中参数化查询的正确使用方式

在使用 Npgsql 和 Entity Framework Core 进行 PostgreSQL 数据库操作时，开发人员经常会遇到参数化查询的问题。本文将详细介绍如何正确使用 SqlQuery 方法执行安全的参数化查询。

常见错误场景

许多开发者在尝试执行包含参数的 SQL 查询时，会遇到类似以下的错误：

// 错误示例：会导致关系 "@p0" 不存在的错误
var count = await context.Database
    .SqlQuery<int>($"select count(\"Id\") from \"{tableName}\"")
    .FirstOrDefaultAsync();

这种错误通常源于对参数化查询机制的理解不足。在 PostgreSQL 中，表名和列名等数据库对象标识符不能作为参数传递，这是数据库系统本身的限制。

正确使用参数化查询

对于真正的参数值（而非表名或列名），应该使用以下方式：

// 正确示例：使用参数化查询
var point = new Point(10, 10);
var tolerance = 50;
var wktPoint = point.ToText().Replace(",", "");

// 正确方式1：使用内插字符串但不包含单引号
var bufferedPoint = await dbContext.Database
    .SqlQuery<Geometry>($"SELECT ST_Buffer(ST_GeogFromText({wktPoint}), {tolerance}, 8) as \"Value\"")
    .FirstOrDefaultAsync();

// 正确方式2：显式使用参数
var bufferedPoint = await dbContext.Database
    .SqlQuery<Geometry>("SELECT ST_Buffer(ST_GeogFromText({0}), {1}, 8) as \"Value\"", 
        wktPoint, tolerance)
    .FirstOrDefaultAsync();

关键注意事项

1. 字符串参数处理：当传递字符串参数时，不要在 SQL 字符串中手动添加单引号。EF Core 的参数化机制会自动处理这些引号。

2. 标识符参数化：表名、列名等数据库对象标识符不能参数化，这是所有数据库系统的通用限制。如果需要动态指定这些标识符，必须使用字符串拼接，但要注意防范 SQL 安全问题。

3. SqlQuery vs SqlQueryRaw：优先使用 SqlQuery 方法，它提供了更好的参数安全性。SqlQueryRaw 应仅在没有其他选择时使用。

4. 空间数据类型：处理 PostGIS 空间数据类型时，确保正确转换几何对象的文本表示形式。

最佳实践建议

1. 对于所有用户输入或变量数据，始终使用参数化查询。

2. 如果必须动态构建包含表名或列名的查询，考虑使用验证列表检查这些标识符。

3. 对于复杂的空间数据操作，考虑创建数据库函数或存储过程，然后通过 EF Core 调用这些预定义的对象。

4. 定期审查代码中的 SQL 查询，确保没有潜在的安全问题。

通过遵循这些准则，开发者可以既保证应用程序的安全性，又能充分利用 Npgsql 和 EF Core 提供的便利功能。