Doctrine DBAL QueryBuilder 新增 UNION 操作支持的技术解析

背景与需求分析

在数据库查询中，UNION 操作符是一个非常重要的功能，它允许开发者将多个 SELECT 语句的结果集合并为一个结果集。虽然所有主流数据库都支持 UNION 操作，但 Doctrine DBAL 的 QueryBuilder 长期以来缺乏对这一功能的原生支持。

UNION 操作的基本原理

UNION 操作遵循几个基本原则：

1. 每个参与 UNION 的 SELECT 语句必须返回相同数量的列
2. 对应位置的列必须具有兼容的数据类型
3. 列名通常取自第一个 SELECT 语句
4. 默认情况下，UNION 会去除重复行（DISTINCT），而 UNION ALL 会保留所有行

Doctrine DBAL 的实现方案

Doctrine DBAL 团队为 QueryBuilder 添加了完整的 UNION 支持，主要包含以下技术实现：

核心架构变更

1. 新增 QueryType::UNION 枚举类型，用于标识 UNION 查询
2. 引入 UnionQuery 作为数据传输对象(DTO)
3. 扩展 getSQL() 方法以支持 UNION 查询类型
4. 新增 getSQLForUnion() 方法作为 UNION SQL 生成入口

新增 API 方法

// 设置或重置 UNION 部分
$qb->union(string|QueryBuilder ...$unionParts);

// 追加 UNION 部分
$qb->addUnion(string|QueryBuilder ...$unionParts);

// 控制 UNION 类型（DISTINCT 或 ALL）
$qb->distinct(true); // UNION DISTINCT
$qb->distinct(false); // UNION ALL

SQL 生成机制

1. 新增 UnionSQLBuilder 接口定义
2. 提供 DefaultUnionSQLBuilder 默认实现
3. 通过 AbstractPlatform::createUnionSQLBuilder() 获取具体实现

实际应用示例

基本 UNION ALL 查询

$qb = $connection->createQueryBuilder();
$qb->union(
    'SELECT 2 AS field_one',
    'SELECT 1 AS field_one'
)
->addUnion('SELECT 4 AS field_one')
->addUnion('SELECT 3 AS field_one')
->orderBy('field_one', 'ASC')
->setMaxResults(1)
->setFirstResult(1);

使用 QueryBuilder 子查询

$unionQb = $connection->createQueryBuilder();

$sub1 = $connection->createQueryBuilder();
$sub1->select('id')->from('a_table')
    ->where('id = :param1')
    ->setParameter('param1', 2);

$sub2 = $connection->createQueryBuilder();
$sub2->select('id')->from('a_table')
    ->where('id = :param2')
    ->setParameter('param2', 1);

$result = $unionQb
    ->union($sub1)
    ->addUnion($sub2)
    ->orderBy('id', 'ASC')
    ->executeQuery()
    ->fetchAllAssociative();

技术实现细节

1. 参数处理：支持将 QueryBuilder 实例作为 UNION 部分时自动处理参数绑定
2. 类型安全：确保所有 UNION 部分的列数量和类型兼容
3. 平台适配：通过抽象工厂模式允许不同数据库平台提供特定实现
4. 查询优化：自动处理 ORDER BY 和 LIMIT 子句的位置关系

开发者注意事项

1. 使用 UNION 时不能在子查询中包含 ORDER BY 子句（MySQL 除外）
2. 所有 UNION 部分的列名必须匹配或兼容
3. 参数绑定在转换为 UNION 查询时会自动处理
4. 结果集的排序和分页应在最外层查询中指定

这一功能的加入显著增强了 Doctrine DBAL QueryBuilder 的表达能力，使开发者能够更灵活地构建复杂查询，同时保持类型安全和跨数据库兼容性。