NestJS Elasticsearch
为 NestJS GraphQL + MongoDB 应用添加 Elasticsearch 支持的集成指南。它首先确立了架构边界（通用基础设施、共享搜索层、每个特性模块拥有自己的索引），然后覆盖了完整生命周期：搜索投影、索引与同步、基于 ID 查询与 MongoDB 数据填充、游标分页、跨实体派生字段、通过可配置后端抽象使搜索可选、无需实际集群即可测试，以及相关的运维和开发者体验。
指导原则是 Elasticsearch 负责查找，MongoDB 负责提供数据：Elasticsearch 仅作为纯搜索索引返回标识符，请求的实体始终从作为唯一数据源的 MongoDB 中填充。
何时应用
在以下情况参考这些指南：
- 为已有的 NestJS GraphQL + MongoDB 应用添加搜索功能
- 连接
@nestjs/elasticsearch客户端和共享搜索层 - 定义或更改索引映射或搜索投影
- 实现 MongoDB 到 Elasticsearch 的同步、重建索引或索引迁移
- 编写搜索查询、游标分页或结果数据填充
- 使派生值（计数、评分）跨实体可搜索
- 通过配置使搜索可选，或在没有集群的情况下切换后端
- 使用模拟后端抽象或针对真实临时集群测试搜索
- 调试过时的搜索结果或索引风暴
按优先级分类的规则类别
| 优先级 | 类别 | 影响程度 | 前缀 |
|---|---|---|---|
| 1 | 架构 | 关键 | arch- |
| 2 | 索引与同步 | 关键 | sync- |
| 3 | 模式与映射 | 高 | map- |
| 4 | 查询 | 高 | query- |
| 5 | 跨实体 | 中高 | rel- |
| 6 | 运维与 DX | 中 | ops- |
| 7 | 配置与环境 | 高 | cfg- |
| 8 | 测试 | 中高 | test- |
快速参考
1. 架构（关键）
arch-base-search-repository- 将共享索引和查询逻辑放入基础仓库arch-entity-vs-search-document- 将 Elasticsearch 字段排除在实体之外arch-feature-owned-index- 让每个特性模块拥有并注册自己的索引arch-infra-module- 将 Elasticsearch 客户端隔离在通用基础设施模块中
2. 索引与同步（关键）
sync-bulk-index- 使用批量 API 批量索引sync-debounce-same-id- 对相同 ID 的爆发进行防抖处理sync-delete-immediately- 立即从索引中删除sync-enqueue-index- 将索引操作排队；绝不内联写入 Elasticsearchsync-full-reindex-alias-swap- 通过版本化索引重建索引并交换别名sync-idempotent-index-creation- 使用确定性名称幂等地创建索引
3. 模式与映射（高）
map-analyzers- 有意识地选择文本分析器map-derived-fields- 在批量映射器中计算派生字段和关联字段map-exclude-non-search-fields- 只索引有搜索目的的字段map-mapping-object- 将映射声明为类型化对象map-typed-search-document- 根据实体类型化搜索文档
4. 查询（高）
query-cursor-pagination- 使用search_after实现游标分页query-hydrate-restore-order- 从 MongoDB 填充数据并恢复相关性顺序query-ids-only-search- 搜索仅返回 IDquery-sort-tiebreaker- 始终包含唯一的排序决胜字段
5. 跨实体（中高）
rel-derived-counter-cache- 在所属文档上缓存派生计数器rel-owning-module-subscribes- 所属模块订阅事件；其他模块发出自己的事件
6. 运维与 DX（中）
ops-cli-scripts- 提供迁移和重建索引的 CLI 命令ops-explain-debug- 提供解释钩子ops-health-check- 将 Elasticsearch 纳入健康检查ops-log-es-requests- 记录 Elasticsearch 请求和响应ops-no-cron-for-indexing- 绝不使用进程内定时器调度索引
7. 配置与环境（高）
cfg-mongo-fallback-backend- 回退到确定性的 MongoDB 查找器cfg-search-backend-seam- 将搜索置于后端抽象之后
8. 测试（中高）
test-mock-elasticsearch-seam- 在单元测试中模拟搜索后端抽象test-real-es-for-query-semantics- 针对真实 Elasticsearch 测试查询语义
如何使用
阅读各个规则文件以获取详细说明和代码示例：
rules/arch-entity-vs-search-document.md
rules/sync-full-reindex-alias-swap.md
rules/query-ids-only-search.md
每个规则文件包含：
- 为什么重要以及适用于哪个层的简要说明
- 带有解释的错误代码示例
- 带有解释的正确代码示例
- 附加上下文和参考
与其他技能的关系
nestjs-graphql-structure— 文件放置。此技能为特性模块添加了search/文件夹，以及common/search/+infra/elasticsearch/层；它遵循该技能的特性模块、仓库和事件规则。nestjs-best-practices— 关于服务、事件、队列、配置和健康检查的行为规则，此技能中的示例基于这些规则。- 一个故意的例外 —
nestjs-graphql-structure的service-background-jobs规则将处理器保留在所属特性模块中。而搜索管道在common/search/中运行一次，并通过索引注册表解析每个特性模块的仓库，因为管道对每个特性模块都是相同的；请参见arch-base-search-repository。
完整编译文档
查看包含所有规则展开的完整指南，请参见 AGENTS.md。