SpringBoot JPA带AttributeConverter的List属性查询问题

问题根因 #

你遇到的核心问题是：@Convert仅在实体与数据库的读写阶段生效，而JPA查询是基于实体属性的Java类型（List<String>）执行的。查询时JPA无法自动将针对List的查询条件，转换为匹配数据库中字符串字段的逻辑，导致派生查询和普通JPQL直接失效。

以下是几个无需原生查询的可行解决方案：

解决方案1：改用@ElementCollection（推荐，符合JPA规范） #

放弃自定义@Convert，使用JPA原生的@ElementCollection映射List<String>。JPA会自动创建关联表存储集合中的每个元素，查询逻辑可以直接正常工作，无需额外处理。

示例代码：

@Entity
public class YourEntity {
    // 其他实体属性...
    
    @ElementCollection
    @CollectionTable(name = "entity_reference_codes", joinColumns = @JoinColumn(name = "entity_id"))
    @Column(name = "reference_code")
    private List<String> referenceCode;
    
    // getter、setter方法...
}

之后即可正常使用派生查询：

public interface YourEntityRepository extends JpaRepository<YourEntity, Long> {
    // 单个值匹配
    List<YourEntity> findByReferenceCode(String reference);
    // 批量IN查询
    List<YourEntity> findByReferenceCodeIn(List<String> references);
}

或者JPQL查询：

@Query("select e from YourEntity e where e.referenceCode IN ?1")
List<YourEntity> findByReferenceCodes(List<String> references);

这个方案完全遵循JPA规范，避免了自定义转换器带来的查询限制，后续维护成本更低。

解决方案2：使用Criteria API构建自定义查询 #

如果不想修改实体映射，可以用Criteria API手动构建查询逻辑，根据你的ListConverter转换规则（比如逗号分隔字符串），调用数据库对应的字符串函数实现匹配。

假设你的转换器是将List<String>转为逗号分隔字符串（如["A","B"] → "A,B"），以下是不同数据库的实现示例：

MySQL 示例 #

@Repository
public class YourEntityDao {
    @PersistenceContext
    private EntityManager entityManager;

    public List<YourEntity> findByReferenceCode(String reference) {
        CriteriaBuilder cb = entityManager.getCriteriaBuilder();
        CriteriaQuery<YourEntity> query = cb.createQuery(YourEntity.class);
        Root<YourEntity> root = query.from(YourEntity.class);

        // 调用MySQL的FIND_IN_SET函数，检查值是否存在于转换后的字符串中
        Expression<Integer> findInSet = cb.function(
            "FIND_IN_SET",
            Integer.class,
            cb.literal(reference),
            root.get("referenceCode").as(String.class)
        );
        query.select(root).where(cb.greaterThan(findInSet, cb.literal(0)));

        return entityManager.createQuery(query).getResultList();
    }
}

PostgreSQL 示例 #

public List<YourEntity> findByReferenceCode(String reference) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<YourEntity> query = cb.createQuery(YourEntity.class);
    Root<YourEntity> root = query.from(YourEntity.class);

    // 调用PostgreSQL的string_to_array函数，将字符串转为数组后检查成员
    Expression<Boolean> contains = cb.isMember(
        cb.literal(reference),
        cb.function("string_to_array", List.class, root.get("referenceCode").as(String.class), cb.literal(","))
    );
    query.select(root).where(contains);

    return entityManager.createQuery(query).getResultList();
}

解决方案3：注册自定义JPA函数 #

通过自定义JPA函数，让JPQL可以直接调用逻辑检查元素是否在转换后的字符串中，无需写原生SQL。

步骤1：自定义数据库方言 #

以MySQL为例，创建自定义Dialect注册函数：

public class CustomMySQLDialect extends MySQL8Dialect {
    public CustomMySQLDialect() {
        super();
        // 注册contains_element函数，对应MySQL的FIND_IN_SET逻辑
        registerFunction(
            "contains_element",
            new SQLFunctionTemplate(
                StandardBasicTypes.BOOLEAN,
                "FIND_IN_SET(?2, ?1) > 0"
            )
        );
    }
}

步骤2：配置SpringBoot使用自定义方言 #

在application.properties中添加：

spring.jpa.properties.hibernate.dialect=com.yourpackage.CustomMySQLDialect

步骤3：在JPQL中使用自定义函数 #

public interface YourEntityRepository extends JpaRepository<YourEntity, Long> {
    // 单个值查询
    @Query("select e from YourEntity e where contains_element(e.referenceCode, ?1) = true")
    List<YourEntity> findByReferenceCode(String reference);

    // 批量IN查询（PostgreSQL适配）
    @Query("select e from YourEntity e where ?1 MEMBER OF function('string_to_array', e.referenceCode, ',')")
    List<YourEntity> findByReferenceCodeIn(List<String> references);
}

内容的提问来源于stack exchange，提问作者CoderJammer