给 Java 论坛加上全文搜索：用 Elasticsearch 实现帖子检索

论坛最初可能只需要按标题查帖子：一条 SQL，加上 LIKE 就能解决。随着帖子增多，用户开始搜索正文、组合关键词、按时间排序、查看关键词高亮片段，数据库查询就会逐渐变得难以维护。Elasticsearch（下文简称 ES）擅长对文本建立倒排索引，适合承担这类检索工作。

但接入 ES 不等于把数据库换掉。数据库仍然是帖子、用户和权限关系的事实来源；ES 保存的是适合搜索的文档副本。两边的数据需要同步，搜索结果也必须服从论坛原有的权限规则。本文以 Java 论坛为例，说明如何设计索引、写入与搜索代码，并列出容易忽略的边界。

一、先判断是否需要 Elasticsearch

ES 适合以下需求：

• 用户需要同时搜索帖子标题和正文。
• 需要相关性排序、短语匹配、关键词高亮等全文检索能力。
• 搜索数据量或检索并发已经让现有查询难以满足延迟要求。
• 计划增加筛选条件，例如版块、作者、发布时间和帖子状态。

如果只是几十个版块、少量帖子，偶尔按标题前缀查询，数据库索引可能更简单，也更容易保证事务一致性。引入 ES 会带来额外的运维、数据同步和故障处理成本；不应仅为了使用新技术而使用它。

还要明确：ES 的搜索结果可能短暂滞后于数据库。发帖成功后，搜索索引不一定立即可见；删除帖子后，索引中的旧文档也可能在同步完成前短暂存在。因此，任何影响访问权限或业务正确性的判断，都不能只依赖搜索索引。

二、示例环境与依赖

下面的代码采用 Java 17、Elasticsearch 8.13.x 和官方 Java API Client。应用依赖的客户端版本应与 ES 服务端版本及兼容策略相符；生产环境不要不经验证就随意混搭版本。请先按部署环境配置 ES 地址、账号和证书，再运行应用。

<dependency>
    <groupId>co.elastic.clients</groupId>
    <artifactId>elasticsearch-java</artifactId>
    <version>8.13.4</version>
</dependency>

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>

Spring Boot 项目通常已经通过依赖管理引入 Jackson。若没有，应使用项目统一管理的 Jackson 版本。ES 8 的安全功能默认启用；不要在生产环境中把客户端配置成跳过 TLS 证书校验。下面用环境变量提供连接参数，避免把密码写进源码。

import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.elasticsearch.client.RestClient;

public final class EsClientFactory {
    private EsClientFactory() {}

    public static ElasticsearchClient create() {
        String endpoint = System.getenv("ES_ENDPOINT");
        if (endpoint == null || endpoint.isBlank()) {
            throw new IllegalStateException("缺少 ES_ENDPOINT");
        }

        RestClient restClient = RestClient.builder(HttpHost.create(endpoint)).build();
        RestClientTransport transport =
                new RestClientTransport(restClient, new JacksonJsonpMapper());

        return new ElasticsearchClient(transport);
    }
}

这段连接示例适用于已在网络层提供可信访问条件的开发环境；启用用户名密码或 TLS 的生产环境，应按官方客户端文档配置凭据、信任证书和连接超时，并在应用关闭时关闭 transport 或底层 REST 客户端。ES 的账号应限制到应用所需的索引权限，不要使用集群管理员账号。

三、设计帖子搜索文档

不要把整张数据库表原样复制到 ES。搜索文档应只包含检索、展示和必要筛选使用的字段，例如：

• postId：稳定的业务主键，可直接用作 ES 文档 ID。
• title、body：全文字段。
• boardId、authorId、status：筛选或权限判断所需的结构化字段。
• createdAt：排序和时间范围筛选字段。

字段类型很重要。text 会经过分析器处理，适合全文搜索；keyword 保持整体值，适合精确匹配、聚合和排序；日期字段应使用 date。标题和正文不宜使用 keyword 代替 text，否则全文查询行为会与预期不同。

以下 mapping 使用 ES 内置的 standard 分析器。它不需要额外插件，但对中文分词并不等同于专业中文分词器，搜索效果必须用真实论坛数据验证。若要使用 IK 等第三方分析器，需要在集群每个相关节点安装兼容版本插件，并在升级时一并维护；不要在未安装插件的集群上直接创建引用该分析器的索引。

import java.io.StringReader;

String mapping = """
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  },
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "postId":    { "type": "keyword" },
      "title":     { "type": "text", "analyzer": "standard" },
      "body":      { "type": "text", "analyzer": "standard" },
      "boardId":   { "type": "keyword" },
      "authorId":  { "type": "keyword" },
      "status":    { "type": "keyword" },
      "createdAt": { "type": "date" }
    }
  }
}
""";

client.indices().create(c -> c
        .index("forum-posts-v1")
        .withJson(new StringReader(mapping)));

dynamic: strict 表示遇到 mapping 未声明的新字段时拒绝写入，适合字段结构明确的搜索文档，可以尽早发现拼写错误。若业务确实要扩展字段，应先设计并更新 mapping，而不是简单删除严格限制。number_of_shards 的取值应结合数据量、节点数和查询负载评估；示例中的一个主分片只为演示，不是所有生产集群的通用配置。副本数量也受集群节点情况影响。

索引名带版本号，是为了以后调整 mapping 或分析器时能创建新索引，再通过别名切换。很多字段类型不能直接原地改成另一种类型；出现这类变更，通常需要新建索引并重建数据。

四、让索引数据跟数据库保持同步

发帖后往 ES 写一份、改帖后再更新、删除时再删，看起来简单，但要考虑数据库事务和 ES 请求无法组成一个普通的本地原子事务。例如数据库写入成功而 ES 请求失败，就会产生索引缺失；ES 写入成功而数据库事务回滚，也会留下多余文档。

小型项目可以在数据库事务提交后异步投递同步任务，并实现失败重试。但不能把“提交后调用一次 ES”当成完整可靠的同步方案：应用在数据库提交后、发送任务前崩溃，事件仍可能丢失。较可靠的做法是事务性 Outbox：在同一个数据库事务中写帖子和事件表，再由后台任务读取事件、写入 ES，成功后标记已处理。消费者需要支持重试和幂等。

下面是单条索引写入示例。ES 文档 ID 使用帖子 ID，重复写入同一个 ID 会更新该文档，便于重试。示例中的数据应来自数据库实体或经过校验的业务对象，而不是直接信任客户端提交的任意字段。

import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch.core.IndexRequest;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;

public void indexPost(
        ElasticsearchClient client,
        long id,
        String title,
        String body,
        long boardId,
        long authorId,
        String status,
        Instant createdAt) throws Exception {

    Map<String, Object> doc = new HashMap<>();
    doc.put("postId", Long.toString(id));
    doc.put("title", title);
    doc.put("body", body);
    doc.put("boardId", Long.toString(boardId));
    doc.put("authorId", Long.toString(authorId));
    doc.put("status", status);
    doc.put("createdAt", createdAt.toString());

    IndexRequest<Map<String, Object>> request =
            new IndexRequest.Builder<Map<String, Object>>()
                    .index("forum-posts-v1")
                    .id(Long.toString(id))
                    .document(doc)
                    .build();

    client.index(request);
}

删除帖子时，应删除对应搜索文档；若业务是软删除，则更新 status，查询时排除不可见状态。定期对比数据库与索引，或提供可重复执行的全量重建任务，可以帮助修复同步缺口。全量重建时可先写入新版本索引，验证完成后再切换别名，避免边重建边让用户查询半成品。

五、执行全文搜索

最常见的查询是标题和正文的多字段检索，同时用结构化条件过滤版块和状态。全文条件负责相关性评分；过滤条件用于精确筛选，不参与相关性评分，适合状态、版块 ID 这类字段。

import co.elastic.clients.elasticsearch.core.SearchResponse;
import co.elastic.clients.elasticsearch._types.SortOrder;
import co.elastic.clients.elasticsearch._types.query_dsl.Operator;
import java.util.Map;

String keyword = "数据库连接池";
int page = 0;
int pageSize = 20;

if (page < 0 || pageSize < 1 || pageSize > 100) {
    throw new IllegalArgumentException("分页参数不合法");
}
if (keyword == null || keyword.isBlank() || keyword.length() > 200) {
    throw new IllegalArgumentException("搜索词不合法");
}

SearchResponse<Map> response = client.search(s -> s
        .index("forum-posts-v1")
        .from(page * pageSize)
        .size(pageSize)
        .query(q -> q.bool(b -> b
                .must(m -> m.multiMatch(mm -> mm
                        .query(keyword)
                        .fields("title^3", "body")
                        .operator(Operator.And)))
                .filter(f -> f.term(t -> t
                        .field("status")
                        .value("PUBLISHED")))))
        .sort(sort -> sort.field(f -> f
                .field("createdAt")
                .order(SortOrder.Desc))),
        Map.class);

response.hits().hits().forEach(hit -> {
    Map source = hit.source();
    if (source != null) {
        System.out.println(source.get("postId") + ": " + source.get("title"));
    }
});

title^3 表示标题字段的权重高于正文，影响相关性排序，不是结果数量限制，也不保证标题匹配一定排在所有正文匹配之前。Operator.And 表示查询词分析后的各个词项都需要匹配，通常会比默认的 OR 更严格；具体效果受分析器影响。论坛可以根据产品需求选择 AND、OR，或分别设计标题与正文的查询策略。

示例限制搜索词长度和每页条数，是应用层的输入校验，不是 ES 参数本身的最大值。限制用于控制接口行为和资源消耗；应结合产品需求设置合理上限，并同时考虑请求超时、并发和集群负载。分页偏移量很大时，from/size 会要求 ES 在分片侧保留并处理越来越多的命中结果，深分页不适合无限使用。对于持续翻页场景，可评估 search_after 与 PIT（Point in Time），并使用稳定的排序条件。

搜索词是通过查询构造器传入的值，不要把用户输入拼接成原始查询字符串。尤其不要把未校验的输入直接拼入 query_string 表达式：其中的运算符和保留字符会带来与普通关键词搜索不同的语义，也可能造成意料外的复杂查询。若产品确实需要高级查询语法，应明确语法、限制复杂度并单独设计接口。

六、权限过滤不是搜索功能的附属品

论坛常见的访问规则包括：未发布帖子不可见、版块需要登录、部分版块仅特定用户组可见、作者可看自己的草稿。查询中加一个 status = PUBLISHED，只能覆盖其中一种规则。授权条件要由服务端根据当前用户身份计算，不能接受客户端随意传入的作者 ID 或权限范围。

可以将可公开访问的条件放入 ES 查询过滤器，以减少无效结果；但如果权限规则复杂或变化频繁，仍应在返回前按权威数据源复核结果。另一种做法是先从数据库计算允许访问的版块集合，再将集合用于 ES 过滤。无论采用哪种策略，都要处理“搜索时可见、点击时已撤权”的竞态：帖子详情接口必须再次做权限校验。

特别注意：只在应用界面隐藏搜索结果并不构成访问控制。搜索 API 返回的标题、摘要、高亮片段本身也可能泄露内容。权限判断应覆盖 ES 搜索接口、详情接口、缓存和导出接口。对于软删除或封禁数据，还要避免旧索引文档在同步延迟期间被展示；高敏感场景可以对返回结果进行数据库复核，宁可少返回，也不要越权返回。

七、高亮展示与 HTML 安全

ES 可以返回命中片段，但高亮片段不是可信 HTML。论坛正文往往包含用户输入，渲染时必须防止跨站脚本攻击。配置 pre_tags、post_tags 只能标记命中位置，不能自动让原文安全。不要把高亮结果未经处理地拼进页面并用“原样 HTML”方式渲染。

一种稳妥做法是将高亮片段作为文本处理，在服务端或前端按明确规则转义文本节点，再仅对服务端生成的标记进行受控渲染。若论坛正文支持 Markdown 或 HTML，也应经过成熟的清洗器处理允许标签和属性；搜索高亮不能替代内容净化。

以下为查询中增加高亮配置的示意代码，具体返回内容应按所用客户端版本检查 API 类型。注意这里的标签只是标记符，不是安全过滤器。

SearchResponse<Map> highlighted = client.search(s -> s
        .index("forum-posts-v1")
        .size(20)
        .query(q -> q.multiMatch(mm -> mm
                .query(keyword)
                .fields("title", "body")))
        .highlight(h -> h
                .preTags("<em>")
                .postTags("</em>")
                .fields("title", f -> f)
                .fields("body", f -> f
                        .fragmentSize(160)
                        .numberOfFragments(2))),
        Map.class);

要向用户展示高亮结果时，还应处理无高亮片段的情况：查询命中并不保证每个字段都产生可展示片段。大正文通常只返回片段，不应为了搜索结果页把整篇帖子正文全部传输。

八、分页、排序与结果稳定性

按时间排序要考虑相同时间值的情况。若用户持续翻页，排序字段最好有确定的次级排序键，例如帖子 ID，避免同一时间戳下的结果顺序不稳定。深分页使用 search_after 时，必须按上一页最后一个命中的排序值继续查询；如果索引在分页期间持续变化，还需评估 PIT，确保视图更稳定。PIT 有生命周期和资源开销，应按需设置并及时关闭。

ES 的总命中数可能默认采用阈值式精确度策略。若页面必须显示精确总数，需要显式评估请求精确计数带来的成本；多数论坛搜索页只展示“约有很多结果”或仅提供下一页按钮，没有必要每次都对大结果集做精确计数。

九、常见错误清单

• 把 ES 当数据库。 ES 索引是可重建的搜索副本，重要业务状态仍以数据库为准。
• 认为写 ES 与写数据库天然一致。 两者没有自动的本地原子事务；需要 Outbox、重试、幂等和数据校验等方案。
• mapping 设计过于随意。 字段类型确定后更改成本可能较高；上线前用代表性数据验证索引与查询效果。
• 忽略中文分析效果。 内置分析器未必符合中文搜索预期。应使用实际帖子测试切词、同义词、标点和混合中英文，再决定是否部署插件或调整方案。
• 把用户输入拼成查询 DSL。 优先使用类型化查询构造器，并对搜索词、页码、过滤条件做业务校验。
• 只在前端做权限控制。 搜索接口和详情接口都必须服务端授权，高亮内容也属于需要保护的数据。
• 接受无限分页和超长查询。 应设置产品级上限、请求超时和并发控制；限制值需按业务与集群容量确定，不存在适用于所有系统的固定数字。
• 认为高亮标记可以防 XSS。 高亮只是搜索展示功能，用户内容仍须按 HTML 安全规则编码或清洗。
• 重建索引时直接清空线上索引。 先写新索引、验证数据和查询，再通过别名切换，并保留回滚能力。

十、上线前的检查步骤

1. 准备一批覆盖中文、英文、标点、长正文和特殊内容的测试帖子，验证分析器与排序是否符合预期。
2. 确认发帖、编辑、删除、软删除、撤权和恢复等路径都会产生对应同步事件，并测试失败重试。
3. 确认搜索接口使用服务端生成的权限过滤条件，帖子详情仍会重新授权。
4. 限制搜索词长度、页大小和请求频率；对超时、ES 不可用和部分结果制定明确的降级策略。
5. 监控索引写入失败、消费延迟、搜索耗时、拒绝请求和磁盘使用，并准备数据重建流程。
6. 核对 ES 账号权限、网络访问范围、TLS 和密钥管理，避免把集群暴露给不可信网络。

为论坛加入 ES，真正的工作不只是写一条 multi_match 查询。索引设计决定搜索质量，数据同步决定结果是否可信，权限校验决定是否安全，而分页、超时和运维策略决定系统能否稳定运行。先从明确的帖子文档和少量搜索场景开始，再根据真实查询数据调整分析器、排序和同步机制，通常比一次性设计复杂的“万能搜索”更容易落地。