3. 插件开发基础：插件生命周期、插件类型与 Scaffolder 模板概念
在 Backstage 中，插件是功能扩展的核心单元。理解插件的生命周期、类型划分以及 Scaffolder 模板的工作方式，是进入实际开发前必须打牢的基础。本章将围绕这三个关键概念展开，帮助你建立清晰的插件开发认知模型。
3.1 插件生命周期
Backstage 插件的生命周期分为三个阶段：注册、加载和运行时。每个阶段都有明确的职责和触发时机。
| 阶段 | 触发时机 | 主要行为 |
|---|---|---|
| 注册 | 应用启动时，通过 createPlugin 或 createFrontendPlugin 等 API 注册 |
声明插件 ID、路由绑定、扩展点注册、依赖声明 |
| 加载 | 用户首次访问插件路由或触发相关扩展点时 | 动态导入插件模块、解析配置、初始化状态 |
| 运行时 | 插件激活后持续运行 | 处理用户交互、调用后端 API、更新 UI 状态 |
开发提示： 注册阶段应保持轻量，避免执行耗时操作。所有初始化逻辑应推迟到加载阶段执行，以优化应用启动性能。
3.2 插件类型
Backstage 插件按运行环境和职责分为三种类型：前端插件、后端插件和独立插件。理解它们的差异有助于合理划分功能边界。
| 类型 | 运行环境 | 典型用途 | 示例 |
|---|---|---|---|
| 前端插件 | 浏览器（React 应用） | UI 组件、页面路由、前端逻辑 | Catalog 页面、TechDocs 阅读器 |
| 后端插件 | Node.js 服务端 | API 接口、数据处理、代理请求 | Scaffolder 后端、Search 索引服务 |
| 独立插件 | 独立进程或容器 | 外部服务集成、定时任务、事件处理 | Lighthouse 审计、PagerDuty 事件同步 |
架构原则： 前端插件只负责展示和交互，后端插件处理业务逻辑和数据持久化，独立插件用于对接外部系统。保持职责单一，避免前端插件直接调用数据库或后端插件渲染 UI。
3.3 Scaffolder 模板概念
Scaffolder 是 Backstage 内置的软件模板引擎，允许用户通过预定义的模板快速创建新项目或组件。模板本质上是一个 YAML 配置文件，描述了模板的输入参数、步骤和输出结果。
一个典型的 Scaffolder 模板包含以下核心部分：
- metadata：模板名称、描述、标签等元信息。
- parameters：定义用户需要输入的变量，如项目名称、语言类型、版本号等。
- steps：按顺序执行的步骤列表，每个步骤调用一个 action（如
fetch:template、catalog:register）。 - output：模板执行完成后返回的结果，通常包含新创建的实体引用或 URL。
# template.yaml 示例
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: react-app-template
title: React 应用模板
description: 创建一个新的 React 前端项目
spec:
parameters:
- title: 项目信息
properties:
projectName:
title: 项目名称
type: string
description: 输入你的项目名称
language:
title: 编程语言
type: string
enum: ['TypeScript', 'JavaScript']
steps:
- id: fetch-base
name: 拉取模板代码
action: fetch:template
input:
url: ./skeleton
values:
projectName: ${{ parameters.projectName }}
- id: register
name: 注册到目录
action: catalog:register
input:
catalogInfoUrl: ${{ steps['fetch-base'].output.result }}/catalog-info.yaml
output:
links:
- title: 打开项目
url: ${{ steps['fetch-base'].output.result }}
常见误区： 模板中的
parameters 字段支持 JSON Schema 校验，但不要将敏感信息（如密码、）作为模板参数传递。敏感数据应通过 Backstage 的 Secrets 管理或环境变量注入。
3.4 插件类型与模板的协作关系
在实际开发中，插件类型和 Scaffolder 模板并非孤立概念。前端插件可以调用 Scaffolder 后端 API 来触发模板执行，后端插件可以注册自定义 action 来扩展模板能力，独立插件则可以作为模板步骤中的外部服务调用目标。
- 前端插件 → Scaffolder：通过
scaffolderApi调用模板列表和创建任务。 - 后端插件 → Scaffolder：注册自定义 action，如
publish:github、debug:log。 - 独立插件 → Scaffolder：作为模板步骤中的 HTTP 回调或事件监听器。