Skip to main content

搬离 @backstage/core

@backstage/core软件包已拆分为三个独立的软件包、@backstage/core-app-api,@backstage/core-plugin-api和@backstage/core-components有关这一变更的原因和软件包命名的更多信息，请参见原 RFC和初始公关.

拆分的主要目的是使插件与应用程序更加解耦，并为使用多个不同版本的核心库的插件组合提供了可能性。 这将大大减轻插件作者的维护负担，并减少核心 API 的破坏性更改所带来的影响。

迁移​

在高层次上，迁移只需简单地替换"...... "的用法即可。@backstage/core新软件包中会有一些破坏性更改，如下所示，但对于大多数插件来说，迁移只是简单的替换。 为了使迁移尽可能顺利，我们提供了一系列工具来自动完成大部分迁移工作。

下面列出的步骤应该能让大多数项目完成迁移，步骤顺序是建议，但不是必须的，所以如果需要返回到之前的步骤来修复问题，也不用担心。

步骤 1 - 运行 codemod​

第一步是运行@backstage/codemods这将自动将源代码中的所有模块导入转换为使用三个新核心包中的一个。 例如，可能会发生以下变化：

import { useApi, configApiRef, InfoCard } from '@backstage/core';
import { useApi, configApiRef } from '@backstage/core-plugin-api';
import { InfoCard } from '@backstage/core-components';

在使用@backstage/create-app运行以下程序：

npx @backstage/codemods apply core-imports packages plugins

最后两个参数、packages和plugins根据项目需要添加或删除文件夹。

codemod 可能会因为某些文件缺少IconKey这是为数不多的破坏性更改之一。 要修复这些更改，请删除任何IconKey导入，并用string类型的使用，详见下面的 "重大变更 "部分。IconKey类型已被删除，您可以重新运行这些文件的 codemod。

请注意，虽然 codemod 会尽量使用项目中的现有格式，但并不总是能做到这一点。 如果您使用的是prettier来格式化项目中的代码，最好运行prettier --write上任何被 codemod 更改的文件。

步骤 2 - 更新依赖项​

下一步是更新您的package.json文件。@backstage/core将需要被一个或多个新软件包替换。 应用程序软件包应将所有三个软件包添加到dependencies而对于插件和其他非应用程序软件包，则使用@backstage/core-plugin-api和@backstage/core-components软件包应添加到常规dependencies和@backstage/core-app-api应加入devDependencies用于测试。

有一个工具可以帮助您迈出这一步，它就是plugin:diff命令中的@backstage/cli，它将把你的插件与基础插件模板进行比较，并对插件偏离的地方提出修改建议。 如果你有最新的项目，完成这一步的快速方法是在项目根目录下运行以下程序：

# The --yes flag causes all suggested changes to be accepted automatically
yarn diff --yes

如果您没有diff中设置的命令package.json您也可以在每个插件文件夹中手动执行以下操作：

yarn backstage-cli plugin:diff --yes

第 3 步 - 手工审查​

此时，您的应用程序已经完成或即将完成迁移。 使用以下命令进行类型检查yarn tsc来检查您是否遇到了下面的破坏性更改，或者是否有其他需要修复的地方。@backstage/core在代码库中，因为这可能会在例如jest模拟调用，而 codemod 并不处理这些调用。

最后一步，您需要启动应用程序，并通过您为项目设置的任何常规验证步骤。 如果您遇到任何问题，或者有任何其他步骤或提示需要添加到本指南中，请不要犹豫，打开 GitHub issue、PR 或联系 Discord！

打破常规​

以下是两个版本之间的重大变更列表@backstage/core由于新核心软件包的新版本可能会带来更多变化，因此这个列表可能并不详尽，这取决于您何时迁移应用程序。

删除了 IconKey 类型​

IconKey类型曾经是一个字符串联盟，它包含了所有用于应用程序图标的已知键，可通过useApp().getSystemIcon(key)该类型已被删除，因为允许的图标键集不再受限制，而只保证应用程序提供最低限度的图标集，但可以提供超出该范围的任何图标。 移植只需用string类型

受约束的 IconComponent 类型​

IconComponent类型，用于允许使用 Material UI 中的所有道具SvgIcon这助长了开源插件中的一些不良模式，例如将颜色应用到图标上，这反过来又损害了用自定义图标替换图标的能力。IconComponent类型，现在可从@backstage/core-plugin-api现在只接受fontSize道具，用于设置图标的大小。 该类型与 Material UISvgIcon但在某些情况下，图标可能需要明确地转为IconComponent以缩小类型范围。