应优先使用 QueryBuilder：它比 DQL 更安全易维护，适合动态条件、复用逻辑和多 JOIN 场景；需显式指定关联路径避免歧义；原生 SQL 虽快但丧失类型安全，全文检索与地理查询须依赖外部服务。
复杂查询不是靠堆语法，而是靠分清场景、选对工具、避开 Doctrine 的隐式陷阱。直接写原生 SQL 最快但失去类型安全；DQL 适合跨实体关联但容易 N+1；QueryBuilder 更灵活且可组合，是多数业务场景的平衡点。
什么时候该用 QueryBuilder 而不是 DQL
QueryBuilder 是面向对象的查询构造器，比拼接 DQL 字符串更安全、更易维护，尤其适合动态条件、多分支逻辑或需要复用部分查询的场景。
- 需要根据用户输入动态加
WHERE条件（比如搜索表单里“价格区间”“分类 ID”“状态”可选填）→ 用andWhere()链式追加，避免字符串拼接风险 - 要复用同一段查询逻辑（如“查所有已启用且未删除的商品”）→ 封装成 Repository 方法，返回
$qb对象，再由调用方继续追加orderBy或setMaxResults - 涉及多个
JOIN且关联字段名易混淆（比如Product同时有$category和$brand属性）→leftJoin('p.category', 'c')比 DQL 里手写LEFT JOIN App\Entity\Category c WITH p.category = c.id更直观、更少出错 - 调试时想看生成的 SQL → 调用
$qb->getQuery()->getSQL()，比解析 DQL 字符串更可靠
多对多关系查询必须显式指定中间表别名
Doctrine 不会自动推导你到底想走哪条多对多路径。即使两个关联都指向同一个目标实体（比如 Sending 有 $sender 和 $recipient 都关联 Address），QueryBuilder 也必须通过属性名明确连接路径，不能直接 join(Address::class, 'a')。
- 错误写法：
$qb->join(Address::class, 'a')→ 缺少ON条件，SQL 报错或结果错乱 - 正确写法：
$qb->leftJoin('s.sender', 'senderAddr')或$qb->innerJoin('s.recipient', 'recipientAddr')，其中s是主实体别名，sender是Sending类中定义的关联属性名 - 如果还要查中间表字段（比如发送时间），Doctrine 默认不暴露中间表为实体 → 得改用原生 SQL 或把中间表建模为独立实体再关联
原生 SQL 查询要注意字段映射和参数绑定
绕过 ORM 直接查数据库时，fetchAssoc() 和 fetchAll() 返回的是纯数组，没有实体对象，字段名默认是数据库列名（如 user_name），不是 PHP 属性名（如 username）。
- 只取一行带键名：
$conn->fetchAssoc('SELECT id, nickname FROM user WHERE id = ?', [123])→ 返回['id' => 123, 'nickname' => 'lili'] - 取多行：
$conn->fetchAll('SELECT id, nickname FROM user WHERE id IN (?, ?)', [1, 2])→ 返回二维数组，每项是带键名的关联数组 - 参数必须用
?占位符，不能写:id（那是 DQL 用的）；类型无法自动推断，数字/字符串都按字符串传，需自行校验 - 如果结果要转成实体，得手动 new 实例 + set 属性，或用
$em-> hydrate()（不推荐，耦合重）
全文检索和地理位置不能靠 Doctrine 原生解决
MySQL 的 MATCH AGAINST 或 PostgreSQL 的 @@@ 在中文分词、性能、排序上都撑不住真实业务；地理距离计算用 ST_Distance 之类函数，Doctrine 也不提供跨库抽象。
- 全文检索 → 必须用 Elasticsearch +
FOSElasticaBundle（注意 Symfony 2.8 用 v3.2.*，Symfony 6+ 用 v6+），配置里analyzer: ik_max_word才能正确切中文 - 地理位置 → 改用 MongoDB + Doctrine ODM，靠
2dsphere索引和$near操作符，比 MySQL 手算 Haversine 公式快一个数量级 - 两者都要额外部署服务、同步数据、处理失败重试 —— 这些不是 Doctrine 能帮你封装的，得自己写事件监听器或命令来补全
真正卡住人的从来不是语法有多难，而是没想清楚“这个查询最终要跑在哪一层”：是 ORM 层（DQL/QueryBuilder）、数据库层（原生 SQL）、还是外部服务层（ES/Mongo）。选错层级，后面所有优化都是徒劳。
