Hibernate Search 中文操作指南

1. Compatibility

1.1. Dependencies

表 1. 兼容的依赖项版本

Table 1. Compatible versions of dependencies

Version

Note

Java Runtime

11, 17 or 21

Hibernate ORM (for the Hibernate ORM mapper

6.5.2.Final

Jakarta Persistence (for the Hibernate ORM mapper

3.1

Apache Lucene (for the Lucene backend)

9.11.0

Elasticsearch server (for the Elasticsearch backend)

7.10+ or 8.x

Most of older minor versions (e.g. 7.11 or 8.0) are not given priority for bugfixes and new features.

OpenSearch server (for the Elasticsearch backend)

1.3 or 2.x

Other minor versions may work but are not given priority for bugfixes and new features.

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

Find more information for all versions of Hibernate Search on our compatibility matrix.

也可能对 compatibility policy 感兴趣。

The compatibility policy may also be of interest.

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

If you get Hibernate Search from Maven, it is recommended to import Hibernate Search BOM as part of your dependency management to keep all its artifact versions aligned:

<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 。

Elasticsearch 7.11+ licensing While Elasticsearch up to 7.10 was distributed under the Apache License 2.0, be aware that Elasticsearch 7.11 and later are distributed under the Elastic License and the SSPL, which are not considered open-source by the Open Source Initiative.

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

Only the low-level Java REST client, which Hibernate Search depends on, remains open-source.

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

OpenSearch While it historically targeted Elastic’s Elasticsearch distribution, Hibernate Search is also compatible with OpenSearch and regularly tested against it; see Compatibility for more information.

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

Every section of this documentation referring to Elasticsearch is also relevant for the OpenSearch distribution.

1.2. Framework support

1.2.1. Quarkus

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

Quarkus has an official extension for Hibernate Search with Hibernate ORM using the Elasticsearch backend, which is a tight integration with additional features, different dependencies, and different configuration properties.

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

As your first step to using Hibernate Search within Quarkus, we recommend you follow Quarkus’s Hibernate Search Guide: it is a great hands-on introduction to Hibernate Search, and it covers the specifics of Quarkus.

1.2.2. WildFly

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

WildFly includes modules for Hibernate Search with Hibernate ORM using either the Lucene backend or the Elasticsearch backend.

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

To start using Hibernate Search within WildFly, see the Hibernate Search section in the WildFly Developer Guide: it covers all the specifics of WildFly.

1.2.3. Spring Boot

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

Hibernate Search can easily be integrated into a Spring Boot application. Just read about Spring Boot’s specifics below, then follow the getting started guide.

Configuration properties

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

application.properties/application.yaml are Spring Boot configuration files, not JPA or Hibernate Search configuration files. Adding Hibernate Search properties starting with hibernate.search. directly in that file will not work.

When integrating Hibernate Search with Hibernate ORM

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

Prefix your Hibernate Search properties with spring.jpa.properties., so that Spring Boot passes along the properties to Hibernate ORM, which will pass them along to Hibernate Search.

例如：

For example:

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

When using the Standalone POJO mapper

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

You can pass properties programmatically to SearchMappingBuilder#property.

Dependency versions

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

Spring Boot automatically sets the version of dependencies without your knowledge. While this is ordinarily a good thing, from time to time Spring Boot dependencies will be a little out of date. Thus, it is recommended to override Spring Boot’s defaults at least for some key dependencies.

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

With Maven, there are a few ways to override these versions depending on how Spring is added to the application. If your application’s POM file is using spring-boot-starter-parent as its parent POM then simply adding version properties to your POM’s <properties> should help:

<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 中的属性名称是否发生了更改，如果发生了更改，则使用新属性名称。

If, after setting the properties above, you still are getting the same version of the libraries, check if property names in the Spring Boot’s BOM have changed, and if so use the new property name.

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

Alternatively, if either the spring-boot-dependencies or the spring-boot-starter-parent is imported into the dependency management (<dependencyManagement>) then overriding the versions can be done either by importing a BOM listing the dependencies we want to override, or by explicitly listing a dependency with its version that we want to be used:

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

. Override dependencies either with another BOM or explicitly

<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>

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

For other build tools refer to their documentation for details.

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

Maven’s dependency plugin (or your build tool corresponding alternative) can be used to verify that the version override was correctly applied, e.g.:

# 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 的版本匹配即可解决问题。

If, after setting the properties above, you still have problems (e.g. NoClassDefFoundError) with some of Hibernate Search’s dependencies, look for the version of that dependency in Spring Boot’s POM and Hibernate Search’s POM: there will probably be a mismatch, and generally overriding Spring Boot’s version to match Hibernate Search’s version will work fine.

Application hanging on startup

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

Spring Boot 2.3.x and above is affected by a bug that causes the application to hang on startup when using Hibernate Search, particularly when using custom components (custom bridges, analysis configurers, …).

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

The problem, which is not limited to just Hibernate Search, has been reported, but hasn’t been fixed yet in Spring Boot 2.5.1.

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

As a workaround, you can set the property spring.data.jpa.repositories.bootstrap-mode to deferred or, if that doesn’t work, default. Interestingly, using @EnableJpaRepositories(bootstrapMode = BootstrapMode.DEFERRED) has been reported to work even in situations where setting spring.data.jpa.repositories.bootstrap-mode to deferred didn’t work.

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

Alternatively, if you do not need dependency injection in your custom components, you can refer to those components with the prefix constructor: so that Hibernate Search doesn’t even try to use Spring to retrieve the components, and thus avoids the deadlock in Spring. See this section for more information.

Spring Boot’s Elasticsearch client and auto-configuration

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

As you may know, Spring Boot includes "auto-configuration" that triggers as soon as a dependency is detected in the classpath.

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

This may lead to problems in some cases when dependencies are used by the application, but not through Spring Boot.

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

In particular, Hibernate Search transitively brings in a dependency to Elasticsearch’s low-level REST Client. Spring Boot, through ElasticsearchRestClientAutoConfiguration, will automatically set up an Elasticsearch REST client targeting (by default) http://localhost:9200 as soon as it detects that dependency to the Elasticsearch REST Client JAR.

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

If your Elasticsearch cluster is not reachable at http://localhost:9200, this might lead to errors on startup.

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

To get rid of these errors, either configure Spring’s Elasticsearch client manually, or disable this specific auto-configuration.

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

Spring Boot’s Elasticsearch client is completely separate from Hibernate Search: the configuration of one won’t affect the other.

1.2.4. Other

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

If your framework of choice is not mentioned in the previous sections, don’t worry: Hibernate Search works just fine with plenty of other frameworks.

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

Just follow the getting started guide to try it out.