Backstage v1.30.0-next.4 版本解读前端插件覆盖机制、Catalog 实体扩展与通知系统增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章针对 Backstage开源开发者门户框架的v1.30.0-next.4预发布版本变更日志进行技术解读覆盖该版本中 frontend-plugin-api 的扩展覆盖Extension Overrides机制、catalog-model 的 Domain/System 实体spec.type属性、Cloudflare Access 认证增强、通知系统默认已读行为以及 Scaffolder、TechDocs 等核心插件的一系列修复。读者读完本文后将能理解本次版本中 API 层面的破坏性变更与新增能力并能直接使用withOverrides、Extension.override、plugin.getExtension等新 API 定制自己的 Backstage 插件同时掌握升级到该版本时需要关注的依赖与行为变化。该版本为1.30.0的第四个预览版本next.4共涉及 70 余个backstage/*包及示例应用的变更其中大部分为依赖升级Patch真正的功能性变化Minor集中在backstage/frontend-plugin-api、backstage/catalog-model、backstage/plugin-auth-backend-module-cloudflare-access-provider、backstage/plugin-notifications与backstage/plugin-scaffolder五个包上。一、前端插件系统扩展覆盖 API 全面落地本次版本在前端插件系统New Frontend System上的改动最为密集也是开发者升级后最需要关注的 API 变化。相关实现集中在 createFrontendPlugin.ts 与 createExtension.ts 中。1.1plugin.withOverrides应用内整体覆盖插件扩展变更99abb6b为前端插件引入了全新的plugin.withOverrides方法用于在不修改插件源码的前提下在应用侧整体覆盖插件内任意扩展的定义。日志中给出的示例为import homePlugin from backstage/plugin-home; export default homePlugin.withOverrides({ extensions: [ homePage.getExtension(page:home).override({ *factory(originalFactory) { yield* originalFactory(); yield coreExtensionData.reactElement(h1My custom home page/h1); }, }), ], });从源码看withOverrides定义在OverridableFrontendPlugin接口上createFrontendPlugin.ts其options支持四个覆盖维度extensions要新增或覆盖的扩展定义列表。若某个扩展的 ID 与插件原有扩展 ID 相同则在原注册位置就地替换保持原有挂载顺序其余新增扩展则追加在末尾——这一顺序语义对应用的扩展挂载顺序至关重要if覆盖整个插件所有扩展共享的启用条件FilterPredicatetitle/icon覆盖插件在页面头部与导航中的显示标题与图标info逐个覆盖插件原始的 info 加载器package.json 与 manifest。withOverrides的返回值仍然是OverridableFrontendPlugin因此支持链式调用多次叠加覆盖。实现上createFrontendPlugin.ts 内部会通过resolveExtensionDefinition解析覆盖扩展的 ID、通过throwOnDuplicateExtensionIds拒绝重复 ID再合并出新的扩展列表后重新调用createFrontendPlugin生成一个新插件实例。1.2plugin.getExtension按 ID 获取扩展定义变更a65cfc8新增了plugin.getExtension(id)方法允许从插件实例上按 ID 取回扩展定义前提是该扩展使用 v2 格式通常即扩展蓝图 Blueprint定义。从源码可见其行为createFrontendPlugin.tsID 不存在时会抛出Attempted to get non-existent extension ${id} from plugin ${pluginId}错误因此在使用前应确保插件确实注册了对应 ID 的扩展。这一方法与withOverrides组合使用即上一节示例中homePage.getExtension(page:home).override(...)的完整调用链。1.3 扩展定义覆盖Extension.override与 Blueprint 工厂覆盖变更2d21599为扩展定义本身增加了override能力日志给出了完整的实体卡片覆盖示例const TestCard EntityCardBlueprint.make({ ... }); TestCard.override({ // override attachment points attachTo: { id: something-else, input: overridden }, // extend the config schema config: { schema: { newConfig: z z.string().optional(), } }, // override factory *factory(originalFactory, { inputs, config }){ const originalOutput originalFactory(); yield coreExentsionData.reactElement( Wrapping {originalOutput.get(coreExentsionData.reactElement)} /Wrapping ); } });源码层面createExtension.ts对override施加了如下约束只能覆盖以新格式outputs 为数组声明的扩展否则报错Cannot override an extension that is not declared using the new format with outputs as an array覆盖output时必须同时覆盖factoryRefused to override output without also overriding factoryparams与factory不能同时覆盖Refused to override params and factory at the same time覆盖工厂后可通过originalFactory()获取原始工厂输出再从返回的数据容器中按数据键取出如originalOutput.get(coreExentsionData.reactElement)实现包装原始输出的叠加式定制。1.4 Blueprint 的.make与.makeWithOverrides拆分变更264e10f将 Blueprint 上原有的.make方法重构为两个.make面向简单场景仅通过高阶参数attachTo、name、namespace等标准参数创建扩展实例.makeWithOverrides面向高级场景允许覆盖更多内容配置 schema、inputs、output、factory 等对最终扩展有更细粒度的控制。同时264e10f还废弃了旧的ExtensionCreators统一迁移到 Blueprint 体系。这意味着基于旧版 Extension Creator API 的代码在升级后应迁移到对应的createExtensionBlueprint体系。另外变更6f72c2b修复了扩展蓝图inputs合并的问题变更34f1b2a明确了语义inputs支持合并但output不再合并且蓝图中的原始工厂现在返回一个数据容器——它既能提供对返回数据的访问也可以作为 output 整体转发。这些改动均可在 createExtension.ts 及对应测试 createFrontendPlugin.test.ts 中验证。二、Catalog 模型Domain 与 System 实体新增可选spec.type变更34fa803为catalog-model1.6.0-next.0中的Domain与System两种实体 Kind 引入了可选的spec.type属性。这是本版本中少数直接影响用户 catalog-info.yaml 数据模型的改动。从源码定义可以看到类型层面的变化DomainEntityV1alpha1.tsspec字段为{ owner: string; subdomainOf?: string; type?: string; }SystemEntityV1alpha1.tsspec字段为{ owner: string; domain?: string; type?: string; }。type是可选属性因此对存量数据完全向后兼容——未提供spec.type的 Domain/System 实体仍然合法。其典型用途是表达领域/系统的业务分类例如领域属于支付风控等类型前端与搜索等下游可以基于该字段做过滤与分组展示。对应的 JSON Schema 校验位于 packages/catalog-model/src/schema/kinds 目录下测试用例可参考 DomainEntityV1alpha1.test.ts 与 SystemEntityV1alpha1.test.ts。注意Domain/System仍同时支持backstage.io/v1alpha1与backstage.io/v1beta1两个 API 版本实体模型注册逻辑见两个文件底部的domainEntityModel/systemEntityModelcreateCatalogModelLayer构建relation 关系ownedBy、partOf不变。三、认证Cloudflare Access 自定义头与 Cookie 支持变更75d026a为backstage/plugin-auth-backend-module-cloudflare-access-provider0.2.0-next.3增加了对Cloudflare Custom Headers与Custom Cookie Auth Name的支持。该模块用于将 Cloudflare AccessZero Trust 网关作为 Backstage 的身份认证来源此前仅支持默认的Cf-Access-Jwt-Assertion请求头与默认 Cookie 名。升级后若你的 Cloudflare Access 策略配置了自定义的 JWT 请求头名称或自定义 Cookie 名称可以在 provider 配置中对应指定Backstage 将按自定义名称解析 JWT 断言。该 provider 同时依赖backstage/backend-plugin-api0.8.0-next.3与backstage/plugin-auth-node0.5.0-next.3的新版本。四、通知系统默认打开即读与无用户目录支持4.1 打开 Snackbar/Web 通知链接即标记已读变更0410fc9backstage/plugin-notifications0.3.0-next.1改变了通知的已读语义默认情况下当用户通过 Snackbar 弹窗或 Web 通知链接打开通知时该通知会被自动标记为已读。这一行为可以从插件源码中得到印证——useWebNotifications.ts 中在处理 Web 通知时调用notificationsApi.updateNotifications({ ... })更新已读状态而 NotificationsTable.tsx 也通过notificationsApi.getNotifications({ read: false })拉取未读列表并批量updateNotifications({ ids, read: true })。Snackbar 组件的配置入口位于 NotificationsSideBarItem.tsx支持通过snackbarPropsenabled、autoHideDuration、anchorOrigin、iconVariant等定制弹窗行为。4.2 无目录用户也能使用通知变更7a05f50backstage/plugin-notifications-backend0.3.4-next.3放宽了后端限制允许在 Catalog 中不存在对应用户实体的情况下使用通知功能。此前通知系统强依赖 Catalog 中的 User 实体来解析收件人对于尚未将全部用户同步进 Catalog 的团队这一改动显著降低了通知功能的接入门槛。五、ScaffolderMyGroupsPicker 展示一致性变更1552c33backstage/plugin-scaffolder1.24.0-next.3重做了 Scaffolder 中MyGroupsPicker字段的实体展示方式改用entityPresentationApi渲染实体使其与 Scaffolder 其他 picker 的展示保持一致。源码证据MyGroupsPicker.tsx 中通过useApi(entityPresentationApiRef)获取 API并在forEntity(item)调用后渲染实体展示信息选项则使用EntityDisplayName组件renderOption{option EntityDisplayName entityRef{option} /}统一呈现测试用例 MyGroupsPicker.test.tsx 中多次 mock 了entityPresentationApiRef来验证该行为。这保证了在 Catalog 中自定义了实体展示规则如自定义头像、显示名称的组织在 Scaffolder 表单中也能得到一致的体验。六、其他值得关注的修复与增强6.1 前端与核心库frontend-app-api、core-compat-api、app-visualizer、dev-utils、frontend-test-utils等包随frontend-plugin-api0.7.0-next.3的覆盖机制同步更新backstage/plugin-api-docs0.11.8-next.3与backstage/plugin-catalog1.22.0-next.3变更6582799为所有表格新增tableOptions属性API 表格额外支持title标题属性backstage/cli0.27.0-next.4将processpolyfill 切换为require.resolve以提升兼容性6d898d8并将module-federation/enhanced升级到 0.3.12ced236backstage/create-app0.5.18-next.4变更bfeba46新脚手架工程默认内置并启用权限permission配置。6.2 后端与安全backstage/backend-defaults0.4.2-next.3变更81f930a使用格式化查询防止 SQL 注入风险backstage/backend-plugin-api0.8.0-next.3变更ddde5fe修复依赖 multiton 服务的插件/模块无法获得正确类型的类型问题该变更同时涉及backend-common的内部类型重构。6.3 Scaffolder 各模块publish:bitbucketCloud动作新增初始化仓库时可设置初始提交信息的能力d57967cgithub:repo:create与github:pages动作补充了示例并改进测试用例6d4cb97、cd203f1publish:azure动作补充示例并更新测试187f583gitlab:issues:create动作新增测试用例da97131Scaffolder Runs 页面加载时标题不再显示 undefinedd18f4ebEntityPicker 下拉增加额外高度当选项少于 10 个时移除滚动条让还有更多选项的提示更清晰47ed51b。6.4 TechDocsTechDocsReaderPage 样式支持更细粒度的主题覆盖主题变量不再影响 Backstage 其他区域27794d1TechDocs 重定向功能在跳转前增加用户通知提示8543e72修复嵌套文档的编辑 URL 生成问题5cedd9ftechdocs-backend更新配置 schema 使其与实际行为一致a16632c。七、升级要点与依赖关系升级工具本版本变更日志顶部附带了官方 Upgrade Helper 入口?to1.30.0-next.4可用于评估当前应用各包与目标版本的差距版本语义各包均遵循语义化版本Minor 变更表示向后兼容的新增能力如上述五个包的next.x版本Patch 变更表示缺陷修复与依赖升级升级时建议按依赖关系自底向上catalog-model→frontend-plugin-api→ 各插件更新依赖传导backstage/catalog-model1.6.0-next.0是本次更新的核心依赖节点几乎所有前端插件scaffolder、catalog、techdocs、search、home 等均因其而重新发版backend-plugin-api0.8.0-next.3则是后端侧的核心依赖节点auth、catalog-backend、search-backend、events、signals、permission 等后端包全部随之更新示例应用仓库内的example-app、example-app-next、example-backend、example-backend-legacy以及e2e-test均同步升级到对应 next 版本见 docs/releases/v1.30.0-next.4-changelog.md 末尾的 example-app 章节可作为升级后各插件搭配的参考清单。结语v1.30.0-next.4是一份以前端插件系统覆盖能力完善为主线的预发布版本withOverrides、getExtension、Extension.override与.make/.makeWithOverrides拆分共同构成了新前端系统在不改源码的前提下定制插件的完整工具链与此同时Catalog 的spec.type扩展、Cloudflare Access 自定义头、通知默认已读与无用户目录支持则为实际部署提供了更灵活的选项。若你的应用大量使用了旧版 Extension Creator 或依赖 Scaffolder picker 的旧展示逻辑升级时应重点回归上述模块。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
