3. 插件基础架构：目录结构、前后端分离与加载机制

Backstage 插件采用“前端 + 后端”分离的架构设计，每个插件在代码仓库中拥有独立的目录结构。理解这一基础架构是开发高质量插件的起点，也是后续性能调优的前提。

3.1 插件目录结构规范

一个标准的 Backstage 插件在 monorepo 中通常包含以下核心目录与文件：

3.2 前端插件与后端插件分离

Backstage 强制将前端（Frontend）与后端（Backend）逻辑拆分为两个独立的 npm 包，但通常放在同一个插件目录下。这种分离带来了以下优势：

• 独立部署： 前端插件运行在浏览器中，后端插件运行在 Node.js 服务端，可分别扩缩容。
• 关注点分离： 前端负责 UI 渲染与用户交互，后端负责数据聚合、代理外部 API、鉴权等。
• 性能隔离： 后端插件可以独立进行缓存、连接池等调优，不影响前端打包体积。

以下是一个典型的前后端分离代码结构示例：

plugins/my-catalog-plugin/
├── package.json                 # 前端包
├── src/
│   ├── index.ts                 # 导出 createPlugin
│   ├── components/
│   │   ├── CatalogPage.tsx
│   │   └── EntityCard.tsx
│   └── routes.ts
├── backend/
│   ├── package.json             # 后端包（独立依赖）
│   ├── src/
│   │   ├── index.ts             # 导出 createRouter
│   │   ├── service/
│   │   │   └── catalogService.ts
│   │   └── types.ts
│   └── config.d.ts
└── README.md

3.3 插件注册与加载机制

Backstage 的插件注册采用“声明式”模式，通过 createPlugin 和 createRouteRef 等 API 将插件挂载到应用骨架中。加载过程分为三个阶段：

1. 静态注册： 在 app-config.yaml 或 packages/app/src/App.tsx 中引入插件实例。
2. 动态发现： 启动时，Backstage 扫描所有已安装的 @backstage/plugin-* 包，自动收集插件元数据。
3. 运行时加载： 前端通过 React Router 按需加载插件页面，后端通过 Express 中间件注册路由。

下面的 SVG 图展示了插件从注册到加载的完整流程：

3.4 插件加载性能关键点

在插件注册与加载过程中，以下三个环节对性能影响最大：

3.5 插件间通信与数据流

在服务目录平台中，多个插件可能需要共享实体数据或事件。Backstage 提供了两种官方通信方式：

• 通过 Catalog API： 插件通过 catalogClient 读取/写入实体，这是最推荐的方式，数据流清晰且可审计。
• 通过 Event Bus： 使用 @backstage/plugin-events-backend 实现跨插件事件通知，适用于异步解耦场景。

下面的 SVG 图展示了插件间数据流的典型拓扑：