4. 软件目录处理器与集成

Backstage 软件目录（Software Catalog）本身只是一套实体模型和存储层，真正让目录“活”起来的是处理器（Processor）。处理器负责把来自不同来源的原始数据转换成符合目录规范的实体，并在转换过程中完成校验、补充和关联。理解内置处理器的分工、掌握自定义处理器的开发方式，以及打通与 GitHub/GitLab/Bitbucket 的集成，是构建可用开发者门户的核心工作。

一、处理器在目录中的位置

目录的数据流可以概括为：实体提供者（EntityProvider）负责从外部系统拉取或接收原始实体数据，处理器对原始实体进行加工，最终写入目录数据库。处理器是纯函数式的转换环节，它接收一个实体，返回零个或多个实体。这种设计让处理器可以链式组合，每个处理器只关注一件事。

二、内置处理器类型

Backstage 默认注册了一批内置处理器，它们覆盖了最常见的目录构建场景。理解每个处理器的职责边界，可以避免重复造轮子。

BuiltinKindsEntityProcessor 是最基础的处理器，负责为内置实体类型（Component、API、System、Domain、Resource、Group、User 等）补充默认字段和关系。例如，当你在 catalog-info.yaml 中声明一个 Component 时，该处理器会确保 spec.type 有合理默认值，并处理 dependsOn、providesApis 等关系字段的规范化。

UrlReaderProcessor 负责从远程 URL 读取实体定义。它支持 url: 定位符，能够解析 GitHub、GitLab、Bitbucket 等平台的仓库地址，拉取指定路径下的 YAML 文件。这个处理器是“目录即代码”模式的关键：你只需要在根目录放一个引用，它就能把分散在各仓库的实体定义聚合起来。

GithubDiscoveryProcessor 和对应的 GitLab、Bitbucket 发现处理器，用于自动扫描组织下的仓库。给定一个组织名和可选的过滤条件，它会遍历仓库列表，查找符合命名约定的 catalog-info.yaml 文件并注册为实体。这解决了“新仓库如何自动进入目录”的问题。

LocationEntityProcessor 处理 Location 类型实体，负责解析 target 字段并触发后续的读取流程。它通常与 UrlReaderProcessor 配合，形成“位置 → 读取 → 解析 → 注册”的链路。

CodeOwnersProcessor 从仓库的 CODEOWNERS 文件中提取归属信息，自动填充实体的 spec.owner 字段。这对于已有成熟 CODEOWNERS 规范的团队非常实用，可以减少手工维护。

三、自定义处理器开发

当内置处理器无法满足需求时，就需要开发自定义处理器。一个处理器本质上是一个实现了 CatalogProcessor 接口的对象，核心方法是 processEntity。

import { CatalogProcessor, CatalogProcessorEmit } from '@backstage/plugin-catalog-node';
import { Entity, LocationSpec } from '@backstage/catalog-model';

export class TeamLabelProcessor implements CatalogProcessor {
  getProcessorName(): string {
    return 'TeamLabelProcessor';
  }

  async processEntity(
    entity: Entity,
    location: LocationSpec,
    emit: CatalogProcessorEmit,
  ): Promise<Entity> {
    // 只处理 Component 类型
    if (entity.kind !== 'Component') {
      return entity;
    }

    // 从注解中读取团队标签，写入 spec.owner
    const teamLabel = entity.metadata.annotations?.['example.com/team'];
    if (teamLabel && !entity.spec?.owner) {
      return {
        ...entity,
        spec: {
          ...entity.spec,
          owner: `group:default/${teamLabel}`,
        },
      };
    }

    return entity;
  }
}

开发自定义处理器时需要注意几个关键点。第一，保持幂等性：同一个实体多次经过处理器，结果应该一致，不能产生累积副作用。第二，只修改必要字段：处理器应该尽量少地改动实体，避免覆盖其他处理器或用户显式声明的值。第三，错误处理要明确：如果处理器遇到无法处理的情况，应该抛出带有清晰信息的错误，而不是静默返回原实体。

注册自定义处理器需要在后端启动时将其加入 catalog 模块：

// packages/backend/src/index.ts
const catalogModule = createBackendModule({
  pluginId: 'catalog',
  moduleId: 'team-label-processor',
  register(env) {
    env.registerInit({
      deps: { catalog: catalogProcessingExtensionPoint },
      async init({ catalog }) {
        catalog.addProcessor(new TeamLabelProcessor());
      },
    });
  },
});

四、实体校验与错误处理

实体校验发生在处理器链执行之后、写入数据库之前。Backstage 使用基于 JSON Schema 的校验机制，每种 Kind 都有对应的 schema 定义。校验失败时，实体不会被写入目录，但错误信息会被记录在 processing_errors 表中，可以通过目录 API 或前端界面查看。

常见的校验错误包括：缺少必填字段（如 metadata.name）、字段类型不匹配（如 spec.lifecycle 应为字符串却给了数组）、引用不存在的实体（如 spec.owner 指向一个未注册的 Group）。处理这些错误时，建议先检查 catalog-info.yaml 的语法和字段拼写，再确认被引用的实体是否已经注册。

五、与代码托管平台集成

与 GitHub、GitLab、Bitbucket 的集成主要解决两个问题：实体发现和实体读取。发现是指自动扫描组织下的仓库并注册实体；读取是指从仓库中拉取 catalog-info.yaml 文件内容。

以 GitHub 为例，集成配置通常包括以下步骤。首先，在 app-config.yaml 中配置集成凭证：

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

然后，在目录配置中启用 GitHub 发现处理器：

catalog:
  providers:
    github:
      providerId:
        organization: 'my-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'
          allowForks: false
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

这段配置的含义是：每 30 分钟扫描一次 my-org 组织下所有仓库的 main 分支，查找根目录的 catalog-info.yaml 并注册。GitLab 和 Bitbucket 的配置结构类似，只是 provider 名称和部分字段不同。

对于需要更精细控制的场景，可以使用 GithubOrgEntityProvider 或自定义 EntityProvider。EntityProvider 与处理器的区别在于：Provider 负责“从哪里获取数据”，Processor 负责“如何加工数据”。两者配合，才能完成从代码托管平台到目录的完整链路。

集成完成后，可以通过 Backstage 的目录页面观察实体是否按预期出现。如果发现实体缺失，优先检查三个位置：Provider 的调度日志、处理器的错误记录、以及目标仓库中 catalog-info.yaml 的路径和分支是否与配置匹配。