SuperAPI AI 工具集

creating-backstage-catalog-provider

通用与其它

查看项目

更新于 10-16 02:27

技能介绍

用途:构建一个从外部数据源摄取目录实体的 Backstage 后端模块,适用于 Azure DevOps、GitHub 主题搜索、内部资产注册表、JSON 文件等来源,也适用于编辑已有的 catalog-backend-module-* 插件。若是一次性处理实体定义文件,应改用 CatalogProcessor 而非 provider。

主要能力:构建 createBackendModule({ pluginId: 'catalog', ... }) 模块,将 provider 注册到扩展点。提供两种 provider 模型:普通 EntityProvider 适合实体总数较小(约数百)、全集可放入内存、源可一次返回完整快照、原型或低频刷新的场景,注册到 @backstage/plugin-catalog-node 的 catalogProcessingExtensionPoint,使用者无需额外安装;IncrementalEntityProvider 适合实体数达数千以上、源支持分页(cursor/page-token/offset 等)、生产规模与高频写入的场景,注册到 @backstage/plugin-catalog-backend-module-incremental-ingestion 的 incrementalIngestionProvidersExtensionPoint,使用方还须安装 catalogModuleIncrementalIngestionEntityProvider。若不确定默认选普通模型,迁移到增量模型较机械。

使用方式:参考 references/entity-provider.md 编写 provider 类,参考 references/module-registration.md 编写接线模块;支持独立模式(编辑已有插件)与脚手架后模式(与 creating-backstage-plugin 配合同时生成 provider 类与模块注册)。

限制与注意事项:getProviderName() 必须在整个目录内唯一且稳定,改名会使已发出的实体孤立;普通 provider 的 applyMutation 支持 full(整体替换)与 delta(增删条目),此 delta 不等同于增量 provider 模型;connect() 之前 connection 不可用,须防 undefined;不要在 connect() 中直接请求外部系统,应通过 SchedulerServiceTaskRunner 调用 this.schedule.run({ id, fn });增量 provider 的迭代循环由框架掌管,next(context, cursor?) 每次返回一页,框架反复调用并持久化游标,不要自行调度刷新;增量模块的使用前提是安装 catalogModuleIncrementalIngestionEntityProvider,需在 README 中说明;catalogProcessingExtensionPoint 来自 @backstage/plugin-catalog-node,incrementalIngestionProvidersExtensionPoint 来自 @backstage/plugin-catalog-backend-module-incremental-ingestion,模块不应依赖 @backstage/plugin-catalog-backend。资料未提供具体版本要求与命令细节。