› › ›

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 运行我们的工具。但是，还有一些已经识别出并且在允许列表中需要解决的循环依赖。您还需要确保您的插件不依赖于该允许列表中的任何其他插件。有关找到和允许列表中的循环依赖以及完整的循环依赖路径的完整概述，请使用 debug 标志 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 作为示例。

« 安全最佳实践架构 »