正在加载

Typescript

虽然这不是必需的，但我们鼓励所有新代码都使用 Typescript 开发。

项目引用

Kibana 已经超过了 200 万行代码。当前的情况在默认的开箱即用设置停止工作时会产生一些扩展问题。 因此，开发人员会受到项目编译缓慢和 IDE 无响应的影响。作为 开发者体验项目的一部分，我们正在迁移我们的工具以使用内置的 TypeScript 功能来解决扩展问题 - 项目引用 & 增量构建

简而言之，这种设置不是一次编译整个 Kibana 代码库，而是强制将代码库拆分为形成有向无环图 (DAG) 的独立项目。 这允许 TypeScript 编译器 (tsc) 应用几个高级优化

  • 每个项目都以 TypeScript 编译器生成的 d.ts 类型声明的形式发出 public 接口
  • 每当在依赖项目中导入被引用的项目时，都会使用这些生成的 d.ts 类型声明
  • 这样就可以确定在源代码已更改为使用更激进的缓存策略时需要重建哪个项目。

更多详细信息请参见 官方文档

注意事项

此架构施加了一些我们必须遵守的限制

  • 项目不能有循环依赖。 即使 Kibana 平台不支持 Kibana 插件之间的循环依赖，TypeScript（和 ES6 模块）确实允许文件之间的循环导入。 因此，理论上，在迁移到 TS 项目引用时，您可能会遇到问题，并且必须解决此循环依赖。 我们构建了一个可用于查找此类问题的工具。 请阅读下面的先决条件部分，了解如何使用它。

  • 项目必须发出其类型声明。 如果编译器无法推断类型，则并非总是可以生成类型声明。 有两个基本情况

    1. 您的插件导出推断 Kibana 代码库中声明的内部类型的类型。 在这种情况下，您必须导出内部类型或显式声明导出的类型。
    2. 您的插件导出的内容会从不导出此类型的第三方库推断类型。 要解决此问题，您必须手动声明导出的类型。

先决条件

由于项目引用依赖于生成的 d.ts 文件，因此迁移顺序确实很重要。 只有当所有插件依赖项都已迁移时，才能迁移插件。 这会创建一个需要首先迁移常用插件（例如 data 或 kibana_react）的情况。 运行 node scripts/find_plugins_without_ts_refs.js --id your_plugin_id 以获取应切换到 TS 项目引用以解除阻止您的插件迁移的插件列表。

此外，为了迁移到项目引用，您还需要确保您的插件在代码和类型导入方面与其他插件没有循环依赖。 我们在 CI 中为每个 PR 运行一个作业，试图查找是否添加了新的循环依赖，该作业使用 node scripts/find_plugins_with_circular_deps 运行我们的工具。 但是，已经识别出一些循环依赖关系，并且这些循环依赖关系位于要解决的允许列表中。 您还需要确保您的插件不依赖于该允许列表中的任何其他插件。 要全面了解已发现的和允许列表中的循环依赖关系以及完整的循环依赖关系路径，请使用调试标志在本地运行以下脚本 node scripts/find_plugins_with_circular_deps --debug 。

实现

  • 确保在 kibana.json 清单文件的 requiredPlugins、optionalPlugins 和 requiredBundles 属性中列出的所有插件都已迁移到 TS 项目引用。
  • 在插件的根文件夹中添加 tsconfig.json。
{
  "extends": "../../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./target/types",
    "emitDeclarationOnly": true,
    "declaration": true,
    "declarationMap": true
  },
  "include": [
    // add all the folders containing files to be compiled
  ],
  "references": [
    { "path": "../../core/tsconfig.json" },
    // add references to other TypeScript projects your plugin depends on
  ]
}

如果您的插件导入了未在 include 中列出的文件，则构建将失败，并显示以下消息 File ‘…’ is not listed within the file list of project …’. Projects must list all files or use an 'include' pattern.

  • 构建你的插件 ./node_modules/.bin/tsc -b src/plugins/my_plugin。 如果 tsc 无法为你的项目生成类型声明，请修复错误。
  • 将你的项目引用添加到 tsconfig.refs.json 的 references 属性
  • 将你的插件添加到它曾经属于的 tsconfig.json 的 references 属性，并将插件文件夹添加到 exclude 属性（例如，对于 src/plugins/** 是 tsconfig.json；对于 x-pack/plugins/** 是 x-pack/tsconfig.json）。
  • 在所有可能导入您的项目的 Kibana tsconfig.json 文件中列出对您新创建的项目的引用：tsconfig.json、test/tsconfig.json、x-pack/tsconfig.json、x-pack/test/tsconfig.json。 以及所有依赖插件的特定于插件的 tsconfig.refs.json 中。
  • 你可以使用 node --max-old-space-size=4096 ./node_modules/.bin/tsc -p tsconfig.json --extendedDiagnostics --noEmit 来衡量你的更改如何影响 tsc 编译器的性能。 与 master 分支进行比较。

你可以使用 https://github.com/elastic/kibana/pull/79446 作为示例。

© . All rights reserved.