📚 课程目录第2章 Backstage架构基础

2. Backstage 架构基础：核心组件、插件生命周期与依赖注入

理解 Backstage 的架构是进行插件隔离与容量规划的前提。Backstage 采用微内核 + 插件化架构，其核心由 App、Backend 和 Plugin 三大组件构成。三者通过明确的接口和生命周期管理协同工作，依赖注入机制则负责将运行时能力（如数据库、缓存、日志）按需注入到插件中。

2.1 核心组件：App、Backend、Plugin

Backstage 的运行时分为前端（App）和后端（Backend），插件（Plugin）则横跨两者，提供业务功能。下表总结了各组件的职责与关键特征：

组件	职责	运行环境	关键特征
App	前端应用容器，负责 UI 组装、路由、主题、身份认证	浏览器（React SPA）	通过 `createApp` 创建；集成所有前端插件；提供统一的 `AppContext`
Backend	后端服务容器，负责 API 网关、认证、数据库、事件总线	Node.js 进程	通过 `createBackend` 创建；管理后端插件生命周期；提供 `BackendContext`
Plugin	功能模块，可包含前端页面、后端 API、实体处理器等	前端 + 后端	通过 `createPlugin` 或 `createBackendPlugin` 定义；独立版本、独立配置

  架构要点： App 和 Backend 是“壳”，Plugin 是“核”。壳负责基础设施（路由、认证、数据库连接），核负责业务逻辑。这种分离使得插件可以在不修改壳代码的情况下独立开发、测试和部署。

2.2 插件生命周期

每个 Backstage 插件都遵循一个明确的生命周期，从注册到销毁。理解生命周期是进行故障域隔离和资源规划的基础。下图展示了插件在前端和后端的完整生命周期阶段：

故障域启示： 后端插件的 start 和 stop 阶段是资源争用的高发区。在容量规划时，应确保每个插件的启动顺序和资源配额（如内存、连接数）是独立可控的，避免一个插件的启动失败阻塞整个 Backend 进程。

2.3 依赖注入机制

Backstage 使用 依赖注入（DI） 来解耦插件与基础设施。插件不直接创建数据库连接或日志实例，而是通过 Service 接口声明依赖，由 Backend 容器在运行时注入具体实现。这种机制对插件隔离和测试至关重要。

2.3.1 核心概念

Service：抽象接口，如 DatabaseService、LoggerService、ConfigService。
ServiceRef：服务的唯一标识，用于在 DI 容器中查找和注入。
ServiceFactory：负责创建 Service 实例的工厂函数，可配置作用域（单例、请求级）。
DI Container：Backend 内部的 IoC 容器，管理所有 Service 的注册、解析和生命周期。

2.3.2 依赖注入流程

以下代码片段展示了一个后端插件如何声明依赖并获取注入的服务：

// 1. 定义 ServiceRef（通常在 @backstage/backend-plugin-api 中）
export const databaseServiceRef = createServiceRef<DatabaseService>('core.database');

// 2. 插件声明依赖
export const myPlugin = createBackendPlugin({
  pluginId: 'my-plugin',
  register(env) {
    env.registerInit({
      deps: {
        db: databaseServiceRef,   // 声明依赖
        logger: coreServices.logger,
      },
      async init({ db, logger }) {
        // 3. 运行时注入
        await db.connect();
        logger.info('My plugin connected to database');
      },
    });
  },
});

2.3.3 依赖注入与插件隔离

DI 机制天然支持故障域隔离，因为每个插件只看到自己声明的依赖，不会直接访问其他插件的内部状态。下表总结了 DI 在隔离和容量规划中的关键作用：

DI 特性	对插件隔离的影响	对容量规划的影响
接口隔离	插件只依赖接口，不依赖实现；可替换或 mock 依赖进行单元测试	可独立评估每个插件的资源消耗（如数据库连接池大小）
作用域控制	Service 可配置为插件级单例或请求级实例，避免状态污染	支持按插件分配独立的连接池、缓存实例，实现资源隔离
延迟初始化	插件只有在首次被请求时才初始化依赖，减少启动时的资源争用	允许按需分配资源，避免预分配导致的浪费
生命周期绑定	Service 的生命周期与插件绑定，插件停止时自动释放其依赖	防止资源泄漏，确保容量回收的及时性

常见陷阱： 不要在后端插件中直接使用 new SomeService() 创建依赖。这会绕过 DI 容器，导致该实例无法被统一管理，在插件卸载时无法自动释放，最终造成内存泄漏和容量规划失真。

2.4 架构总览：组件协作关系

下图展示了 App、Backend、Plugin 三者之间的协作关系，以及依赖注入在其中的位置：

2.5 本章小结

App 和 Backend 是基础设施容器，Plugin 是业务功能单元。
插件生命周期分为前端（注册→加载→挂载→卸载）和后端（注册→初始化→启动→停止），每个阶段都是故障域隔离的切入点。
依赖注入 通过 ServiceRef 和 DI Container 实现插件与基础设施的解耦，是资源隔离和容量规划的技术基础。
在后续章节中，我们将基于这些架构特性，设计插件的故障域边界和容量测试方案。