Skip to main content

阅读Backstage配置

配置应用程序接口​

前端和后端插件都有一个通用的配置应用程序接口(API)。 可以在此找到应用程序接口参考资料这里.

配置应用程序接口专为配置缺失或配置错误时快速失败而设计，这是因为配置错误始终可被视为编程错误，并将确定性地失败。

类型 安全​

读取基元值的方法是类型化的，并在运行时验证类型。 例如getNumber()要求底层值是一个数字，并且不会将其他类型强制转换为所需的类型。getNumber()接收到字符串值时，会抛出一个错误，解释错误配置的来源，以及期望类型和实际类型。

读取嵌套配置​

后备配置数据是嵌套的 JSON 结构，也就是说，在对象中会有对象，在对象中会有数组，等等。 在读取配置时，有几种不同的方法来访问嵌套值，但最主要的是使用点分隔路径。

例如，配置如下

app:
  baseUrl: http://localhost:3000

我们可以访问baseUrl使用config.getString('app.baseUrl')事实上，配置密钥是通过以下正则表达式验证的：/^[a-z][a-z0-9]*(?:[-_][a-z][a-z0-9]*)*$/i这基本上意味着密钥必须只包含字母a通过z此外，每个组的第一个字符必须是字母，而不是数字。

另一种访问baseUrl值是创建配置的子视图、config.getConfig('app').getString('baseUrl')在读取单个值时，最好使用点路径模式，但在需要通过单独函数读取部分配置时，创建子视图也很有用。

my-plugin:
  items:
    a:
      title: Item A
      path: /a
    b:
      title: Item B
      path: /b

您可以使用.keys()方法，然后将每个子视图分别传递给其他视图进行处理。

for (const itemKey of config.keys('my-plugin.items')) {
  const itemConfig = config.getConfig(`my-plugin.items`).getConfig(itemKey);
  const title = itemConfig.getString('title');
  // ...
}

另一种遍历配置键的方法是调用config.get('my-plugin.items')，它只会返回该位置的 JSON 结构，而不会进行任何验证。 有时使用这种方法会很方便，尤其是在将配置传递给外部库的情况下。 不过，子视图方法有一个明显的好处，那就是用户会收到更详细、更相关的错误信息。 例如，如果itemConfig.getString('title')在上述示例中，由于提供了一个布尔值，因此运行失败，用户将收到一条包含完整路径的错误信息，例如："......"。my-plugin.items.b.title相反，如果尝试访问原始 JSON 中缺失的字段，往往会出现技术性很强、难以理解的 javascript 类型错误。

请注意，无论使用哪种方法读出嵌套配置，都适用相同的合并规则。 无论使用哪种方法访问嵌套配置，都会得到相同的值：

// Equivalent as long as a.b.c exists and is a string
config.getString('a.b.c');
config.getConfig('a.b').getString('c');
config.get('a').b.c;

必须配置与可选配置的对比​

读取配置可分为两类：必需配置和可选配置。 读取可选配置时，可使用可选方法，如getOptionalString这些方法只会返回undefined但可选方法仍会验证类型，因此在调用config.getOptionalNumber仍然会出错。

读取可选配置值的一个好方法是使用??例如

const title = config.getOptionalString('my-plugin.title') ?? 'My Plugin';

要读取所需的配置，只需使用不带Optional例如getString如果没有可用值，就会出错。

在前端插件中访问 ConfigApi​

配置应用程序在前端是一个实用程序可以像往常一样通过configApiRef从@backstage/core-plugin-api:

import { useApi, configApiRef } from '@backstage/core-plugin-api';
...
const MyReactComponent = (...) => {
  const config = useApi(configApiRef);
  ...
}

不过，取决于另一个应用程序接口中的配置应用程序编程接口的情况略有不同，因为ConfigApi的实现是通过应用程序本身提供的，而不是像其他应用程序接口那样被实例化。 请参见packages/app/src/apis.ts以了解如何进行布线。

中的独立插件设置。dev/index.ts的静态模拟实现注册一个工厂。 使用ConfigReader从@backstage/config创建一个实例，并为configApiRef从@backstage/core-plugin-api.

在后端插件中访问 ConfigApi​

在后端插件中，配置是通过主后端软件包中的选项传入的。 例如，请参见packages/backend/src/plugins/auth.ts.