Spring Data JPA自定义Converter未按预期调用问题排查

核心原因 #

Converter不生效的最直接原因是Repository层使用了nativeQuery = true的原生SQL写入方法：

• JPA的AttributeConverter仅在实体被持久化上下文托管的场景下触发，包括：调用JPA内置的save()/saveAll()等方法持久化实体、执行基于实体映射的JPQL/Criteria查询时的属性映射转换。
• 原生SQL是直接将参数拼入SQL语句发送给数据库执行，完全绕过了JPA的实体生命周期管理、属性转换逻辑，自然不会调用定义的Converter。
• 额外注意：当前原生方法的入参s_con定义为String类型，但业务层传入的是List<String>，本身就存在类型不匹配问题，只是未触发显性异常。

其他需要排查的潜在问题 #

除了核心的原生SQL问题，代码里还有几个容易导致Converter失效的隐患：

• 实体类与Repository泛型不匹配：实体类是CMark，但Repository继承JpaRepository时写的泛型是ClassificationMarking，类名不一致会导致JPA无法正确扫描实体上的@Convert注解映射。
• Converter未被Spring容器扫描：如果Converter类不在Spring Boot的默认扫描包路径下，即使加了@Converter注解也不会被识别，可以在启动类上加@EntityScan指定实体、Converter的扫描包，或者给Converter加上@Component注解注册为Bean。
• 字段映射笔误：实体字段是sCon，toString方法里错误引用了不存在的s_con变量，这类映射书写错误也会干扰JPA的正常映射逻辑。

解决方案 #

方案一（推荐）：使用JPA内置的持久化方法，删除自定义原生插入 #

直接调用Spring Data JPA内置的save()方法即可自动触发Converter，不需要自己写插入SQL：

// 业务层直接调用save方法
public int postCMark(CMark cMark) {
    int status = 0;
    try {
        cMarkingRepository.save(cMark);
        status = 1;
    } catch ( Exception e) {
        e.printStackTrace();
    }
    return status;
}

使用这种方式时，JPA会自动检测sCon字段上的@Convert注解，在插入数据库前自动调用convertToDatabaseColumn方法把List<String>转为逗号分隔的字符串存入s_con列，查询时也会自动转回List类型。
注意需要先修正Repository的泛型错误，把JpaRepository <ClassificationMarking, String>改成JpaRepository <CMark, String>，同时修正实体类toString方法里的变量笔误。

方案二：必须使用原生SQL时手动调用转换逻辑 #

如果因为特殊场景必须保留原生SQL插入，就不要依赖自动转换，手动在业务层做参数转换再传入：

1. 把Converter注入到业务类中
2. 调用convertToDatabaseColumn方法把List转为字符串后，再作为参数传入Repository的原生方法

// 业务层示例
@Autowired
private StringListConverterCommaDelim converter;

public int postCMark(CMark cMark) {
    int status = 0;
    try {
        String sConStr = converter.convertToDatabaseColumn(cMark.getSCon());
        status = cMarkingRepository.insertCMark(cMark.getCFk(), sConStr);
    } catch ( Exception e) {
        e.printStackTrace();
    }
    return status;
}

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