Backstage v1.20.0 发布详解React 18 官方支持、新前端系统路由体系与 OpenAPI 工具链落地【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 docs/releases/v1.20.0-changelog.md 完整梳理 Backstage v1.20.0 的 3723 行变更记录聚焦三大主线全栈 React 18 官方支持、实验性新前端系统new frontend system路由与扩展体系的演进、以及围绕 OpenAPI 的后端类型安全与测试工具链落地并逐一解读 Catalog、Scaffolder、Auth、TechDocs、Search 等核心插件的关键变更与升级注意事项。读完本文你将掌握 v1.20.0 中每个破坏性变更的迁移方法、新配置项的语义与默认值以及如何在现有 Backstage 应用中安全升级。一、版本纵览v1.20.0 的几条主线v1.20.0 是一次跨前后端、覆盖面极广的版本发布涉及backstage/cli、core-plugin-api、frontend-app-api、frontend-plugin-api、backend-openapi-utils、repo-tools、plugin-catalog、plugin-catalog-backend、plugin-scaffolder、plugin-auth-backend、plugin-techdocs等数十个包。整体来看可以归纳为五条主线React 18 官方支持几乎所有前端包都打上了6c2b872153: Add official support for React 18的补丁标记包括core-plugin-api1.8.0、core-app-api1.11.1、core-components0.13.8、app-defaults1.4.5、frontend-app-api0.3.0及全部插件。新前端系统new frontend system持续成型frontend-plugin-api0.3.0引入新的RouteRef/SubRouteRef/ExternalRouteRef类型体系frontend-app-api0.3.0支持通过app.routes.bindings配置路由绑定并新增AppTreeApi。OpenAPI 工具链正式落地新包backstage/backend-openapi-utils0.1.0提供OPENAPI_SPEC_ROUTE/openapi.json标准端点与wrapInOpenApiTestServer测试辅助backstage/repo-tools0.4.0新增schema openapi test命令。Catalog 性能与展示层升级引入catalog.stitchingStrategy.modeimmediate/deferred可选配置以及新的EntityPresentationApi。Scaffolder 表单体系重构升级到rjsf/*v5 系列next版本字段扩展 API 被提升为正式公开接口。二、React 18 官方支持全栈范围内的统一升级v1.20.0 中React 18 支持不再只是个别包的实验能力而是被提升为官方支持。这一变更横跨了core-plugin-api、core-app-api、core-components、theme、version-bridge、test-utils、app-defaults以及 catalog、scaffolder、techdocs、search、playlist、home、kubernetes、graphiql 等几乎所有前端插件包。在 core-plugin-api 侧IconComponent现在支持fontSize: inherit便于行内图标的使用变更1e5b7d993a同时引入AnyRouteRefParams作为已被废弃的AnyParams的替代变更cb6db75bc2。在渲染层core-app-api与dev-utils中react-dom/client的加载方式从require(...)切换为动态import(...)变更67cc85bb14并使用 React 18 的createRootAPI变更38cda52746。这意味着升级到 v1.20.0 后应用可以放心使用 React 18 的并发特性前端渲染入口不再与 CommonJS 的require强绑定为后续 ESM 化铺路。从仓库示例看packages/app-legacy 与 packages/app 都随版本同步升级依赖作为官方升级模板可直接参考其package.json的依赖组合。三、新前端系统演进新的路由体系与 AppTreeApiv1.20.0 是新前端系统new frontend system演进的重要里程碑核心变化集中在backstage/frontend-plugin-api0.3.0与backstage/frontend-app-api0.3.0两个包。3.1 新的 RouteRef 类型体系frontend-plugin-api0.3.0新增了RouteRef、SubRouteRef、ExternalRouteRef及相关类型并让本包所有导出不再依赖core-plugin-api中的同名旧类型变更68fc9dc60e。与此同时core-plugin-api1.8.0对旧路由系统中的若干类型及 route ref 上的字段进行了废弃标记并新增/alpha导出工具convertLegacyRouteRef// 旧路由 ref 与新前端系统 API 之间的临时桥接 import { convertLegacyRouteRef } from backstage/core-plugin-api/alpha;该工具的存在意味着 v1.20.0 正处于新旧路由体系并存的过渡期已用新前端系统组装应用createApp的开发者可以通过convertLegacyRouteRef让存量 route ref 继续工作。3.2 createApp 路由绑定与 AppTreeApifrontend-app-api0.3.0的关键能力是createApp使用的路由系统已替换为仅支持frontend-plugin-api新格式 route ref 的实现并且不再要求 route ref 的 ID 与其关联的扩展 ID 相同。应用可以通过app.routes.bindings配置绑定路由变更68fc9dc60e。同时v1.20.0 将内部 app graph 重构为 app tree并实现新的AppTreeApi变更733bd95746、4d6fa921db扩展实例系统整体被 app tree 取代。createApp的 options 参数现在变为可选变更fdc348d5d3传入的 features 会按引用与 ID 双重去重且显式传入的 features 优先级高于自动发现与加载的 features变更685a4c8901。3.3 扩展工厂输出方式变更frontend-plugin-api0.3.0中扩展的工厂函数改为直接返回输出而不再调用bind(...)变更77f009b35d。这是一个面向新前端系统插件作者的行为级变更任何基于该包早期实验版本编写的扩展都需要同步调整。core-plugin-api还新增了默认的扩展 Suspense 组件以改善加载体验变更6af88a05ff。3.4 各插件的 alpha 声明式扩展v1.20.0 中大量插件通过/alpha子路径发布了面向新前端系统的声明式扩展Catalogplugin-catalog1.15.0新增 sidebar item、index page、filter 等声明式扩展预设并给出初始的实体页实现0bf6ebda88、bb98953cb9overview 页默认启用、about card 作为可选卡片TechDocsplugin-techdocs1.9.0导出 alpha 路由与导航项扩展a3add7a682并新增实体页内容0bf6ebda88Homeplugin-home0.5.10通过/alpha子路径支持声明式集成5b364984bfCatalog Importplugin-catalog-import0.10.2创建与声明式集成系统兼容的实验插件6db75b900aStack Overflowplugin-stack-overflow0.1.22迁移到新前端系统b168d7e7eaSearch / User Settings / Tech Radar 等均更新了 alpha 导出以适配新的路由体系68fc9dc60e。提示/alpha子路径导出属于实验性 API仅适用于使用新前端系统的应用正式生产应用建议等待其 GA。四、后端 OpenAPI 工具链从规范校验到运行时测试v1.20.0 最值得关注的底层能力建设是全新的backstage/backend-openapi-utils0.1.0包与配套的 repo-tools 命令。4.1 标准化的 /openapi.json 端点backend-openapi-utils0.1.0为所有经过校验的路由器validated router新增了/openapi.json标准端点用于在统一路径上暴露完整的 OpenAPI 规范变更785fb1ea75。在源码中该路由常量定义于 constants.tsexport const OPENAPI_SPEC_ROUTE /openapi.json;而路由实现位于 stub.ts当请求到达/openapi.json时会使用openapi-merge将当前插件挂载的 base path 前插到规范中prepend: req.originalUrl.replace(OPENAPI_SPEC_ROUTE, )从而保证返回的 spec 中 server/path 与实际部署位置一致。createValidatedOpenApiRouter则基于express-openapi-validator构建带请求校验默认coerceTypes: false、allowUnknownQueryParameters: false的 typed router。4.2 wrapInOpenApiTestServer 与 schema openapi test补丁变更6694b369a3为backend-openapi-utils增加了wrapInOpenApiTestServer允许在运行时对请求做代理用于支撑新的yarn backstage-repo-tools schema openapi test命令。在 testUtils.ts 中可以看到其雏形wrapServer它启动一个捕获型 Proxy将 Express 应用的监听端口指向代理端口从而让所有请求/响应都经过 OpenAPI 规范一致性校验并通过afterAll钩子统一清理代理资源。配套地backstage/repo-tools0.4.0新增了schema openapi test命令变更6694b369a3它基于 Optic 引擎用你的测试数据对 OpenAPI spec 做运行时校验。使用前需在仓库根目录安装依赖yarn add useoptic/optic之后即可运行yarn backstage-repo-tools schema openapi test这套工具链的意义在于Backstage 的 OpenAPI 校验从构建期静态类型延伸到运行期行为验证catalog-backend 与 search-backend 在本版本中也同步更新了更完整的错误响应与请求体 spec同样基于 Optic并把测试用例切换到backend-openapi-utils提供的 supertest 直通能力。4.3 将插件 OpenAPI spec 纳入 Catalog新包backstage/plugin-catalog-backend-module-backstage-openapi0.1.0提供一个新的 catalog 模块用于把 Backstage 插件自身的 OpenAPI spec摄取进 Catalog 并展示为 API 实体变更785fb1ea75。结合上一节的标准端点这形成了一个闭环插件通过/openapi.json暴露 speccatalog 模块定时抓取并建模为API类型实体再通过 api-docs 插件呈现。这也解释了example-backend-next的依赖清单中为什么会新增该模块。五、Catalogstitching 策略、展示层 API 与扩展点5.1 新增 catalog.stitchingStrategy.mode 配置plugin-catalog-backend1.15.0引入可选配置catalog.stitchingStrategy.mode变更8d756968f9取值为取值默认行为immediate是与升级前行为一致每个 processing 任务完成后**立即in-band、阻塞**执行 stitchingdeferred否将 stitching 推迟到独立的异步 worker 队列上执行与 processing 解耦catalog: stitchingStrategy: mode: deferred # 可选immediate默认 | deferred适用场景当大批量摄取实体、且实体之间关系呈现扇形展开/收敛fan-out / fan-in规模很大时deferred模式可以平滑吞吐、降低 p99 处理时延并避免热点实体被反复过度 stitching。代价是引入队列带来的额外墙钟时间开销。从源码看DefaultProcessingDatabase与DefaultProviderDatabase中已存在deferredEntities的完整处理链路见 DefaultProcessingDatabase.ts 与 DefaultProviderDatabase.tsdeferred 实体会被写入refresh_state表等待后续处理。5.2 新的 EntityPresentationApiplugin-catalog-react1.9.0新增EntityPresentationApi与entityPresentationApiRef变更1e5b7d993a用于统一控制实体引用链接、标题、图标等在 UI 中的呈现方式。plugin-catalog1.15.0提供默认实现DefaultEntityPresentationApi它会按需批量抓取并缓存 catalog 数据同时允许采纳方注册自定义渲染函数。配套变化EntityRefLink/EntityRefLinks组件改用该 API 渲染更准确的实体引用fetchEntities与getTitleprops 被废弃新增EntityDisplayName组件与EntityRefLink类似但无链接EntityRefLink图标按 Material-UI 规范移到左侧且支持hideIcons避免双图标69c14904b6catalog-graph0.3.0将完整Entity对象加入EntityNodeData并废弃name、kind、title、namespace、spec等冗余字段a604623324import { DEFAULT_NAMESPACE } from backstage/catalog-model; const { kind, metadata: { name, namespace DEFAULT_NAMESPACE, title }, } entity;5.3 位置分析Location Analyzer扩展点catalog-backend1.15.0与catalog-node1.5.0新增 catalog 分析扩展点支持注册 location analyzers同时把AnalyzeOptions与ScmLocationAnalyzer类型迁移到backstage/plugin-catalog-node变更e5bf3749adcatalog-backend-module-github也已改为从新位置导入这些类型。5.4 其他 Catalog 修复UserListPicker性能改进不再依赖EntityListContext推断 owned/starred 数量改为异步加载并为其导出的过滤器实现getCatalogFilters方法1fd53fa0c6实体的spec.lifecycle、spec.type字段现在始终按字符串渲染71c97e7d73MissingAnnotationEmptyState迁移至plugin-catalog-react导出6c357184e2core-components 中的旧组件被废弃0c5b78650c。六、Scaffolderrjsf v5、任务回收配置与模板按钮文案6.1 rjsf 升级到 v5next 能力转正plugin-scaffolder1.16.0与plugin-scaffolder-react1.6.0完成设计改进并支持rjsf/*v5变更3fdffbb699这是本版本中最容易引发编译错误的变更原先的createNextFieldExtension、NextScaffolderPage已提升为正式 APIcreateScaffolderFieldExtension与ScaffolderPage旧导入位置backstage/plugin-scaffolder/alpha、backstage/plugin-scaffolder-react/alpha失效需改从backstage/plugin-scaffolder与backstage/plugin-scaffolder-react导入如果遇到兼容问题旧实现以createLegacyFieldExtension、LegacyScaffolderPage的名义保留在/alpha但下一个主版本会移除rjsf/utils、rjsf/core、rjsf/material-ui、rjsf/validator-ajv8统一升级到5.13.6scaffolder-common为Template.v1beta3.schema.json补充了缺失的必填属性type2e0cef42ab。6.2 模板级控制按钮文案现在可以在每个模板中定义按钮文案Back / Create / Review76d07da66ascaffolder-react同时修复了非运行中任务的时间展示问题dda56ae265。6.3 任务回收Janitor可配置化plugin-scaffolder-backend1.19.0将过期任务回收改为可配置变更f3ab9cfcb7暴露两个配置项scaffolder: # 陈旧任务的扫描处理间隔 processingInterval: ... # 任务心跳超时阈值超过即视为陈旧任务 taskTimeoutJanitorFrequency: ...6.4 文件复制与 Git 动作增强copyWithoutTemplating/copyWithoutRender支持 globby 负向匹配7d5a921114可以包含整个子目录、同时排除某个文件让其继续参与模板渲染避免维护冗长的排除清单publish:github:pull-requestaction 支持update: true5e4127c18e可更新已存在的 PR大量 action 补充了示例与测试github:environment:create、github:webhook、github:deployKey:create、publish:github:pull-request、gitlab:projectAccessToken:create、publish:gerrit等。七、AuthStaticTokenIssuer、Okta 扩展作用域与 Vault 新后端系统7.1 StaticTokenIssuer 与 StaticKeyStoreplugin-auth-backend0.20.0新增StaticTokenIssuer与StaticKeyStore变更bdf08ad04a这是一种使用预定义公私钥对为 Authorization header 签名令牌的替代 token 签发器适合需要固定密钥、可预测签名的集成场景例如与外部系统共享验证公钥。对应实现见 plugins/auth-backend/src/identity/StaticTokenIssuer.ts 与 plugins/auth-backend/src/identity/StaticKeyStore.ts并配有 StaticTokenIssuer.test.ts 与 StaticKeyStore.test.ts 测试。7.2 Okta additionalScopes 与 Microsoft 相关修复oktaprovider 新增可选配置additionalScopes可在默认作用域之上追加自定义作用域f2fc5acca6Microsoft provider 回退到此前实现96c4f54bf6并修复了 profile 头像缺失与外部作用域 access token 获取问题头像尺寸从 48x48 调整为 96x96fde212dd10、client secret 标记、移除promptconsent等Azure Active Directory 品牌更名为 Entra ID相关 JSDoc 与错误消息同步更新243c655a68。7.3 Vault 插件支持新后端系统plugin-vault-backend0.4.0增加对新后端系统new backend system的支持a873a32a1f迁移方式import { createBackend } from backstage/backend-defaults; const backend createBackend(); // ... 其他功能注册 backend.add(import(backstage/plugin-vault-backend)); backend.start();token 续期任务可通过配置文件定义调度vault: baseUrl: BASE_URL token: TOKEN schedule: frequency: ... # 例如每小时 timeout: ... # 其他调度选项scope、initialDelay 等调度语义省略或设为false时不调度续期任务设为true时按默认每小时续期给出对象时使用自定义调度。同时VaultApi与VaultSecret被废弃改从backstage/plugin-vault-node导入7a41bcf2af。八、CLI 与工具链构建选项收敛与开发体验改进8.1 移除 --experimental-type-build 与 alphaTypes/betaTypesbackstage/cli0.24.0移除了已废弃的--experimental-type-build选项4e36abef14并停止支持publishConfig.alphaTypes/publishConfig.betaTypes字段8db5c3cd7a。如需生成/alpha、/beta入口请改用exports字段。cli-node0.2.0同步移除相关支持。8.2 从 esbuild-kit 切换到 tsxCLI 从已废弃的esbuild-kit/*包切换到tsx并在可用时使用新的register模块加载 API消除了启动 backend 时的实验性警告4ba4ac351f。8.3 EXPERIMENTAL_VITE 标志与 start 命令修复新增EXPERIMENTAL_VITE环境标志用于在开发时以 Vite 替代 Webpack 作为 dev servere14cbf563dstart命令生成 backend 子进程时忽略stdin修复 backend 启动挂起的问题7cd34392f5实验性包检测会忽略不提供package.json的包6bf7561d3c。8.4 基础设施升级knex 3 与 better-sqlite3 9本版本将knex提升到 major 3、better-sqlite3提升到 major 9013611b42e这同时意味着 Node 16 不再受支持。在自有仓库中可按如下方式对齐依赖以获取后续 Node 18 相关更新参考 packages/create-app 的迁移模板dependencies: { // ... knex: ^3.0.0 }, devDependencies: { // ... better-sqlite3: ^9.0.0 }九、TechDocs、Search 与其他插件要点9.1 TechDocsplugin-techdocs1.9.0访问不存在的文档站点时发布新的not-foundanalytics 事件17f93d5589修复跨页导航与浏览器前进/后退时的滚动位置问题4728b3960dplugin-techdocs-backend1.9.0暴露自定义构建策略的扩展点DocsBuildStrategy类型迁移到plugin-techdocs-node并废弃ShouldBuildParameters67cff7b06f构建失败时补充实体信息c3c5c7e514修复 build log transport 未提供时创建传输导致的内存泄漏48a61bfdcatechdocs/cli1.7.0运行 mkdocs server 前校验 Docker 状态8600b86820。9.2 Search新模块backstage/plugin-search-backend-module-stack-overflow-collator0.1.0从plugin-stack-overflow-backend中抽出后者被废弃46f0f1700e、b168d7e7eacollator 的requestParams现为可选默认值为{ order: desc, sort: activity, site: stackoverflow }plugin-search-backend-module-elasticsearch1.3.10支持 AWS OpenSearch Serverless不支持_refresh端点plugin-search-backend-module-pg0.5.16优化大表上过期文档删除逻辑2b4cd1ccaeplugin-search-backend-node1.2.11修复 Lunr 引擎对非字符串字段的高亮问题plugin-search-react1.7.2将搜索 analytics 采集移入 search hook并修复搜索框竞态问题f48cde800a、f75caf9f3dtechdocs 搜索索引字段的定制流程被简化c437253b7a。9.3 其他值得关注的变更api-docs0.10.0以 DocExplorer 取代 GraphiQL playground并为swagger-ui-react的oauth2RedirectUrl定义默认值0ac0e10822、62310404b7Playlist0.2.0支持自定义可组合的 Playlist 首页但包含一个破坏性变更——PlaylistPage路由需手动接入-import { PlaylistIndexPage } from backstage/plugin-playlist; import { PlaylistIndexPage, PlaylistPage } from backstage/plugin-playlist; Route path/playlist element{PlaylistIndexPage /} / Route path/playlist/:playlistId element{PlaylistPage /} /Home0.5.10新增FeaturedDocsCard组件可按 filter 展示任意实体302316d231修复retrieveAll未抓取访问记录的问题d86b2acec4backend-common0.19.9数据库创建并发限制为 1aa13482090core-components0.13.8修复 Safari 16.3 兼容性消除extractInitials中的 RegExp lookbehindRoutedTabs无 tabs 时不再崩溃StructuredMetadataTable的options.titleFormat应用到包括嵌套在内的所有键user-settings-backend补充对backstage/config的依赖dd0350379b。十、升级路径与破坏性变更清单基于 v1.20.0 changelog升级到该版本时需要重点检查以下破坏性变更Playlist 路由拆分必须手动添加Route path/playlist/:playlistId element{PlaylistPage /} /否则播放列表详情页不可用。Scaffolder 字段扩展 API 转正将createNextFieldExtension/NextScaffolderPage的导入从/alpha改为正式包旧 API 仅保留一个版本周期。CLI 选项移除删除--experimental-type-build与publishConfig.alphaTypes/betaTypes改用exports字段定义/alpha、/beta入口。Node 16 弃用knex3/better-sqlite39意味着运行环境需 Node 18。部分类型迁移AnalyzeOptions/ScmLocationAnalyzer移至plugin-catalog-nodeDocsBuildStrategy移至plugin-techdocs-nodeVaultApi/VaultSecret移至plugin-vault-nodeMissingAnnotationEmptyState改从plugin-catalog-react导入。废弃项提示AnyParams被AnyRouteRefParams取代EntityNodeData上的name、kind、title、namespace、spec字段废弃plugin-stack-overflow-backend与plugin-playlist中旧版相关能力废弃。升级完成后可以立刻验证两项新能力访问任一已接入 OpenAPI 工具链的后端插件路由/openapi.json查看其规范输出以及在 catalog 配置中尝试catalog.stitchingStrategy.mode: deferred观察大批量实体摄取时的性能表现。十一、总结v1.20.0 是 Backstage 在三个方向上同时发力的版本全面拥抱 React 18让全栈前端生态站在最新的渲染模型之上新前端系统路由与扩展体系成型app.routes.bindings、AppTreeApi、新RouteRef体系与/alpha声明式扩展共同勾勒出下一代前端插件的轮廓OpenAPI 工具链闭环从createValidatedOpenApiRouter、/openapi.json标准端点到wrapInOpenApiTestServer与schema openapi test运行时校验再到catalog-backend-module-backstage-openapi将 spec 建模为 Catalog 实体为后端插件的契约化开发提供了完整支撑。与此同时Catalog 的 deferred stitching、Scaffolder 的 rjsf v5 与任务回收配置、Auth 的 StaticTokenIssuer 等改进则为生产环境的大规模实体管理、模板工程化与身份集成提供了更精细的控制能力。如需逐包核对变更可继续阅读仓库内的 docs/releases 目录下的各版本 changelog或参考 packages/backend-openapi-utils、plugins/catalog-backend、plugins/scaffolder-backend、plugins/auth-backend 的源码与测试用例深入验证。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考