« 安全最佳实践 架构 »
Elastic 文档 ›Kibana 指南 [8.14] ›开发者指南 ›最佳实践

TypeScript

编辑

TypeScript编辑

虽然这不是强制要求，但我们鼓励所有新代码都使用 TypeScript 开发。

项目引用编辑

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

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

  • 每个项目都以 d.ts 类型声明的形式发出 public 接口，这些声明由 TypeScript 编译器生成
  • 每当在依赖项目中导入引用项目时，都会使用这些生成的 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。

实现编辑
  • 确保 requiredPlugins、optionalPlugins 和 requiredBundles 属性中列出的所有插件 kibana.json 清单文件已迁移到 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 属性中
  • 将您的插件添加到 references 属性中，并将插件文件夹添加到其所属的 tsconfig.json 的 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 作为示例。

« 安全最佳实践 架构 »