搜索模块 search.md 25 KB

搜索模块 search

本文引用的文件

  • SearchDoc.java
  • SearchDocRepository.java
  • SearchQueryService.java
  • SearchIndexInitializer.java
  • SearchDocIndexService.java
  • SearchController.java
  • SearchDTO.java
  • SearchQuery.java
  • search-settings.json
  • SearchDocIndexServiceTest.java

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与容量特性
  8. 使用示例
  9. 故障排查
  10. 结论

简介

搜索模块 search 是后端全文检索能力,提供文档索引、增量写入、查询服务和启动初始化器。它通过 Elasticsearch 对清洗后的案件数据、Agent 附件内容、知识库片段等文本进行加速检索,替代了早期基于嵌入式 Lucene 的实现。

该模块的核心职责包括:

  • 维护一个名为 zsjz_search 的 Elasticsearch 索引。
  • 将业务记录组装为统一文档模型,按“案件隔离”策略写入。
  • 支持关键词模糊匹配、结果高亮和按时间降序排序。
  • 在 ES 不可用时熔断降级,确保不阻塞主清洗链路。
  • 提供 REST 接口 /search/list,返回前端可直接渲染的高亮内容。

需要明确的是:当前搜索模块仅使用传统全文索引(text + wildcard),没有集成向量检索。 向量检索由知识文档和清洗模板等其他模块单独处理,不应与本模块混为一谈。

章节来源

  • SearchDoc.java:1-96
  • SearchQueryService.java:1-108
  • SearchDocIndexService.java:1-242

项目结构

搜索模块位于 ai-server 的 Java 包下,采用领域对象、仓库、服务、控制器分层组织:

graph TB
    subgraph "搜索模块"
        domain["领域模型<br/>SearchDoc"]
        repo["仓库接口<br/>SearchDocRepository"]
        initializer["启动初始化器<br/>SearchIndexInitializer"]
        indexService["写入服务<br/>SearchDocIndexService"]
        queryService["查询服务<br/>SearchQueryService"]
        controller["对外控制器<br/>SearchController"]
        dto["查询结果 DTO<br/>SearchDTO"]
        settings["ES 分词配置<br/>search-settings.json"]
    end

    controller --> queryService
    queryService --> repo
    queryService --> settings
    indexService --> repo
    indexService --> settings
    initializer --> indexService
    domain --> repo

图表来源

  • SearchDoc.java:1-96
  • SearchDocRepository.java:1-10
  • SearchQueryService.java:1-108
  • SearchIndexInitializer.java:1-30
  • SearchDocIndexService.java:1-242
  • SearchController.java:1-26
  • search-settings.json:1-21

章节来源

  • SearchController.java:1-26
  • SearchQueryService.java:1-108
  • SearchDocIndexService.java:1-242
  • SearchIndexInitializer.java:1-30

核心组件

组件 职责 关键行为
SearchDoc 全文检索文档领域模型 定义 zsjz_search 索引字段、分词字段、业务标识、时间戳、文件名、工作表名等
SearchDocRepository Spring Data Elasticsearch 仓库 暴露批量保存方法,内部走 ES _bulk
SearchDocIndexService 索引写入与容错 按案件攒批、批量提交、刷新、按文件/案件删除、ES 熔断
SearchQueryService 查询与高亮 关键词 wildcard 匹配、caseId 过滤、高亮片段拼接、时间倒序、最多 500 条
SearchIndexInitializer 应用启动时创建索引 幂等创建,ES 不可用只记日志
SearchController REST 入口 GET /search/list,接收关键词并返回搜索结果
SearchDTO 查询结果传输对象 包含行 id、文件信息、表名、时间、高亮内容
search-settings.json ES 分词器配置 使用 pattern 分词器按 \x1F 切分,再转小写

章节来源

  • SearchDoc.java:1-96
  • SearchDocRepository.java:1-10
  • SearchQueryService.java:1-108
  • SearchIndexInitializer.java:1-30
  • SearchDocIndexService.java:1-242
  • SearchController.java:1-26
  • SearchDTO.java:1-21
  • search-settings.json:1-21

架构总览

搜索模块以 Spring Boot 服务形式运行,对外暴露 HTTP 接口,对内通过 Spring Data Elasticsearch 访问 Elasticsearch。

sequenceDiagram
    participant FE as "前端或调用方"
    participant Controller as "SearchController"
    participant Query as "SearchQueryService"
    participant Repo as "SearchDocRepository"
    participant ES as "Elasticsearch"

    FE->>Controller: "GET /search/list?keyword=xxx"
    Controller->>Query: "search(keyword)"
    Query->>Query: "解析案件上下文 caseId"
    Query->>Repo: "NativeQuery wildcard 匹配 content"
    Repo->>ES: "执行搜索"
    ES-->>Repo: "返回命中文档"
    Repo-->>Query: "SearchHit"
    Query->>Query: "高亮 content 片段"
    Query-->>Controller: "List<SearchDTO>"
    Controller-->>FE: "Result<List<SearchDTO>>"

图表来源

  • SearchController.java:1-26
  • SearchQueryService.java:1-108
  • SearchDocRepository.java:1-10

详细组件分析

文档模型 SearchDoc

SearchDoc 是全文检索文档的唯一实体。它直接映射到 Elasticsearch 中的 zsjz_search 索引。

关键字段含义如下: | 字段 | 类型 | 用途 | |---|---|---| | docId | keyword | ES 文档 _id,格式为 caseId|tableName|rowId,保证同表同记录幂等覆盖 | | caseId | keyword | 案件隔离字段,所有写入和删除必须带此条件 | | rowId | keyword | 原始业务行主键,不能命名为 id,否则与 Spring Data 的 @Id 冲突 | | sheetId | keyword | 工作表标识 | | fileId | keyword | 上传文件标识 | | tableName | keyword | 源数据表名 | | fileName | keyword | 源文件名 | | sheetName | keyword | 工作表名称 | | dateTime | date | 业务时间,用于排序和展示 | | content | text | 全字段拼接文本,使用自定义分词器 unit_separator |

content 字段的设计非常关键:它不是普通自然语言文本,而是把多个实体的字符串表示用分隔符 \x1F 拼接后存储。ES 分词器会按该分隔符切分,再做小写处理。查询时对 token 做 wildcard 子串匹配,因此语义上更接近“按片段模糊匹配”,而不是完整的中文语义检索。

classDiagram
    class SearchDoc {
        +string docId
        +string caseId
        +string rowId
        +string sheetId
        +string fileId
        +string tableName
        +string fileName
        +string sheetName
        +LocalDateTime dateTime
        +string content
    }

图表来源

  • SearchDoc.java:1-96

章节来源

  • SearchDoc.java:1-96

写入服务 SearchDocIndexService

写入服务负责索引构建、批量提交、刷新、删除和容错。它是整个搜索模块中最复杂、也最重要的组件。

写入流程

flowchart TD
    Start(["add(doc)"]) --> RequireCase["校验案件上下文"]
    RequireCase --> SetFields["设置 caseId 和 docId"]
    SetFields --> BreakerCheck{"是否处于熔断期"}
    BreakerCheck -->|是| Drop["丢弃并累计计数"]
    BreakerCheck -->|否| Buffer["按 caseId 攒批"]
    Buffer --> BatchFull{"是否达到批次大小"}
    BatchFull -->|是| SaveBatch["saveAll 批量提交"]
    BatchFull -->|否| EndAdd(["返回"])
    SaveBatch --> Success{"是否成功"}
    Success -->|是| RecordSuccess["重置失败计数"]
    Success -->|否| RecordFailure["记录失败并可能熔断"]
    RecordSuccess --> EndAdd
    RecordFailure --> EndAdd

图表来源

  • SearchDocIndexService.java:1-242

关键设计点:

  • 批次大小:默认 1000 条。
  • 按案件缓冲:不同案件互不影响,避免跨案件污染。
  • 幂等文档 id:docId = caseId|tableName|rowId,重复清洗不会产生重复文档。
  • 刷新策略:flush() 会提交尾批并对索引执行 refresh,使新数据立即可被搜索。
  • 删除能力:支持按文件列表删除、按案件删除。
  • 熔断机制:连续 3 批失败后进入约 60 秒熔断期;期间 add() 直接跳过,不再承受 ES 超时。
  • 旁路容错:ES 异常不会上抛给清洗主链路,只会记录日志并累计丢弃数量。

    flowchart TD
    FStart(["ES 写入失败"]) --> IncFail["连续失败批数加一"]
    IncFail --> CheckThreshold{"是否达到阈值"}
    CheckThreshold -->|否| LogWarn["记录失败日志"]
    CheckThreshold -->|是| OpenBreaker["打开熔断截止时间"]
    LogWarn --> FEnd(["返回"])
    OpenBreaker --> FEnd
    

图表来源

  • SearchDocIndexService.java:201-242

初始化与索引创建

SearchIndexInitializer 实现 ApplicationRunner,在应用启动时调用 ensureIndex()。如果 ES 不可用,只记录错误日志,不阻断应用启动;首次写入时会再次尝试创建索引。

章节来源

  • SearchDocIndexService.java:1-242
  • SearchIndexInitializer.java:1-30

查询服务 SearchQueryService

查询服务提供关键词搜索、高亮和排序能力。

核心规则:

  • 空关键词直接返回空列表。
  • 必须存在案件上下文 caseId,否则跳过检索。
  • 关键词统一转为小写,并用 wildcard 模式 *keyword* 匹配 content 字段。
  • 查询强制加上 caseId filter,防止跨案件泄漏。
  • 按 dateTime 降序排序。
  • 最多返回 500 条。
  • 对 content 字段进行高亮,使用 <em class="search-highlight"> 标签包裹。
  • 高亮片段超过限制时用 ... 拼接。

    sequenceDiagram
    participant Svc as "SearchQueryService"
    participant Ctx as "CaseContextHolder"
    participant Ops as "ElasticsearchOperations"
    
    Svc->>Svc: "检查 keyword 是否为空"
    Svc->>Ctx: "获取 caseId"
    Svc->>Svc: "构造 wildcard 查询"
    Svc->>Ops: "执行 NativeQuery"
    Ops-->>Svc: "SearchHit 列表"
    Svc->>Svc: "高亮 content 片段"
    Svc-->>Svc: "转换为 SearchDTO"
    

图表来源

  • SearchQueryService.java:1-108

章节来源

  • SearchQueryService.java:1-108

REST 接口 SearchController

控制器暴露单一接口:

方法 路径 参数 返回值
GET /search/list keyword Result<List<SearchDTO>>

该接口没有分页参数,也没有独立的权重字段控制。分页和更多筛选应放在调用方或上层业务中处理。

章节来源

  • SearchController.java:1-26
  • SearchDTO.java:1-21

分词策略 search-settings.json

ES 索引配置定义了一个自定义分词器:

  • 分词器类型:pattern。
  • 分隔符:\x1F。
  • 过滤器:lowercase。
  • 分片数:1。
  • 副本数:0。

这意味着 content 字段不是按中文词语分词,而是按业务约定的分隔符拆成片段,然后统一小写。搜索时也是对这些片段做通配匹配。

flowchart TD
    Input["原始 content<br/>多字段用 \\x1F 拼接"] --> Tokenizer["pattern 分词器<br/>按 \\x1F 切分"]
    Tokenizer --> Lower["lowercase 过滤器"]
    Lower --> Tokens["token 列表"]
    Tokens --> Wildcard["wildcard *keyword* 匹配"]

图表来源

  • search-settings.json:1-21
  • SearchDoc.java:1-96

章节来源

  • search-settings.json:1-21

依赖关系分析

搜索模块依赖以下外部或跨模块能力:

  • Elasticsearch:通过 Spring Data Elasticsearch 访问。
  • CaseContextHolder:用于注入和校验当前案件上下文。
  • Spring Boot:提供 ApplicationRunner、REST 控制器、依赖注入。
  • Spring Data Elasticsearch:提供 Repository、NativeQuery、Highlight、IndexOperations。
  • Lombok:简化类定义。

注意:搜索模块本身不依赖向量检索相关代码。项目中还存在其他模块(如知识文档、清洗模板)使用 pgvector 或向量索引,但它们与 search 模块是独立实现的。

graph LR
    SearchModule["搜索模块 search"] --> ES["Elasticsearch"]
    SearchModule --> SpringDataES["Spring Data Elasticsearch"]
    SearchModule --> CaseContext["CaseContextHolder"]
    SearchModule --> SpringBoot["Spring Boot"]
    OtherVector["其他模块向量检索<br/>pgvector/向量索引"] -. 不共用 .-> SearchModule

图表来源

  • SearchDocRepository.java:1-10
  • SearchQueryService.java:1-108
  • SearchDocIndexService.java:1-242

章节来源

  • SearchDocRepository.java:1-10
  • SearchQueryService.java:1-108
  • SearchDocIndexService.java:1-242

性能与容量特性

维度 当前实现 说明
索引结构 单索引 zsjz_search 所有案件共享同一索引,靠 caseId 隔离
分词方式 pattern 按 \x1F 切分 + lowercase 不是标准中文分词器,也不是向量语义检索
查询方式 wildcard 模糊匹配 适合片段查找,不适合复杂布尔语法
排序 按 dateTime 降序 未提供多字段排序
分页 硬编码最大 500 条 不支持页码、每页大小
写入批量 1000 条/批 按案件缓冲,满批触发 _bulk
刷新 flush 时 refresh 增量清洗完成后使数据可搜
容错 连续 3 批失败熔断约 60 秒 清洗主链路不受影响
并发安全 ConcurrentHashMap + buffer synchronized 多虚拟线程写同一案件时同步缓存

优化建议:

  • 如果未来需要更细粒度的分页,应在查询服务增加分页参数,并在控制器中透传。
  • 如果需要更强的中文分词能力,应评估引入 IK 等中文分词器,但要注意现有 content 约定是 \x1F 分隔的业务片段。
  • 如果数据量增长明显,应考虑分片策略、冷热数据和索引生命周期管理。
  • 如果高亮性能成为瓶颈,可减少高亮片段长度或在前端做轻量级高亮。
  • 如果需要按用户维度过滤,当前 API 没有用户字段;可在 SearchDoc 扩展字段并在查询中增加 filter,但需注意这会改变现有契约。

章节来源

  • SearchQueryService.java:1-108
  • SearchDocIndexService.java:1-242
  • search-settings.json:1-21

使用示例

关键词搜索

调用方发送请求:

  • 方法:GET
  • 路径:/search/list
  • 参数:keyword

后端行为:

  1. 从 CaseContextHolder 读取案件 ID。
  2. 将关键词转为小写并包裹 wildcard。
  3. 对 content 字段执行 wildcard 查询。
  4. 强制加上 caseId 过滤。
  5. 按 dateTime 降序返回最多 500 条。
  6. 对 content 进行高亮,返回 SearchDTO。

注意事项:

  • 若没有案件上下文,返回空列表。
  • 若关键词为空,返回空列表。
  • 若 ES 查询异常,捕获异常并返回空列表。

章节来源

  • SearchController.java:1-26
  • SearchQueryService.java:1-108

按案件维度过滤

搜索已经内置案件隔离:

  • 写入时强制注入 caseId。
  • 查询时强制加上 caseId filter。
  • 删除时按 caseId 清理。

这意味着调用方无法绕过案件隔离进行搜索。这是重要的安全边界。

章节来源

  • SearchDocIndexService.java:1-242
  • SearchQueryService.java:1-108

按用户维度过滤

当前 SearchDoc 没有用户字段,SearchController 也没有用户过滤参数。若需要按用户维度过滤,推荐做法:

  1. 在 SearchDoc 新增用户标识字段。
  2. 在写入时填充用户字段。
  3. 在 SearchQueryService 增加用户过滤参数。
  4. 在控制器中接收用户参数并传入查询服务。
  5. 更新测试用例,确保用户隔离生效。

当前版本不建议在查询层直接通过 tableName、fileId 等方式模拟用户维度,因为这不是设计意图。

章节来源

  • SearchDoc.java:1-96
  • SearchController.java:1-26
  • SearchQueryService.java:1-108

搜索结果高亮

高亮逻辑:

  • 高亮字段:content。
  • 前缀标签:<em class="search-highlight">。
  • 后缀标签:</em>。
  • 片段大小:120。
  • 片段数量:1。
  • 如果没有高亮片段,返回原始 content。

前端可直接渲染 HTML 片段,无需自行高亮。

章节来源

  • SearchQueryService.java:1-108

增量索引更新

典型场景:

  1. 清洗任务按虚拟线程写入多条 SearchDoc。
  2. SearchDocIndexService.add() 按案件攒批。
  3. 达到 1000 条后触发 saveAll。
  4. 清洗完成回调 flush(),提交尾批并 refresh。
  5. 前端搜索可立即看到最新数据。

如果清洗过程中 ES 失败:

  • 前几批失败会被记录。
  • 连续 3 批失败后进入熔断。
  • 熔断期间 add() 丢弃文档但不抛异常。
  • 后续成功批次会重置熔断计数。

章节来源

  • SearchDocIndexService.java:1-242
  • SearchDocIndexServiceTest.java:1-112

故障排查

现象 可能原因 处理建议
搜索无结果 没有案件上下文 确认调用链绑定了 CaseContextHolder
搜索无结果 关键词为空 前端不要发送空关键词
搜索无结果 ES 尚未创建索引 检查启动日志和首次写入日志
写入很慢 ES 连接超时或慢查询 查看 ES 健康状态和集群负载
清洗链路变慢 ES 持续失败导致频繁重试 检查熔断日志,确认是否进入熔断期
数据不一致 flush 前 ES 失败 使用按案件重建索引补偿
搜索结果过多 wildcard 匹配过宽 缩小关键词或在上层增加过滤条件
高亮样式异常 前端未渲染 HTML 确认前端使用富文本渲染高亮字段

重要容错原则:

  • 搜索是旁路能力,不应让 ES 故障影响主业务流程。
  • 写入失败应记录日志并累计丢弃数量。
  • 删除操作也应尽力而为,失败只记日志。

章节来源

  • SearchQueryService.java:1-108
  • SearchDocIndexService.java:1-242
  • SearchDocIndexServiceTest.java:1-112

结论

搜索模块 search 是一个围绕 Elasticsearch 的传统全文检索子系统。它通过统一文档模型、案件隔离、批量写入、刷新和高亮能力,为案件数据、Agent 内容和清洗结果提供关键词检索。其核心优势在于:

  • 与主清洗链路解耦,具备明确的熔断降级策略。
  • 以 caseId 作为强制隔离条件。
  • 使用简单稳定的 wildcard 匹配和自定义分隔符分词。
  • 提供启动时索引初始化与运行时批量写入。

需要注意的限制:

  • 不支持分页。
  • 不支持复杂的全文检索语法。
  • 不使用向量检索。
  • 没有内置用户维度过滤。
  • 分词策略依赖业务约定的分隔符,不是通用中文语义检索。

在 Agent RAG 集成方面,应将本模块与向量检索模块区分开:本模块适合“快速定位业务片段”,向量检索适合“语义相似召回”。两者可以互补,但不应混用同一个索引或同一个查询语义。