using-backstage-backend-system

Backstage 后端系统模式

何时使用此技能

• 定义新的后端插件（src/plugin.ts）
• 定义扩展其他插件的后端模块（src/module.ts）
• 在完整插件和模块之间进行选择
• 暴露扩展点，以便其他模块扩展你的插件

选择合适的模式

正在构建……	模式	参考资料
插件本身	createBackendPlugin({ pluginId, register })	references/plugin-definition.md
扩展其他插件的模块	createBackendModule({ pluginId, moduleId, register })	references/modules.md
供其他模块扩展的扩展点	createExtensionPoint<T>({ id })	references/extension-points.md

两种调用模式

• 独立模式：编辑现有后端插件/模块。
• 脚手架后处理（由 creating-backstage-plugin 针对 backend-plugin、backend-plugin-module、catalog-provider-module、scaffolder-backend-module 调用）：接入规范结构（src/plugin.ts 或 src/module.ts，以及重新导出的 src/index.ts）。

常见注意事项

• 所有接线相关的导入都来自 @backstage/backend-plugin-api，而不是仅用于前端的 @backstage/core-plugin-api。
• register(env) 回调会接收一个环境对象，其中包含 env.registerInit({ deps, async init }) 和 env.registerExtensionPoint(point, impl)。deps 是初始化函数所需服务引用的映射；init 接收解析后的实例。
• 每个插件/模块只能调用一次 registerInit。必须先调用 registerExtensionPoint，再调用 registerInit。
• 插件作用域与根作用域服务：大多数引用（logger、httpRouter、database、scheduler、auth、httpAuth、userInfo、cache、discovery、urlReader、lifecycle、permissions）都属于插件作用域——每个插件都会获得自己的实例，并带有插件感知行为（例如，日志记录器会预先附加 pluginId 标签，数据库会为每个插件提供独立的架构）。六个引用（rootConfig、rootLogger、rootLifecycle、rootHealth、rootHttpRouter、rootInstanceMetadata）属于根作用域——由所有插件共享同一个实例。两类服务都可以在插件的 register 代码块中声明依赖；二者的区别在于行为，而非注入语法。
• 插件的 pluginId 和模块的 moduleId 必须符合模式 [a-z][a-z0-9-]*（字母、数字、连字符；必须以字母开头）。
• 模块依赖于目标插件库包（例如 @backstage/plugin-catalog-node）导出的扩展点，而不是插件的主包。