升级Spring 2.4.0后Spring Data Cassandra UDT转换器缺失异常

我之前升级到Spring Data Cassandra 2.4.x版本时也碰到过完全一样的问题，这个异常本质上是Spring Data没有找到自定义UDT类对应的转换器，通常是由UDT配置或包扫描的细节问题导致的，下面是一步步的解决方案：

1. 确认@UserDefinedType注解的名称匹配Cassandra中的UDT #

Spring Data Cassandra默认会把类名转小写作为UDT名称，但如果你的Cassandra UDT名称和类名不一致（比如UDT叫contact_address而类是Address），必须显式指定name属性：

@UserDefinedType(name = "address") // 这里要和Cassandra中创建的UDT名称完全一致
public class Address {
    private String street;
    private String city;
    // 构造方法、getter/setter
}

2. 确保UDT类被包含在实体扫描路径中 #

很多人会忽略这一点：你的AbstractCassandraConfiguration子类必须把UDT类所在的包也加入到getEntityBasePackages()返回的数组里，否则Spring Data无法识别这个UDT，也就不会生成对应的转换器：

@Configuration
public class CassandraConfig extends AbstractCassandraConfiguration {

    @Override
    protected String getKeyspaceName() {
        return "your_keyspace_name";
    }

    @Override
    protected String getContactPoints() {
        return "localhost";
    }

    @Override
    public String[] getEntityBasePackages() {
        // 要包含Contact和Address所在的所有包，比如两者在同一个包就写一个
        return new String[]{"com.sellingsimplified.msor.common.schema"};
    }
}

3. 完善@CassandraType注解的参数 #

只指定type=Name.UDT是不够的，需要明确指定userTypeName来关联Cassandra中的UDT名称，避免类型匹配歧义：

@Table("contact")
public class Contact {
    @PrimaryKey
    private UUID id;
    private String fullName;
    
    @CassandraType(type = Name.UDT, userTypeName = "address") // 这里要和UDT的名称一致
    private Address address;
    
    // 构造方法、getter/setter
}

4. 排查自定义转换器的冲突 #

如果你项目中手动注册了Cassandra转换器，要确保没有覆盖或排除默认的MappingCassandraConverter，这个转换器负责处理UDT的自动转换逻辑。如果必须自定义转换器，要确保在配置中保留UDT转换的相关逻辑。

5. 清理项目缓存并重新构建 #

升级版本后，旧的编译文件或依赖缓存可能导致类加载异常，执行以下命令清理缓存：

• Maven项目：mvn clean install
• Gradle项目：./gradlew clean build

完成以上步骤后，Spring Data Cassandra应该能正确识别你的UDT类并生成对应的转换器，ConverterNotFoundException异常就会消失了。

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