Backstage v1.12.0 版本解析：Catalog 游标分页、Scaffolder Zod 动作定义与后端系统导出重命名

Backstage v1.12.0 版本解析Catalog 游标分页、Scaffolder Zod 动作定义与后端系统导出重命名【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南围绕 Backstage 开源开发者门户框架的 v1.12.0 版本发布展开系统梳理该版本引入的核心能力软件目录Catalog基于游标cursor的分页查询接口、Scaffolder 模板动作的zod声明式输入输出、新后端系统模块的命名规范重命名以及两个新插件Octopus Deploy、StackStorm的落地方式。读者读完本篇后能够掌握 v1.12.0 新增 API 的请求/响应结构与配置要点了解如何利用zod编写类型安全的 Scaffolder 动作并能在升级时正确迁移被重命名的导出符号。一、版本概览与升级说明v1.12.0 是 Backstage 的一个常规增量版本主体由一批小的功能增强与缺陷修复构成同时在开发体验上有若干明显改进。本仓库的正式发布说明位于 docs/releases/v1.12.0.md对应的完整逐包变更记录changeset位于 docs/releases/v1.12.0-changelog.md。安全修复该版本不包含任何安全修复项。升级建议官方推荐将 Backstage 项目持续保持到最新版本具体升级指引可参考 keeping-backstage-updated。版本配套本次发布伴随多个核心包的主/次版本号更新例如backstage/backend-plugin-api升至 0.5.0、backstage/backend-tasks升至 0.5.0、backstage/catalog-client升至 1.4.0、backstage/core-app-api升至 1.6.0、backstage/plugin-catalog-backend升至 1.8.0、backstage/plugin-scaffolder-backend升至 1.12.0 等。二、核心亮点用 zod 定义 Scaffolder 动作的输入输出2.1 为什么引入 zod此前编写自定义 Scaffolder 动作时需要在input与output中手写 JSON Schema并同时维护对应的 TypeScript 类型二者极易失步。v1.12.0 起动作作者可以改用zodschema 声明输入与输出编辑器内即可获得即时类型反馈比手工编写 JSON Schema 更直观、更安全。2.2 源码层面的实现机制本仓库 plugins/scaffolder-node/src/actions/createTemplateAction.ts 中createTemplateAction被泛型化为同时接受普通 JSON Schema 风格对象与zod schemazImpl z.ZodType两种形态泛型参数TInputSchema/TOutputSchema既可以是一组字段函数对象{ [key in string]: (zImpl: typeof z) z.ZodType }也可以是单个函数(zImpl: typeof z) z.ZodType内部通过z.infer...与z.output...推导出输入/输出的精确 TypeScript 类型从而让动作的handler参数获得完整类型检查函数内部createTemplateAction.ts通过parseSchemas将 zod schema 转换为 JSON Schema再以统一格式交给系统校验与渲染。也就是说zod 只是编写时的便利层最终在整个系统中流转的仍是 JSON SchemaTemplateAction的对外契约保持不变。在 plugins/scaffolder-node/src/actions/createTemplateAction.test.ts 中可找到对应测试验证了 zod 定义被正确转换为 JSON Schema 并参与safeParse校验。2.3 编写一个使用 zod 的模板动作在自定义动作模块中createTemplateAction的入参可简化为如下形态示意需按实际安装的版本引入依赖import { createTemplateAction } from backstage/plugin-scaffolder-node; import { z } from zod/v3; export const exampleAction createTemplateAction({ id: example:hello, description: 输出一段问候, schema: { input: (zImpl) zImpl.object({ name: zImpl.string().describe(被问候者的名字), times: zImpl.number().default(1).describe(重复次数), }), output: (zImpl) zImpl.object({ message: zImpl.string(), }), }, async handler(ctx) { ctx.output(message, hello ${ctx.input.name}.repeat(ctx.input.times)); }, });要点说明input/output中每个字段的.describe()会被带入最终的 JSON Schema 描述供模板参数表单展示通过zod的.default()、.optional()等能力可以自然表达参数默认值与可选性由于类型由 schema 自动推导ctx.input与ctx.output的键和值在编辑器内即可获得静态校验避免了类型与 schema 不一致的经典问题。2.4 配套的 Scaffolder 前端与行为增强同版本中backstage/plugin-scaffolder、backstage/plugin-scaffolder-react与backstage/plugin-scaffolder-backend也同步更新EntityPicker改为使用完整限定的实体引用fully qualified entity ref而不是人类可读的简化名称将useTaskStream、TaskBorder、TaskLogStream、TaskSteps等组件/钩子从plugin-scaffolder迁移进plugin-scaffolder-react便于其他前端复用任务流展示catalog:fetch动作扩展为可按实体引用一次获取多个实体catalog:write动作允许写入任意形状的对象当catalog:fetch获取不到实体且optional为false时会抛出错误。三、核心亮点从目录读取分页数据/entities/by-query3.1 新增的后端端点与客户端方法v1.12.0 为软件目录新增了带游标的分页查询端点GET /entities/by-query与对应的客户端方法queryEntities。它支持游标式分页首请求返回nextCursor后续请求携带cursor获取下一页同时响应中包含prevCursor以便回溯服务端过滤支持传统的 key-valuefilter语法与基于谓词的query语法$all、$any、$not、$exists、$in、$hasPrefix、$contains等逻辑与匹配操作符服务端排序通过orderFields如metadata.name,asc指定排序字段与方向字段裁剪通过fields仅返回所需字段减小响应体积。3.2 请求与响应类型本仓库 packages/catalog-client/src/types/api.ts 中完整定义了相关类型QueryEntitiesRequest QueryEntitiesInitialRequest | QueryEntitiesCursorRequestapi.tsQueryEntitiesInitialRequest支持fields、limit、offset、filter、query、orderFields、fullTextFilter以及totalItems取值include/exclude默认include设exclude可跳过总数统计以提升游标分页 UI 的性能api.tsQueryEntitiesCursorRequest仅需cursor并可选fields与limitapi.tsQueryEntitiesResponse返回items、totalItems以及含nextCursor/prevCursor的pageInfoapi.ts。其中filter用于传统 key-value 过滤query用于谓词式过滤二者可以同时提供。3.3 客户端调用示例// 首次请求过滤 排序 限制条数 const response await catalogClient.queryEntities({ filter: [{ kind: group }], limit: 20, fields: [metadata, kind], fullTextFilter: { term: A }, orderFields: { field: metadata.name, order: asc }, }); // 游标翻页携带 nextCursor 获取下一批 const nextPage await catalogClient.queryEntities({ cursor: response.pageInfo.nextCursor, limit: 20, fields: [metadata, kind], });上述示例会匹配所有名称以 A 开头、kind 为 group 的实体按名称升序返回若结果超过 20 条则可通过nextCursor继续获取prevCursor用于回到上一批。3.4 服务端路由与 OpenAPI 契约后端路由定义位于 plugins/catalog-backend/src/service/createRouter.tsPOST /entities/by-querycreateRouter.ts承载谓词式过滤查询GET /entities/by-querycreateRouter.ts承载 key-value 过滤与排序查询。服务端的 OpenAPI 描述位于 plugins/catalog-backend/src/schema/openapi.yaml其中给出了丰富的过滤示例例如/entities/by-query?filterkinduser,metadata.namespacedefaultfilterkindgroup,spec.type表示kinduser 且 namespacedefault或 kindgroup 且存在 spec.type同一 filter 内条件为 AND多个 filter 之间为 OR。排序示例/entities/by-query?orderFieldmetadata.name,asc默认情况下实体按其内部uid排序orderField后可跟asc升序或desc降序。此外该版本还同步新增了POST /locations/by-query用于对 Location 实体做同样的游标式查询。对应的路由测试集中在 plugins/catalog-backend/src/service/createRouter.test.ts如GET /entities/by-query与POST /entities/by-query两组 describe覆盖了过滤、排序、游标编解码以及非法游标/非法 limit 的错误处理可作为接口行为的权威参照。3.5 目录客户端与其他配套更新backstage/catalog-client新增queryEntities方法并修复了getEntitiesByRefs对缺失项返回undefined而非null的问题批量按引用获取batch fetch by ref与过滤例如启用授权时组合使用的缺陷得到修复backstage/plugin-catalog-backend为一批久已迁往backstage/plugin-catalog-node的符号CatalogProcessor、EntityProvider、processingResult、EntityRelationSpec等补充了弃用标记并将locationSpecToLocationEntity、locationSpecToMetadataName迁至plugin-catalog-node作为新家前端backstage/plugin-catalog-react支持在EntityPicker过滤器中复用多选能力。四、新后端系统插件导出重命名按推荐命名模式随着新后端系统new backend system逐步定型v1.12.0 将一批插件的模块导出更名为官方推荐的命名模式推荐规范可参见仓库文档 docs/backend-system/architecture/naming-patterns.md。核心规则为以catalogModuleName、eventsModuleName等作为前缀例如变更前旧导出变更后新导出所属包githubEntityProviderCatalogModulecatalogModuleGithubEntityProviderplugin-catalog-backend-module-githubawsS3EntityProviderCatalogModulecatalogModuleAwsS3EntityProvidersplugin-catalog-backend-module-awsazureDevOpsEntityProviderCatalogModulecatalogModuleAzureDevOpsEntityProviderplugin-catalog-backend-module-azurebitbucketCloudEntityProviderCatalogModulecatalogModuleBitbucketCloudEntityProviderplugin-catalog-backend-module-bitbucket-cloudbitbucketServerEntityProviderCatalogModulecatalogModuleBitbucketServerEntityProviderplugin-catalog-backend-module-bitbucket-servergerritEntityProviderCatalogModulecatalogModuleGerritEntityProviderplugin-catalog-backend-module-gerritgitlabDiscoveryEntityProviderCatalogModulecatalogModuleGitlabDiscoveryEntityProviderplugin-catalog-backend-module-gitlabincrementalIngestionEntityProviderCatalogModulecatalogModuleIncrementalIngestionEntityProviderplugin-catalog-backend-module-incremental-ingestionmicrosoftGraphOrgEntityProviderCatalogModulecatalogModuleMicrosoftGraphOrgEntityProviderplugin-catalog-backend-module-msgraphawsSqsConsumingEventPublisherEventsModuleeventsModuleAwsSqsConsumingEventPublisherplugin-events-backend-module-aws-sqsgithubEventRouterEventsModuleeventsModuleGithubEventRouterplugin-events-backend-module-githubgithubWebhookEventsModuleeventsModuleGithubWebhookplugin-events-backend-module-githubgitlabEventRouterEventsModuleeventsModuleGitlabEventRouterplugin-events-backend-module-gitlabazureDevOpsEventRouterEventsModuleeventsModuleAzureDevOpsEventRouterplugin-events-backend-module-azure这些导出仍处于 alpha 阶段因此本次重命名被官方视为非破坏性变更non-breaking但如果你已经在使用新后端系统需要同步更新import语句。同一批变更还对所有包的/alpha导出做了内部重构changeset928a12a9b3e并在backstage/plugin-catalog-backend-module-gitlab中弃用了GitlabDiscoveryEntityProvider的branch配置键改用fallbackBranch。五、新插件catalog-backend 的 PuppetDB 模块backstage/plugin-catalog-backend-module-puppetdb0.1.0为本版本首次发布用于将 PuppetDB可作为 Entity Provider 定时把 PuppetDB 中的节点/事实同步为目录实体适用于以 Puppet 做配置管理的团队构建基础设施目录视图。六、新插件Octopus Deploy 与 StackStorm6.1 Octopus Deploy 部署插件backstage/plugin-octopus-deploy0.1.0为本版本首次发布的正式插件用于集成 Octopus 部署平台源码位于 plugins/octopus-deploy。它面向使用 Octopus 作为发布/部署编排工具的团队可将部署信息环境、项目、发布版本等纳入 Backstage 的软件目录实体详情页。该插件随包携带 Octopus Deploy 官方 Logo 资源。6.2 StackStorm 集成插件backstage/plugin-stackstorm0.1.0提供与 StackStorm 的集成源码位于 plugins/stackstorm通过对接 StackStorm API 让用户直接在 Backstage 中查看工作流执行workflow executions、包packs与动作actions。安装与配置指引以该插件目录内的 README 为准。七、其他值得关注的功能与修复7.1 目录前端EntitySwitch 支持渲染多个匹配分支backstage/plugin-catalog的EntitySwitch组件新增renderMultipleMatchesall参数当多个EntitySwitch.Case的if条件同时为真时将所有匹配分支一并渲染未匹配时渲染默认分支若有。典型场景是在同一页面上展示多个 CI/CD 系统EntitySwitch renderMultipleMatchesall EntitySwitch.Case if{isJenkinsAvailable}Jenkins/EntitySwitch.Case EntitySwitch.Case if{isCodebuildAvailable}CodeBuild/EntitySwitch.Case EntitySwitch.CaseNo CI/CD/EntitySwitch.Case /EntitySwitch7.2 OAuth2 与 OIDC 语义对齐backstage/core-app-api中OAuth2在申请openidscope 的会话时现在会显式获取 ID Token。这并非破坏性变更——符合规范的 OIDC 提供方本就会在授予openidscope 时返回 ID Token该改动只是将这一依赖显式化使基于 OAuth2 的提供方无需再手动把openid加入默认 scope从而可以避免为资源型访问令牌申请多余的 ID Token 相关 scope。同时 GitLab 认证提供方现在可以用于获取 OpenID 令牌。7.3 UrlReaderService 的 lastModified 支持backstage/backend-plugin-api的UrlReaderService.readUrl响应新增lastModifiedAt字段并支持lastModifiedAfter选项便于按文件修改时间做增量读取或缓存决策。7.4 后端基础设施细节backstage/backend-common新增backend.database.role配置用于设置 Postgres 中新建 schema 与表的归属用户配合pluginDivisionMode: schema例如backend: database: client: pg pluginDivisionMode: schema role: backstage connection: user: v-backstage-123 # ...上例以v-backstage-123连接数据库但新建对象的属主为backstageAwsS3UrlReader升级到 AWS SDK v3backstage/errors新增NotImplementedErrorbackstage/backend-app-api会将其正确映射为 501 状态码backstage/plugin-proxy-backend的createRouter支持reviveConsumedRequestBodies: true可恢复被 express 中间件如express.json()消费过的请求体默认不启用backend-tasks新增从调度器获取任务描述description的能力便于展示任务触发原因。7.5 TechDocs 与 CLItechdocs/cli generate --verbose会输出 mkdocs 构建过程日志techdocs AWS S3 请求支持 HTTPS 代理backstage/plugin-techdocs-backend引入新后端系统下的techdocsPluginalpha 导出TechDocs 前端修复了某些 mkdocs-material 版本下上一篇/下一篇链接失效的问题并保留插入到 shadow DOM 中文档内容的 HTML 标签属性以改善可访问性backstage/cli新增migrate package-exports命令用于同步所有package.json的exports字段并新增了 Web 与 Node.js 库类型的新插件模板。7.6 其余代表性修复Catalog 相关getEntitiesByRefs缺失项返回undefined修复批量按引用获取与过滤如授权组合使用的缺陷Scaffolder 相关RepoUrlPicker对无 owner 的目标如 Bitbucket Server也能获取凭据修复数组字段校验、空对象hasErrors判断等前端通用core-components中 Sidebar 按钮文案不再强制大写按给定大小写原样显示Table组件支持columns[*].headerStyle搜索分页在最后一页正确禁用下一页按钮快捷方式插件修复了新增快捷方式会覆盖整个列表的问题主题相关一批插件将硬编码的黑/白颜色改为感知主题theme aware。八、升级到 v1.12.0 的注意事项清单综合以上变更从旧版本升级到 v1.12.0 时建议重点检查以下几点新后端系统导入路径如已使用 alpha 导出按上文表格将旧的xxxEntityProviderCatalogModule/xxxEventRouterEventsModule等重命名为新命名模式Scaffolder 动作 schema可逐步将手写 JSON Schema 迁移为zod声明以获得类型安全系统仍兼容原有 JSON Schema 形态GitLab Discovery Provider 配置若使用了branch键重命名为fallbackBranch目录查询需要游标分页/服务端排序时优先采用queryEntities//entities/by-querygetEntities依旧可用数据库归属如使用 Postgres schema 划分模式可评估backend.database.role以统一对象属主代理行为proxy-backend 默认不复活已消费请求体需要该行为时显式开启reviveConsumedRequestBodies: trueUI 覆盖样式Sidebar 按钮文案不再自动大写、多个组件切换为主题感知颜色如有自定义样式覆盖需复核。九、相关文档与进一步阅读发布说明docs/releases/v1.12.0.md逐包变更记录docs/releases/v1.12.0-changelog.md新后端系统架构docs/backend-system/architecture后端系统命名模式docs/backend-system/architecture/naming-patterns.md保持 Backstage 更新docs/getting-started/keeping-backstage-updated.md版本化与支持策略docs/overview/versioning-policy.md说明本仓库为 Backstage 官方仓库的快照文章中引用的源码路径如 createTemplateAction.ts、api.ts、createRouter.ts与文档路径均可在当前仓库中直接查阅文中所有版本号与配置均以本仓库 v1.12.0 版本内容为准。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考