Backstage v1.45.0-next.0 版本更新解读Postgres 18 测试支持、ESLint 新规则与yarn new模板增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南基于 Backstage 官方仓库的 v1.45.0-next.0 版本说明系统梳理该 pre-release 版本中影响开发流程的关键变更包括backstage/backend-test-utils新增 Postgres 18 测试支持并调整默认测试数据库矩阵、backstage/eslint-plugin新增no-ui-css-imports-in-non-frontend规则、CLIyarn new模板系统支持文件名模板化并新增 Catalog Entity Provider 模板以及多个插件与核心包的行为修复。读者读完本文后可以准确判断升级到 1.45.0-next.0 时哪些行为会变化、如何适配新规则并掌握测试矩阵与模板系统的底层实现原理。版本概览与升级建议v1.45.0-next.0是 Backstage 1.45 版本的第一个next预发布版本遵循 Backstage 的发布节奏该版本包含两个Minor Changes引入新能力的变更与大量Patch Changes修复与内部重构。官方为升级提供了 Upgrade Helper 工具to1.45.0-next.0可自动对比依赖差异并生成升级指引。本版本值得关注的变更集中在四个方向测试基础设施backstage/backend-test-utils支持 Postgres 18且默认测试数据库从 Postgres 13/17 切换为 14/18。代码规范backstage/eslint-plugin新增 UI CSS 导入范围校验规则。CLI 与脚手架yarn new模板支持文件名模板化新增 Catalog Entity Provider 模板。全仓库的 TypeScript 兼容性重构将构造函数参数属性parameter properties重构为显式属性声明以兼容erasableSyntaxOnly编译设置。升级到该版本属于常规 minor 级别升级但测试矩阵的默认值变化需要测试维护者特别留意详见下文。亮点一backend-test-utils支持 Postgres 18 并调整默认测试矩阵backstage/backend-test-utils1.10.0-next.0是本版本唯一的测试基础设施 Minor 变更核心内容包括两点。新增 Postgres 18 支持TestDatabases类现在可以在测试环境中启动 Postgres 18 实例。在源码层面新增的数据库平台注册在 packages/backend-test-utils/src/database/types.ts 中TestDatabaseId联合类型已扩展为POSTGRES_18 | POSTGRES_17 | ... | SQLITE_3完整的可用平台如下TestDatabaseId名称驱动Docker 镜像连接字符串环境变量POSTGRES_18Postgres 18.xpgpostgres:18BACKSTAGE_TEST_DATABASE_POSTGRES18_CONNECTION_STRINGPOSTGRES_17Postgres 17.xpgpostgres:17BACKSTAGE_TEST_DATABASE_POSTGRES17_CONNECTION_STRINGPOSTGRES_16Postgres 16.xpgpostgres:16BACKSTAGE_TEST_DATABASE_POSTGRES16_CONNECTION_STRINGPOSTGRES_15Postgres 15.xpgpostgres:15BACKSTAGE_TEST_DATABASE_POSTGRES15_CONNECTION_STRINGPOSTGRES_14Postgres 14.xpgpostgres:14BACKSTAGE_TEST_DATABASE_POSTGRES14_CONNECTION_STRINGPOSTGRES_13Postgres 13.xpgpostgres:13BACKSTAGE_TEST_DATABASE_POSTGRES13_CONNECTION_STRINGPOSTGRES_12Postgres 12.xpgpostgres:12BACKSTAGE_TEST_DATABASE_POSTGRES12_CONNECTION_STRINGPOSTGRES_11Postgres 11.xpgpostgres:11BACKSTAGE_TEST_DATABASE_POSTGRES11_CONNECTION_STRINGPOSTGRES_9Postgres 9.xpgpostgres:9BACKSTAGE_TEST_DATABASE_POSTGRES9_CONNECTION_STRINGMYSQL_8MySQL 8.xmysql2mysql:8.4BACKSTAGE_TEST_DATABASE_MYSQL8_CONNECTION_STRINGSQLITE_3SQLite 3.xbetter-sqlite3无内嵌无从该文件可以看到每个平台都通过connectionStringEnvironmentVariableName提供外部数据库接入能力如果设置了对应的连接字符串环境变量TestDatabases会直接使用外部数据库否则回退到 Docker 镜像启动实例Docker 被禁用时该平台会被过滤掉。这一逻辑可以在 packages/backend-test-utils/src/database/TestDatabases.ts 的create静态方法中看到依次检查显式ids参数、默认idssetDefaults设置与全部平台然后按连接字符串环境变量是否存在 → 是否需要 Docker → Docker 是否被禁用的优先级过滤出当前环境实际支持的平台集合。默认测试数据库矩阵的调整破坏性行为这是本版本最值得注意的行为变化TestDatabases类默认测试的数据库集合从包含 Postgres 13 和 17 改为包含 Postgres 14 和 18。具体来说升级后不带任何参数使用TestDatabases.create()时默认测试平台不再包含POSTGRES_13与POSTGRES_17而是包含POSTGRES_14与POSTGRES_18。这意味着如果你的测试代码依赖默认矩阵跑到了 Postgres 13/17升级后这两组用例将静默消失除非平台本身被显式指定。新增的 Postgres 14/18 用例会进入默认执行集合CI 会多出两条数据库测试线需要确保 CI 环境Docker 或外部连接字符串能够提供这两个版本。官方给出的适配方式是显式传入ids参数覆盖默认值例如TestDatabases.create({ ids: [POSTGRES_17, POSTGRES_13, SQLITE_3], });TestDatabases.create的完整签名来自 TestDatabases.ts为static create(options?: { ids?: TestDatabaseId[]; disableDocker?: boolean; }): TestDatabases典型用法是在测试文件的顶层创建一个实例然后在各个测试用例中通过init(id)快速创建独立的逻辑数据库const databases TestDatabases.create(); describe.each(databases.eachSupportedId())(%s, id { const db await databases.init(id); // 返回 Knex 连接 // ... 在 db 上执行迁移与断言 });TestDatabases实例会在 JestafterAll钩子中统一清理所有引擎资源超时 60 秒因此每个测试文件通常只需create一次。此外create返回的实例支持supports(id)判断平台可用性eachSupportedId()便于配合describe.each做参数化测试。亮点二ESLint 新规则限制backstage/uiCSS 导入范围backstage/eslint-plugin0.2.0-next.0引入了新规则backstage/no-ui-css-imports-in-non-frontend用于确保backstage/ui的 CSS 只在前端应用包中被导入。这条规则的动机很直接随着 Backstage UIBUI体系在仓库内推广backstage/ui的样式文件不应被非前端角色如 Node 库、后端插件、通用库的包导入否则会造成样式作用域混乱与打包体积问题。规则实现位于 packages/eslint-plugin/rules/no-ui-css-imports-in-non-frontend.js其校验逻辑可以归纳为遍历源码中的 import 语句仅关注外部或内部包导入中packageName backstage/ui的条目判断导入路径是否以.css结尾读取当前包package.json中的backstage.role字段未定义backstage.role的包直接放行role为frontend的包放行其余角色如backend、node-library、web-library等触发noCssImport错误报告。对应的报错信息为CSS imports from backstage/ui are only allowed in packages with backstage.role set to frontend. Current role: {{role}}规则的完整文档位于 packages/eslint-plugin/docs/rules/no-ui-css-imports-in-non-frontend.md测试用例见 packages/eslint-plugin/src/no-ui-css-imports-in-non-frontend.test.ts。适配指南升级后若 CI 中出现该规则告警检查报错包在package.json中的backstage.role声明。如果该包确实属于前端应用应将backstage.role设置为frontend否则应移除对backstage/ui下.css文件的导入或改用主题/令牌等受支持的方式传递样式。该版本同时包含一个配套修复backstage/dev-utils通过懒加载backstage/ui/css/styles.css修复了开发模式下的样式问题b29a856而backstage/ui本身也修复了默认文本颜色、默认字号、CSS 层顺序、字体平滑与默认字重/字体族等问题26c6a78、dac851f、3c0ea67、4eb455c、00bfb83这些改动共同推进了 UI 体系向 BUI 的迁移。亮点三yarn new模板系统支持文件名模板化新增 Catalog Entity Provider 模板backstage/cli0.34.5-next.0对脚手架模板系统做了两项增强backstage/create-app0.7.6-next.0同步把新模板纳入next-app的显式模板配置模板文件名支持模板语法yarn new执行时使用的模板现在可以对文件名本身进行模板化而不只是文件内容。这意味着模板作者可以根据用户输入如插件名、类名动态生成不同名称的文件极大提升模板的灵活性。新增 Catalog Entity Provider 模板可以通过yarn new直接生成一个 Catalog Entity Provider 模块的骨架。若要在根package.json的显式模板列表中加入该模板使用路径标识backstage/cli/templates/catalog-provider-module。新模板的实际骨架位于 packages/cli-module-new/templates/catalog-provider-module/其目录结构清晰展示了生成代码的组成catalog-provider-module/ ├── src/ │ ├── provider/ │ │ ├── readProviderConfigs.ts.hbs # 读取 provider 配置的辅助函数 │ │ ├── {{providerClass}}.test.ts.hbs # provider 单元测试骨架 │ │ └── {{providerClass}}.ts.hbs # provider 主实现类名可模板化 │ ├── index.ts.hbs # 包导出入口 │ └── module.ts.hbs # 后端模块定义register 入口 ├── README.md.hbs ├── config.d.ts.hbs # 配置类型声明 ├── package.json.hbs └── portable-template.yaml从骨架可见模板不仅生成 provider 实现与测试还包含配置读取辅助函数readProviderConfigs与配置类型声明config.d.ts生成的模块可直接作为后端动态特性backend dynamic feature或静态插件模块挂载进 catalog。生成后的使用方式与普通 Catalog Provider 一致在模块的register中通过catalog.provideLocations或等价服务注册实体 provider并在app-config.yaml的catalog.providers下填写配置。亮点四核心包修复与全仓库 TypeScript 兼容性重构backend-defaultsBitbucket URL 读取器 token 修复backstage/backend-defaults0.13.1-next.0修复了 issue #31348BitbucketUrlReader之前会忽略调用方传入的 token始终使用 integration 中配置的凭据提交b2f6a5a。该行为在 packages/backend-defaults/CHANGELOG.md 中有对应记录。修复后显式传入的 token 会优先生效这对于通过运行时凭据读取私有仓库内容的场景如 Scaffolder 的fetch:template动作意义重大。仓库历史还提示后续版本中旧的BitbucketUrlReader已被拆分废弃应使用BitbucketCloudUrlReader或BitbucketServerUrlReader。同版本还调整了任务 worker 启动日志的措辞9bcfa77。erasableSyntaxOnly兼容性重构全仓库范围本版本有一项覆盖面极广的内部重构提交05f60e1将构造函数参数属性constructor parameter properties重构为显式属性声明以兼容 TypeScript 的erasableSyntaxOnly编译选项。该设置要求语法在编译后可以被擦除而不产生运行时语义而参数属性如constructor(private readonly foo: Bar) {}属于会产生实际代码的非可擦除语法。重构后所有受影响包的功能保持不变仅调整属性声明方式。涉及包包括backstage/backend-app-api、catalog-model、config、config-loader、core-components、plugin-auth-backend、plugin-catalog-backend、plugin-scaffolder-backend、plugin-search-backend等数十个核心包。对普通使用者而言这是透明变更但如果你维护自定义 TS 配置并启用了erasableSyntaxOnly升级后与官方包的编译兼容性将更好。Scaffolder 模板解析与 TechDocs 渲染修复backstage/plugin-scaffolder-react1.19.3-next.0886a8a1修复useTemplateSchema钩子中模板解析的一个 bug——之前移除 title的实现方式是将其设置为undefined现改为真正移除该字段避免生成的 schema 中出现多余的title: undefined属性。该钩子位于 plugins/scaffolder-react/src/next/hooks/useTemplateSchema 附近被 Scaffolder 的 Step 表单Stepper等组件消费直接关系到模板表单步骤的渲染。backstage/plugin-techdocs1.15.2-next.0a4d4a70修复在同一实体的文档内部进行页面间导航时整个 TechDocs 页面被重复重渲染的问题导航性能得到改善。backstage/plugin-auth0.1.2-next.01609e79认证内容页面登录界面现在使用应用标题而非硬编码文案。backstage/plugin-notifications-backend-module-email0.3.15-next.022a5362AWS SES 客户端升级到 v2以兼容nodemailerv7。techdocs/cli1.10.1-next.0c2a2017修复由于迁移到 BUI 而丢失样式的问题。backstage/plugin-user-settings0.8.29-next.02b6fda3回退storageApiRef的实现变更。依赖面变化速览除上述行为变更外本版本几乎所有backstage/*包都有 Patch 级依赖更新。从 changelog 的Updated dependencies清单可以梳理出几条贯穿全仓库的依赖主线升级后这些依赖将同步更新核心基础设施层backstage/backend-plugin-api1.4.5-next.0、backstage/backend-app-api1.2.9-next.0、backstage/backend-defaults0.13.1-next.0、backstage/config1.3.6-next.0、backstage/config-loader1.10.6-next.0。前端核心层backstage/core-app-api1.19.2-next.0、backstage/core-components0.18.3-next.0、backstage/core-plugin-api1.11.2-next.0、backstage/frontend-plugin-api0.12.2-next.0、backstage/frontend-app-api0.13.2-next.0。权限与认证backstage/plugin-permission-common0.9.3-next.0、backstage/plugin-permission-node0.10.6-next.0、backstage/plugin-auth-node0.6.9-next.0、backstage/plugin-auth-backend0.25.6-next.0。Catalog 生态backstage/catalog-model1.7.6-next.0、backstage/catalog-client1.12.1-next.0、backstage/plugin-catalog-backend3.1.3-next.0、backstage/plugin-catalog-react1.21.3-next.0。固定版本无变更backstage/errors1.2.7、backstage/types1.2.2、backstage/theme0.7.0、backstage/version-bridge1.0.11、backstage/cli-common0.1.15。升级到 1.45.0-next.0 的行动清单基于以上分析升级时建议按以下清单逐项核对测试配置如果使用TestDatabases.create()的默认矩阵确认 CI 能提供 Postgres 14 与 18Docker 镜像或外部连接字符串如需保留旧的 13/17 覆盖显式传入ids参数。ESLint 规则升级backstage/eslint-plugin到 0.2.0 后运行一次 lint检查是否有包在非frontend角色下导入了backstage/ui的 CSS。Bitbucket 集成如果通过BitbucketUrlReader读取私有仓库验证显式 token 现在能正确生效关注后续版本中该 reader 的拆分迁移BitbucketCloudUrlReader/BitbucketServerUrlReader。模板使用如需快速创建 Catalog Entity Provider在根package.json的new模板列表中注册backstage/cli/templates/catalog-provider-module后执行yarn new。回归验证重点回归 TechDocs 页内导航、Scaffolder 表单渲染、认证页面与通知邮件发送SES/nodemailer等功能路径。总结v1.45.0-next.0 是一个以测试基础设施升级 规范收口 内部兼容性重构为主基调的预发布版本Postgres 18 进入测试矩阵标志着对最新数据库版本的支持跟进新的 ESLint 规则为 BUI 体系划定了清晰的样式边界yarn new的文件名模板化与 Catalog Entity Provider 模板则进一步降低了扩展 Backstage 的开发门槛。对于大多数使用者本版本无破坏性 API 变更但默认测试矩阵的变化与新 ESLint 规则的引入是升级时最需要主动适配的两点。建议结合 Upgrade Helper 自动对比依赖差异并按上文行动清单完成验证后再合入。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考