当 Spring Boot 应用需要接入 Solr 时，最繁琐的部分并不是发送 HTTP 请求，而是把大量 Repository 接口的样板代码维护好。Spring Data Solr 提供了一组注解和接口，其中 @EnableSolrRepositories 承担了扫描、注册、代理生成等核心工作。本文围绕这个注解说明整合步骤、参数配置以及查询实现，帮助读者把 Solr 检索能力快速落到项目中。
一、整合前准备：引入依赖与 Solr 连接配置
Spring Boot 对 Solr 提供了自动化配置模块，核心依赖是 spring-boot-starter-data-solr。它内部集成了 Spring Data Solr 和 SolrJ，后者是 Solr 官方提供的 Java 客户端。在 Maven 项目的 pom.xml 中加入以下依赖即可，版本由 Spring Boot 统一管理，不需要单独声明。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-solr</artifactId>
</dependency>
随后在 application.properties 或 application.yml 中指定 Solr 服务地址。属性名是 spring.data.solr.host，如果 Solr 部署在本地并开放默认端口，可以写成如下形式。需要注意的是，该地址必须指向一个已经创建好的 Solr Core 或 Collection，否则后续 Repository 初始化时会连接失败。
spring.data.solr.host=http://localhost:8983/solr
如果项目需要多个 Solr 核心或自定义连接参数，也可以自己声明 SolrClient Bean。Spring Boot 的自动配置在检测到自定义 Bean 后会退避，不会重复创建默认客户端。连接超时、读超时等参数可以通过 SolrClient 的构建器设置，适合对可用性要求较高的生产环境。
二、使用 @EnableSolrRepositories 扫描仓库接口
要启用 Spring Data Solr 的仓库能力，必须在某个配置类或启动主类上添加 @EnableSolrRepositories。该注解的作用类似 @EnableJpaRepositories，会扫描指定包下继承 Solr Repository 接口的接口，并自动生成代理实现。如果省略 basePackages 参数，则默认扫描注解所在类的当前包及所有子包，这在小项目中比较方便，但为了结构清晰建议显式指定。
@Configuration
@EnableSolrRepositories(basePackages = "com.example.demo.solr.repository")
public class SolrConfig {
}
仓库接口通常继承 SolrCrudRepository<T, ID>，它已经提供了 save、findById、delete、count 等基础方法。也可以继承 PagingAndSortingRepository 获得分页和排序能力。
public interface ProductRepository extends SolrCrudRepository<Product, String> {
List<Product> findByTitleContaining(String keyword);
}
实体类需要使用 @SolrDocument 标注，并通过 @Id 标识主键。字段映射用 @Indexed 指定 Solr 中的字段名和类型。下面是一个商品文档的示例，其中 title 字段适合全文检索，price 字段适合范围过滤和排序。
@SolrDocument(solrCoreName = "product")
public class Product {
@Id
@Indexed(name = "id", type = "string")
private String id;
@Indexed(name = "title", type = "text_general")
private String title;
@Indexed(name = "price", type = "pdouble")
private Double price;
// 省略 getter 和 setter
}
三、实现增删改查与自定义查询
完成注解和接口声明后，可以直接在 Service 层注入仓库接口并使用，无需编写实现类。Spring 会在启动阶段为每个 Repository 接口创建 JDK 动态代理，所有方法调用都会转换为 Solr 查询请求。保存实体时，代理会调用 SolrJ 将文档写入指定 Core；查询方法则会根据方法名解析出 Solr 查询语句。
@Service
public class ProductService {
private final ProductRepository productRepository;
public ProductService(ProductRepository productRepository) {
this.productRepository = productRepository;
}
public void save(Product product) {
productRepository.save(product);
}
public List<Product> searchByTitle(String keyword) {
return productRepository.findByTitleContaining(keyword);
}
}
如果需要更复杂的查询条件，可以使用 @Query 注解直接编写 Solr 查询语法。例如查找标题包含关键字且价格在指定区间内的商品，可以这样声明。注意 ?0 和 ?1 是参数占位符，对应方法参数顺序。Solr 的范围查询使用方括号表示包含边界。
public interface ProductRepository extends SolrCrudRepository<Product, String> {
@Query("title:*?0* AND price:[?1 TO ?2]")
List<Product> search(String keyword, Double minPrice, Double maxPrice);
}
分页和排序可以直接通过方法参数注入 Pageable 和 Sort。Spring Data 会把这些信息拼接到 Solr 查询中，避免手动拼接 start、rows 和 sort 参数。下面的示例展示按价格降序查询第一页数据。
Page<Product> page = productRepository.findAll(
PageRequest.of(0, 10, Sort.by(Sort.Direction.DESC, "price"))
);
四、注解参数解析与常见问题排查
@EnableSolrRepositories 除了 basePackages 之外，还提供了多个可选参数。理解这些参数可以避免部分配置错误。下表列出了常用参数及其作用。
| 参数名 | 作用 |
|---|---|
| basePackages | 指定仓库接口扫描的包路径列表 |
| basePackageClasses | 通过类定位扫描包，适合模块化项目 |
| namedQueriesLocation | 指定外部查询定义文件的位置 |
| schemaCreationSupport | 是否根据实体自动创建或更新 Solr Schema |
| multicoreSupport | 是否支持一个 SolrClient 连接多个 Core |
| repositoryBaseClass | 自定义所有仓库接口的公共基础类 |
其中 schemaCreationSupport 在开发环境可以开启，让 Spring Data Solr 根据实体注解自动补充字段定义；但在生产环境建议关闭，改为由 Solr 管理员管理 Schema，避免数据结构被应用意外修改。multicoreSupport 如果设为 true，实体类上的 solrCoreName 会生效，否则所有操作默认走客户端配置的 Core。
整合过程中最常见的问题是找不到仓库 Bean，报错通常为 NoSuchBeanDefinitionException。这多半是因为仓库接口不在 @EnableSolrRepositories 的扫描路径下，或者注解忘记添加。另一个高频问题是连接超时，需要检查 spring.data.solr.host 是否指向正确的 Core 地址，以及 Solr 服务是否允许远程访问。中文检索效果差则通常与字段类型有关，建议将标题类字段设置为 text_general 或配置中文分词器，而不是使用 string 类型。
最后需要提醒，Spring Data Solr 在较高版本中依赖的 SolrJ 客户端与 Solr 服务端存在兼容性要求，若升级 Spring Boot 后出现连接异常，可以先核对客户端版本与服务端版本是否匹配。定期查看官方迁移说明，能减少很多无谓的排查时间。
Spring Boot整合SolrEnableSolrRepositoriesSolrRepository修改时间：2026-08-21 08:29:51