Backstage v1.30.0-next.1 预发布变更深度解析邮件模板异步化、配置解析扩展与前端扩展 v2 迁移【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstagev1.30.0-next.1 是 Backstage v1.30.0 发布前的第二个预发布版本next.1集中呈现了通知系统、配置加载、前端插件框架等核心模块的破坏性变更与新能力。本文将逐项拆解本版本中带有代码示例的实质性变更——包括邮件模板渲染器强制异步化、ConfigSource自定义解析逻辑、前端扩展 v2 声明格式迁移、GitLab Catalog Provider 的excludeRepos过滤以及 techdocs-common 新包首秀并对照当前仓库源码给出迁移与配置实操指引。一、版本概览与升级入口本变更日志见 docs/releases/v1.30.0-next.1-changelog.md覆盖了从前端核心运行时、后端基础设施到各大插件在内的几十个backstage/*包其中标注为Minor Changes新增能力或破坏性变更的包包括backstage/config-loader1.9.0-next.1File/RemoteConfigSource新增解析逻辑配置Minorbackstage/plugin-notifications-backend-module-email0.2.0-next.1模板渲染器方法强制异步BREAKINGMinorbackstage/plugin-techdocs-common0.1.0-next.0新包初始发布Minor其余大量包为 Patch 级别修复与依赖同步。官方为每次版本升级提供了 Upgrade Helper 工具?to1.30.0-next.1可用于评估升级对当前应用的影响由于这是预发布版本生产环境建议等待正式版 v1.30.0 后再升级。二、破坏性变更通知邮件模板渲染器强制异步化2.1 变更内容backstage/plugin-notifications-backend-module-email0.2.0-next.1变更条目def53a7引入了一个破坏性变更NotificationTemplateRenderer的getSubject、getText、getHtml三个方法现在返回Promise调用方必须await。从当前仓库源码 extensions.ts 可以看到该接口的最终形态export interface NotificationTemplateRenderer { getSubject?(notification: Notification): Promisestring; getText?(notification: Notification): Promisestring; getHtml?(notification: Notification): Promisestring; }这一改动的直接收益是邮件内容模板可以调用任何异步的数据源例如查询外部服务、读取数据库、调用渲染库的异步 API来生成主题与正文而不再局限于同步字符串拼接。2.2 迁移指引官方 diff 示例若你的后端模块通过notificationsEmailTemplateExtensionPoint注册了自定义模板渲染器需要按如下方式为三个方法补上async并await异步调用import { notificationsEmailTemplateExtensionPoint } from backstage/plugin-notifications-backend-module-email; import { Notification } from backstage/plugin-notifications-common; import { getNotificationSubject, getNotificationTextContent, getNotificationHtmlContent } from my-notification-processing-library; export const notificationsModuleEmailDecorator createBackendModule({ pluginId: notifications, moduleId: email.templates, register(reg) { reg.registerInit({ deps: { emailTemplates: notificationsEmailTemplateExtensionPoint, }, async init({ emailTemplates }) { emailTemplates.setTemplateRenderer({ - getSubject(notification) { async getSubject(notification) { - return New notification from ${notification.source}; const subject await getNotificationSubject(notification); return New notification from ${subject}; }, - getText(notification) { async getText(notification) { - return notification.content; const text await getNotificationTextContent(notification); return text; }, - getHtml(notification) { async getHtml(notification) { - return p${notification.content}/p; const html await getNotificationHtmlContent(notification); return html; }, }); }, }); }, });即使你暂时不需要异步逻辑也应将方法声明为async返回Promise否则同步返回值仍会被包装成已兑现的 Promise——但类型上不满足新接口要求会在编译期报错。2.3 配套的完整配置参考该模块用于把 Backstage 通知以邮件形式投递给用户支持smtp、ses、azure、sendmail、stream调试用等传输方式。仓库内 README.md 给出了可直接参考的配置骨架notifications: processors: email: # 传输配置完整选项见 config.d.ts transportConfig: transport: smtp hostname: my-smtp-server port: 587 secure: false username: my-username password: my-password # AWS SES # transportConfig: # transport: ses # accessKeyId: my-access-key # region: us-west-2 # Azure Communication Service # transportConfig: # transport: azure # endpoint: https://my-endpoint.communication.azure.com # accessKey: my-access-key # 可选不填则使用 Managed Identity # sendmail # transportConfig: # transport: sendmail # path: /usr/sbin/sendmail # newline: unix # 发件人地址 sender: sendermycompany.com replyTo: no-replymycompany.com # 广播通知收件人 broadcastConfig: receiver: users # 并发发送数默认 2 concurrencyLimit: 10 # 邮件发送节流间隔默认 100ms throttleInterval: seconds: 60 # 收件人地址缓存避免频繁查询 Catalog cache: ttl: days: 1 # 该处理器处理的通知过滤条件 filter: minSeverity: high maxSeverity: critical excludedTopics: - scaffolder # 允许的邮箱域名精确匹配、大小写不敏感不隐含子域 allowedEmailDomains: - mycompany.com # 始终放行的地址可越过 allowedEmailDomains allowlistEmailAddresses: - contractorgmail.com # 拒绝的地址最后生效可覆盖放行名单 denylistEmailAddresses: - jane.doebackstage.io需要注意收件人地址来自 Catalog 中的用户资料可能受上游身份源影响。生产环境应通过allowedEmailDomains与allowlistEmailAddresses/denylistEmailAddresses将投递范围限制在可信域名内格式校验不能替代这类策略。三、config-loaderFile/Remote ConfigSource 支持自定义解析逻辑3.1 变更内容backstage/config-loader1.9.0-next.1变更条目274428f为 File 和 Remote 两类ConfigSource增加了配置解析逻辑的配置键此前仅支持 YAML现在可以通过传入自定义parser支持 JSON 等多种格式。对照仓库源码 FileConfigSource.tsparser?: Parser;其默认实现为parseYamlContent第 115 行this.#parser options.parser ?? parseYamlContent;读取内容后通过await this.#parser({ contents })得到解析结果第 174 行。RemoteConfigSource.ts 提供了同样的parser选项。配套的测试用例FileConfigSource.test.ts直接演示了 JSON 解析用法it(should read a config file with optional parser, async () { // ... parser: async ({ contents }) ({ result: JSON.parse(contents) }), });3.2 如何使用自定义 parser当你希望使用 JSON或自定义格式作为配置文件源时可以在构造 File/RemoteConfigSource时传入 parserimport { FileConfigSource } from backstage/config-loader; const source FileConfigSource.fromPath(/path/to/app-config.json, { parser: async ({ contents }) ({ result: JSON.parse(contents) }), });parser 的职责是接收文件原始内容contents并返回{ result: ... }result为undefined时表示该文件应被忽略。3.3 相关修复本版本同时修复了ConfigSources.default的env选项允许undefined成员的问题1edd6c2。此外$include变换目前按扩展名选择解析器include.ts 中.json/.yaml/.yml各对应一种解析若包含的文件无可用解析器会报 no configuration parser available 错误——自定义 parser 的引入为这类场景提供了更灵活的扩展空间。四、前端插件框架扩展声明改为数组形式的 v2 格式4.1 变更内容backstage/frontend-plugin-api0.6.8-next.1变更条目3be9aeb将扩展的声明方式从「命名数据引用data ref映射」改为「inputs/outputs 数组」目的是减少对 input/output 名称角色的困惑并为覆盖扩展override提供更强大的 API。backstage/frontend-app-api0.7.5-next.1与frontend-test-utils同步支持了这种 v2 扩展3be9aeb。4.2 迁移示例旧写法v1data map 形式const exampleExtension createExtension({ name: example, inputs: { items: createExtensionInput({ element: coreExtensionData.reactElement, }), }, output: { element: coreExtensionData.reactElement, }, factory({ inputs }) { return { element: ( div Example {inputs.items.map(item { return div{item.output.element}/div; })} /div ), }; }, });新写法v2数组形式输出通过coreExtensionData.reactElement(...)构造数据容器返回const exampleExtension createExtension({ name: example, inputs: { items: createExtensionInput([coreExtensionData.reactElement]), }, output: [coreExtensionData.reactElement], factory({ inputs }) { return [ coreExtensionData.reactElement( div Example {inputs.items.map(item { return div{item.get(coreExtensionData.reactElement)}/div; })} /div, ), ]; }, });关键差异createExtensionInput([...])接收数据引用数组output直接声明为数据引用数组工厂函数返回一个数据容器数组使用coreExtensionData.reactElement(...)包裹 JSX读取子扩展输出从item.output.element改为item.get(coreExtensionData.reactElement)。4.3 同版本相关的其他前端能力Blueprint 支持 zod 配置 schema3fb421d可在 Blueprint 与扩展实例中定义 zod 配置 schema并内置合并逻辑扩展 config input 类型6349099扩展新增配置输入类型core-compat-api、catalog、search、user-settings、techdocs 等多个插件同步接入config-loader 与前端模块联动frontend-app-api的依赖中同步引入config-loader1.9.0-next.1使前端配置源同样受益于新的解析能力。五、Catalog 相关变更5.1 GitLab Provider 新增excludeRepos过滤backstage/plugin-catalog-backend-module-gitlab0.3.22-next.1变更条目c7b14ed为 GitLab Catalog Provider 新增了可选的excludeRepos配置项用于在批量导入 GitLab 仓库时排除指定仓库。配置方式示意catalog: providers: gitlab: yourProviderId: host: gitlab.example.com group: my-group excludeRepos: - my-group/legacy-repo - my-group/archive-project该能力与现有group、org等导入范围配置配合使用可在不新增过滤器代码的前提下精确控制入库仓库集合。5.2 Catalog Locations 扩展点行为修正backstage/plugin-catalog-backend1.24.1-next.1变更条目51240ee修复了CatalogLocationsExtensionPoint.setAllowedLocationTypes()未被调用时默认allowedLocationTypes丢失的问题——现在未调用时将保留默认值避免因扩展点未配置而意外放宽或收紧可注册的 location 类型。六、新包与其余值得关注的修复6.1 techdocs-common 包初始发布backstage/plugin-techdocs-common0.1.0-next.0变更条目4698e1f作为新包首次发布旨在承载 TechDocs 前端与后端共享的注解常量等公共定义。同版本的 techdocs 前端与后端69bd940已改用该包中的注解常量替代原先分散在各包中的硬编码字符串为后续 TechDocs 演进提供了统一的类型与常量出口。6.2 其他重要修复一览包变更说明backstage/core-app-api1.14.2-next.09a46a81应用处于 protected 模式时删除 session cookie 的请求改用原生fetch而非FetchApi修复登出删除 cookie 期间应用立即尝试重新登录的缺陷backstage/cli0.27.0-next.1e6e7d86编译目标从ES2022调整为es2022以兼容更老版本的swcbackstage/backend-plugin-api0.7.1-next.1f011d1b修正getPluginRequestToken注释中的拼写错误backstage/plugin-permission-common0.8.1-next.0137fa34将MetadataResponseSerializedRule类型迁入 common 包plugin-permission-node中仍重导出但标记弃用backstage/plugin-scaffolder-backend1.23.1-next.1ef87e06修复catalog:write动作向不存在的目录写入失败的问题backstage/plugin-catalog-react1.12.3-next.17ca331c修正EntityDisplayName图标与文本的对齐backstage/plugin-kubernetes0.11.13-next.1e6c15cc新增对新前端系统/alpha子路径导出的支持backstage/plugin-scaffolder-backend-module-github0.4.1-next.1d21d307为github:environment:create动作补充示例与测试用例七、升级注意事项与结论综合本预发布版本的全部变更升级到 v1.30.0 系列时需重点关注三类工作邮件模板渲染器异步化必须迁移任何实现NotificationTemplateRenderer的模块都要将getSubject/getText/getHtml改为async方法否则在类型检查阶段即会失败前端扩展 v2 声明格式渐进迁移createExtension的 inputs/outputs 从 data map 迁移到数组形式读取子输出改用item.get(...)官方同时提供了 Blueprint 与 zod 配置 schema 等新能力承接旧扩展创建器新配置能力的利用可选增强config-loader的 parser 选项使 JSON 等格式的配置源成为一等公民GitLab Provider 的excludeRepos与CatalogLocationsExtensionPoint的默认值保留则为 Catalog 运维提供了更精细的控制手段。由于本文件为预发布next变更日志所有结论均以 v1.30.0-next.1-changelog.md 及仓库内对应包源码为准生产环境升级前建议对照后续发布的正式版 v1.30.0-changelog.md 确认变更是否最终进入正式版。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
