NestJS Elasticsearch 整合指南
將 Elasticsearch 支援的搜尋功能加入 NestJS GraphQL + MongoDB 應用程式的整合指南。它明確定義架構邊界（通用基礎設施、共用搜尋層、每個功能擁有自己的索引），然後涵蓋完整的生命週期：搜尋投影、索引與同步、僅 ID 查詢搭配 MongoDB 還原、游標分頁、跨實體衍生欄位、透過可設定後端接縫讓搜尋成為選項、無需即時叢集的測試，以及相關的操作與開發體驗。
主要的合約是 Elasticsearch 負責查找，MongoDB 負責提供資料：Elasticsearch 是純粹的搜尋索引，僅回傳識別碼，而要求的實體永遠從 MongoDB (資料來源) 還原。
適用時機
當下列情況時參考這些準則：
- 為現有的 NestJS GraphQL + MongoDB 應用程式加入搜尋功能
- 配線
@nestjs/elasticsearch客戶端與共用搜尋層 - 定義或更改索引映射或搜尋投影
- 實作 MongoDB 到 Elasticsearch 的同步、重建索引或索引遷移
- 編寫搜尋查詢、游標分頁或結果還原
- 讓衍伸值（計數、評分）可在不同實體間搜尋
- 從設定中讓搜尋成為選項，或無需叢集即可切換後端
- 使用模擬後端接縫或真實的短暫測試叢集進行測試
- 偵錯過時的搜尋結果或索引風暴
依優先順序分類的規則
| 優先級 | 類別 | 影響 | 前綴 |
|---|---|---|---|
| 1 | 架構 | 關鍵 | arch- |
| 2 | 索引與同步 | 關鍵 | sync- |
| 3 | 綱要與映射 | 高 | map- |
| 4 | 查詢 | 高 | query- |
| 5 | 跨實體 | 中高 | rel- |
| 6 | 操作與開發體驗 | 中 | 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. 操作與開發體驗 (中)
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。