本文详解 Laravel Eloquent 中使用 join() 时如何安全传递动态 SQL 表达式（如 Haversine 距离计算）及修复 LIKE 模糊查询因引号缺失导致的列名解析错误。
本文详解 laravel eloquent 中使用 `join()` 时如何安全传递动态 sql 表达式（如 haversine 距离计算）及修复 `like` 模糊查询因引号缺失导致的列名解析错误。
在 Laravel 开发中，当需要在 JOIN 子句中结合地理距离筛选（如 Haversine 公式）与模糊匹配（LIKE）时，若直接将函数调用或拼接字符串作为 where() 数组条件的键名，极易引发 SQL 解析异常——典型表现为 Unknown column '3909.6209753917' in 'on clause'。该错误本质是 Laravel 将浮点数结果（如 3909.6209753917）误识别为列名，而非表达式值；同时，LIKE 条件中未包裹单引号会导致 SQL 语法错误。
✅ 正确做法：使用 whereRaw() 替代数组式 where()
where([]) 仅适用于标准字段-值对，不支持 SQL 表达式作为键名。对于 Haversine 计算或带通配符的 LIKE，必须改用 whereRaw() 显式构造 SQL 片段，并通过参数绑定确保安全性：
public function searchNearUsers($id)
{
$store = storeData::where('store_id', auth()->user()->id)->first();
// ✅ 使用 whereRaw 安全注入地理距离计算和 LIKE 条件
$users = User::join('user_data', function ($join) use ($store) {
$join->on('user_data.user_id', '=', 'users.id')
->whereRaw("user_data.city LIKE ?", ["%{$store->city}%"])
->whereRaw("user_data.address LIKE ?", ["%{$store->address}%"])
->whereNull('users.is_admin')
->whereNull('users.is_store')
->where('user_data.active', 1)
->where('user_data.anyOrders', 1)
// ✅ Haversine 表达式必须写入 whereRaw，不可放入 where([]) 键位
->whereRaw(
"({$this->haversineGreatCircleDistance('user_data.lat', 'user_data.lon', ?, ?)}) <= ?",
[$store->lat, $store->lon, 3]
);
})
->select('users.*', 'user_data.avatar')
->get();
return response()->json($users);
}⚠️ 注意：haversineGreatCircleDistance() 方法需返回纯 SQL 字符串（如 "6371 * ACOS(...)"），而非执行后的数值。示例实现如下：
protected function haversineGreatCircleDistance($lat1, $lon1, $lat2, $lon2) { return "6371 * ACOS( COS(RADIANS({$lat1})) * COS(RADIANS({$lat2})) * COS(RADIANS({$lon2}) - RADIANS({$lon1})) + SIN(RADIANS({$lat1})) * SIN(RADIANS({$lat2})) )"; }
❌ 常见错误与规避指南
| 错误写法 | 问题原因 | 修正方案 |
|---|---|---|
| ['user_data.city', 'LIKE', "%{$store->city}%"] | 缺少单引号，SQL 解析为 WHERE city LIKE %abc%（语法错误） | 改用 whereRaw("city LIKE ?", ["%{$store->city}%"]) |
| [$this->haversine(...), '<=', 3] | 将函数返回值（如 3909.62...）当作列名拼入 SQL | 绝对禁止在 where([]) 键位中使用动态表达式，必须用 whereRaw() |
| 直接拼接 $store->lat 到 SQL 字符串中 | 导致 SQL 注入风险 | 始终使用参数绑定（? 占位符 + 第二个参数数组） |
总结
- where([]) 仅用于静态字段比较，不可承载 SQL 表达式或计算逻辑；
- LIKE 模糊查询必须通过 whereRaw() + 参数绑定实现，避免引号缺失；
- 地理距离等复杂计算应封装为返回 SQL 字符串的辅助方法，并严格配合 whereRaw() 与参数化查询；
- 所有用户输入（如 $store->city、$store->lat）必须经参数绑定处理，杜绝 SQL 注入。
遵循以上规范，即可稳定构建兼具地理围栏与文本搜索能力的 Laravel 复合查询。
