绝大多数 symfony 应用应使用 doctrine\orm\querybuilder，而非 dbal\querybuilder；前者操作实体与关系（如 join('m.actors', 'a')），后者仅拼接原生 sql 字符串，混用会导致实体未找到或 join 失效。
QueryBuilder 该用 ORM 还是 DBAL
绝大多数 Symfony 应用该用 Doctrine\ORM\QueryBuilder，不是 Doctrine\DBAL\QueryBuilder。前者操作实体和关系（如 join('m.actors', 'a')），后者只拼 SQL 字符串（如 addSelect('name') + from('movie')）。混用会导致“Class App\Entity\Movie does not exist”或 JOIN 失效——因为 DBAL 根本不认实体映射。
验证方式：查 $em->createQueryBuilder() 返回类型，或看 use 语句是否含 ORM\。
- ORM QueryBuilder：用于带
@ORM\*注解的实体，自动处理中间表、懒加载、生命周期 - DBAL QueryBuilder：仅用于原始表操作（如日志归档、报表导出），绕过 ORM 层
- 别在 Controller 里直接 new QueryBuilder()——它必须由 EntityManager 或 Repository 提供
JOIN 多对多时为什么总报错 “Unknown relation”
错误典型提示：Unknown relation 'movies' on entity App\Entity\Actor。根本原因是 JOIN 的路径写错了：你写了 join('a.movies', 'm')，但 Doctrine 找不到 Actor::$movies 这个属性名，或者它没被正确配置为 @ORM\ManyToMany。
检查三件事：
- 确认
Actor实体中存在 public/protected 属性$movies，且注解是@ORM\ManyToMany(mappedBy="actors") - 确认反向实体
Movie中有对应属性$actors，且inversedBy="movies"拼写完全一致（大小写敏感） - 别写
join('movie_actor', 'ma')—— 中间表名对 ORM QueryBuilder 是透明的，强行写会报错
WHERE 条件里怎么安全传入实体对象
常见错误：->where('a.user = :user')->setParameter('user', $currentUser) 报错 Expression of type 'App\Entity\User' not allowed。Doctrine 不允许把实体对象直接当标量值塞进 WHERE。
正确做法始终用 DQL 属性路径 + 命名参数：
- ✅
->where('a.user = :userId')->setParameter('userId', $currentUser->getId()) - ✅
->where('a.user = :user')->setParameter('user', $currentUser)—— 这种写法其实也合法，但仅限于关联字段（a.user是 ManyToOne），且要求$currentUser是已托管的实体（即从 EntityManager 加载或 merge 过） - ❌
->where('a.user = ?1')->setParameter(1, $currentUser)—— 位置参数在关联比较中不稳定，易出错
更稳妥的是统一用 ID，避免状态不确定性。
select() 里漏写关联实体就拿不到数据
比如你想查电影及其演员：->select('m')->from(Movie::class, 'm')->leftJoin('m.actors', 'a')，结果 $result['m']->getActors() 还是空集合——因为 leftJoin 只影响 SQL 的 ON 条件，不自动 fetch 关联数据。
必须显式声明要取哪些字段或实体：
- 要整个 Actor 对象：
->select('m', 'a')（注意顺序，m在前） - 只要演员名字：
->select('m', 'a.name')，但此时a不是完整实体，getActors()仍为空 - 用
addSelect('a')配合->select('m')也行，但不如直接select('m', 'a')直观
没写 a 就等于告诉 Doctrine：“我只需要电影数据，演员信息不用 hydrate”，即使写了 JOIN 也没用。
