Hibernate Search 中文操作指南

1. Compatibility

1.1. Dependencies

表 1. 兼容的依赖项版本

Version

Note

Java Runtime

11, 17 or 21

Hibernate ORM（用于 Hibernate ORM mapper

6.5.2.Final

Jakarta Persistence（用于 Hibernate ORM mapper

3.1

Apache Lucene（用于 Lucene backend

9.11.0

Elasticsearch 服务器（用于 Elasticsearch backend

7.10+ or 8.x

大部分较旧的次要版本（例如 7.11 或 8.0）不会优先考虑错误修复和新功能。

OpenSearch 服务器（用于 Elasticsearch backend

1.3 or 2.x

其他次要版本可能有效，但不会优先考虑错误修复和新功能。

在我们的 compatibility matrix 上查找所有版本的 Hibernate Search 的更多信息。

也可能对 compatibility policy 感兴趣。

如果您从 Maven 获取 Hibernate Search，建议导入 Hibernate Search BOM 作为依赖项管理的一部分，以保持其所有工件版本的对齐：

<dependencyManagement> <dependencies> <!-- Import Hibernate Search BOM to get all of its artifact versions aligned: -→ <dependency> <groupId>org.hibernate.search</groupId> <artifactId>hibernate-search-bom</artifactId> <version>7.2.0.Alpha2</version> <type>pom</type> <scope>import</scope> </dependency> <!-- Any other dependency management entries -→ </dependencies> </dependencyManagement> <dependencyManagement> <dependencies> <!-- Import Hibernate Search BOM to get all of its artifact versions aligned: -→ <dependency> <groupId>org.hibernate.search</groupId> <artifactId>hibernate-search-bom</artifactId> <version>7.2.0.Alpha2</version> <type>pom</type> <scope>import</scope> </dependency> <!-- Any other dependency management entries -→ </dependencies> </dependencyManagement>

Elasticsearch 7.11+ 许可证虽然 Elasticsearch 7.10 之前是在 Apache License 2.0 下分发的，但请注意 Elasticsearch 7.11 及更高版本是在 Elastic License 和 SSPL 下分发的，这些是 not considered open-source by the Open Source Initiative 。

只有 Hibernate Search 依赖的底层 Java REST 客户端仍然是开源的。

OpenSearch 虽然它最初针对 Elastic’s Elasticsearch distribution ，但 Hibernate Search 也与 OpenSearch 兼容，并针对它进行定期测试；有关更多信息，请参阅 Compatibility 。

本说明中引用 Elasticsearch 的每节也与 OpenSearch 分发相关。

1.2. Framework support

1.2.1. Quarkus

Quarkus有一个官方 Hibernate Search with Hibernate ORM扩展，该扩展使用 Elasticsearch backend，它与其他功能、其他依赖项和不同的配置属性紧密集成。

作为在 Quarkus 中使用 Hibernate Search 的第一步，我们建议您关注 Quarkus 的 Hibernate Search Guide：它是 Hibernate Search 实操简介，and 涵盖了 Quarkus 的具体信息。

1.2.2. WildFly

WildFly包含使用 Lucene backend或 Elasticsearch backend的 Hibernate Search with Hibernate ORM模块。

要在 WildFly 中开始使用 Hibernate Search，请参阅 Hibernate Search section in the WildFly Developer Guide：它涵盖了 WildFly 的所有具体信息。

1.2.3. Spring Boot

Hibernate Search 可以轻松集成到 Spring Boot应用程序中。只需阅读下面 Spring Boot 的详细信息，然后按照 getting started guide操作即可。

Configuration properties

application.properties/application.yaml 是 Spring Boot 配置文件，而不是 JPA 或 Hibernate Search 配置文件。直接在该文件中添加以 hibernate.search. 开头的 Hibernate Search 属性不会生效。

When integrating Hibernate Search with Hibernate ORM

用 spring.jpa.properties. 为 Hibernate Search 属性加前缀，以便 Spring Boot 将属性传递给 Hibernate ORM，后者将它们传递给 Hibernate Search。

例如：

spring.jpa.properties.hibernate.search.backend.hosts = elasticsearch.mycompany.com

When using the Standalone POJO mapper

可以按编程方式将属性传递给 SearchMappingBuilder#property 。

Dependency versions

Spring Boot 在您不知情的情况下自动设置依赖项版本。虽然这通常是一件好事，但有一段时间，Spring Boot 依赖项会有点过时。因此，建议至少针对一些关键依赖项覆盖 Spring Boot 的默认值。

使用 Maven，有几种方法可以覆盖这些版本，具体取决于如何向应用程序添加 Spring。如果应用程序的 POM 文件使用 spring-boot-starter-parent 作为其父 POM，那么只需将版本属性添加到您的 POM 的 <properties> 中即可：

<properties>
    <hibernate.version>6.5.2.Final</hibernate.version>
    <elasticsearch-client.version>8.14.0</elasticsearch-client.version>
    <!-- ... plus any other properties of yours ... -->
</properties>

如果您在设置上述属性后仍然获取同版本的库，请检查 Spring Boot 的 BOM 中的属性名称是否发生了更改，如果发生了更改，则使用新属性名称。

或者，如果 spring-boot-dependencies 或 spring-boot-starter-parent 已导入依赖项管理 (<dependencyManagement>)，则可以通过导入列出我们想要覆盖的依赖项的 BOM 或明确列出我们要使用的版本的依赖项来覆盖版本：

  1. 通过另一个 BOM 或明确覆盖依赖项

<dependencyManagement>
    <dependencies>
        <!--
            Overriding Hibernate ORM version by importing the BOM.
            Alternatively, can be done by adding specific dependencies
            as shown below for Elasticsearch dependencies.
        -->
        <dependency>
            <groupId>org.hibernate.orm</groupId>
            <artifactId>hibernate-platform</artifactId>
            <version>${version.org.hibernate.orm}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.3.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!--
            Since there is no BOM for the Elasticsearch REST client,
            these dependencies have to be listed explicitly:
        -->
        <dependency>
            <groupId>org.elasticsearch.client</groupId>
            <artifactId>elasticsearch-rest-client</artifactId>
            <version>8.14.0</version>
        </dependency>
        <dependency>
            <groupId>org.elasticsearch.client</groupId>
            <artifactId>elasticsearch-rest-client-sniffer</artifactId>
            <version>8.14.0</version>
        </dependency>
        <!-- Other dependency management entries -->
    </dependencies>
</dependencyManagement>

对于其他构建工具，请参阅其文档以获取详细信息。

Maven 的 dependency 插件（或你的构建工具对应的替代方法）可以用于验证版本覆盖已正确应用，例如：

# Show the dependency tree filtering for Hibernate and Elasticsearch dependencies to reduce the output: mvn dependency:tree "-Dincludes=org.hibernate.,org.elasticsearch." # Show the dependency tree filtering for Hibernate and Elasticsearch dependencies to reduce the output: mvn dependency:tree "-Dincludes=org.hibernate.,org.elasticsearch."

如果在设置上述属性后，您仍然遇到问题（例如 NoClassDefFoundError），则某些 Hibernate Search 的依赖项中会出现这些问题，请在 Spring Boot’s POM和 Hibernate Search’s POM中查找该依赖项的版本：很可能会出现不匹配，并且通常将 Spring Boot 的版本覆盖为与 Hibernate Search 的版本匹配即可解决问题。
Application hanging on startup

当使用 Hibernate Search，特别是使用自定义组件（自定义桥接、分析配置器等）时，Spring Boot 2.3.x 及更高版本受错误影响，该错误会导致应用程序在启动时挂起。

该问题并不仅限于 Hibernate Search， has been reported，但 Spring Boot 2.5.1 中尚未解决。

作为解决方法，您可以将属性 spring.data.jpa.repositories.bootstrap-mode 设置为 deferred，如果不起作用，请 default。有趣的是，据报告说，@EnableJpaRepositories(bootstrapMode = BootstrapMode.DEFERRED) 甚至可以在将 spring.data.jpa.repositories.bootstrap-mode 设置为 deferred 不起作用的情况下使用。

另外，如果你不需要自定义组件中的依赖注入，则可以通过前缀 _constructor:_引用这些组件，这样 Hibernate Search 甚至就不会尝试使用 Spring 来检索这些组件，从而避免了 Spring 中的死锁。请参阅 this section了解更多信息。

Spring Boot’s Elasticsearch client and auto-configuration

如您所知，Spring Boot 包括“自动配置”，只要在类路径中检测到依赖项，就会触发该配置。

当应用程序使用依赖项但未通过 Spring Boot 使用依赖项时，在某些情况下这可能会导致问题。

特别是，Hibernate Search 通过传递形式引入了对 Elasticsearch 的低级 REST 客户端的依赖。Spring Boot 通过 ElasticsearchRestClientAutoConfiguration 将自动设置 Elasticsearch REST 客户端，在检测到对 Elasticsearch REST 客户端 JAR 的依赖时将其定向到 (默认情况下) _ http://localhost:9200_ 。

如果在 _ http://localhost:9200_ 无法访问 Elasticsearch 集群，则这可能导致启动时出现错误。

要消除这些错误，请 configure Spring’s Elasticsearch client manually 或 disable this specific auto-configuration。

Spring Boot 的 Elasticsearch 客户端与 Hibernate Search 完全分离：一个的配置不会影响另一个。

1.2.4. Other

如果上文未提及您的首选框架，请不要担心：Hibernate Search 可以与许多其他框架很好地配合使用。

遵照 getting started guide即可尝试使用。