EsQueryFacade 使用手册

游鹄君大约 5 分钟

EsQueryFacade 使用手册

概述

EsQueryFacade 是游鹄生态系统中 Elasticsearch 查询的封装门面，提供 Laravel 风格的链式查询语法，自动将常见查询条件转换为 ES DSL 语法。

特点：

✅ 链式调用，语法接近 Laravel Query Builder
✅ 自动转换 =、>、>=、<、<=、!=、like、in、between、null/notNull 等常用操作符
✅ 支持 orWhere、orWhereLike 逻辑查询
✅ 自动区分 keyword/text 字段，智能添加 .keyword 后缀
✅ 支持分页（返回 Laravel 标准 LengthAwarePaginator）和普通查询
✅ 支持排序和计数统计
✅ ES 连接自动初始化

核心方法

1. 指定索引

`index(string $index): self`

指定要查询的 ES 索引名称，同时重置所有查询条件。

参数：

$index - ES 索引名

示例：

use App\Facades\Common\V1\Es\EsQueryFacade;

EsQueryFacade::index('user_index');

2. 条件查询 where

`where(string $field, ...$params): self`

支持多种比较操作符的通用查询方法。

用法：

语法	含义	ES 映射
`where('field', $value)`	等于 `=`	`term`
`where('field', '>', $value)`	大于	`range.gt`
`where('field', '>=', $value)`	大于等于	`range.gte`
`where('field', '<', $value)`	小于	`range.lt`
`where('field', '<=', $value)`	小于等于	`range.lte`
`where('field', '!=', $value)`	不等于	`bool.must_not.term`

示例：

$result = EsQueryFacade::index('user_index')
    ->where('status', 1)           // 等于
    ->where('age', '>=', 18)       // 大于等于
    ->where('level', '!=', 0)      // 不等于
    ->get();

3. 模糊查询

`whereLike(string $field, string $value): self`

模糊查询，对应 MySQL WHERE field LIKE '%xxx%'，自动处理 keyword/text 字段类型。

参数：

$field - 字段名（自动判断是否需要加 .keyword 后缀）
$value - 模糊匹配值

示例：

$result = EsQueryFacade::index('user_index')
    ->whereLike('nickname', '游鹄')
    ->get();

4. 范围查询 whereBetween

`whereBetween(string $field, array $range): self`

区间查询，对应 MySQL WHERE field BETWEEN a AND b。

参数：

$field - 字段名
$range - [起始值, 结束值]

示例：

$result = EsQueryFacade::index('order_index')
    ->whereBetween('create_time', ['2025-01-01', '2025-12-31'])
    ->get();

5. IN 查询 whereIn

`whereIn(string $field, array $values): self`

批量查询，对应 MySQL WHERE field IN (1,2,3)。

示例：

$result = EsQueryFacade::index('user_index')
    ->whereIn('role', [1, 2, 3])
    ->get();

6. NULL 查询

`whereNull(string $field): self`

查询字段为 NULL 的记录，ES 实现为 must_not exists。

示例：

$result = EsQueryFacade::index('user_index')
    ->whereNull('avatar')
    ->get();

`whereNotNull(string $field): self`

查询字段不为 NULL 的记录，ES 实现为 exists。

示例：

$result = EsQueryFacade::index('user_index')
    ->whereNotNull('email')
    ->get();

7. OR 查询

`orWhere(string $field, ...$params): self`

OR 条件查询，与其他条件形成 should（至少满足一个）。

用法：

语法	含义
`orWhere('field', $value)`	OR 等于
`orWhere('field', '>', $value)`	OR 大于
`orWhere('field', 'like', $value)`	OR 模糊

示例：

$result = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->orWhere('level', '>', 10)       // OR 条件
    ->get();

8. OR 模糊查询

`orWhereLike(string $field, string $value): self`

OR 模糊查询，与其他条件形成 should。

注意： 此方法未在 Facade 中声明，可在 Service 层直接使用实例调用。

示例：

$esQuery = new EsQueryFacadeService();
$result = $esQuery
    ->index('user_index')
    ->where('status', 1)
    ->orWhereLike('nickname', '游鹄')  // OR 模糊
    ->get();

9. 排序

`orderBy(string $field, string $direction = 'asc'): self`

设置排序规则。

示例：

$result = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->orderBy('create_time', 'desc')  // 按创建时间倒序
    ->orderBy('id', 'asc')            // 再按 ID 正序
    ->get();

10. 设置分页

`page(int $page, int $pageSize): self`

设置分页参数，需配合 paginate() 使用。

参数：

$page - 当前页（自动防负数和零值，最小为 1）
$pageSize - 每页条数（自动防负数和零值，最小为 1）

示例：

$result = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->orderBy('create_time', 'desc')
    ->page(1, 20)        // 第1页，每页20条
    ->paginate();

11. 获取数据

`get(): Collection`

获取查询结果，返回 Illuminate\Support\Collection（对象集合，自动附带 id 字段）。

如果设置了 page()，按分页获取
未设置分页时，默认获取 10000 条
空查询条件自动转换为 match_all

示例：

$users = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->orderBy('id', 'desc')
    ->get();

foreach ($users as $user) {
    echo $user->id . ' - ' . $user->nickname;
}

12. 分页查询

`paginate(): LengthAwarePaginator`

分页查询，返回 Laravel 标准的 LengthAwarePaginator 分页对象，方便前端渲染分页条。

返回值：

LengthAwarePaginator 对象，包含 total()、perPage()、currentPage()、items() 等方法

示例：

$paginator = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->orderBy('create_time', 'desc')
    ->page(1, 20)
    ->paginate();

echo "总条数: " . $paginator->total();
echo "当前页: " . $paginator->currentPage();
echo "每页条数: " . $paginator->perPage();

foreach ($paginator->items() as $user) {
    echo $user->nickname;
}

13. 统计

`count(): int`

统计符合条件的记录总数，使用 ES _count API，性能高效。

示例：

$total = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->where('age', '>=', 18)
    ->count();

echo "符合条件用户总数: {$total}";

字段类型自动适配

ES 中有两种常见的字段类型：

类型	精确查询	模糊查询
keyword	直接使用字段名	直接使用字段名
text	使用 `.keyword` 子字段	直接使用字段名（分词搜索）

EsQueryFacade 内置 getQueryField() 方法自动处理：

已包含 .keyword → 原样返回
在 config/common_es.php 的 query_keyword_field_array 白名单中 → 原样返回
其他字段 → 自动添加 .keyword 后缀

配置示例：

// config/common_es.php
'query_keyword_field_array' => [
    'id',
    'status',
    'role',
    // ... 其他 keyword 类型字段
],

完整示例

示例 1：分页搜索用户

use App\Facades\Common\V1\Es\EsQueryFacade;

$paginator = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->whereLike('nickname', '游鹄')
    ->orderBy('create_time', 'desc')
    ->page(1, 20)
    ->paginate();

return response()->json([
    'total' => $paginator->total(),
    'page' => $paginator->currentPage(),
    'list' => $paginator->items(),
]);

示例 2：统计活跃用户数

$activeUserCount = EsQueryFacade::index('user_index')
    ->where('status', 1)
    ->where('last_login_time', '>=', '2026-01-01')
    ->count();

echo "2026年活跃用户数: {$activeUserCount}";

示例 3：高级组合查询

use App\Facades\Common\V1\Es\EsQueryFacade;

$users = EsQueryFacade::index('order_index')
    ->where('status', 1)                           // 等于
    ->whereBetween('amount', [100, 1000])           // 范围
    ->whereNotNull('pay_time')                      // 不为 NULL
    ->orWhere('type', '=', 2)                       // OR 条件
    ->orderBy('create_time', 'desc')
    ->page(1, 50)
    ->get();

示例 4：服务层直接使用（带 orWhereLike）

use App\Services\Facade\Common\V1\Es\EsQueryFacadeService;

$esQuery = new EsQueryFacadeService();

$result = $esQuery
    ->index('product_index')
    ->where('status', 1)
    ->orWhereLike('title', '游鹄')          // OR 模糊搜索标题
    ->orWhereLike('description', '游鹄')     // OR 模糊搜索描述
    ->orderBy('sort', 'desc')
    ->page(1, 10)
    ->paginate();

错误处理

所有查询方法内置错误处理：

索引名称为空 → 抛出 CommonException('EsIndexNameEmptyError')
ES 初始化失败 → 抛出 CommonException('EsInitError')
ES 查询返回错误 → 抛出 CommonException('EsQueryError')，同时记录详细日志到 EsQueryFacadeService
ES 配置缺失 → 抛出 CommonException('EsHostConfigEmptyError')

注意事项

索引名称必传：所有查询前必须先调用 index() 指定索引。
查询条件自动重置：每次调用 index() 会重置所有查询条件、排序、分页参数。
分页自动空查询：空条件查询时自动转换为 match_all，避免 ES 报错。
keyword 字段白名单：在 config/common_es.php 中维护 query_keyword_field_array，避免模糊查询时错误添加 .keyword 后缀。
分页优先用 paginate()：返回标准 Laravel 分页对象，前端可直接渲染分页条。
重置机制：get() 和 paginate() 执行后自动重置查询条件，但 count() 仅在查询结束后重置。

作者： 游鹄君 & 雪儿
更新日期： 2026-05-23