JOOQ 作为面向 Java 开发者的关系型数据库查询框架，提供了类型安全的 SQL 构建能力，其中 UNION 查询是合并多个查询结果集的常用操作，而类型映射机制与自定义转换器的配合是使用过程中的核心要点。
JOOQ UNION 查询的基础类型映射规则
JOOQ 执行 UNION 查询时，要求所有参与 UNION 的 SELECT 语句的字段数量和对应位置的类型必须兼容。框架会按照第一个 SELECT 语句的字段类型作为基准，后续 SELECT 的对应字段类型需要能够转换为基准类型，否则会在运行时抛出异常。
比如第一个 SELECT 返回字段类型为Integer，第二个 SELECT 对应位置返回Long类型，JOOQ 会自动处理数值类型的向上转型，将Long转换为Integer时会检查是否在取值范围内，超出范围则会报错。如果第一个 SELECT 返回的是String类型，第二个 SELECT 对应位置返回Integer类型，JOOQ 会尝试将数值转换为字符串，转换失败则抛出异常。
基础类型映射示例
以下代码展示两个类型兼容的 SELECT 进行 UNION 查询的示例：
import org.jooq.DSLContext;
import org.jooq.Record2;
import org.jooq.Result;
import static com.example.jooq.Tables.USER;
public class UnionTypeDemo {
public Result<Record2<Integer, String>> queryUnionData(DSLContext dsl) {
// 第一个查询，返回id(Integer)和name(String)
var select1 = dsl.select(USER.ID, USER.NAME).from(USER).where(USER.AGE.gt(18));
// 第二个查询，返回id(Integer)和name(String)，类型与第一个查询兼容
var select2 = dsl.select(USER.ID, USER.NAME).from(USER).where(USER.AGE.lt(16));
// 执行UNION查询
return select1.union(select2).fetch();
}
}
自定义转换器的作用与基础用法
自定义转换器用于实现数据库字段类型和 Java 对象类型之间的自定义映射，需要实现 JOOQ 提供的Converter接口，该接口包含两个核心方法：from用于将数据库值转换为 Java 对象，to用于将 Java 对象转换为数据库值。
自定义转换器实现示例
假设数据库中用INT类型存储用户状态，0 表示禁用，1 表示启用，我们定义对应的 Java 枚举类并编写转换器：
import org.jooq.Converter;
// 用户状态枚举
enum UserStatus {
DISABLED(0), ENABLED(1);
private final int code;
UserStatus(int code) {
this.code = code;
}
public int getCode() {
return code;
}
public static UserStatus fromCode(int code) {
for (UserStatus status : values()) {
if (status.code == code) {
return status;
}
}
return null;
}
}
// 自定义转换器，实现数据库INT到UserStatus的转换
class UserStatusConverter implements Converter<Integer, UserStatus> {
@Override
public UserStatus from(Integer databaseObject) {
if (databaseObject == null) {
return null;
}
return UserStatus.fromCode(databaseObject);
}
@Override
public Integer to(UserStatus userObject) {
if (userObject == null) {
return null;
}
return userObject.getCode();
}
@Override
public Class<Integer> fromType() {
return Integer.class;
}
@Override
public Class<UserStatus> toType() {
return UserStatus.class;
}
}
UNION 查询中自定义转换器的正确用法
在 UNION 查询中使用自定义转换器时，需要保证所有参与 UNION 的 SELECT 语句中对应字段都使用相同的转换器配置，否则会出现类型映射不一致的问题。
错误用法示例
以下代码是常见错误用法，两个 SELECT 语句的 status 字段一个使用了转换器，一个没有使用，会导致 UNION 时类型不匹配：
import org.jooq.DSLContext;
import org.jooq.Record2;
import org.jooq.Result;
import static com.example.jooq.Tables.USER;
public class UnionWrongDemo {
public Result<Record2<Integer, UserStatus>> wrongQuery(DSLContext dsl) {
// 第一个查询对status字段使用了自定义转换器
var select1 = dsl.select(USER.ID, USER.STATUS.convert(new UserStatusConverter()))
.from(USER)
.where(USER.AGE.gt(18));
// 第二个查询没有对status字段使用转换器，返回类型是Integer
var select2 = dsl.select(USER.ID, USER.STATUS)
.from(USER)
.where(USER.AGE.lt(16));
// 执行UNION会抛出类型不匹配异常
return select1.union(select2).fetch();
}
}
正确用法示例
正确的做法是对所有参与 UNION 的 SELECT 语句的对应字段统一应用相同的转换器：
import org.jooq.DSLContext;
import org.jooq.Record2;
import org.jooq.Result;
import static com.example.jooq.Tables.USER;
public class UnionCorrectDemo {
public Result<Record2<Integer, UserStatus>> correctQuery(DSLContext dsl) {
// 第一个查询对status字段应用转换器
var select1 = dsl.select(USER.ID, USER.STATUS.convert(new UserStatusConverter()))
.from(USER)
.where(USER.AGE.gt(18));
// 第二个查询对status字段同样应用相同的转换器
var select2 = dsl.select(USER.ID, USER.STATUS.convert(new UserStatusConverter()))
.from(USER)
.where(USER.AGE.lt(16));
// 执行UNION查询，类型一致不会报错
return select1.union(select2).fetch();
}
}
注意事项
- UNION 查询中所有 SELECT 的字段数量必须完全一致，否则 JOOQ 会在编译阶段就提示错误。
- 自定义转换器的
fromType必须与数据库字段的实际类型匹配，toType是 Java 端的对象类型，不要写反。 - 如果 UNION 的多个查询来自不同的表，需要确保对应位置的字段类型在经过转换器处理后能够兼容，避免运行时转换异常。
- 使用 UNION ALL 时同样遵循上述类型映射规则，只是 UNION ALL 不会去重，类型检查逻辑与 UNION 一致。
总结
JOOQ 的 UNION 查询类型映射以第一个 SELECT 的字段类型为基准，要求后续 SELECT 对应字段类型可兼容转换。自定义转换器需要统一应用到所有参与 UNION 的 SELECT 对应字段上，才能保证类型映射的一致性。实际开发中建议将常用的转换器封装为工具方法，避免重复配置导致的错误，同时可以通过单元测试验证 UNION 查询的类型兼容性，提前发现潜在问题。
JOOQUNION_querytype_mappingcustom_converter修改时间：2026-07-16 05:39:15