Elasticsearch REST API是Elasticsearch 全部功能的唯一入口，所有操作（索引、搜索、集群管理）。
理解 REST API = 掌握 Elasticsearch 的通用语言，与客户端语言（PHP/Java/Python）。
一、API 设计哲学：RESTful + JSON
📜四大核心原则
资源导向（Resource-Oriented）
- 索引（Index） = 资源集合
- 文档（Document） = 单个资源
- 路径= 资源定位符（
/index/_doc/id）
HTTP 方法语义化
方法 用途 幂等性 GET查询文档/搜索 ✅ POST创建文档（自动生成 ID） ❌ PUT创建/更新文档（指定 ID） ✅ DELETE删除文档/索引 ✅ JSON 作为统一数据格式
- 请求体= JSON
- 响应体= JSON
- 错误信息= JSON（含
error字段）
无状态（Stateless）
- 每个请求包含全部上下文（无会话）
🔑真相：ES 是“JSON over HTTP”的极致实践。
二、核心端点：五大 API 分类
🔍 **1. 文档 API **(Document APIs)
| 端点 | 用途 | 示例 |
|---|---|---|
PUT /index/_doc/id | 创建/更新文档 | PUT /articles/_doc/1 |
GET /index/_doc/id | 获取文档 | GET /articles/_doctype/1 |
DELETE /index/_doc/id | 删除文档 | DELETE /articles/_doc/1 |
POST /index/_update/id | 部分更新 | POST /articles/_update/1 { "doc": { "views": 100 } } |
🔎 **2. 搜索 API **(Search APIs)
| 端点 | 用途 | 示例 |
|---|---|---|
GET /index/_search | 全文搜索 | GET /articles/_search?q=title:php |
POST /index/_search | 复杂查询 | POST /articles/_search { "query": { "match": { "title": "php" } } } |
GET /index/_count | 计数 | GET /articles/_count?q=status:published |
🗃️ **3. 索引 API **(Index APIs)
| 端点 | 用途 | 示例 |
|---|---|---|
PUT /index | 创建索引 | PUT /articles { "settings": { "number_of_shards": 1 } } |
GET /index | 获取索引信息 | GET /articles |
DELETE /index | 删除索引 | DELETE /articles |
POST /index/_close | 关闭索引 | POST /articles/_close |
📊 **4. 集群 API **(Cluster APIs)
| 端点 | 用途 | 示例 |
|---|---|---|
GET /_cluster/health | 集群健康 | GET /_cluster/health?pretty |
GET /_cat/indices | 索引列表 | GET /_cat/indices?v |
GET /_nodes/stats | 节点统计 | GET /_nodes/stats |
⚙️5. 别名与模板 API
| 端点 | 用途 | 示例 |
|---|---|---|
POST /_aliases | 管理别名 | POST /_aliases { "actions": [{ "add": { "index": "articles_v2", "alias": "articles" } }] } |
PUT /_index_template/name | 创建索引模板 | PUT /_index_template/articles { "index_patterns": ["articles*"], "template": { ... } } |
💡
_catAPI：为人类设计的可读格式（?v= verbose）。
3. 请求/响应结构：标准化格式
📤请求结构
POST /articles/_search Content-Type: application/json Authorization: Basic xxx { "query": { "match": { "title": "php" } }, "highlight": { "fields": { "title": {} } }, "from": 0, "size": 10 }- 路径：资源定位
- Headers：认证/内容类型
- Body：JSON 操作描述
📥响应结构
{"took":15,// 耗时（ms）"timed_out":false,// 是否超时"_shards":{// 分片统计"total":1,"successful":1,"skipped":0,"failed":0},"hits":{// 搜索结果"total":{"value":5,"relation":"eq"},"max_score":0.2876821,"hits":[{"_index":"articles","_type":"_doc","_id":"1","_score":0.2876821,"_source":{"title":"PHP Guide"},"highlight":{"title":["<em>PHP</em> Guide"]}}]}}took：关键性能指标_shards：分片健康度hits：核心结果集
四、安全实践：生产环境必做
🔒1. 认证与授权
- 启用 HTTPS：
# elasticsearch.ymlxpack.security.http.ssl.enabled:true - 使用 API Key（推荐）：
curl-H"Authorization: ApiKey xxx"http://es:9200/_search - 避免 Basic Auth 明文：用 API Key 或证书；
🛡️2. 请求体大小限制
- 防止 OOM：
# elasticsearch.ymlhttp.max_content_length:100mb
📉3. 搜索防护
- 禁止通配符
*：{"query":{"query_string":{"query":"title:*",// 危险！"allow_leading_wildcard":false// 禁止}}} - 限制分页深度：
{"from":10000,// 超过 index.max_result_window（默认 10000）会失败"size":10}
五、调试技巧：开发者必备
🐞1. 格式化输出
# ?pretty 参数curl"http://localhost:9200/_cluster/health?pretty"📋2. 详细错误信息
# ?error_trace 参数curl"http://localhost:9200/invalid_index/_search?error_trace"🔍3. Explain API（分析查询）
curl-X POST"http://localhost:9200/articles/_explain/1"-H"Content-Type: application/json"-d' { "query": { "match": { "title": "php" } } }'- 输出：为什么文档匹配/不匹配；
📈4. Profile API（性能分析）
{"profile":true,"query":{"match":{"title":"php"}}}- 输出：查询各阶段耗时；
六、高危误区
🚫 误区 1：“PUT 和 POST 可互换”
- 真相：
PUT /index/_doc/id= 指定 ID（幂等）POST /index/_doc= 自动生成 ID（非幂等）
- 解法：创建用 POST（无 ID），更新用 PUT（有 ID）；
🚫 误区 2：“ES 支持 JOIN”
- 真相：
- ES 无传统 JOIN；
- 用嵌套对象/父子文档/应用层 JOIN；
- 解法：数据建模时反范式化；
🚫 误区 3：“DELETE 立即释放磁盘”
- 真相：
- DELETE 仅标记删除；
- 磁盘空间由后台 Merge 释放；
- 解法：用
_forcemerge手动释放；
七、终极心法：REST API 是 ES 的通用语言
不要依赖客户端封装，
而要直接理解 HTTP + JSON。
- 脆弱使用：
- “Laravel Scout 能用就行” → 遇到性能问题无法优化；
- 韧性使用：
- “直接调 REST API” → 精准控制查询/索引；
- 结果：
- 前者是用户，后者是主人。
真正的 ES 能力，
不在“客户端多熟”，
而在“API 多透”。
八、行动建议：今日 REST API 实战
## 2025-10-08 REST API 实战 ### 1. 创建索引 - [ ] PUT /articles { "settings": { "number_of_shards": 1 } } ### 2. 索引文档 - [ ] PUT /articles/_doc/1 { "title": "PHP Guide" } ### 3. 搜索文档 - [ ] POST /articles/_search { "query": { "match": { "title": "php" } } } ### 4. 调试分析 - [ ] 用 ?pretty 格式化输出 - [ ] 用 _explain 分析匹配原因✅完成即掌握 ES 核心 API。
当你停止用“客户端方法”黑盒操作，
开始用“REST API”直接对话 ES，
Elasticsearch 就从工具，
变为数据基石。
这，才是专业工程师的搜索观。
