本教程旨在解决如何使用 doctrine query builder 高效地通过关联实体的某个字段（如 `slug`）的数组值来筛选主实体。我们将探讨传统的两步查询方法的不足，并详细介绍如何利用 `join` 和 `in` 子句在单次数据库查询中直接实现这一目标，从而优化性能并简化代码逻辑。
引言：基于关联实体属性的筛选挑战
在复杂的数据库应用中，我们经常需要根据关联实体的特定属性来筛选主实体。例如，假设我们有一个 Listing 实体代表各种场所列表，每个 Listing 都关联到一个 City 实体。现在，我们面临一个需求：给定一个城市 slug（如 new_york, rome）的数组，需要查询所有属于这些指定城市的 Listing。
一个直观但效率较低的解决方案是执行两步操作：
- 首先，根据给定的 slug 数组查询 City 实体，获取它们的 ID。
- 然后，使用这些 City ID 作为参数，查询所有关联的 Listing 实体。
这种方法需要两次数据库往返，并且在应用层进行数据处理（提取 ID），当城市列表较长时，可能会导致性能瓶颈和不必要的复杂性。
实体关系概览
为了更好地理解问题和解决方案，我们先来看一下 Listing 和 City 实体之间的关系：
Listing 实体包含一个 city 属性，它是一个 ManyToOne 关系，指向 City 实体。 City 实体包含 id 和 slug 等属性。
// Listing 实体简化
class Listing
{
private int $id;
private string $name;
private City $city; // ManyToOne 关联到 City 实体
// ...
}
// City 实体简化
class City
{
private int $id;
private string $name;
private string $slug; // 城市唯一标识符
// ...
}我们的目标是，给定一个 $cities = ['new_york', 'rome', 'hong_kong']; 这样的 slug 数组，直接获取所有属于这些城市的 Listing。
低效方案及其局限性
正如前文所述，一种可能的实现方式是先查询城市 ID，再查询列表：
// 假设在 ListingRepository 中
public function findAllByCities(array $citySlugs): array
{
// 步骤 1: 根据 slugs 查询 City 实体并获取 ID
// 假设有一个 CityRepository 负责此操作
$cityRepository = $this->_em->getRepository(City::class);
$cities = $cityRepository->findBy(['slug' => $citySlugs]); // 获取 City 实体集合
$citiesIds = array_map(static fn(City $city): int => $city->getId(), $cities);
// 步骤 2: 使用获取到的城市 ID 查询 Listing
$qb = $this->createQueryBuilder('l');
return $qb
->select('l')
->where($qb->expr()->in('l.city', ':cities')) // 注意这里 l.city 是一个实体对象，Doctrine 会自动解析为 ID
->setParameter('cities', $citiesIds, \Doctrine\DBAL\Connection::PARAM_INT_ARRAY) // 使用 PARAM_INT_ARRAY
->getQuery()
->getResult();
}这种方法虽然可行，但存在明显缺点：
- 两次数据库查询： 增加了数据库的负载和网络延迟。
- 额外的数据处理： 需要在 PHP 中遍历 City 实体以提取 ID，增加了 CPU 开销。
- 代码冗余： 逻辑分散，不够简洁。
高效解决方案：利用 JOIN 和 IN
Doctrine Query Builder 提供了一种更优雅、更高效的解决方案，即在单次查询中利用 JOIN 关联表，然后直接在 JOIN 后的关联表字段上使用 IN 子句进行筛选。
核心思想是：通过 join('l.city', 'c') 将 Listing 实体与 City 实体连接起来，然后就可以在 where 子句中直接引用 City 实体（别名为 c）的 slug 字段。
以下是实现此功能的优化代码：
* * @method Listing|null find($id, $lockMode = null, $lockVersion = null) * @method Listing|null findOneBy(array $criteria, array $orderBy = null) * @method arrayfindAll() * @method array findBy(array $criteria, array $orderBy = null, $limit = null, $offset = null) */ class ListingRepository extends ServiceEntityRepository { public function __construct(ManagerRegistry $registry) { parent::__construct($registry, Listing::class); } /** * 根据城市 slug 数组查询所有关联的 Listing 实体。 * * @param array $citySlugs 城市 slug 的数组，例如 ['new_york', 'rome'] * @return array 返回匹配的 Listing 实体数组 */ public function findAllByCitySlugs(array $citySlugs): array { $qb = $this->createQueryBuilder('l'); // 'l' 是 Listing 实体的主别名 return $qb ->select('l') // 选择 Listing 实体 ->join('l.city', 'c') // 关键步骤：通过 Listing 的 'city' 属性连接到 City 实体，并为其指定别名 'c' ->where($qb->expr()->in('c.slug', ':cities')) // 在连接后的 City 实体（别名 'c'）的 'slug' 字段上使用 IN 子句 ->setParameter('cities', $citySlugs, Connection::PARAM_STR_ARRAY) // 绑定参数数组，指定为字符串数组类型 ->getQuery() ->getResult(); } }
代码详解
- $qb = $this->createQueryBuilder('l');：创建一个针对 Listing 实体（别名为 l）的查询构建器。
- ->select('l')：指定我们希望查询并返回的是 Listing 实体。
- ->join('l.city', 'c')：这是实现高效查询的核心。
- l.city：表示 Listing 实体中的 city 关联属性。
- 'c'：为 City 实体指定一个别名 c，这样我们就可以在后续的 where 子句中引用它。
- 这个操作会在生成的 SQL 中创建一个 INNER JOIN，将 listings 表和 cities 表连接起来。
- ->where($qb->expr()->in('c.slug', ':cities'))：
- $qb->expr()->in()：Doctrine Query Builder 提供的方法，用于生成 SQL 的 IN 子句。
- 'c.slug'：现在我们可以直接引用 JOIN 后的 City 实体（别名 c）的 slug 字段。
- ':cities'：这是一个命名参数，用于后续绑定 citySlugs 数组。
- ->setParameter('cities', $citySlugs, Connection::PARAM_STR_ARRAY)：
- 'cities'：要绑定的参数名称，与 where 子句中的命名参数一致。
- $citySlugs：实际的城市 slug 数组。
- Connection::PARAM_STR_ARRAY：这一点非常重要。 当向 IN 子句传递一个数组参数时，必须明确指定其类型为 PARAM_STR_ARRAY（或 PARAM_INT_ARRAY，取决于数组元素类型）。这会告诉 Doctrine 正确地将数组展开为 ('value1', 'value2', ...) 的形式，避免 SQL 注入风险并确保查询正确执行。
- ->getQuery()->getResult()：执行查询并返回结果，这里会返回一个 Listing 实体数组。
优势与总结
使用 JOIN 和 IN 的组合方法具有以下显著优势：
- 单次数据库查询： 将数据获取和筛选逻辑合并到一次数据库往返中，大大减少了网络延迟和数据库负载。
- 性能提升： 减少了 PHP 端的循环和处理，将大部分工作交由数据库高效完成。
- 代码简洁性： 逻辑集中，易于理解和维护。
- Doctrine 最佳实践： 充分利用了 Doctrine Query Builder 的强大功能，遵循了 ORM 的设计哲学。
通过本教程，您应该已经掌握了如何使用 Doctrine Query Builder 中 JOIN 和 IN 的强大组合，来高效地根据关联实体的特定字段数组值筛选主实体。这种方法是处理此类关联查询场景的最佳实践，能够显著提升应用程序的性能和可维护性。
