Backstage v1.2.0-next.1 发布解读测试基础设施增强、ADR 插件首发与破坏性变更迁移指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方发布说明 docs/releases/v1.2.0-next.1-changelog.md 整理聚焦backstage/test-utils的渲染能力升级、backstage/plugin-search-react的破坏性 API 变更、Tech Insights 后端的tokenManager接入、全新 ADR 插件与create-app模板调整。读完本文你将掌握这些变更对现有 Backstage 应用的迁移影响并能够对照仓库源码理解每个变更的底层实现。一、backstage/test-utils1.1.0-next.1渲染测试基础设施升级本次发布对测试工具包做了三处关键增强全部由提交1da8b248c2引入直接影响所有插件开发者编写前端组件测试的方式。1.renderWithEffects新增options参数renderWithEffects现在接受一个可选的options参数并将其转发给testing-library/react的render函数。首个版本仅支持wrapper选项。import { renderWithEffects } from backstage/test-utils; const result await renderWithEffects(MyComponent /, { wrapper: MyCustomWrapper, });在仓库源码 packages/test-utils/src/testUtils/testingLibrary.ts 中可以看到该签名与实现export async function renderWithEffects( nodes: ReactElement, options?: PickRenderOptions, wrapper LegacyRootOption, ): PromiseRenderResult { let value: RenderResult; await act(async () { value render(nodes, options); }); return value!; }renderWithEffects的核心价值在于它把渲染过程包裹进act()中执行从而让组件中通过useEffect触发的异步动作如 fetch能够在断言之前完成状态更新避免出现 not wrapped in act 警告。新增的options参数则让调用方可以同时传入自定义的 React 组件树包装而不再需要手工在节点外层嵌套包装组件。2. 新增createTestAppWrappercreateTestAppWrapper返回一个可直接作为render或renderWithEffects的wrapper选项使用的组件它在组件外提供一套完整的 Backstage 测试应用上下文mock 主题、mock API、路由环境等。import { render } from testing-library/react; import { createTestAppWrapper } from backstage/test-utils; render(MyComponent /, { wrapper: createTestAppWrapper({ routeEntries: [/my-page] }), });从源码 packages/test-utils/src/testUtils/appWrappers.tsx 可以看到该函数内部通过createSpecializedApp构建了一个精简的 Backstage 应用实例并支持TestAppOptions配置项routeEntries传给MemoryRouter的初始路由路径mountedRoutes把路径绑定到RouteRef/ExternalRouteRef使被测组件中的useRouteRef能正常解析components/icons透传给createApp的自定义组件与图标。createTestAppWrapper的引入把原先wrapInTestApp内部重复使用的包装逻辑独立出来让调用方能够在自定义 wrapper 与内置测试应用包装之间自由组合。wrapInTestApp现在正是基于它实现的见 appWrappers.tsx。3. 修复renderInTestApp的重渲染问题本次发布还修复了renderInTestApp的一个缺陷之前重复调用rerender会导致应用包装层被移除现在修复后重渲染会保留完整的应用包装。从 appWrappers.tsx 的实现可以看出renderInTestApp正是通过renderWithEffects(wrappedElement, { wrapper: createTestAppWrapper(options), legacyRoot })组合上述两项新能力实现的因此它天然继承了这些修复与增强。二、backstage/plugin-search-react0.2.0-next.1破坏性变更——以MockSearchApi取代 Storybook 专用 Provider本次发布删除了SearchContextProviderForStorybook和SearchApiProviderForStorybook两个组件提交bdbe620797并引入全新的SearchApimock 实现MockSearchApi。这是一个BREAKING 变更所有在 Storybook 或测试中依赖这两个 Provider 的代码都需要迁移。官方推荐的迁移方式如下import { searchApiRef, MockSearchApi, SearchContextProvider, } from backstage/plugin-search-react; import { TestApiProvider } from backstage/test-utils; TestApiProvider apis{[[searchApiRef, new MockSearchApi()]]} SearchContextProvider Component / /SearchContextProvider /TestApiProvider;这一写法的核心思路是先用backstage/test-utils的TestApiProvider把 mock 实例注册到searchApiRef上再通过SearchContextProvider提供搜索上下文。MockSearchApi类在仓库源码 plugins/search-react/src/api.ts 中定义实现了标准的SearchApi接口可完全替代此前散落在 Storybook 组件中的 mock 逻辑。迁移要点删除对SearchContextProviderForStorybook、SearchApiProviderForStorybook的导入统一改用TestApiProvider MockSearchApi模式这既减少了维护成本也让 mock 行为与真实 API 契约保持严格一致。三、Tech Insights 后端tokenManager成为必选参数破坏性变更backstage/plugin-tech-insights-backend0.4.0-next.1与backstage/plugin-tech-insights-node0.3.0-next.1同时引入了BREAKING 变更tokenManager被加入buildTechInsightsContext的选项参数与FactRetrieverContext类型中。1.buildTechInsightsContext新增tokenManagertokenManager是TokenManager的实例来自后端初始化代码的env。升级后需要显式传入const builder buildTechInsightsContext({ logger: env.logger, config: env.config, database: env.database, discovery: env.discovery, scheduler: env.scheduler, tokenManager: env.tokenManager, factRetrievers: [ /* ... */ ], });2.FactRetrieverContext类型扩展FactRetrieverContext类型现在同样包含tokenManager字段提交58e2c46151。这意味着自定义的 fact retriever 可以在执行时获得TokenManager用于发起需要服务间认证的调用例如访问受保护的 API 或向其他后端插件请求数据。任何手动构造FactRetrieverContext的测试代码或实现都需要补上该字段否则会出现类型编译错误。四、全新 ADR 插件架构决策记录的插件化落地本次发布通过提交e73075a301首次引入了完整的 ADRArchitecture Decision Records架构决策记录插件族共三个新包backstage/plugin-adr0.1.0-next.0前端插件提供 ADR 的浏览与展示界面backstage/plugin-adr-backend0.1.0-next.0后端插件负责从代码仓库读取 ADR 文档backstage/plugin-adr-common0.1.0-next.0前后端共享的类型与工具。ADR 插件的前端依赖backstage/plugin-catalog-react与backstage/integration-react后端依赖backstage/backend-common说明它是一个依托软件目录实体entity与代码仓库集成能力工作的插件将团队代码库中以 Markdown 形式维护的 ADR 文档聚合到 Backstage 界面中统一浏览。仓库自身也在 docs/architecture-decisions 目录下维护着一套 ADR如 adr002-default-catalog-file-format.md、adr010-luxon-date-library.md并提供了 adr000-template.md 模板可作为接入该插件的实际素材样例。五、TechDocs 测试工具包首发backstage/plugin-techdocs-addons-test-utils0.1.0-next.0配合 TechDocs Addon 框架的推进本次发布引入backstage/plugin-techdocs-addons-test-utils提交52fddad92d为 TechDocs Addons 的测试提供工具函数。该包依赖backstage/test-utils、backstage/plugin-techdocs、backstage/plugin-techdocs-react与backstage/plugin-search-react等说明其作用是把 TechDocs 阅读页的完整渲染环境addon 注入、search 上下文、catalog 上下文封装成可复用的测试基础设施。与之配套backstage/plugin-techdocs1.1.1-next.1与backstage/plugin-techdocs-react0.1.1-next.1也发生了 API 归属调整TechDocsStorageApi及其关联 ref 改为由backstage/plugin-techdocs-react导出在原backstage/plugin-techdocs中的对应导出被标记为 deprecated 并将在未来版本移除。addon 扩展机制createTechDocsAddonExtension与挂载点枚举TechDocsAddonLocations的实现在 plugins/techdocs-react/src/addons.tsx 与 plugins/techdocs-react/src/types.ts 中后续引入的 addon如 ReportIssue、TextSize都基于这套机制注册。六、backstage/core-components0.9.4-next.0可访问性a11y批量改进本次发布在core-components中集中合入了一批无障碍改进涉及多个常用组件Page组件新增 ARIA landmarkmain提交ac19f82936DesktopSidebar与Sidebar组件新增 ARIA landmarknav外链对屏幕阅读器进行播报提交c0055ece91AlertDisplay新增可选的anchorOrigin对齐属性用于控制提示条弹出的位置提交cfc0f2e5bd支持按钮增加aria-label改善屏幕阅读器体验提交f4380eb602。backstage/plugin-catalog051fc60258与backstage/plugin-catalog-react0418447669也同步修复了按钮 ARIA 属性与菜单项父级角色等问题。这些改动不涉及配置迁移升级后即可直接受益。七、认证相关变更auth-backend修复与 OAuth2 Proxy 简化1. 修复 token 的entclaim 丢失问题backstage/plugin-auth-backend0.13.1-next.1修复了0.13.1-next.0引入的一个 bug该 bug 导致签发 token 中的ententityclaim 被丢弃提交cac3ba68a2。受影响用户应尽快升级。2. OAuth2 Proxy Provider 降低基础设施配置门槛OAuth2 Proxy provider 进行了简化提交5d268623ddauth 结果对象现在可直接访问请求头既可通过headers对象也可通过getHeader方法原有的从 ID token 解析用户信息的逻辑被标记为 deprecated将在未来版本移除新增默认authHandler实现可直接从请求头读取 display name 与 email。这意味着在纯代理场景下不再强制依赖 ID token 解析接入成本显著降低。若你依赖旧行为应尽快迁移到基于请求头的用户信息提取方式。3. 认证 API 不再是alphabackstage/core-plugin-api1.0.2-next.0中认证相关 API 不再标记为alpha提交b653a5595c。由于该包没有/alpha入口此前alpha标记的唯一作用就是让它们在文档中被隐藏取消标记后这些 API 会在官方文档中正常展示。它们仍会被广泛使用未来如有变更官方会提供迁移路径。八、create-app模板调整与既有应用迁移指南backstage/create-app0.4.27-next.1带来多项模板调整官方同时给出了既有应用的对齐方式这里逐条整理。1. 移除create-app的数据库选择步骤create-app命令不再询问数据库类型默认安装全部依赖并在app-config.production.yaml中预置生产配置提交00fa0dada0同时新增app-config.local.yaml用于本地配置覆盖。既有安装可这样对齐touch app-config.local.yaml同时在packages/backend/package.json中把 SQLite 从dependencies移到devDependencies避免生产构建携带多余依赖dependencies: { ... pg: ^8.3.0, - better-sqlite3: ^7.5.0, winston: ^3.2.1 }, devDependencies: { ... types/luxon: ^2.0.4, better-sqlite3: ^7.5.0 }2. 升级 TypeScript 版本模板中的typescript升级到~4.6.4。既有应用需同步修改根package.jsondependencies: { ... - typescript: ~4.5.4 typescript: ~4.6.4 },backstage/plugin-catalog-backend1.1.2-next.1也做了对 TypeScript 4.6 兼容性的内部微调提交1ccbe081cc说明该版本对 TS 4.6 的适配是系统性的。3. 提供 sign-in 配置指引模板在packages/backend/src/plugins/auth.ts中加入了 sign-in 配置的示例与说明提交7b253072c6。既有应用无需强制添加但若需要配置 sign-in可参考官方 identity resolver 文档对应仓库内文档 docs/auth/identity-resolver.md。九、CLI 与其余补丁级变更速览backstage/cli0.17.1-next.1修复BACKSTAGE_NEXT_TESTS下的覆盖率配置新增 lint 规则阻止生产代码导入 stories 或 tests调整 Rollup 的 TypeScript 类型定义插件配置忽略css、scss、sass、svg、eot、woff、woff2、ttf文件并新增帮助用户初始化新组织的能力提交2737777e02。backstage/backend-common0.13.3-next.1更新类型以匹配新版keyv/redis。backstage/plugin-scaffolder1.2.0-next.1允许对类型为object的自定义字段扩展进行校验提交8dce7d5244。backstage/plugin-tech-radar0.5.12-next.0将象限命名use改为adopt与 Zalando Tech Radar 的表述保持一致提交3588a77994。backstage/plugin-org0.5.5-next.1修复命名空间场景下 ownership card 链接到 catalog owner 过滤器的问题提交cb0db62344。backstage/plugin-tech-insights0.2.1-next.1新增EntityTechInsightsScorecardCard组件可放入实体页 overview 或多个卡片组合展示提交aa8db01acb。backstage/plugin-techdocsTechDocs CLI 的 embedded app 改为统一从backstage/plugin-techdocs-react导入 API ref提交52fddad92d。大量插件随core-components、core-plugin-api、core-app-api的next版本同步更新依赖属于常规的版本对齐无额外迁移动作。十、升级路径与注意事项总结对于从 v1.1.x 升级到 v1.2.0-next.1 的应用建议按以下顺序处理优先处理两个破坏性变更搜索相关测试/Storybook 代码从SearchApiProviderForStorybook迁移到TestApiProvider MockSearchApiTech Insights 后端的buildTechInsightsContext补传tokenManager: env.tokenManager并同步检查自定义 fact retriever 的FactRetrieverContext。跟随模板迁移升级 TypeScript 到~4.6.4、创建app-config.local.yaml、把better-sqlite3移入devDependencies。关注认证行为变化确认 OAuth2 Proxy 的用户信息提取方式并升级修复entclaim 的 auth-backend 版本。常规升级升级后即可获得core-components的可访问性改进与新插件能力无需额外配置。需要注意的是本文所描述的行为以当前仓库源码与 docs/releases/v1.2.0-next.1-changelog.md 记录为准由于这是next预发布版本部分 API 在正式版 v1.2.0 发布前仍可能调整生产环境升级前建议对比最终发布说明。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考