3. 插件架构基础：Backstage 插件模型、前端与后端插件分离、插件包结构解析

Backstage 的插件体系是其扩展能力的核心。每个插件都是一个独立的功能单元，遵循“前端 + 后端”分离的架构模式。理解插件模型、前后端分离机制以及标准包结构，是进行插件调试与基线核验的前提。

3.1 插件模型：App 与 Plugin 的关系

Backstage 采用“App 聚合 Plugin”的模型。App 是一个容器，负责加载、路由、主题和全局配置；Plugin 是独立的功能模块，通过标准接口注册到 App 中。每个 Plugin 可以包含前端组件、后端 API、实体提供者、权限策略等。

3.2 前端与后端插件分离

Backstage 强制将插件的前端和后端拆分为独立的包。这种分离带来了以下优势：

• 独立部署： 前端插件运行在浏览器中，后端插件运行在 Node.js 服务中，可以分别扩缩容。
• 职责清晰： 前端负责 UI 渲染和用户交互，后端负责数据处理、外部系统集成和权限控制。
• 调试隔离： 前端问题通常出现在组件渲染或 API 调用上，后端问题则集中在服务逻辑和数据库访问上。

3.3 插件包结构解析

一个标准的 Backstage 插件通常包含以下目录和文件。理解这些结构有助于快速定位调试目标。

plugins/
  └── my-plugin/                    # 插件根目录
      ├── package.json              # 插件元数据、依赖、入口
      ├── README.md                 # 插件说明文档
      ├── src/
      │   ├── index.ts              # 插件入口，导出 createPlugin
      │   ├── plugin.ts             # 插件定义，注册路由、组件、API
      │   ├── components/           # 前端 UI 组件
      │   │   ├── MyComponent.tsx
      │   │   └── index.ts
      │   ├── api/                  # 前端 API 客户端
      │   │   ├── MyApiClient.ts
      │   │   └── index.ts
      │   ├── routes.ts             # 前端路由配置
      │   └── types.ts              # TypeScript 类型定义
      ├── dev/                      # 开发环境配置
      │   └── index.ts
      ├── config.d.ts               # 插件配置类型声明
      └── dist/                     # 构建产物（调试时通常忽略）

3.4 插件注册与生命周期

插件在 App 中的注册过程决定了其加载顺序和可用性。调试时需关注以下生命周期阶段：

1. 初始化： 插件构造函数执行，注册路由和 API。
2. 挂载： 前端组件首次渲染，触发 API 调用。
3. 运行： 用户交互，数据更新，组件重渲染。
4. 卸载： 页面切换，组件销毁，清理资源。

3.5 插件间通信与依赖

插件之间可以通过 Backstage 的 Plugin API 和 Entity 系统进行通信。调试时需注意：

• API 引用： 插件 A 可以通过 createApiRef 暴露接口，插件 B 通过 useApi 注入。
• 实体上下文： 插件通过 EntityProvider 共享实体数据，避免重复获取。
• 事件总线： 使用 EventBus 进行松耦合通信，适合跨插件通知。