本文详解 laravel 中使用 join() 和 where() 构建复合查询时的两大常见错误：一是 haversine 距离计算表达式被误解析为列名，二是 like 条件中未正确转义通配符导致 sql 语法错误，并提供安全、可维护的解决方案。
本文详解 laravel 中使用 join() 和 where() 构建复合查询时的两大常见错误：一是 haversine 距离计算表达式被误解析为列名，二是 like 条件中未正确转义通配符导致 sql 语法错误，并提供安全、可维护的解决方案。
在 Laravel 的 Eloquent 查询构建器中，将业务逻辑（如地理距离计算）直接嵌入 where() 数组条件中，极易引发 SQL 解析异常。你遇到的两个核心问题——Unknown column '3909.6209753917' 报错和 LIKE 参数失效——本质源于对查询构建器执行机制的误解。
❌ 错误根源分析
-
Haversine 表达式被当作文本列名
[$this->haversineGreatCircleDistance('user_data.lat', ...), '<=', '3']此写法会立即执行 $this->haversineGreatCircleDistance() 方法，返回一个浮点数（如 3909.6209753917），然后将其作为数组第一个元素传入 where()。Laravel 将该数值字符串误认为是列名（如 '3909'.'6209753917'），最终生成非法 SQL：... AND3909.6209753917<= 3。
LIKE 条件缺少 SQL 字符串引号包裹
原写法 '%'.$store->city.'%' 生成的是 PHP 字符串，但 where([['col','LIKE','value']]) 中的 value 不会自动加单引号。数据库引擎收到的是裸值（如 tripoli），而非合法的字符串字面量 'tripoli'，导致语法错误或意外全表扫描。
✅ 正确实践：分离计算逻辑与 SQL 构建
✅ 方案一：使用 whereRaw() 处理动态表达式（推荐）
将 Haversine 计算逻辑移至 whereRaw()，确保其作为原生 SQL 表达式执行：
public function searchNearUsers($id)
{
$store = storeData::where('store_id', auth()->user()->id)->first();
// 预先验证必要字段存在性
if (!$store || !$store->lat || !$store->lon) {
return collect(); // 或抛出异常
}
$users = User::join('user_data', function ($join) use ($store) {
$join->on('user_data.user_id', '=', 'users.id')
->where('user_data.city', 'LIKE', "%{$store->city}%")
->where('user_data.address', 'LIKE', "%{$store->address}%")
->whereNull('users.is_admin')
->whereNull('users.is_store')
->where('user_data.active', 1)
->where('user_data.anyOrders', 1)
// ✅ 使用 whereRaw 安全注入 Haversine 表达式
->whereRaw(
'6371 * acos(
cos(radians(?)) *
cos(radians(user_data.lat)) *
cos(radians(user_data.lon) - radians(?)) +
sin(radians(?)) *
sin(radians(user_data.lat))
) <= ?',
[$store->lat, $store->lon, $store->lat, 3]
);
})
->select('users.*', 'user_data.avatar')
->get();
return $users;
}? 说明：此处采用标准球面余弦公式（单位：公里），6371 为地球平均半径。四个 ? 占位符依次绑定 $store->lat, $store->lon, $store->lat, 3，完全避免 SQL 注入风险。
✅ 方案二：若坚持封装为方法，需返回 SQL 片段（不推荐初学者）
protected function haversineSql($latCol, $lonCol, $lat, $lon, $maxKm = 3): string
{
return "6371 * acos(
cos(radians({$lat})) * cos(radians({$latCol})) * cos(radians({$lonCol}) - radians({$lon})) +
sin(radians({$lat})) * sin(radians({$latCol}))
) <= {$maxKm}";
}
// 使用时：
->whereRaw($this->haversineSql('user_data.lat', 'user_data.lon', $store->lat, $store->lon))⚠️ 关键注意事项
- 永远不要在 where([...]) 数组中调用返回数值的方法：它破坏了查询构建器的延迟执行模型。
- LIKE 值无需手动加单引号：Laravel 的 where() 方法会自动处理参数绑定（如 ->where('city', 'LIKE', "%{$store->city}%") 是安全的），但切勿在字符串中硬编码 '%' 并拼接引号（如 "'%...%'"），这会导致双重转义或语法错误。
- 空值检查不可省略：$store->lat 等字段为空时，Haversine 计算将返回 NULL 或报错，务必前置校验。
- 索引优化建议：为 user_data.lat、user_data.lon、user_data.city、user_data.active 等高频查询字段建立复合索引，显著提升性能。
通过将动态计算逻辑交由 whereRaw() 承载，并严格遵循参数绑定规范，即可彻底规避列名解析错误与 SQL 注入风险，写出健壮、高效且符合 Laravel 最佳实践的地理查询代码。
