升级EclipseLink至4.0.0后，PostgreSQL UUID主键查询失效问题

问题背景 #

EclipseLink从2.7.3升级至4.0.0后，使用UUID作为实体主键时，实体可正常入库，但调用find方法查询时触发类型不匹配错误，错误信息如下：

Internal Exception: org.postgresql.util.PSQLException: ERROR: operator does not exist: uuid = character varying
Hint: No operator matches the given name and argument types. You might need to add explicit type casts.
Position: 96

当前配置信息 #

实体主键定义 #

@Id
@Column(name="ID", columnDefinition="UUID")
@Convert(converter = UuidConverter.class)
protected UUID id;

自定义UUID转换器 #

@Converter(autoApply = true)
public class UuidConverter implements AttributeConverter<UUID, UUID> {

    @Override
    public UUID convertToDatabaseColumn(UUID attribute) {
        return attribute;
    }

    @Override
    public UUID convertToEntityAttribute(UUID dbData) {
        return dbData;
    }
}

PostgreSQL已配置的类型转换 #

create or replace function uuid(_text character varying) returns uuid language sql as 'select uuid_in(_text::cstring)';
create cast (character varying as uuid) with function uuid(character varying) as assignment;

查询方法 #

public T find(Object id) {
    return getEntityManager().find(entityClass, id);
}

可行解决方案 #

1. 移除冗余的自定义转换器 #

EclipseLink 4.0.0已原生支持UUID类型处理，自定义的UuidConverter（输入输出均为UUID）属于冗余配置，会干扰框架的类型绑定逻辑：

• 删除实体上的@Convert(converter = UuidConverter.class)注解
• 删除UuidConverter类文件

2. 显式指定主键的JDBC类型 #

在@Column注解中添加jdbcType属性，强制框架按照正确的JDBC类型处理UUID字段：

@Id
@Column(name="ID", columnDefinition="UUID", jdbcType=java.sql.Types.OTHER)
protected UUID id;

3. 确保查询参数为UUID类型 #

检查调用find方法时传入的参数，必须是UUID对象而非字符串。如果传入的是字符串，先转换为UUID：

// 错误示例：传入字符串
repository.find("550e8400-e29b-41d4-a716-446655440000");

// 正确示例：转换为UUID后传入
repository.find(UUID.fromString("550e8400-e29b-41d4-a716-446655440000"));

4. 修改PostgreSQL的类型转换为隐式转换 #

原配置的是赋值型转换（assignment），仅在插入/更新时生效，查询时需要隐式转换（implicit）：

create cast (character varying as uuid) with function uuid(character varying) as implicit;

5. 使用EclipseLink原生UUID生成器（可选） #

如果主键生成逻辑存在类型不一致问题，改用框架自带的UUID生成器：

@Id
@GeneratedValue(generator = "UUIDGenerator")
@UuidGenerator(name = "UUIDGenerator")
@Column(name="ID", columnDefinition="UUID")
protected UUID id;

内容的提问来源于stack exchange，提问作者Sogawa-sps