为插件定义配置

Backstage 中的配置是通过配置模式组织的，而配置模式又是通过以下超集定义的JSON 模式草案-07Backstage 应用程序中的每个插件或软件包都可以为模式作出贡献，在验证过程中，这些插件或软件包会拼接成一个模式。

模式收集和定义

模式是从每个软件仓库中属于 backstage 生态系统一部分的所有软件包和依赖包(包括根软件包和传递依赖包)中收集的。目前对 "生态系统一部分 "的定义是，一个软件包至少有一个依赖包在@backstage命名空间或"configSchema"字段中的package.json但可能会有变化。

每个软件包都在一个入口点搜索模式，这个入口点就是顶层的"configSchema"字段中的package.json该字段可以包含内联 JSON 模式，也可以是模式文件的相对路径。支持的模式文件格式有.json或.d.ts.

package.json
{
  // ...
  "files": [
    // ...
    "config.d.ts"
  ],
  "configSchema": "config.d.ts"
}

定义模式文件时，确保在 > package.json > "files" 字段中也包含该文件！

TypeScript 配置模式文件应导出单个Config例如

export interface Config {
  app: {
    /**
     * Frontend root URL
     * @visibility frontend
     */
    baseUrl: string;

    // Use @items.<name> to assign annotations to primitive array items
    /** @items.visibility frontend */
    myItems: string[];
  };
}

分离式.json模式文件可以使用顶层"$schema": "https://backstage.io/schema/config-v1"举例来说：

{
  "$schema": "https://backstage.io/schema/config-v1",
  "type": "object",
  "properties": {
    "app": {
      "type": "object",
      "properties": {
        "baseUrl": {
          "type": "string",
          "description": "Frontend root URL",
          "visibility": "frontend"
        }
      },
      "required": ["baseUrl"]
    },
    "required": ["app"]
  }
}

可见度

https://backstage.io/schema/config-v1元模式是 JSON 模式 Draft 07 的超集。visibility关键字，用于指示给定的配置值是否应在前台可见。可能的值有frontend,backend和secret其中backend的可见性为默认值。secret在运行时具有相同的作用域，但在某些上下文中会受到更严格的处理。frontend和secret会导致模式合并时出错。

可见性只适用于模式中关键字所在位置的直接父级。例如，如果将可见性设置为frontend的模式子集的type: "object"的叶子节点的可见性就足够了。type: "string".

|visibility| | | ------------ | ------------------------------------------------------------------ | |frontend在前端和后端都能看到 | | |backend| (默认)仅在后端 | | | | | | | | | | | |secret| 仅在后端，出于安全原因可能会从日志中排除 | 仅在后端，出于安全原因可能会从日志中排除 | 仅在后端，出于安全原因可能会从日志中排除 | 仅在后端，出于安全原因可能会从日志中排除

您可以使用@visibility在ConfigTypescript 界面。

export interface Config {
  app: {
    /**
     * Frontend root URL
     * @visibility frontend
     */
    baseUrl: string;
  };
}

验证

可以使用backstage-cli config:check如果您想验证除默认的app-config.yaml请确保将所有配置文件作为--config <path>选项。

要验证和检查前端配置，请使用backstage-cli config:print --frontend就像验证一样，您可能需要使用一个或多个--config <path>选项。

准则

有限度地使用静态配置。首先要问的问题是，某个特定选项是否真的需要使用静态配置，或者它是否可以 > 使用 TypeScript API。一般来说，希望能够 > 针对不同部署环境进行更改的选项应使用静态 > 配置，否则应避免使用静态配置。

为插件定义配置时，请将按键放在camelCase形式，并遵循现有的套管约定，如baseUrl而不是baseURL.

通常情况下，最好选择对象而不是数组，因为这样可以使用单独的文件或环境变量来覆盖单个值。

尽量避免创建新的顶层字段，要么将配置放在现有的已知顶层块中，要么使用插件集成的产品名称等创建一个新的顶层字段。

模式收集和定义​

可见度​

验证​

准则​

模式收集和定义

可见度

验证

准则