Backstage v1.33.0-next.0 版本解析CLI 破坏性变更、目录客户端请求分块与后端服务演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 开源仓库中的官方发布说明 docs/releases/v1.33.0-next.0-changelog.md系统梳理该预发布next版本在 CLI 构建工具链、软件目录Catalog客户端、后端插件 API、认证、事件、通知与 TechDocs 等领域的关键变更。作为构建开发者门户的开放框架Backstage 每次版本发布都通过 changesets 机制同步更新数十个backstage/*包本文面向正在升级或计划升级到 1.33.x 的开发团队帮助读者提前识别破坏性变更、掌握新配置项如events.useEventBus、rejectFrontendNetworkRequests、并理解目录客户端大请求自动分块、Cookie 超限拆分等底层实现原理。一、版本概况与升级路径v1.33.0-next.0是 Backstage 1.33 版本的第一个 next预发布迭代采用 next 迭代 → 正式发布 的节奏推进。本次发布涉及的包级变更遵循 Backstage 的语义化版本策略带Minor Changes的包通常引入新功能或破坏性变更用**BREAKING**明确标注而Patch Changes则只做缺陷修复与依赖升级。升级时官方推荐使用 Upgrade Helper 工具它可以根据当前版本自动计算升级到目标版本所需的依赖调整。该工具链接由 CLI 的versions:bump命令在检测到 yarn 插件已安装时自动附带yarnPlugin参数本次由变更17850a5修复。升级后可参考仓库内的完整发布记录 docs/releases/v1.33.0.md正式版与该 changelog 文件交叉核对。本次 next.0 中影响面较大的变更集中在三个包包新版本变更级别核心内容backstage/cli0.29.0-next.0Minor含 BREAKING移除LEGACY_BACKEND_START与src/run.ts开发入口backstage/catalog-client1.8.0-next.0MinorgetEntitiesByRefs大请求自动分块backstage/plugin-catalog-node1.14.0-next.0Minor新增独立的CatalogService接口与catalogServiceRef二、必须提前处理的破坏性变更1. CLILEGACY_BACKEND_START与src/run.ts入口被移除变更bc71665标记为BREAKINGbackstage/cli0.29.0-next.0彻底移除了LEGACY_BACKEND_START环境变量标志同时不再支持将src/run.ts作为开发dev入口文件。这对仍在使用旧式后端启动方式的团队意味着如果项目在package.json的 dev 脚本中依赖LEGACY_BACKEND_START1升级后必须移除该标志如果仓库中存在src/run.ts需要迁移到新后端系统new backend system的标准入口。新入口推荐使用backstage/backend-defaults提供的createBackend模式示例可参考仓库中的 packages/backend/src/index.ts。该变更与 Backstage 持续推进的新后端系统路线一致旧入口的长期维护成本已高于收益官方选择在 minor 版本直接移除。2. 认证后端AWS ALBfullProfile不再强制小写变更75168e3影响backstage/plugin-auth-backend0.24.0-next.0与backstage/plugin-auth-backend-module-aws-alb-provider0.3.0-next.0同样标注BREAKING通过 AWS Application Load BalancerALB登录时fullProfile中的用户名和邮箱不再被转换为小写以保证用户唯一性处理的一致性。升级注意事项如果现有代码依赖小写化的fullProfile.username/fullProfile.email例如在 sign-in resolver 中做匹配升级后行为会变化官方建议为此配置自定义的 sign-in resolversign-in resolver或 profile transformprofile transform显式地做规范化处理而不是依赖框架默认的小写转换。相关模块的现有实现与文档位于 plugins/auth-backend-module-aws-alb-providerauth 配置示例可参考 docs/auth/aws-alb。三、目录客户端getEntitiesByRefs大请求自动分块1. 变更内容backstage/catalog-client1.8.0-next.0的 Minor Change31c4fe0指出客户端现在会在需要时自动将非常大的getEntitiesByRefs调用拆分成多个较小的请求确保单个请求不会超过常见的 Express.js 请求体大小限制也不会压垮服务器。这在源码中有完整实现证据。在 packages/catalog-client/src/CatalogClient.ts 中getEntitiesByRefs通过splitRefsIntoChunks将request.entityRefs分批并逐批调用底层 API 后合并结果const getOneChunk async (refs: string[]) { const response await this.apiClient.getEntitiesByRefs( { body: { entityRefs: refs, fields: request.fields, ...(filterPredicate { query: filterPredicate as unknown as { [key: string]: any }, }), }, query: filterPredicate ? {} : { filter: this.getFilterValue(request.filter) }, }, options, ); // ... return body.items.map(i i ?? undefined); }; let result: ArrayEntity | undefined | undefined; for (const refs of splitRefsIntoChunks(request.entityRefs)) { const entities await getOneChunk(refs); if (!result) { result entities; } else { result.push(...entities); } } return { items: result ?? [] };注意该实现还同时处理了filter与query两种过滤方式的合并——当同时提供query与filter时通过convertFilterToPredicate将 filter 转换为谓词并与 query 做$all合并见同文件第 240-255 行。2. 分块算法的具体约束分块逻辑定义在 packages/catalog-client/src/utils.ts其设计目标是每个分块按 JSON 数组编码后的总字符串长度不超过 Express.js 默认请求体限制 100 kB并留有余量const { maxCountPerChunk 1000, maxStringLengthPerChunk 90 * 2 ** 10, // 约 90 KiB extraStringLengthPerRef 3, // 每个 ref 额外计入引号与逗号 } options ?? {};默认约束可归纳为maxCountPerChunk 1000每个分块最多 1000 个 entity refs无论 ref 多短都不能突破maxStringLengthPerChunk 90 * 2**10每个分块的字符串总长度不超过约 90 KiB对 100 kB 的 Express 默认上限留出余量extraStringLengthPerRef 3计算长度时每个 ref 额外计入 3 个字符JSON 数组中每个条目被引号包裹并跟随逗号。三个默认值均可通过options覆盖且函数内部会同时遵守数量上限与长度上限两个硬约束。对应的单元测试与使用方式可继续阅读 packages/catalog-client/src/CatalogClient.test.ts。3. 配套修复同一包还修复了catalogApiMock中某些 filter 字段大小写敏感的问题873f89a使 mock 行为与真实 catalog 行为保持一致相关实现位于 packages/catalog-client/src/testUtils/InMemoryCatalogClient.ts。四、CLI 与前端构建链的批量改进backstage/cli0.29.0-next.0除了破坏性变更外还包含多项针对构建、测试与工作区管理的改进1. 前端构建新增--link选项移除 Webpack linked workspace 插件变更946fa34为前端构建新增了--link workspace-path选项允许在运行时通过覆盖模块解析module resolution将外部工作区链接进来。作为该方案的一部分旧的 Webpack linked workspace 解析插件已被移除——它当初是为 Yarn 时代的旧式 workspace 链接设计的而该方式已不再可用。这一改动与 Backstage 前端系统的模块联邦/动态插件方向相呼应。2. Webpack 依赖范围提升到^5.94.0变更b084f5a将 Webpack 依赖范围提升到^5.94.0原因是当前 CLI 配置与部分旧版本不兼容。升级后建议运行yarn install让依赖解析到新范围内。3. Jest 新增rejectFrontendNetworkRequests全局开关变更a7f97e4引入了一个新的rejectFrontendNetworkRequests配置标志可设置在根目录package.json的jest字段中只能设置于根 package.json无法在单个包的配置中覆盖{ jest: { rejectFrontendNetworkRequests: true } }开启后前端包frontend与公共包common测试中任何形式的网络请求都会被拒绝。这对于杜绝测试中意外发起真实 HTTP 请求例如误用真实 fetch、意外命中外部服务非常有用是强化测试隔离性的好工具。4.repo test/repo lint的--successCache改为加法式存储变更04297a0repo test与repo lint命令的--successCache选项现在使用加法式存储additive store旧条目会保留约一周后自动清理。相比之前的覆盖式缓存这能更有效地利用历史成功结果加快仓库级monorepo的重复测试与 lint。5. 其他 CLI 修复28b60adJest 配置中对react-dom/client的检查现在会正确地从目标目录执行e30b65dbuild-workspace命令新增--alwaysPack替代已被隐藏的--alwaysYarnPack标志b4627f2修复raw-loader加载 HTML 模板时未从 CLI 包上下文解析的问题17850a5versions:bump命令的 upgrade-helper 链接在安装 yarn 插件时附带yarnPlugin参数。五、后端 Catalog 服务抽象新的CatalogService接口backstage/plugin-catalog-node1.14.0-next.0的 Minor Changebc13b42是后端 API 层面的重要演进catalogServiceRef现在有了自己配套的CatalogService接口该接口要求调用方显式传入 Backstagecredentials对象新版catalogServiceRef已提升为正式 API可通过backstage/plugin-catalog-node的主入口直接导入旧的catalogServiceRef使用旧的CatalogApi类型仍可从/alpha入口获取但属于过渡性保留。从源码看plugins/catalog-node/src/catalogService.ts 定义了CatalogServiceRequestOptionsexport interface CatalogServiceRequestOptions { credentials: BackstageCredentials; }并在其上建立了要求凭据的服务方法签名createServiceFactory实现可继续阅读该文件后半部分。这一变更的意义在于后端插件在调用 Catalog 服务时不再隐式携带身份而是显式传递调用方凭据使权限判定permission与多租户场景下的身份边界更清晰。测试工具侧的对应类型定义可参考 plugins/catalog-node/src/testUtils/types.ts。六、认证安全突破浏览器 4KB Cookie 限制backstage/plugin-auth-node0.5.4-next.0的 Patch Changea0a9a4a解决了一个隐蔽且关键的问题浏览器会静默丢弃超过 4KB 的 Cookie而这对于 refresh token 等大型 Cookie 尤其致命可能导致用户在刷新会话时被静默登出。该变更实现了Cookie 拆分逻辑cookie splitting当 Cookie如 refresh token过大时将其拆分为多个不超过浏览器限制的 Cookie 片段写入并在读取时重组从而保证认证流程的完整性。变更同时包含了相应的测试用例来验证拆分与重组功能。这对使用大型 JWT / OIDC token 作为 Cookie 的部署场景是重要的健壮性提升。七、事件系统新增events.useEventBus行为控制backstage/plugin-events-node0.4.3-next.0带来两项值得关注的改动1. 订阅失败不再一次放弃变更4501631修复了一个事件订阅的过早放弃问题此前调用subscribe时如果初始请求失败例如事件后端未安装后台轮询循环会直接放弃之后永远不会再尝试连接事件后端。修复后订阅方法会持续重试连接事件后端即使初次请求失败。2. 新增events.useEventBus配置伴随而来的是一个新配置events.useEventBus以及DefaultEventsService的对应选项用于控制事件服务与事件后端事件总线 API 的交互方式never完全禁用对事件后端 API 的调用例如部署中确实未安装事件后端时可以彻底关闭该能力避免无谓的重试日志与开销always始终允许调用事件总线 API不允许被禁用。该配置此前存在未正确传递到DefaultEventsService的问题已由e02a02b在 plugins/events-backend/src 中修复。默认行为未显式配置时是若事件后端未安装导致失败则放弃与旧行为一致需要时请显式设置always或never。八、通知系统支持用户级通知设置backstage/plugin-notifications、backstage/plugin-notifications-backend、backstage/plugin-notifications-common三包共同变更97ba58f新增对用户特定通知设置user specific notification settings的支持。这意味着通知的订阅与接收偏好可以按用户维度独立配置而非只能使用全局默认设置。同时backstage/plugin-scaffolder-backend1.26.3-next.0也基于该能力新增了发送通知的示例模板97ba58fscaffolder 模板作者可以参考该示例在模板中直接触发通知。通知相关的架构说明可查阅 beps/0001-notifications-system/README.md 与 docs/notifications。九、Signals 后端支持多实例水平扩展部署backstage/plugin-signals-backend0.2.3-next.0的 Patch Changea1e01ff支持了可扩展部署scaled deployments客户端可能连接到多个 signals 后端实例中的任意一个。这意味着信号signals通道不再局限于单实例模式为大规模部署提供了更强的横向扩展能力。相关后端模块位于 plugins/signals-backend。十、动态后端插件alpha 包元数据补全backstage/backend-dynamic-feature-service0.4.4-next.0的 Patch Change8593dfa改进了动态后端插件加载 alpha 包的方式从 alphapackage.json加载的动态后端插件的ScannedPluginPackage描述符现在同时包含主包 manifest 与 alpha manifest此前该描述符只包含近乎为空的 alphapackage.json内容。这一改进使开发者更容易读取/展示动态加载后端插件的元数据这些信息存放在主 manifest 中例如插件的名称、描述、版本等。实现位于 packages/backend-dynamic-feature-service。十一、TechDocs 体验与安全增强backstage/plugin-techdocs1.11.1-next.0包含多项改进4f0cb89新增 DomPurify 消毒器配置支持在 TechDocs 中启用自定义元素custom elements使文档渲染可扩展的同时保持 XSS 防护605bdc0/4a2f73a修复点击同页锚点链接导致页面重新渲染的问题以及导航到另一篇文档时当前页面被误渲染的问题f246178移除canvas开发依赖。十二、其他值得关注的插件修复本次 next.0 还包含大量分散在各插件的 Patch 修复按主题归类如下Scaffolder软件模板6aa5b98修复 PostgreSQL 下的任务列表tasks listing问题相关实现见 plugins/scaffolder-backend59137ff修复 token 因变为不可枚举属性而不可用的问题e4f5d95模板 filter/global function 的类型声明对齐支持返回undefined前端侧99471cd修复RepoUrlPicker使用onInputChange后值不更新的问题7669af3回退EntityPicker选项标签的变更8b5ff7e/ade301c修复表单状态刷新与 Stepper 额外属性裁剪liveOmit/omitExtraData问题。Search搜索0b8f344修复 catalog collator 的filter设置不允许为数组的 bugplugins/search-backend-module-catalogdae59c1/a9a7c7c升级 opensearch-mock 与 explore-common 依赖。Catalog 后端模块884a86cLDAP 模块新增dnCaseSensitive标志以支持属性大小写混合的 LDAP 服务器plugins/catalog-backend-module-ldap。Home / UI8b1b2cf改进已加星标的实体Starred EntitiesUI通过 Entity Presentation APIEntityDisplayName展示实体名称、以次级文本展示kind与spec.type并压缩列表间距。OpenAPI 工具47fdbb4repo-tools的schema openapi generate命令新增--watch模式便于本地编写 schema 时实时重新生成。十三、测试工具链改进1.mockBreakpoint支持按断点 mock 与动态切换backstage/core-components0.16.0-next.0的 Patch Changeaf9097e为mockBreakpoint增加了按断点breakpointmock 媒体查询以及测试中动态切换活动断点的能力。该工具的完整实现位于 packages/core-components/src/testUtils.ts它通过替换window.matchMedia模拟 Material UI 的useMediaQueryJSDOM 未实现该方法使用方式const { set } mockBreakpoint({ initialBreakpoint: md, queryBreakpointMap: { (min-width:1500px): xl, (min-width:1000px): lg, (min-width:700px): md, (min-width:400px): sm, (min-width:0px): xs, }, }); // 断言活动断点为 md 时的行为 set(lg); // 断言活动断点为 lg 时的行为从源码可见未指定queryBreakpointMap时默认映射为xl: 1920px / lg: 1280px / md: 960px / sm: 600px / xs: 0pxset()会通过act()触发所有已注册媒体查询监听器remove()恢复原始matchMedia。该工具极大简化了响应式组件在不同断点下的测试。2.SupportButton在无 support 配置时自动隐藏同一包的 Minor Changedc409c5当 app-config 中未配置 support 信息时SupportButton组件将自动隐藏避免出现一个点开没有实际内容的空按钮。3. 后端测试工具backstage/backend-test-utils1.0.3-next.0mockServices.discovery.factory()现在直接使用 mock 的 discovery 服务作为实现7aae8e3无需再为测试准备额外配置同时移除了未使用的msw依赖eb82994backstage/backend-openapi-utils0.2.1-next.0将msw从 dependencies 移到 devDependenciesf01787a。十四、升级建议与行动清单综合本 changelog升级到 1.33.x 前建议按以下清单自查CLI 入口删除LEGACY_BACKEND_START标志与src/run.ts确认使用新后端系统入口AWS ALB 认证检查 sign-in resolver / profile transform 是否依赖小写化的 username/email如有则补充自定义规范化逻辑目录大请求升级backstage/catalog-client后超大getEntitiesByRefs请求会自动分块若业务代码手动分批可考虑简化为一次性传入全部 refs后端 Catalog 调用若使用catalogServiceRef注意新版要求显式传入BackstageCredentials旧 API 暂时保留在/alpha入口事件系统根据部署是否包含事件后端显式设置events.useEventBus为never或always测试隔离在根package.json开启rejectFrontendNetworkRequests杜绝前端测试中的意外网络请求Webpack 与 workspace确认 Webpack 解析到^5.94.0如使用旧式 workspace 链接请迁移到--link方案。以上所有变更均可在本仓库对应源码与测试中验证目录分块见 packages/catalog-client/src/CatalogClient.ts 与 packages/catalog-client/src/utils.ts断点 mock 见 packages/core-components/src/testUtils.tsCatalog 服务抽象见 plugins/catalog-node/src/catalogService.ts。正式发布的完整变更明细可对照 docs/releases/v1.33.0.md 阅读。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考