SuperAPI AI 工具集

creating-backstage-scaffolder-action

部署与运维

查看项目

更新于 10-16 02:21

技能介绍

创建 Backstage Scaffolder Action

【用途】 当需要构建供 scaffolder 模板从 YAML 步骤中调用的自定义动作时使用本技能,例如 acme:user:create、myorg:slack:notify 这类步骤;也适用于编辑已有的 scaffolder-backend-module-* 插件。

【你将构建什么】 一个 scaffolder action 本质上是一个后端模块,通过 createBackendModule({ pluginId: 'scaffolder', ... }) 向 scaffolderActionsExtensionPoint 注册一个 TemplateAction。它由两部分组成:

  1. 动作本身(通过 createTemplateAction 创建)
  2. 注册该动作的模块

【选择正确的模式】

  • 独立模式(Standalone):编辑已有的 scaffolder-backend-module-*。
  • post-scaffold 模式(由 creating-backstage-plugin 为 scaffolder-backend-module 调用):同时脚手架生成两个文件——动作定义 + 模块注册。

相关参考文档:动作本身参见 references/template-action.md,负责将其接入的模块参见 references/module-registration.md。

【两种调用模式】

  • Standalone:编辑已有 scaffolder-backend-module-*。
  • Post-scaffold(由 creating-backstage-plugin 为 scaffolder-backend-module 调用):同时生成两个文件——动作定义 + 模块注册。

【常见注意事项】

  • 动作 id 遵循 <namespace>:<name>(或 <namespace>:<group>:<name>)命名约定。命名空间由你自行选择,应选一个稳定且不会与已安装模块目录中其他动作冲突的名称。
  • Schema 是工厂函数,不是原始 Zod schema:应写作 input: { name: z => z.string() },而不是 input: { name: z.string() }。Backstage 使用此模式在内部固定其 Zod 版本;请对照 ../backstage/plugins/scaffolder-node/src/actions/createTemplateAction.ts 核实写法。
  • 动作处理器上下文(ctx)提供:ctx.logger、ctx.workspacePath、ctx.input(由 input schema 推导类型)、ctx.output(name, value) 用于发出输出、ctx.getInitiatorCredentials() 获取用户身份、ctx.createTemporaryDirectory() 用于沙箱化工作、ctx.signal(AbortSignal)用于取消、ctx.isDryRun 用于 dry-run 模式。
  • 长时间运行的动作应定期调用 ctx.logger.info——scaffolder UI 会将日志流式展示给用户。
  • 若要支持 dry-run,需设置 supportsDryRun: true,并在处理器中检查 ctx.isDryRun 以跳过副作用操作。
  • 模板可以使用 if: ${{ always() }} 和 if: ${{ failure() }} 控制失败后步骤的执行:always() 无条件运行,failure() 仅在先前步骤失败时运行。这些由模板引擎内建,动作作者无需为此做任何额外处理。

【适用场景】 需要为 Backstage scaffolder 模板扩展自定义后端步骤、封装内部系统调用(如创建用户、发送通知)或改造现有 scaffolder 后端模块插件时。

【限制】 资料未提供具体的收费、价格、平台支持范围与效果等信息。