creating-backstage-catalog-provider

创建 Backstage Catalog Provider

何时使用此技能

• 构建一个从外部来源（Azure DevOps、GitHub 主题搜索、内部资产注册表、JSON 文件等）导入目录实体的模块
• 编辑现有的 catalog-backend-module-* 插件
• 导入会定期运行（provider 模式）——若要一次性处理实体定义文件，请改用 CatalogProcessor

构建内容

目录 provider 是一个后端模块（createBackendModule({ pluginId: 'catalog', ... })），用于通过扩展点注册 provider。provider 有两种模式——根据数据量选择。

先选择模式：普通模式还是增量模式

在以下情况下使用普通 EntityProvider……	在以下情况下使用 IncrementalEntityProvider……
实体总数较少（最多约数百个）	实体总数较多（数千个以上）
可以轻松地将完整实体集保存在内存中	将完整实体集保存在内存中并不实际
数据源通过一次往返（或少量几次）返回完整快照	数据源支持分页——游标／页令牌／偏移量等
正在制作原型或构建 POC	正在为生产级目录交付功能
刷新频率较低	写入频率或规模较高；增量模式可处理批处理、退避和重试

这两种模式注册到不同的扩展点，运行时语义也不同：

• 普通模式注册到 @backstage/plugin-catalog-node 中的 catalogProcessingExtensionPoint。采用方无需额外安装。
• 增量模式注册到 @backstage/plugin-catalog-backend-module-incremental-ingestion 中的 incrementalIngestionProvidersExtensionPoint。采用方还必须安装 catalogModuleIncrementalIngestionEntityProvider（负责协调批次并通过目录数据库持久化游标的框架模块）。

如果无法提前确定，默认选择普通模式。之后迁移到增量模式只需进行机械式修改——领域数据获取逻辑相同，只需更改框架接线方式。

如果确实无法确定数据量，请询问用户。粗略阈值：少于 500 个实体 → 普通模式即可；超过 10,000 个 → 必须使用增量模式；介于两者之间 → 询问数据源是否支持分页以及数据增长趋势。

选择合适的模式

正在构建……	参考资料
普通 EntityProvider 类（小／中等数据量的默认选择）	references/entity-provider.md（普通模式部分）
IncrementalEntityProvider 类（大数据量）	references/entity-provider.md（增量模式部分）
为任一类型接线的模块	references/module-registration.md

两种调用模式

• 独立模式：编辑现有的 catalog-backend-module-* 插件。
• 脚手架生成后（由 creating-backstage-plugin 为 catalog-provider-module 调用）：同时生成两个文件——provider 类和模块注册。

常见注意事项

• 提供者的 getProviderName() 在整个目录中必须唯一（普通提供者和增量提供者都遵循此规则）。请使用稳定的名称——发出的实体通过该名称与提供者关联；重命名会导致实体失去关联。
• 普通提供者： applyMutation({ type: 'full', entities }) 会替换该提供者拥有的全部实体。applyMutation({ type: 'delta', added, removed }) 会添加或移除单个条目——适用于只能逐步获知变更的情况。请注意，这是 增量变更，与 IncrementalEntityProvider 模型不同。
• 普通提供者： 直到运行 connect() 后，连接才可用——在任何可能于 connect() 运行前调用的方法中，都要检查 this.connection 是否为 undefined。
• 普通提供者： 不要直接在 connect() 中从外部系统获取数据——接收一个 SchedulerServiceTaskRunner，并在 connect() 中调用 this.schedule.run({ id, fn })，以便定期执行任务并在重启后继续运行。
• 增量提供者： 迭代循环由框架管理。你的 next(context, cursor?) 会返回一页数据；框架会使用你之前返回的游标反复调用该方法，并将状态持久化到目录数据库中。不要自行安排刷新任务。
• 增量提供者： 使用者必须在你的模块之外安装 catalogModuleIncrementalIngestionEntityProvider（来自 @backstage/plugin-catalog-backend-module-incremental-ingestion）。请在模块的 README 中说明这一前置要求。
• catalogProcessingExtensionPoint 来自 @backstage/plugin-catalog-node（库包）。incrementalIngestionProvidersExtensionPoint 来自 @backstage/plugin-catalog-backend-module-incremental-ingestion。不要让模块依赖 @backstage/plugin-catalog-backend——它是宿主插件。