Skip to main content

软件包角色迁移

Backstage CLI 引入了软件包角色的概念，其目的是为了实现更强大的工具、优化和更精简的软件包配置。 有关这一变化的更多背景和信息，请参阅原 RFC和常见问题在这一页上。

软件包角色是通过一个著名的"backstage"."role"字段中的package.json到目前为止，已定义的角色屈指可数，而且无法使用超出一组预定义角色.

在所有软件包中设置了角色后，Backstage CLI 就能自动决定如何处理每个软件包。 例如，不同的构建命令已被一个单一的命令所取代，而后者知道如何构建每个角色。 测试和 lint 配置也会根据角色自动选择，并新增了一个类别为repo命令，这些命令可以同时在所有软件包中运行。

软件包角色在 Backstage 主版本库中已经使用了一段时间，现在我们建议所有 Backstage 项目都迁移到使用软件包角色。

迁移​

为了使迁移尽可能顺利@backstage/cli在大多数项目中，将这些工具与一些手动审查和可选步骤相结合，就可以完成向软件包角色的迁移。

在开始迁移之前，请确保您已更新到最新版本的@backstage/cli.

TL;DR, Step 1-4：​

下面是所有步骤的简略版，以防万一。

运行以下命令

yarn backstage-cli migrate package-roles
yarn backstage-cli migrate package-scripts
yarn backstage-cli migrate package-lint-configs

请查看yarn backstage-cli repo与它们相比，速度往往要快得多。lerna等价物。

第 1 步 - 添加软件包角色​

第一步是添加"backstage"."role"这当然可以手动完成，但下面的命令将尝试自动检测项目中每个软件包的角色：

yarn backstage-cli migrate package-roles

自动检测并不完美，因此建议手动查看分配给每个软件包的角色。 您可以使用软件包角色定义作为参考。

第 2 步 - 移植软件包脚本​

向软件包角色的迁移还引入了新的package命令类别。package类别旨在直接映射到"scripts"于package.json这些命令取代了现有的命令，如build,app:build,lint和test它们看起来是这样的

{
  "scripts": {
    "start": "backstage-cli package start",
    "build": "backstage-cli package build",
    "lint": "backstage-cli package lint",
    ...
  }
}

每个软件包角色都有一套固定的推荐脚本。 强烈建议您使用这些脚本，因为这样可以优化 CLI 的其他部分。 您可以通过运行以下命令迁移到使用所有这些脚本：

yarn backstage-cli migrate package-scripts

迁移命令还会沿用旧脚本中传递的任何现有标记。

如果您最终不想使用这种确切的脚本设置，仍建议迁移到使用package命令，因为顶层命令将被弃用和移除。 如果也不想使用软件包角色，可以向某些软件包命令传递明确的角色，例如yarn backstage-cli package build --role web-library.

第 3 步 - 迁移软件包 ESLint 配置​

作为向软件包角色转移的一部分，ESLint 配置也得到了简化。 现在，它们不再让每个软件包选择自己想要的配置(而且还会弄错)，而是使用一个共享的配置工厂，该工厂利用软件包角色。 您可以在《软件包角色》一书中了解有关新配置设置的更多信息。构建系统文档.

要迁移项目中所有软件包的 ESLint 配置，请运行以下命令：

yarn backstage-cli migrate package-lint-configs

这将迁移所有现有的.eslintrc.js扩展旧配置的@backstage/cli并可继承任何其他配置。

第 4 步 - 使用 backstage-cli repo.​

Backstage CLI 最近推出了一个新的repo命令类别，其中包含了可同时对整个 monorepo 进行操作的命令。 这些命令在软件包迁移到使用角色后效果尤佳，因为这样可以进行一些非常有效的优化。 使用这些命令通常比使用诸如lerna因为它们可以避免通过yarn您可以阅读更多有关repo命令中的CLI 命令文档.

执行这一步迁移的方法不像前几步那么明确，因为这取决于你的开发和 CI/CD 设置。 在你的根目录中寻找以下模式进行替换package.json以及 CI/CD 设置：

  • Commands that lint the entire repo should be replaced with yarn backstage-cli repo lint along with a --since flag if needed. For example this: sh lerna run lint --since origin/master -- would be replaced by the following:sh backstage-cli repo lint --since origin/master * In places where the entire repo is being built, use yarn backstage-cli repo build, which also supports the --since flag. The migration here is a bit more nuanced as it depends on why you are building all packages. - If you are building all packages to verify that you are able to build them, you most likely want backstage-cli repo build --all. The --all flag signals that bundled packages like packages/app and packages/backend should be built as well. Pair this up with a --since flag in CI to avoid needing to build all packages. - If you are building all packages to publish them, then backstage-cli repo build is enough, as it builds all published packages. - If you are building all packages to **deploy

FAQ​

为何引入软件包角色？​

以精简配置，提供更多实用程序和工具，并优化构建系统。原 RFC.

我必须迁移到使用软件包角色吗？​

简短的回答--是的。

更长的答案--大多数情况下，您可以在命令调用或配置中明确声明软件包的角色，从而避免声明软件包的角色。app:build命令会消失，但你可以用package build --role frontend如果您不想在package.json但强烈建议声明软件包角色。

###我有一个软件包，现有的角色都不适用

web-library,node-library和common-library角色是通用角色，应涵盖大多数使用情况。 如果您觉得这些角色都不适合您，请在Backstage repo并建议增加一个新角色。

我应该在发布的软件包中包含角色吗？​

是的，虽然目前还没有任何工具可以使用该角色，但未来的工具很可能会在发布的软件包包含该角色时为用户提供更好的体验。