Backstage v1.43.0-next.0 版本解析：配置热更新测试能力、Microsoft Graph 过滤编码破坏性变更与关键修复清单

Backstage v1.43.0-next.0 版本解析配置热更新测试能力、Microsoft Graph 过滤编码破坏性变更与关键修复清单【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章以仓库中发布的 v1.43.0-next.0 变更日志 为核心主体逐项剖析该预发布版本中backstage/backend-test-utils新增的配置热更新测试能力、backstage/plugin-catalog-backend-module-msgraph引入的查询过滤器编码破坏性变更以及 CLI、create-app、catalog、techdocs 等多个包的关键修复。读者读完后既能掌握如何在单元测试中模拟配置动态更新也能明确升级到该版本前需要调整的配置写法同时获得一份可直接对照检查的修复影响清单。一、版本定位与升级须知v1.43.0-next.0是 Backstage 在 v1.43.0 正式发布前的首个 Next预发布版本遵循 Backstage 的发布节奏next系列版本用于提前验证变更包含随正式版本一起发布的 Minor新增特性与 Patch缺陷修复两类变更。该版本的发布产物来自当前仓库涉及 30 余个backstage/*包以及仓库内的example-app、example-backend、e2e-test、techdocs-cli-embedded-app等工作区示例包。升级到该版本时需要特别关注两点两个包包含 Minor Changesbackstage/backend-test-utils1.9.0-next.0、backstage/plugin-catalog-backend-module-msgraph0.8.0-next.0其中 msgraph 模块为破坏性变更BREAKING升级后需同步调整配置其余包均为 Patch Changes可在常规升级流程中一并处理。由于本版本为next预发布版本正式升级建议以最终发布的 v1.43.0 稳定版变更日志为准在开发环境验证新特性时可直接引入*-next.0版本的包。二、backend-test-utilsmockServices.rootConfig()新增update方法2.1 变更内容backstage/backend-test-utils1.9.0-next.0的 Minor Change提交4e2c237为mockServices.rootConfig()实例新增了update方法用于测试配置订阅subscription与配置更新update场景。此前测试中只能通过mockServices.rootConfig({ data })在创建时一次性注入静态配置对于依赖config服务可观察能力即在运行时监听配置变化并做出响应的代码缺少便捷的模拟手段。2.2 源码级实现原理从 mockServices.ts 的实现 可以看到rootConfig的返回值类型被声明为RootConfigService { update(options: { data: JsonObject }): void }其内部实现基于ObservableConfigProxyexport function rootConfig( options?: rootConfig.Options, ): RootConfigService { update(options: { data: JsonObject }): void } { const config ObservableConfigProxy.create(new AbortController()); config.setConfig(new ConfigReader(options?.data ?? {}, mock-config)); return Object.assign(config, { update({ data }: { data: JsonObject }): void { config.setConfig(new ConfigReader(data, mock-config)); }, }); }关键点在于初始配置通过ConfigReader包装后setConfig注入update方法再次以新数据构造ConfigReader并调用setConfig从而触发ObservableConfigProxy的订阅通知返回对象通过Object.assign同时具备完整RootConfigService接口与新增的update方法。这意味着一处实现即可同时覆盖初始值与运行时更新两种测试场景无需自行手写可观察配置的桩实现。此外同一命名空间还提供了mockServices.rootConfig.factory(...)可作为startTestBackend的 features 注入与mockServices.rootConfig.mock(...)基于 jest.fn 的纯 mock两种形态前者适合集成式测试后者适合断言调用行为。2.3 典型测试用法针对订阅配置变化的服务可以这样编写测试import { mockServices } from backstage/backend-test-utils; const rootConfig mockServices.rootConfig({ data: { app: { baseUrl: https://old.example.com } }, }); // 将 rootConfig 注入被测服务服务内部 subscribe 配置变化... rootConfig.update({ data: { app: { baseUrl: https://new.example.com } }, }); // 断言服务感知到新配置并做出响应需要注意update是整体替换配置数据基于传入的data构造全新ConfigReader而非对现有配置做深合并编写用例时应把update视为配置快照被整体刷新这一语义。三、plugin-catalog-backend-module-msgraph查询过滤器编码破坏性变更BREAKING3.1 变更内容与迁移方式backstage/plugin-catalog-backend-module-msgraph0.8.0-next.0的 Minor Change提交577f0ed为对 Microsoft Graph 发起的请求强制编码查询过滤器query filters。如果此前在配置中手动写入了 URL 编码字符如%26表示则升级后会被二次编码double encoded属于破坏性变更必须改回原始字符user: - filter: department in(MARKETING, RESEARCH %26 DEVELOPMENT) filter: department in(MARKETING, RESEARCH DEVELOPMENT)即配置中应写人类可读的 OData 表达式、、(等原样书写模块在发送请求时会统一完成编码。3.2 源码实现佐证在 MicrosoftGraphClient.requestApi 中查询串通过qs库序列化并显式启用编码const queryString qs.stringify( { $search: query?.search, $filter: query?.filter, $select: query?.select?.join(,), $expand: query?.expand, $count: query?.count, $top: query?.top, }, { addQueryPrefix: true, encode: true, }, );正是encode: true让$filter、$search等内容在发往 Graph API 前被统一编码因此配置中若已含%26这类编码序列就会叠加编码导致查询失效。这也是该变更被标记为 BREAKING 的根本原因。另可注意 requestCollection 在advanced查询模式下会自动携带ConsistencyLevel: eventual头并在使用$filter/$select时补充$counttrue这些行为与本变更共同决定了过滤器在高级查询下的语义。3.3 相关配置项速查该模块通过 readProviderConfig 解析 provider 配置与过滤器相关的核心配置项包括配置项说明user.filter提取用户的 OData 过滤器被禁用的用户accountEnabled false始终在客户端被过滤掉userGroupMember.filter按组成员关系提取用户时使用的过滤器group.filter提取组时使用的过滤器group.search提取组时的搜索条件queryModebasic或advanced非法取值会在配置解析阶段直接抛错配置解析还内置了若干互斥校验例如userFilter与userGroupMemberFilter互斥不可同时指定定义了userFilter时不能再指定userGroupMemberSearch或userGroupMemberPathclientId与clientSecret必须成对出现。升级到0.8.0-next.0后请重点检查上述过滤器配置中是否残留%xx形式的编码序列并将其恢复为原始 OData 表达式。相关解析校验在 config.test.ts 中有对应覆盖可作参考。四、CLInew-frontend-plugin模板修复与多应用模块检测冲突4.1 模板参数修复backstage/cli0.34.1-next.0修复了new-frontend-plugin模板提交080f252此前模板错误地向createFrontendPlugin传递了id参数正确参数应为pluginId并且模板中存在不必要的React导入。该问题会导致通过 CLI 脚手架生成的新前端插件在参数命名上与createFrontendPlugin/createFrontendModule的 API 契约不一致。仓库内现有示例可以印证正确写法在 default-app 的 home 模块 中模块创建使用的是pluginId: homeexport const homeModule createFrontendModule({ pluginId: home, extensions: [gettingStartedWidget], });升级 CLI 后重新执行new命令生成的新插件模板即为修复后的形态已有代码中若有id误用的前端插件也应同步改为pluginId。4.2 多应用工作区模块检测冲突另一个 Patch提交275bda8修复了在包含多个应用的 workspaces 中已检测模块detected modules可能产生冲突的问题。该问题源于 CLI 对工作区模块的检测与聚合逻辑在多应用 monorepo 场景下模块归属判断可能错乱。修复后CLI 在解析工作区模块时会避免此类冲突。五、create-appHome 页默认跳转 Catalog消除 404 错误页backstage/create-app0.7.4-next.0提交b2d9fc1在默认应用模板中创建了一个从 Home 页重定向到 Catalog 索引页的插件避免启动应用后访问/出现页面未找到not found错误。这一修复在仓库模板中同样有据可查在 legacy-app 的 App.tsx 中根路径通过 react-router 直接重定向Route path/ element{Navigate tocatalog /} /新生成的应用在根路径访问时会自动进入 Catalog 索引页已存在的老应用若出现根路径 404可参照该方式自行添加跳转路由。六、其他值得关注的前端与后端修复本版本还包含一系列前端体验与后端正确性修复建议按清单逐一核对6.1 core-compat-apicompatWrapper不再创建多余的 Providerbackstage/core-compat-api0.5.2-next.0提交dc01d6f修复了compatWrapper在不该创建 Provider 的情况下创建了大量包裹用Providers的问题。该问题会影响旧版插件通过兼容层compat在新前端系统New Frontend System下运行时的 Provider 层级修复后可减少不必要的组件树嵌套。6.2 plugin-catalogEntityContextMenu交互细节backstage/plugin-catalog1.31.3-next.0提交ce1239e为EntityContextMenu增加了两项改进自动聚焦第一个菜单项提升键盘导航与辅助功能体验当传入空数组给UNSTABLE_extraContextMenuItems时不再渲染分隔线divider。6.3 plugin-org路由多余斜杠修复backstage/plugin-org0.6.44-next.0提交22b69f2修复了路由中出现多余斜杠extra slash的问题避免在某些路由拼接场景下产生无效 URL。6.4 plugin-techdocsCSS 布局回滚backstage/plugin-techdocs1.14.2-next.0提交1dfee19回滚了一处 CSS 布局变更——该变更曾导致 TechDocs 内容整体左移过远。升级后 TechDocs 页面内容布局将恢复至预期位置。6.5 plugin-catalog-react兼容旧包default*导出backstage/plugin-catalog-react1.20.2-next.0提交ad0f58d为该包在/alpha破坏性变更影响范围内的旧版本继续提供default*形式的导出支持降低依赖该包的插件在升级时的破坏风险。6.6 plugin-kubernetes-backend默认对象加载修复backstage/plugin-kubernetes-backend0.20.2-next.0提交80cf8c9修复了默认对象default objects未能被正确加载的问题确保 Kubernetes 资源的默认检索逻辑符合预期。6.7 plugin-search-backend-module-explorecollator 弃用标记backstage/plugin-search-backend-module-explore0.3.6-next.0提交9a93520将 explore collator 标记为已弃用deprecated并注明其已迁移。仍在配置中引用该 collator 的用户应关注后续正式版本中的迁移指引。七、版本依赖联动与升级建议该 Next 版本中各包的依赖关系整体联动升级核心依赖链包括backstage/backend-app-api1.2.6、backstage/backend-defaults0.12.0、backstage/backend-plugin-api1.4.2等后端基础包backstage/config1.3.3、backstage/errors1.2.7、backstage/types1.2.1等通用基础包backstage/core-compat-api0.5.2-next.0与backstage/plugin-catalog-react1.20.2-next.0构成前端插件升级的主干plugin-api-docs、plugin-catalog、plugin-catalog-graph、plugin-catalog-import、plugin-home、plugin-kubernetes、plugin-notifications、plugin-org、plugin-scaffolder、plugin-search、plugin-signals、plugin-techdocs、plugin-user-settings等前端插件均随其更新。升级实操建议按如下顺序进行先升级backstage/plugin-catalog-backend-module-msgraph至0.8.0-next.0并同步修正user.filter、group.filter等配置中的手动编码字符去掉%xx使用原始 OData 表达式这是本版本唯一需要主动改配置的破坏性变更升级backstage/cli至0.34.1-next.0重新生成新前端插件模板时验证pluginId参数写法其余包按 changelog 的依赖关系整体升级并在升级后重点回归验证 TechDocs 页面布局、Catalog 实体菜单键盘导航、Kubernetes 默认对象加载与 Home 页根路径跳转若项目使用mockServices.rootConfig()编写后端测试可尝试用新增的update方法补充配置热更新相关用例并确认backstage/backend-test-utils升级至1.9.0-next.0后原有测试行为不变。八、小结v1.43.0-next.0是一次典型的 Backstage 预发布版本两个 Minor Change 分别强化了测试基建rootConfig().update并修正了 Graph 集成层的编码契约msgraph filter 编码十余个 Patch 覆盖了 CLI 模板、应用脚手架、Catalog 交互、TechDocs 布局与 Kubernetes 后端等关键环节。对使用者而言最重要的行动项是完成 msgraph 模块的配置迁移对插件开发者而言new-frontend-plugin模板修复与compatWrapper优化同样值得关注。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考