ES REST API 的庖丁解牛

Elasticsearch REST API是Elasticsearch 全部功能的唯一入口，所有操作（索引、搜索、集群管理）。
理解 REST API = 掌握 Elasticsearch 的通用语言，与客户端语言（PHP/Java/Python）。

一、API 设计哲学：RESTful + JSON

📜四大核心原则

1. 资源导向（Resource-Oriented）

   • 索引（Index） = 资源集合
   • 文档（Document） = 单个资源
   • 路径= 资源定位符（/index/_doc/id）

2. HTTP 方法语义化

   方法	用途	幂等性
   GET	查询文档/搜索	✅
   POST	创建文档（自动生成 ID）	❌
   PUT	创建/更新文档（指定 ID）	✅
   DELETE	删除文档/索引	✅

3. JSON 作为统一数据格式

   • 请求体= JSON
   • 响应体= JSON
   • 错误信息= JSON（含error字段）

4. 无状态（Stateless）

   • 每个请求包含全部上下文（无会话）

🔑真相：ES 是“JSON over HTTP”的极致实践。

二、核心端点：五大 API 分类

🔍 **1. 文档 API **(Document APIs)

🔎 **2. 搜索 API **(Search APIs)

🗃️ **3. 索引 API **(Index APIs)

📊 **4. 集群 API **(Cluster APIs)

⚙️5. 别名与模板 API

💡_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 就从工具，
变为数据基石。

这，才是专业工程师的搜索观。