使用Doctrine 2 QueryBuilder构建查询时遇QueryException异常

嘿，我之前在做Doctrine 2项目的时候也踩过类似的坑，findAll()能正常跑但自定义查询抛QueryException，大概率是手写查询时忽略了Doctrine ORM的几个关键规则，我给你列几个最常见的问题和解决办法：

1. 混淆了实体属性名和数据库字段名 #

Doctrine的DQL/Query Builder是基于实体类的属性名来查询的，不是数据库表的字段名。比如你的实体里定义的是$loginName，但数据库字段是login_name，那查询时必须用loginName而不是login_name：

// ❌ 错误：用了数据库字段名
$qb->where('u.login_name = :login');

// ✅ 正确：用实体属性名
$qb->where('u.loginName = :login');

2. 忘记绑定查询参数或者参数名不匹配 #

自定义查询里的占位符（比如:login）必须通过setParameter()绑定值，而且参数名要完全对应，不然会直接抛异常：

// ❌ 错误：没绑定参数
$query = $em->createQuery('SELECT u FROM App\Entity\User u WHERE u.loginName = :login');

// ✅ 正确：绑定对应参数
$query = $em->createQuery('SELECT u FROM App\Entity\User u WHERE u.loginName = :login');
$query->setParameter('login', $userSubmittedLogin);

3. DQL里的实体类名没带命名空间 #

如果你的实体在命名空间下（比如App\Entity\User），DQL里必须写完整的类名，不然Doctrine找不到对应的实体：

// ❌ 错误：只写了类名，没带命名空间
$query = $em->createQuery('SELECT u FROM User u WHERE u.loginName = :login');

// ✅ 正确：使用完整命名空间的类名
$query = $em->createQuery('SELECT u FROM App\Entity\User u WHERE u.loginName = :login');

// 用Query Builder的话，可以直接传类常量更稳妥
$qb = $em->createQueryBuilder()
    ->select('u')
    ->from(App\Entity\User::class, 'u')
    ->where('u.loginName = :login')
    ->setParameter('login', $userSubmittedLogin);

4. 模糊查询时错误处理通配符 #

如果是做模糊匹配（比如LIKE），不要把%写在DQL语句里，应该把它包含在绑定的参数值中：

// ❌ 错误：DQL里直接写%
$qb->where('u.loginName LIKE %:login%');

// ✅ 正确：把%放在参数值里
$qb->where('u.loginName LIKE :login')
   ->setParameter('login', "%{$userSubmittedLogin}%");

最关键的一步：查看异常的具体信息 #

QueryException会把错误原因写得很清楚，比如语法错误、属性不存在、参数缺失等，你可以用try-catch捕获异常并打印详细信息：

try {
    // 你的查询执行代码
    $user = $query->getOneOrNullResult();
} catch (\Doctrine\ORM\Query\QueryException $e) {
    var_dump($e->getMessage()); // 直接看这里的错误提示，比瞎猜高效多了
}

先按上面的点排查，尤其是异常信息里的提示，基本能定位到问题所在。

内容的提问来源于stack exchange，提问作者Kev