在 Spring Boot 项目里接入 Cassandra 时，有一个注解经常被忽略，却直接影响 Repository 是否可用，那就是 @EnableCassandraRepositories。虽然 Spring Boot 的自动配置在很多场景下已经帮我们完成了扫描工作，但一旦项目结构稍复杂，例如需要连接多个 Cassandra 集群、把 Repository 接口放在非标准包名下，或者想统一替换 Repository 基类，自动配置就未必可靠。本文围绕这个注解展开，说明它到底做了什么，以及怎样在不同需求下正确配置。
@EnableCassandraRepositories 的核心作用与自动配置差异
@EnableCassandraRepositories 是 Spring Data Cassandra 提供的模块注解，功能与 Spring Data JPA 中的 @EnableJpaRepositories 非常相似。它通过在配置类上导入 CassandraRepositoriesRegistrar，扫描指定包路径下所有继承了 CassandraRepository 的接口，并为这些接口生成动态代理对象注册到 Spring 容器中。因此，业务代码里可以直接使用 @Autowired 注入这些 Repository，而不需要手写实现类。
Spring Boot 的自动配置类 CassandraDataAutoConfiguration 通常会在满足条件时自动开启 Repository 扫描。但自动扫描默认只覆盖主启动类所在包及其子包。如果你的 Repository 位于 com.example.repository，而启动类在 com.example，这是没问题的；如果启动类和 Repository 包没有公共父包，或者项目被拆分为多个模块，那么自动扫描就会漏掉这些接口。这时显式使用 @EnableCassandraRepositories 并指定 basePackages 是更可靠的做法。
下面是一个最小配置示例，展示如何在配置类中启用扫描：
import org.springframework.context.annotation.Configuration;
import org.springframework.data.cassandra.repository.config.EnableCassandraRepositories;
@Configuration
@EnableCassandraRepositories(basePackages = "com.example.repository")
public class CassandraConfig {
}
除了 basePackages，该注解还提供了 basePackageClasses 属性，可以通过指定一个标记类或 Repository 接口所在包来定位扫描范围，避免字符串硬编码。例如 basePackageClasses = OrderRepository.class 可以让 Spring 扫描 OrderRepository 所在的包。其他常用属性包括 includeFilters 和 excludeFilters，用于基于注解类型或自定义规则过滤接口；repositoryBaseClass 用于替换默认的 SimpleCassandraRepository 基类；repositoryFactoryBeanClass 用于指定自定义工厂 Bean；namedQueriesLocation 用于加载外部命名查询文件。掌握这些属性可以帮助我们灵活控制 Repository 的注册行为。
多集群与多 keyspace 场景下的扫描配置
在实际项目中，有时需要连接两个不同的 Cassandra 集群，或者同一个集群下的不同 keyspace。这时如果只使用一个全局的 @EnableCassandraRepositories，所有 Repository 接口都会绑定到同一个 CassandraTemplate 和 CqlSession，无法实现数据源隔离。正确做法是为不同业务域分别创建配置类，并在每个配置类上使用 @EnableCassandraRepositories，通过 cassandraTemplateRef 属性指定对应的模板 Bean。
假设订单模块连接 keyspace1，用户模块连接 keyspace2，可以建立两个独立的配置类。代码结构大致如下：
@Configuration
@EnableCassandraRepositories(
basePackages = "com.example.repository.orders",
cassandraTemplateRef = "ordersCassandraTemplate"
)
public class OrdersCassandraConfig {
// 配置第一个 CqlSession 和 CassandraTemplate
}
@Configuration
@EnableCassandraRepositories(
basePackages = "com.example.repository.users",
cassandraTemplateRef = "usersCassandraTemplate"
)
public class UsersCassandraConfig {
// 配置第二个 CqlSession 和 CassandraTemplate
}
上面的代码中，cassandraTemplateRef 属性接收的是 Spring 容器中的 Bean 名称。需要在同一个配置类或独立的 @Bean 方法里创建对应的 CassandraTemplate。每个 CassandraTemplate 又需要绑定各自的 CqlSession，而 CqlSession 连接不同的 contact points 和 keyspace。这样订单模块的 Repository 只会使用订单模板，用户模块的 Repository 只会使用用户模板，避免了查询串到错误 keyspace 的情况。
还需要注意 Bean 命名冲突的问题。当容器中存在多个 CassandraTemplate 时，必须给它们设置明确的 Bean 名称，同时不能存在两个同类型的 @Primary Bean，否则依赖注入会因无法确定唯一候选而失败。如果某些通用组件需要注入一个默认模板，可以使用 @Qualifier 显式指定。另外，Spring Boot 的自动配置可能会因为检测到已有自定义 CqlSession 而退避，此时要确保配置类的加载顺序正确，一般通过 @Configuration 和 @Bean 方法即可满足要求。
常见错误分析与最佳实践
第一个常见错误是启动时抛出 NoSuchBeanDefinitionException，提示找不到某个 Repository 接口。检查依赖和注解后，问题往往出在扫描路径。很多人误以为只要添加了 spring-boot-starter-data-cassandra 依赖，Spring 就会自动扫描所有包，实际上自动扫描范围受启动类包路径限制。最稳妥的方法是始终在配置类上显式声明 @EnableCassandraRepositories 并指定 basePackages 属性，而不是完全依赖自动配置。
第二个常见错误是将 @EnableCassandraRepositories 与 @EnableReactiveCassandraRepositories 混用。后者用于扫描响应式 Repository 接口，如 ReactiveCassandraRepository。如果一个项目同时使用阻塞式和响应式数据访问，需要把两类接口放在不同包中，并分别使用对应注解，避免 Spring 尝试用错误的工厂 Bean 创建代理。否则可能出现类型不匹配或查询方法无法识别的问题。
第三个值得注意的点是使用自定义基类时的配置遗漏。假如我们希望所有 Repository 都继承一个带有公共查询逻辑的 BaseRepositoryImpl，单纯继承还不够，必须通过 repositoryBaseClass 告诉 Spring Data 使用这个基类，否则默认的 SimpleCassandraRepository 仍然会被实例化，自定义逻辑不会生效。同理，如果自定义了 RepositoryFactoryBean，也要通过 repositoryFactoryBeanClass 显式指定。
最佳实践方面，建议按业务域划分 Repository 包，每个包对应一个配置类，这样在单集群和多集群之间切换时改动最小。对于小型项目，可以在启动类上使用 @EnableCassandraRepositories 并指定 basePackageClasses，既类型安全又易于重构。最后，启动日志中可以开启 Spring Data 的 debug 级别日志，查看 Repository 扫描结果，帮助快速发现未被扫描的接口。通过合理使用这个注解，Spring Boot 与 Cassandra 的整合会更加稳定可控。
Spring BootCassandraEnableCassandraRepositories修改时间：2026-08-19 13:53:55