EasyCore.Elasticsearch 8.3.0

🔎 EasyCore.Elasticsearch

EasyCore.Elasticsearch 是面向 .NET 8 的通用 Elasticsearch 集成库。基于官方 Elastic.Clients.Elasticsearch，一键完成客户端 DI、索引管理、文档仓储与健康检查。

<p align="center"> <img src="https://raw.githubusercontent.com/RockyWang0521/EasyCore.Elasticsearch/master/png/EasyCoreLogo.png" alt="EasyCore Logo" width="120" /> </p>

🌍 Language

• 中文（当前文档）
• English: README.en.md

源码：github.com/RockyWang0521/EasyCore.Elasticsearch

📚 目录

第一部分：总览

• 1. 项目定位
• 2. 仓库结构

第二部分：快速上手

• 3. 安装
• 4. 三分钟快速开始
• 5. 配置项

第三部分：能力与 Demo

• 6. 核心能力
• 7. Demo
• 8. FAQ
• 9. License

1. 🎯 项目定位

EasyCore.Elasticsearch 解决「在 ASP.NET Core 里一键接好 Elasticsearch，而不是手写一长串客户端与仓储样板代码」的问题：

1.1 设计原则

2. 📁 仓库结构

EasyCore.Elasticsearch/
├── src/EasyCore.Elasticsearch/
│   ├── Client/                 # 客户端工厂与响应映射
│   ├── DependencyInjection/    # AddEasyCoreElasticsearch 扩展
│   ├── Health/                 # 健康检查
│   ├── Indexing/               # 索引 / 模板 / 别名
│   ├── Models/                 # 搜索请求与结果模型
│   ├── Options/                # Options + Validator
│   └── Repository/             # 通用文档仓储
├── demo/
│   ├── docker-compose.yml      # 单节点 ES（easycore-es-demo）
│   └── Web.EasyCore.Elasticsearch/
├── tests/EasyCore.Elasticsearch.Tests/
├── png/EasyCoreLogo.png
├── README.md
└── README.en.md

3. 📦 安装

dotnet add package EasyCore.Elasticsearch

需要 .NET 8。底层依赖 Elastic.Clients.Elasticsearch 8.17.3（面向 Elasticsearch 8.x）。

本地可用 Docker Compose 拉起单节点 Elasticsearch（见 Demo）。

4. ⚡ 三分钟快速开始

4.1 代码注册

using EasyCore.Elasticsearch;

builder.Services.AddEasyCoreElasticsearch(options =>
{
    options.Nodes = ["http://localhost:9200"];
    options.DefaultIndex = "demo-products";
    options.RequestTimeout = TimeSpan.FromSeconds(30);
    options.MaxRetryCount = 3;
    // 可选 Basic Auth（ApiKey 优先）：
    // options.Username = "elastic";
    // options.Password = "***";
    // options.ApiKey = "***";
});

builder.Services.AddHealthChecks()
    .AddEasyCoreElasticsearch();

注意：DI 扩展方法名为 AddEasyCoreElasticsearch，不是 AddEasyCoreElasticsearch。

4.2 配置节示例

{
  "Elasticsearch": {
    "Nodes": [ "http://localhost:9200" ],
    "DefaultIndex": "demo-products",
    "RequestTimeoutSeconds": 30,
    "MaxRetryCount": 3,
    "EnableCertificateValidation": true
  }
}

var section = builder.Configuration.GetSection("Elasticsearch");
builder.Services.AddEasyCoreElasticsearch(options =>
{
    options.Nodes = section.GetSection("Nodes").Get<string[]>()?.ToList()
        ?? ["http://localhost:9200"];
    options.DefaultIndex = section["DefaultIndex"] ?? "demo-products";
    options.Username = section["Username"];
    options.Password = section["Password"];
    options.ApiKey = section["ApiKey"];
});

4.3 注入使用

public sealed class ProductService
{
    private readonly IElasticsearchRepository<ProductDocument> _repository;
    private readonly IElasticsearchIndexManager _indexes;

    public ProductService(
        IElasticsearchRepository<ProductDocument> repository,
        IElasticsearchIndexManager indexes)
    {
        _repository = repository;
        _indexes = indexes;
    }

    public async Task IndexAsync(ProductDocument doc, CancellationToken ct)
    {
        if (!await _indexes.IndexExistsAsync("demo-products", ct))
        {
            await _indexes.CreateIndexAsync("demo-products", cancellationToken: ct);
        }

        await _repository.IndexAsync(doc, "demo-products", doc.Id, ct);
    }

    public Task<ElasticsearchSearchResult<ProductDocument>> SearchAsync(
        string? q, string? category, int pageIndex = 0, int pageSize = 20, CancellationToken ct = default)
    {
        var request = new ElasticsearchSearchRequest
        {
            Query = q,
            PageIndex = pageIndex < 0 ? 0 : pageIndex,
            PageSize = pageSize <= 0 ? 20 : pageSize,
            SortField = "createdAt",
            SortDescending = true,
            // text 字段的 Term 过滤请使用 .keyword 子字段
            Filters = string.IsNullOrWhiteSpace(category)
                ? null
                : new Dictionary<string, object?> { ["category.keyword"] = category }
        };

        return _repository.SearchAsync(request, "demo-products", ct);
    }
}

5. ⚙️ 配置项

配置节名：Elasticsearch（ElasticsearchOptions.SectionName）。

6. 🧩 核心能力

6.1 客户端与 DI

• AddEasyCoreElasticsearch(Action<ElasticsearchOptions>)：注册 ElasticsearchClient、IElasticsearchIndexManager、IElasticsearchRepository<>，并启用 Options 校验
• 多次调用安全：后续调用仅更新 Options，不会重复注册核心服务

6.2 索引管理（IElasticsearchIndexManager）

6.3 文档仓储（IElasticsearchRepository<T>）

6.4 搜索约定

6.5 健康检查

builder.Services.AddHealthChecks()
    .AddEasyCoreElasticsearch(); // 默认 name = "elasticsearch"

app.MapHealthChecks("/health");

6.6 与审计的关系

本包不包含审计写入、审计查询或审计中间件。若需要操作审计，请使用独立包 EasyCore.Audit。

7. 🧪 Demo

7.1 🐳 启动 Elasticsearch

docker compose -f demo/docker-compose.yml up -d

停止 / 再开：docker compose -f demo/docker-compose.yml down / up -d。

7.2 🚀 运行 Demo

dotnet run --project demo/Web.EasyCore.Elasticsearch

顺序：先起 easycore-es-demo（9200 通）→ 再跑 Demo → 再调 API。

7.3 示例请求

# 创建索引
curl -X POST http://localhost:5089/api/indexes/demo-products

# 写入
curl -X POST http://localhost:5089/api/products -H "Content-Type: application/json" -d "{\"name\":\"Keyboard\",\"category\":\"peripherals\",\"price\":99.5}"

# 搜索（category Term 过滤）
curl "http://localhost:5089/api/products?category=peripherals&pageIndex=0&pageSize=20"

8. ❓ FAQ

Q: 扩展方法叫什么？
A: AddEasyCoreElasticsearch。不要写成 AddEasyCoreElasticsearch。

Q: 按 category 过滤为什么查不到？
A: 动态映射下 category 多为 text。Term 过滤请使用 category.keyword。

Q: pageIndex / pageSize 默认是多少？
A: PageIndex 从 0 开始；PageSize 默认 20。Demo API 在 pageSize <= 0 时回退为 20。

Q: 本包是否自带审计？
A: 不包含。审计请使用 EasyCore.Audit。

Q: 健康检查怎么挂？
A: builder.Services.AddHealthChecks().AddEasyCoreElasticsearch();，再 MapHealthChecks("/health")。

Q: 需要 Elasticsearch 几？
A: 面向 8.x；客户端包版本为 Elastic.Clients.Elasticsearch 8.17.3。

9. 📄 License

MIT

🤝 贡献

1. Fork 并创建特性分支
2. 在 tests/EasyCore.Elasticsearch.Tests 补充测试
3. 执行 dotnet test 与 dotnet build
4. 提交 Pull Request

欢迎 Issue / PR 🚀