即时文档 — 一个快捷键打开任意 API 参考

当你在 Dev Tools 中编写 Elasticsearch 查询时，最令人抓狂的时刻不是 JSON 中的打字错误——而是不得不切换到浏览器标签页去查找 API 语法的瞬间。ES 8.x 中某个 GET /my-index/_search 可能需要一个在 6.x 中不存在的参数。POST /_reindex 的响应格式又变了。你记住了常用端点，但边缘情况总是让你转向 Google。

DocKit 刚刚解决了这个问题。在编辑器中按 ⌘D（Mac）或 Ctrl+D（Windows / Linux），即可获取当前 API 的精确文档页面——版本感知、语言感知、引擎感知。

DocKit Ctrl+D 文档快捷方式

我们解决的问题

在这次更新之前，DocKit 的 Ctrl+D 快捷键通过约 28 个硬编码的正则表达式来匹配已知 API 端点。它覆盖了基础内容：GET _search、PUT _mapping、POST _bulk。但 Elasticsearch REST API 有数百个端点，手动维护这个字典根本跟不上：

覆盖率不完整——大量 _cat/、_ml/、_security/、_transform/ 以及新的 v8/v9 端点没有文档链接
版本不匹配——所有链接指向单一版本，不管你的集群版本是多少
不支持 OpenSearch——OpenSearch 有完全不同的文档 URL
不支持 DynamoDB——AWS API 参考完全分离

结果：Ctrl+D 最多只能匹配 1/3 的查询。其余的，你还是得打开浏览器。

我们做了什么改变

我们从零开始重建了文档系统——9 个文件、1,300+ 行新代码和测试。具体来说：

1. 基于 API 规范的 100% 覆盖率

不再使用零散的正则表达式，DocKit 现在使用全面的 API 规范提供者（apiSpecProvider）——这也是我们的 Search DSL 自动补全功能背后的同一套数据。该规范包含每个 Elasticsearch 端点：

索引操作——创建、删除、打开/关闭、验证、设置、映射
文档操作——获取、更新、删除、批量操作
搜索与聚合——search、msearch、terms-enum、explain
集群管理——健康状态、集群状态、节点信息、设置
安全——角色、API 密钥、角色映射
ML 与转换——推理、转换、enrich
Cat API——indices、aliases、nodes、shards
以及所有其他——CCR、SLM、pipeline、快照等

只要 Search DSL 补全中存在的端点，Ctrl+D 现在都知道去哪里找到它的文档。

2. 跨版本文档策略

从 v9 开始，Elasticsearch 分成了两种文档格式：

旧指南格式（≤ v8.19）：https://www.elastic.co/guide/en/elasticsearch/reference/{version}/{page}.html
新 API 文档（≥ v9）：https://www.elastic.co/docs/api/doc/elasticsearch/v{major}/operation/{name}

DocKit 自动检测你的集群版本并选择正确的格式：

你的集群	文档格式
ES 6.x	旧指南 → 最接近的可用版本（如 6.8）
ES 7.x	旧指南 → 最接近的可用版本（如 7.17）
ES 8.x（≤ 8.19）	旧指南 → 匹配的次要版本
ES 9.x+	新 API 文档 → 匹配的主版本
OpenSearch	OpenSearch 官方文档 → 版本对齐
DynamoDB	AWS API 参考 → 带版本号

对于每个版本，DocKit 都映射到 Elastic 指南索引中最接近的可用文档。不会错误回退——如果你的集群运行 8.5，你会看到 8.5 的文档，而不是硬编码的 v8.19。

3. 多引擎支持

系统现在处理三个引擎，完全不同的文档来源：

引擎	文档来源
Elasticsearch	Elastic 官方 API 文档（双格式）
OpenSearch	OpenSearch 官方文档（版本特定）
DynamoDB	AWS 操作 API 参考

同一个快捷键覆盖所有三引擎——系统自动检测你连接的引擎并拉取正确的文档。

4. 语言支持

按文档快捷键时用你设置的语言打开文档：

中文→ 打开中文文档页面
英文→ 打开英文文档页面

无需手动翻译——URL 根据你配置的语言自动构建。

5. 边缘案例修复

这次重构中我们修复了数十个边缘案例：

基于方法转换——部分端点同时支持 GET 和 POST。DocKit 现在将方法特定的操作映射到精确的文档页
多方法端点——_cat/indices、_settings、_reindex 等多用途端点现在都有正确的操作到页面映射
旧版到新版页面名修正——cat-alias → cat-aliases，modules-snapshots → 当前正确名称
HEAD 请求——别名和索引存在性检查现在链接到正确文档
DELETE scroll——scroll API 清理操作现在有文档了

技术详情

架构概览

用户按下 ⌘D / Ctrl+D
        │
        ▼
  读取编辑器当前行内容
        │
        ▼
  通过 apiSpecProvider 匹配端点
        │
        ├─ Elasticsearch → 构建 API 文档 URL
        │                   ├─ 版本检测（6→9+）
        │                   ├─ 格式选择（旧指南 vs 新 API）
        │                   └─ 方法映射（GET/POST/PUT/DELETE）
        │
        ├─ OpenSearch → 构建 OpenSearch 文档 URL
        │                └─ 版本对齐映射
        │
        └─ DynamoDB → 构建 AWS API 参考 URL
                        └─ 操作名称解析
        │
        ▼
  在系统浏览器中打开 URL

前后对比

之前：

typescript

// 28 个硬编码正则表达式，覆盖约 1/3 API
const actionRegexMap: { [key in ActionType]: RegExp } = {
  POST_SEARCH: /POST .*\/_search/,
  POST_COUNT: /POST .*\/_count/,
  // ...还有很多，但不完整
};

之后：

typescript

// 基于规范驱动，通过 apiSpecProvider 获取覆盖率
// 补全规范中的每个端点都有文档路径
const docPath = apiSpecProvider.getDocPath(action, method, version);
const url = buildDocUrl(backendType, version, docPath, language);

包含内容

467 行重写的 referDoc.ts（文档系统）
381 行更新的 completionProvider.ts（自动补全现在共享文档逻辑）
71 行扩展的 apiSpec.ts（带有文档路径的 API 规范）
373 行新测试（referDoc.test.ts、index.test.ts）
37 个测试用例覆盖 v0.90 → v9.x 特定版本文档映射
9 个文件变更，共 1,300+ 行新增代码

这对你的工作流为什么重要

零上下文切换——留在 DocKit 里。无需浏览器标签，无需 Google 搜索。
版本精确——ES 6.x 集群看 6.x 文档，ES 9 看 9。不会有废弃参数带来的意外。
多引擎——同一快捷键适用于 Elasticsearch、OpenSearch 和 DynamoDB。
中文文档——如果你偏好中文文档，一键即可获取。
100% 覆盖率——每个端点都有文档链接。不是"大多数"——是每一个。

立即试用

打开 DocKit 并连接任意 Elasticsearch/OpenSearch/DynamoDB 服务器
在编辑器中输入任意操作：GET _cluster/health、PUT my-index/_mapping、POST /_reindex
将光标放在该行并按 ⌘D（Mac）或 Ctrl+D（Windows / Linux）
精确的文档页面将在浏览器中打开

就是这样。无需配置、无需设置——它对任意连接自动生效。

即时文档 — 一个快捷键打开任意 API 参考 ​

我们解决的问题 ​

我们做了什么改变 ​

1. 基于 API 规范的 100% 覆盖率 ​

2. 跨版本文档策略 ​

3. 多引擎支持 ​

4. 语言支持 ​

5. 边缘案例修复 ​

技术详情 ​

架构概览 ​

前后对比 ​

包含内容 ​

这对你的工作流为什么重要 ​

立即试用 ​

相关资源 ​