在 jooq 的 union（如 union all）查询中，仅首个子查询的 ad-hoc converter 生效，后续子查询的 mapping 会被忽略——这是由 jdbc 结果集无源标识特性决定的设计约束，而非 bug。本文详解其原理并提供两种可靠绕过方案。
在 jooq 的 union（如 union all）查询中，仅首个子查询的 ad-hoc converter 生效，后续子查询的 mapping 会被忽略——这是由 jdbc 结果集无源标识特性决定的设计约束，而非 bug。本文详解其原理并提供两种可靠绕过方案。
JOOQ 的 UNION 类操作（包括 UNION ALL、UNION、EXCEPT 等）在语义上要求所有子查询返回结构兼容的行类型（row type）。jOOQ 严格遵循 SQL 标准：整个联合结果的列名、数据类型和映射行为均由第一个子查询定义，后续子查询仅需保证列数与类型兼容，其独立声明的 mapping()（如 .mapping(B::new)）在运行时被完全忽略——因为 jOOQ 在执行阶段仅通过单次 ResultSet 遍历获取全部结果行，而 JDBC 并不提供“该行来自第几个子查询”的元信息。
这并非 ad-hoc converter 的特有问题，而是贯穿于所有客户端映射机制（包括 Converter、Binding、RecordMapper）的底层限制。例如以下代码看似合理，实则第二处 mapping(B::new) 不起作用：
List<Something> records = db.select(
row(TABLE_A.ID, TABLE_A.NAME).mapping(A::new)
)
.from(TABLE_A)
.unionAll(
select(row(TABLE_B.ID, TABLE_B.NAME).mapping(B::new)) // ⚠️ 此处 mapping 被忽略！
.from(TABLE_B)
)
.fetch(Record1::component1); // 实际返回 List<A>编译能通过，是因为 Java 泛型擦除与 jOOQ API 的灵活性允许你在子查询中声明任意 mapping；但运行时 jOOQ 始终使用第一个子查询的 Row 类型进行统一映射，最终结果必为 List，B 实例永远不会被构造。
✅ 推荐方案一：显式判别器 + 全局映射（推荐）
最清晰、易维护的方式是在每个子查询中添加一个人工判别列（discriminator column），并在最终 fetch() 时统一处理：
Function3<String, UInteger, String, Something> discriminatorMapper =
(type, id, name) -> {
return switch (type) {
case "A" -> new A(id, name);
case "B" -> new B(id, name);
default -> throw new IllegalArgumentException("Unknown type: " + type);
};
};
List<Something> records = db.select(
inline("A").as("source"),
TABLE_A.ID,
TABLE_A.NAME
)
.from(TABLE_A)
.unionAll(
select(
inline("B").as("source"),
TABLE_B.ID,
TABLE_B.NAME
).from(TABLE_B)
)
.fetch(discriminatorMapper); // ✅ 单点映射，逻辑集中? 提示：inline("A") 生成常量列，as("source") 为其命名（非必需但增强可读性）；fetch(Function3) 直接按列顺序解包，无需 Record1::component1。
✅ 推荐方案二：使用 Record 解构 + 条件分支
若需更高灵活性（如动态字段数或复杂转换），可先获取 Record 列表，再手动映射：
List<Something> records = db.select(
inline("A"), TABLE_A.ID, TABLE_A.NAME
).from(TABLE_A)
.unionAll(
select(inline("B"), TABLE_B.ID, TABLE_B.NAME)
.from(TABLE_B)
)
.fetch()
.stream()
.map(r -> {
String type = r.value(0, String.class);
UInteger id = r.value(1, UInteger.class);
String name = r.value(2, String.class);
return switch (type) {
case "A" -> new A(id, name);
case "B" -> new B(id, name);
default -> throw new IllegalArgumentException();
};
})
.toList();⚠️ 注意事项与最佳实践
- 避免重复 mapping 声明：不要在多个 UNION 子查询中分别写 .mapping(...)，既无效又误导维护者；
- 优先全局映射：fetch(FunctionN) 比嵌套 row(...).mapping() 更直观、可控；
- 判别列类型建议：使用 String 或 ENUM 类型作为 discriminator，便于扩展（如未来加入 C 类型）；
- 性能无损耗：inline() 是纯 SQL 字面量，不增加数据库计算负担；
- 兼容性保障：该方案适用于所有 jOOQ 版本（≥ 3.14），且与 ResultQuery.fetchInto(Class) 等其他映射方式正交。
从根本上说，这不是缺陷，而是 jOOQ 对 SQL 语义的忠实实现。理解“UNION 行类型由首子句定义”这一原则，能帮你规避大量隐式类型错误，并写出更健壮、可演进的数据访问层代码。
