Backstage v1.10.0 版本深度解析Scaffolder 组件包化、后端系统服务化重构与 Catalog 服务端排序【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage v1.10.0 是围绕Scaffolder 生态重构与新后端系统New Backend System服务化落地两个主线展开的里程碑版本Scaffolder 前端通用代码被拆分为独立的backstage/plugin-scaffolder-react包后端系统则完成了createServiceFactory签名重构、根 HTTP 路由服务引入等一系列破坏性变更。本文基于仓库内的官方变更日志docs/releases/v1.10.0-changelog.md结合当前仓库源码逐项解读 v1.10.0 的 Major/Minor/Patch 变更帮助你评估升级影响、掌握新 API 用法并理解底层实现原理。一、Scaffolder 前端通用代码搬家到新包 plugin-scaffolder-reactv1.10.0 最值得关注的 Major 变更是新发布了backstage/plugin-scaffolder-react1.0.0b4955ed7b9一批原本属于backstage/plugin-scaffolder的公共类型、组件、Hook 以及scaffolderApiRef被re-home重新安置到这个新包中以便所有希望与 Scaffolder 交互的组件轻松复用避免从插件主包中引用内部实现。对应的backstage/plugin-scaffolder1.10.0对下列导出标记为弃用Deprecated请改为直接从backstage/plugin-scaffolder-react导入createScaffolderFieldExtension、ScaffolderFieldExtensions、useTemplateSecrets、scaffolderApiRef、ScaffolderApi、ScaffolderUseTemplateSecrets、TemplateParameterSchema、CustomFieldExtensionSchema、CustomFieldValidator、FieldExtensionOptions、FieldExtensionComponentProps、FieldExtensionComponent、ListActionsResponse、LogEvent、ScaffolderDryRunOptions、ScaffolderDryRunResponse、ScaffolderGetIntegrationsListOptions、ScaffolderGetIntegrationsListResponse、ScaffolderOutputlink、ScaffolderScaffoldOptions、ScaffolderScaffoldResponse、ScaffolderStreamLogsOptions、ScaffolderTask、ScaffolderTaskOutput、ScaffolderTaskStatus。同时还有两点结构性调整rootRouteRef导出被弃用应改用scaffolderPlugin.routes.root以下/alpha类型已从本包移除并迁入backstage/plugin-scaffolder-react/alphacreateNextScaffolderFieldExtension、FormProps、NextCustomFieldValidator、NextFieldExtensionComponentProps、NextFieldExtensionOptions。此外该版本把校验器从rjsf/validator-ajv8回退到rjsf/validator-v63c112f6967并给 Scaffolder 动作描述启用了MarkdownContent渲染2fadff2a25动作文档页开始展示动作示例 YAML489935d625。二、表单字段升级catalogFilter 正式取代 allowedKindsv1.10.0 为OwnerPicker和EntityPicker组件新增了catalogFilter字段e4c0240445用于按实体的任意字段过滤候选选项同时弃用allowedKinds。catalogFilter的结构与传入CatalogClient的EntityFilterQuery一致。只筛选kind为Group的所有实体owner: title: Owner type: string description: Owner of the component ui:field: OwnerPicker ui:options: catalogFilter: - kind: Group同时限定kind为Group且spec.type为teamowner: title: Owner type: string description: Owner of the component ui:field: OwnerPicker ui:options: catalogFilter: - kind: Group spec.type: team从源码可以看到其兼容与优先级的真实逻辑在 EntityPicker.tsx 的buildCatalogFilter中catalogFilter显式优先未配置时才会回退到旧的allowedKinds转换为{ kind: allowedKinds }数组形式会逐个映射为查询条件对应的测试用例EntityPicker.test.tsx也专门覆盖了catalogFilter优先于allowedKinds的行为。三、Scaffolder 后端新增 catalog:fetch 动作与动作示例 API3.1 新动作catalog:fetchbackstage/plugin-scaffolder-backend1.10.0新增动作catalog:fetchc0ad7341f7可按实体引用从 Catalog 中获取实体。其实现位于 fetch.ts输入输出如下参数类型说明entityRefstring可选要获取的单个实体的实体引用entityRefsstring[]可选要获取的多个实体引用optionalboolean可选允许实体不存在默认false为true时缺失实体输出null而非报错defaultKindstring可选实体引用的默认 kinddefaultNamespacestring可选实体引用的默认 namespace输出entityobject仅使用entityRef时的输出输出entitiesobject[]仅使用entityRefs时的输出实现细节上动作会先经parseEntityRef/stringifyEntityRef规范化引用再调用catalog.getEntityByRef/catalog.getEntitiesByRefs并透传ctx.getInitiatorCredentials()作为凭据动作声明了supportsDryRun: true且当optional为false而实体缺失时会抛出Entity ... not found错误。3.2 createTemplateAction 支持 examples/v2/actions 可获取示例createTemplateAction函数现在接受一个examples列表b44eb68bcb用于为动作提供使用示例const actionExamples [ { description: Example 1, example: yaml.stringify({ steps: [ { action: test:action, id: test, input: { input1: value, }, }, ], }), }, ]; export function createTestAction() { return createTemplateAction({ id: test:action, examples: [ { description: Example 1, examples: actionExamples, }, ], // ... }); }这些示例可通过 API 获取curl http://localhost:7007/api/scaffolder/v2/actions[ { id: test:action, examples: [ { description: Example 1, example: steps:\n - action: test:action\n id: test\n input:\n input1: value\n } ], schema: { input: { type: object, properties: { input1: { title: Input 1, type: string } } } } } ]该端点实现在 router.tsGET /v2/actions从actionRegistry.list()中取出动作仅公开id、description、examples、schema四个字段并按 id 排序返回前端ActionsPage据此渲染动作示例 YAML 与 Markdown 描述。3.3 GitHub / Bitbucket 发布动作增强publish:github动作a6808b67a7、04a2048fb8、a69664faee新增能力支持Required approving review count必需批准审查数、Restrictions分支限制与Required commit signing必需提交签名支持在 GitHub 仓库上配置自定义仓库角色custom repository roles支持squash merge的 commit title 与 message 选项。publish:bitbucketServer动作72d6b9f4e2新增了对 commit message 与 author 详情的覆盖能力。3.4 新模块Sentry Scaffolder 动作包新发布的backstage/plugin-scaffolder-backend-module-sentry0.1.066ff367af6提供 Sentry 相关的 Scaffolder 动作源码位于 plugins/scaffolder-backend-module-sentry/src/actions包含createProject创建项目与fetchDSN获取 DSN等动作并配套了示例与测试文件。四、后端系统New Backend System的重大演进v1.10.0 对实验性后端系统做了一轮大规模重构涉及backend-plugin-api0.3.0、backend-app-api0.3.0、backend-common0.18.0、backend-defaults0.1.5等核心包升级时需重点核对。4.1 createServiceFactory 新签名用 createRootContext 取代嵌套回调createServiceFactory不再使用重复回调模式创建插件级服务483e907eaf外层回调被可选的createRootContext方法取代工厂与根上下文函数现在可以是同步的同时为支持TypeScript 4.9做了铺垫。迁移前后的写法对比源自变更日志// 旧写法 createServiceFactory({ service: coreServices.cache, deps: { config: coreServices.config, plugin: coreServices.pluginMetadata, }, async factory({ config }) { const cacheManager CacheManager.fromConfig(config); return async ({ plugin }) { return cacheManager.forPlugin(plugin.getId()); }; }, });// 新写法 createServiceFactory({ service: coreServices.cache, deps: { config: coreServices.config, plugin: coreServices.pluginMetadata, }, async createRootContext({ config }) { return CacheManager.fromConfig(config); }, async factory({ plugin }, manager) { return manager.forPlugin(plugin.getId()); }, });许多场景并不需要根上下文可直接写同步工厂createServiceFactory({ service: coreServices.logger, deps: { rootLogger: coreServices.rootLogger, plugin: coreServices.pluginMetadata, }, factory({ rootLogger, plugin }) { return rootLogger.child({ plugin: plugin.getId() }); }, });该签名在 types.ts 中体现为PluginServiceFactoryOptions的createRootContext?(deps): TContext | PromiseTContextcreateServiceFactory实现会在检测到createRootContext时透传给InternalServiceFactory见 types.ts。4.2 根 HTTP 路由服务 rootHttpRouterServiceRefbackend-app-api0.3.0引入破坏性变更httpRouterFactory现在接受getPath选项而非indexPlugin02b119ff93如需自定义 index 路径应通过新的rootHttpRouterFactory配置indexPath。同版本新增rootHttpRouterServiceRef与RootHttpRouterService接口并把DefaultRootHttpRouter作为导出实现公开51b7a7ed07。RootHttpRouterService的接口非常精简见 RootHttpRouterService.tsexport interface RootHttpRouterService { use(path: string, handler: Handler): void; }其默认实现 DefaultRootHttpRouter.ts 对indexPath的处理规则是undefined时默认/api/app显式false时禁用 index 路由空字符串会直接抛错indexPath option may not be an empty string对应测试见 DefaultRootHttpRouter.test.ts。在backend-defaults0.1.5中新的根 HTTP 路由服务默认安装02b119ff93插件级 HTTP 路由会挂载到根路由上见 httpRouterServiceFactory.ts 中的rootHttpRouter.use(/api/${plugin.getId()}, router)。4.3 生命周期、身份、日志与配置服务下沉新增RootLifecycleService与rootLifecycleServiceRef6cfd4d7073LifecycleServiceShutdownHook增加logger选项backend-defaults与backend-test-utils均包含其默认实现新增核心身份服务core identity service843a0a158cbackend-defaults将其加入默认服务工厂集合日志与配置加载实现从backend-common迁入backend-app-api新增实现RootLoggerService的WinstonLoggerloadBackendConfig改为返回带config属性的对象0e63aab311RootLoggerService新增addRedactions方法插件日志器的标签由pluginId改为plugine3fca10038新增ServiceFactoryOrFunction类型ecc6bfe4c9支持直接传ServiceFactory或() ServiceFactorycreateSpecializedBackend在提供重复服务实现时会抛出错误015a6dced6backend-defaults同步保证自定义实现可替换默认实现。4.4 拆分后端支持createSharedEnvironmentbackend-plugin-api新增createSharedEnvironment5b7bcd3c5e用于在拆分后端split backend部署中创建包含常用服务的共享环境backend-defaults的createBackend也支持传入该共享环境。这为多进程拆分部署场景提供了官方基础设施。4.5 测试工具增强backend-test-utils0.1.32的startTestBackend现在会为所有核心服务提供默认实现a3ec2f32ea并返回一个TestBackend实例可通过其server配合supertest等库进行 HTTP 级测试51b7a7ed07。配合上述默认服务实现编写后端集成测试的门槛大幅降低。4.6 UrlReader 清理与 legacy 包装器backend-common0.18.0有破坏性变更移除了UrlReader接口上已弃用的read方法所有实现都应改用readUrl5e2cebe9a3UrlReader及关联类型迁入backend-plugin-api当前仍从backend-common重新导出以兼容。同时backend-common新增legacyPlugin与底层makeLegacyPlugin包装器31e2309c8c用于把旧式插件桥接到新后端系统为后续迁移铺路官方暂不建议主动使用。4.7 依赖升级better-sqlite3升级到^8.0.0f23eef3aa2涉及 backend-common、catalog-backend、backend-test-utils 等若手工维护packages/backend/package.json可按create-app0.4.36给出的 diff 升级- better-sqlite3: ^7.5.0, better-sqlite3: ^8.0.0,五、Catalog服务端排序与实体接口增强backstage/catalog-client1.3.0为getEntities实现order指令支持f75bf76330前端可按字段指定排序方向backstage/plugin-catalog-backend1.7.0在 entities 端点实现了服务端排序f75bf76330将排序压力从客户端下沉到后端by-refs端点现在可以通过POST body接收fields而不只是查询参数e23f13a573有助于避免 URL 过长修复了 catalog 内部引用滞留时间过长、导致实体无法如期删除或成为孤儿orphan的问题d136793ff0backstage/plugin-catalog-backend-module-github0.2.3为GithubOrgEntityProvider增加基于事件webhook的更新427d8f4411收到 GitHub 事件后刷新受影响的User/Group实体含新增、刷新与删除并修复了catalogPath对 GitHub 事件的 glob 匹配问题f8d91a8810。六、应用级 Feature Flags 与配置布尔值解析backstage/app-defaults1.1.0、backstage/core-app-api1.4.0、backstage/core-plugin-api1.3.0现在允许在应用层面定义 Feature Flagsbca8e8b393详见 feature-flags 文档同时 Feature Flags 新增description属性bca8e8b393体现在 plugin-user-settings0.6.2 中。backstage/config1.0.6的getBoolean现在支持布尔值强转ba2d69ee17true、1、on、y会变为true对应的反义值变为false。这对环境变量替换场景尤为重要——环境变量永远是字符串此前getBoolean无法直接解析它们。七、搜索、技术雷达与 CLI 实用改进7.1 搜索backstage/plugin-search-react1.4.0的SearchResult支持通过noResultsComponent属性自定义空结果状态6d9a93def8SearchResult noResultsComponent{No results were found/} {({ results }) ( List {results.map(({ type, document }) { switch (type) { case custom-result-item: return ( CustomResultListItem key{document.location} result{document} / ); default: return ( DefaultResultListItem key{document.location} result{document} / ); } })} /List )} /SearchResultplugin-search1.0.7打开搜索弹窗时焦点自动落在搜索输入框a24387c6deplugin-search-backend1.2.1搜索结果的最大分页数现在可配置bfd66b0478plugin-search-backend-module-elasticsearch1.1.1修复了索引过程静默失败/超时/陈旧索引累积、客户端错误导致后端意外终止等问题并通过优化批量客户端文档投递提升索引吞吐1e1a9fe979、56633804dd、aa33a06894。7.2 技术雷达backstage/plugin-tech-radar0.6.0增加图例项高亮与悬停气泡显示38fd519fc1。7.3 CLI 与 TechDocs CLIbackstage/cli0.22.1repo test、repo lint、repo build现在会分析yarn.lock的依赖变化来定位变更包--since ref在仅有锁文件变更时也可用7c8a974515修复 Yarn 3 下同一包同时存在 workspace 与非 workspace 版本时 CLI 失效的问题47c10706df新增实验性环境变量为生产构建启用缓存4b572126f1更新后端插件创建时的插件 ID使其与用户输入一致2b435be4cf。techdocs/cli1.3.0的serve命令新增--preview-app-bundle-path与--preview-app-port选项bc18c902a2允许使用自带的应用包与端口进行 TechDocs 预览。八、其余值得关注的变更ADR 插件plugin-adr0.3.0现在可以支持 GitHub 之外的站点但需要安装backstage/plugin-adr-backend并通过其createRouter方法接入后端e4469d0ec1破坏性变更默认 ADR 解析器明确支持 MADR 规范 v2.x21ffbdd5ee。事件系统plugin-events-backend0.2.1默认事件代理会捕获并记录订阅者onEvent抛出的错误publish返回的 Promise 会等待所有订阅者处理完毕217149ae98。Tech Insights 后端plugin-tech-insights-backend0.5.6单个检查出错不再阻塞其余检查7a38a31699暴露可选persistenceContext让集成方提供自定义事实存储44c18b4d3f数据库清理逻辑优化为按实体删除全部事实大幅改善大数据集查询性能b48317cfc6。AWS 集成integration-aws-node0.1.1在不需要时跳过 STS API 调用以支持 Minio 场景89062b8ba0。Catalog 前端plugin-catalog1.7.2新增EntityLabelsCard展示实体 labelscebe24ef1d实体上下文菜单增加 tooltip5353b4df61。Catalog Reactplugin-catalog-react1.2.4新增可复用的EntityPeekAheadPopover悬浮卡片组件516b2039b6。Kubernetes 后端plugin-kubernetes-backend0.9.1修复带 base path 的集群 URL 被替换而非追加的问题083bf1b9fa并在配置 schema 中补充缺失的googleServiceAccount认证提供方c6f29bfcdc。Cloudbuildplugin-cloudbuild0.3.14修复reRunWorkflow请求方法未显式指定而默认 GET 的问题现显式改为 POST1188407632。示例应用example-app、example-backend、example-backend-next、techdocs-cli-embedded-app等均随依赖同步升级到 v1.10.0 对应版本。九、升级到 v1.10.0 的迁移清单Scaffolder 导入调整将变更日志列出的弃用导出改为从backstage/plugin-scaffolder-react导入rootRouteRef改用scaffolderPlugin.routes.root/alpha类型从backstage/plugin-scaffolder-react/alpha导入。表单字段用catalogFilter取代allowedKindscatalogFilter优先级更高二者均可临时共存。后端系统 API 迁移按createRootContext新签名重写createServiceFactoryhttpRouterFactory的indexPlugin选项替换为getPathindex 路径通过rootHttpRouterFactory的indexPath配置默认/api/app。UrlReader将read调用替换为readUrl。依赖升级better-sqlite3升至^8.0.0。ADR 插件若使用 ADR 且目标站点非 GitHub需安装并接入backstage/plugin-adr-backend。配置布尔值环境变量替换后的true/1/on/y字符串现在会被getBoolean正确解析注意与旧行为差异。以上就是 Backstage v1.10.0 的核心变更全景。对 Scaffolder 使用者而言重点是导入路径与catalogFilter的迁移对正在跟进新后端系统的开发者createServiceFactory新签名、根 HTTP 路由服务与createSharedEnvironment则标志着后端服务化架构正式进入下一阶段。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
