Backstage Scaffolder 如何为自定义 Action 启用并测试 dry run【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage如果你写了一个自定义 Scaffolder action比如调用 GitHub 创建 webhook、写代码仓库的 action直接跑模板会立刻产生真实副作用无法安全地验证模板逻辑。Backstage 的 Scaffolder 提供了 dry run空跑机制在不真正执行外部操作的前提下模拟 action 的运行过程并返回执行日志与生成的工作区文件。本文的完整路径是在 action 声明上启用 dry run → 在 handler 中处理 dry run 分支 → 为分支写单元测试 → 通过 dry-run API 或 contrib 提供的命令行工具做一次端到端验证。工作机制isDryRun 何时为 trueActionContext上的isDryRun字段有一个关键限制只有当 action 被标记为支持 dry run 时它才会为 true见 types.ts 中isDryRun的注释。也就是说如果 action 没有声明supportsDryRun: true即使整个模板走的是 dry-run 流程handler 里的ctx.isDryRun也不会成立你必须显式启用。dry run 的执行入口在后端 createDryRunner.ts它把请求携带的模板目录内容解包到临时目录以isDryRun: true驱动工作流执行所有步骤并在末尾附加一个dry-run:extract步骤把工作区序列化回响应最后清理临时目录。第一步在 action 上声明 supportsDryRun在你定义 action 行为的函数里给createTemplateAction的配置对象加上supportsDryRun: trueexport function exampleAction() { return createTemplateAction{ example: string; }({ id: action:example, description: Example action, schema: { input: { type: object, properties: { example: { title: example, type: string, }, }, }, }, supportsDryRun: true, async handler(ctx) { ... }, }); }其中id、description、schema.input换成你的 action 实际的标识与输入 schema...是你 handler 中已有的业务逻辑。这是唯一的“启用”动作不需要其他后端配置。第二步在 handler 中处理 dry run 分支声明之后在 handler 里对ctx.isDryRun做检查。检查命中时执行 dry run 场景下期望的行为官方文档给出的示例是打印日志后直接返回也可以输出非敏感的输入信息避免走到真实副作用的逻辑async handler(ctx) { ... // If this is a dry run, log and return if (ctx.isDryRun) { ctx.logger.info(Dry run complete); return; } ... }要点return必须放在所有会产生外部副作用的调用之前。dry run 的意义就是“模拟而不变更环境”handler 中任何在检查之后的真实 API 调用都不应被执行。第三步为 dry run 分支写单元测试官方文档要求为 dry run 分支补充测试。示例中...mockContext是你测试文件里已有的模拟上下文对象input按该 action 的输入 schema 填入expect(...)断言“action 没有执行”例如断言某个被 mock 的外部客户端方法未被调用it(should not perform action during dry run, async () { ... // Create the context object with the necessary properties for a dry run const ctx { ...mockContext, isDryRun: true, input: { ... }, }; // Call the handler with the context await action.handler(ctx); expect(...); });这段测试直接调用action.handler(ctx)不依赖运行中的 Backstage 实例适合放进 action 所属模块现有的 Jest 测试文件。第四步调用 dry-run API 做端到端验证单元测试通过只代表分支逻辑正确完整验证要走 Scaffolder 的 dry-run 接口POST /api/scaffolder/v2/dry-run接口定义见 openapi.yaml 中的DryRun操作。请求体需要四个字段template、values、directoryContents必填secrets可选{ template: { apiVersion: backstage.io/v1beta3, kind: Template, metadata: { name: my-template }, spec: { steps: [] } }, values: {}, directoryContents: [ { path: template.yaml, base64Content: template.yaml 的 base64 } ] }各字段的用途template是完整的 Template 实体会被校验是否为合法的 templatevalues是模板参数的取值directoryContents是模板目录文件的 base64 内容secrets是键值均为字符串的机密。注意上面 JSON 仅为字段结构示意template的具体内容必须是你真实的模板实体。路由侧的处理逻辑见 router.ts包含两个前置判断可据此排查请求失败权限请求需要同时满足taskCreatePermission与templateDryRunPermission。如果你的部署启用了后端权限backend permissions匿名或无权限的调用会被拒绝参数校验values不匹配模板spec.parameters时接口返回 400 并在响应体中给出errors字段提示“Could not execute dry run”。成功时200返回DryRunResult包含log每个步骤的日志消息含stepId、status、directoryContentsdry run 结束时工作区中的文件和output。判断方式检查log中你的 action 是否打出了 dry run 分支的日志如Dry run complete且没有发生真实外部变更。可选用 contrib 的 scaffolder-dry 命令行工具如果你只想对一个运行中的实例本地或远端反复测试模板可以用 contrib/scaffolder 提供的命令行脚本实现见 template-testing-dry-run.md。它对运行中的实例发起上述 dry-run 请求参数依次为实例 URL、模板源目录、输入值的 YAML 文件、输出目录scaffolder-dry http://localhost:7007/ template-directory values.yml output-directory其中template-directory是包含template.yaml的模板目录values.yml是渲染模板所需的输入output-directory是 dry run 结果文件的落盘位置——该目录内容会由脚本写入属于预期副作用。如果你使用 backend permissions需要通过--token传入当前浏览器会话的前端 auth tokenscaffolder-dry --token $FRONTEND_TOKEN http://localhost:7007/ template-directory values.yml output-directory脚本会把响应中的日志逐条打印到终端并把directoryContents写入目标目录方便你直接核对 dry run 生成的文件是否符合预期。限制与核对清单ctx.isDryRun仅在 action 声明了supportsDryRun: true时为 true遗漏声明会导致 dry run 时仍走真实逻辑这是最常见的配置失误。dry run 只是“模拟而不变更”不校验外部系统如 GitHub的连通性与凭据有效性handler 中 dry run 分支能覆盖的就是你在检查之后跳过的那些调用。端到端验证要求一个正在运行的 Backstage 实例且调用方具备taskCreatePermission和templateDryRunPermission。完整的启用、分支处理与单测写法见 dry-run-testing.md。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考