如何在Hibernate Search中创建并使用LuceneAnalysisDefinitionProvider

问题背景 #

搜索LuceneAnalysisDefinitionProvider时，网上大多是复制粘贴的代码，缺乏清晰解释和实际示例。自行实现时遇到以下问题，代码如下：

public class CustomLuceneAnalysisDefinitionProvider
        implements LuceneAnalysisDefinitionProvider {

  @Override
  public void register(final LuceneAnalysisDefinitionRegistryBuilder builder) {
    builder
      .analyzer("customAnalyzer")
        .tokenizer(StandardTokenizerFactory.class)
        .charFilter(MappingCharFilterFactory.class)
          .param("mapping",
            "org/hibernate/search/test/analyzer/mapping-chars.properties")
        .tokenFilter(ASCIIFoldingFilterFactory.class)
        .tokenFilter(LowerCaseFilterFactory.class)
        .tokenFilter(StopFilterFactory.class)
          // WRONG! It's not "mapping"!
//        .param("mapping",
//          "org/hibernate/search/test/analyzer/stoplist.properties")
          .param("words",
            "classpath:/stoplist.properties")
          .param("ignoreCase", "true");
  }

}

需解决的具体问题：

1. 为MappingCharFilterFactory配置mapping参数时，mapping-chars.properties的存放位置与正确引用方式？
2. mapping-chars.properties的内容格式是什么，如何创建修改？
3. 为StopFilterFactory配置参数时，stoplist.properties的存放位置与正确引用方式？
4. 如何将自定义的customAnalyzer应用到单个@Field字段上？

另外，不想替换默认分词器，仅为特定属性使用自定义分词器，网上看到的application.properties配置如下：

hibernate.search.lucene.analysis_definition_provider = com.thevegcat.app.search.CustomAnalysisDefinitionProvider

编辑1：查看org.apache.lucene.analysis.core.StopFilterFactory第86行可知，该工厂接受的参数键是words而非mapping。

编辑2：若停用词文件放在src/main/resources目录下，需用如下方式引用：

.param("words", "classpath:/stoplist.properties")

问题解答 #

1. mapping-chars.properties的存放与引用 #

• 存放位置：放在项目src/main/resources目录下，也可放在其子目录（如src/main/resources/analyzer）。
• 引用规则：
  • 根目录直接引用：classpath:/mapping-chars.properties；
  • 子目录引用：比如放在analyzer子目录，用classpath:/analyzer/mapping-chars.properties；
  • 代码中原路径是Hibernate Search测试用例路径，实际项目需替换为自己的路径。

2. mapping-chars.properties的内容格式 #

该文件用于定义字符映射规则，每行格式为原始字符/字符串 → 目标字符/字符串，示例：

# 全角逗号替换为半角逗号
，→,
# 连续破折号替换为单个破折号
——→-
# 特殊字符转义
é→e
ñ→n

可根据业务需求添加任意映射规则，注释用#开头。

3. stoplist.properties的存放与引用 #

• 存放位置：同mapping-chars.properties，放在src/main/resources或其子目录。
• 引用方式：使用classpath:/前缀指定路径，根目录用classpath:/stoplist.properties，子目录则对应调整路径。
• 注意：StopFilterFactory的参数为words，你已在编辑1中纠正，此写法正确。

4. 为单个@Field字段应用customAnalyzer #

无需替换默认分词器，直接在@Field注解中指定analyzer属性即可，修改后代码：

@Field(
    index = Index.YES,
    analyze = Analyze.YES,
    store = Store.NO,
    bridge = @FieldBridge(impl = LocalizedFieldBridge.class),
    analyzer = @Analyzer(definition = "customAnalyzer") // 指定自定义分词器
)
private LocalizedField description;

同时需在application.properties中配置自定义分析器提供者，确保Hibernate Search能识别你的实现：

hibernate.search.lucene.analysis_definition_provider = com.thevegcat.app.search.CustomAnalysisDefinitionProvider

此配置仅注册自定义分词器，不会替换默认规则，未指定analyzer的字段仍使用默认分词器。

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