Backstage v1.10.0-next.0 版本解读Catalog 服务端排序、Scaffolder 实体过滤与搜索索引稳定性增强【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南基于 docs/releases/v1.10.0-next.0-changelog.md 整理并结合本仓库源码packages/catalog-client、plugins/catalog-backend、plugins/scaffolder、plugins/search-backend-module-elasticsearch等对三项核心变更进行纵深剖析。读者读完可以掌握如何利用getEntities的order参数与 Catalog 服务端排序 API 落地稳定、可预期的实体列表顺序如何用catalogFilter取代已废弃的allowedKinds精确控制 Scaffolder 选择器候选实体以及如何理解 Elasticsearch 索引吞吐与进程稳定性修复背后的实现细节。文中给出的 API 参数格式、请求示例与配置代码均来自当前仓库实际代码可直接用于v1.10.0系列的升级与排障。版本概览一次围绕 Catalog 与 Scaffolder 的 minor 升级v1.10.0-next.0是 Backstage 1.10 系列的第一个预发布next版本采用 Backstage 常规的按包版本化发布节奏各backstage/*包独立版本号并在本次迭代中集中升级。本仓库docs/releases/目录下保存了完整的版本变更记录本文对应的 v1.10.0-next.0-changelog.md 全文约 1900 行覆盖了包括backstage/cli、backstage/core-components、backstage/create-app、backstage/repo-tools以及数十个前端插件在内的依赖更新。其中真正带来行为变化的核心亮点集中在三处均以Minor Changes标记变更涉及包类型getEntities支持order指令entities 端点实现服务端排序backstage/catalog-client1.3.0-next.0、backstage/plugin-catalog-backend1.7.0-next.0MinorOwnerPicker/EntityPicker新增catalogFilter字段allowedKinds废弃backstage/plugin-scaffolder1.10.0-next.0及多个 scaffolder-backend 模块MinorCatalog 内部引用残留修复d136793ff0backstage/plugin-catalog-backend1.7.0-next.0PatchElasticsearch 索引吞吐与进程稳定性修复backstage/plugin-search-backend-module-elasticsearch1.1.1-next.0Patch此外plugin-search-backend1.2.1-next.0允许配置搜索结果的最大分页限制plugin-catalog-react1.2.4-next.0修复了EntityTagPicker对已选 kind 过滤不可用标签的问题backstage/cli0.22.1-next.0则带来若干与 Yarn 工作区相关的修复详见后文。Catalog 服务端排序从客户端排序到order指令变更内容与动机在v1.10.0-next.0之前getEntities返回的实体顺序在服务端并不保证稳定依赖列表排序的调用方需要自行处理。本次通过提交f75bf76330在 packages/catalog-client/src/types/api.ts 中新增了EntityOrderQuery类型并把它挂到GetEntitiesRequest.order上同时在 packages/catalog-client/src/CatalogClient.ts 中把该指令编码进 HTTP 请求参数。与之对应plugins/catalog-backend在 entities 端点实现了真正的服务端排序。EntityOrderQuery的定义如下export type EntityOrderQuery | { field: string; order: asc | desc; } | Array{ field: string; order: asc | desc; };该类型在注释中明确了以下语义见 types/api.tsfield是实体内以点分隔的字段路径例如kind、metadata.name、spec.typeorder只能是asc升序字典序或desc降序逆字典序排序大小写不敏感传入数组时按顺序构成多级排序靠前的指令优先级更高仅当高优先级字段值相等时才使用后面的指令例如先按kind升序、再在同 kind 内按metadata.name降序当某个字段在结果集中部分实体上不存在时缺失该字段的实体在该排序步骤中始终排在最后无论期望是升序还是降序。客户端如何编码order在 CatalogClient.ts 中getEntities将order序列化为asc:field/desc:field形式的查询参数if (order) { for (const directive of [order].flat()) { encodedOrder.push(${directive.order}:${directive.field}); } // ... params.order encodedOrder; }即{ field: metadata.name, order: desc }会被编码为orderdesc:metadata.name。多个指令可以重复order参数例如orderasc:kindorderdesc:metadata.name。服务端解析格式校验与归一化服务端在 plugins/catalog-backend/src/service/request/parseEntityOrderParams.ts 中用正则^(asc|desc):(.)$校验每个order参数非法格式会抛出InputErrorInvalid order parameter value, expected asc or desc:field name解析得到的EntityOrder[]会进入查询流水线parseEntityQuery.ts 还统一校验order值必须为asc/desc否则抛出Invalid order field order, must be asc or desc最终在数据库层转换为排序条件。相关测试覆盖了单字段、多字段、缺省顺序以及非法顺序如metadata.uid,invalid等场景可参考 parseEntityOrderParams.test.ts 与 parseEntityQuery.test.ts。客户端调用示例import { catalogApiRef, useApi } from backstage/core-plugin-api; const catalogApi useApi(catalogApiRef); // 单级排序按 name 降序 const result await catalogApi.getEntities({ order: { field: metadata.name, order: desc }, }); // 多级排序先按 kind 升序再按 name 降序 const multi await catalogApi.getEntities({ order: [ { field: kind, order: asc }, { field: metadata.name, order: desc }, ], });顺带的变化orderFields走向统一值得留意的是同一版本的 CatalogClient.ts 中queryEntities的orderFields参数也被保留并编码为orderFieldfield,order形式例如orderFieldmetadata.name,desc服务端解析见 parseEntityOrderFieldParams.ts。两套排序入口在语义上保持对齐createQueryCatalogEntitiesAction也支持在模板 Action 中使用orderFields单条或数组见 createQueryCatalogEntitiesAction.ts。Scaffolder 选择器用catalogFilter取代allowedKinds变更内容backstage/plugin-scaffolder1.10.0-next.0以及plugin-scaffolder-backend、scaffolder-backend-module-cookiecutter/rails/yeoman通过提交e4c0240445为OwnerPicker、EntityPicker新增catalogFilter字段用于按实体的任意字段过滤候选选项。同时TheallowedKindsfield has been deprecated. UsecatalogFilterinstead.即allowedKinds被标记为废弃。在前端字段 Schema 中可以看到明确的废弃标注allowedKinds: z .array(z.string()) .optional() .describe(DEPRECATED: Use catalogFilter instead. ...),见 plugins/scaffolder/src/components/fields/EntityPicker/schema.ts。catalogFilter的取值类型为“单条过滤表达式或过滤表达式数组”t.or(t.array())每个表达式是键值对记录见 schema.ts。底层映射uiSchema到EntityFilterQuery在 EntityPicker.tsx 中catalogFilter会被构造成查询条件并通过getEntities流式请求拉取候选const catalogFilter buildCatalogFilter(uiSchema); const streamRequest catalogFilter ? { query: {}, filter: catalogFilter, fields } : // ... 原有查询路径buildCatalogFilterEntityPicker.tsx负责把ui:options.catalogFilter中的表达式转换为EntityFilterQuery数组输入被逐条convertSchemaFiltersToQuery单个对象输入则直接转换。也就是说模板中写的过滤条件最终会透传给 CatalogClient与getEntities的filter参数同构。模板中的完整用法原 changelog 示例获取所有kind: Group的实体作为 Owner 候选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对比旧写法ui:options: { allowedKinds: [Group] }catalogFilter的表达能力从“只按 kind”扩展为“任意字段含spec.*的任意组合”并且支持传入数组表达“或”关系的多组过滤条件。同版本OwnerPicker、MultiEntityPicker也一并支持该字段相关测试可参考 EntityPicker.test.tsx、MultiEntityPicker.test.tsx 与 OwnerPicker.test.tsx。升级提示存量模板如果使用allowedKinds功能仍然可用仅废弃未移除但建议在升级到v1.10.0系列时迁移为等价的catalogFilterallowedKinds: [Group]对应catalogFilter: [{ kind: Group }]由于该字段作用于ui:options属于前端表单 Schema 与后端执行共用的描述scaffolder-backend各模块同样接收该配置见 changelog 中三个 backend 模块的同步更新因此前后端版本需同步升级。版本中的其他值得关注的变化Scaffolder 表单体验Stepper与校验器回退223e2c5f03为Stepper组件新增onChange处理器便于在多步表单切换时感知状态变化3c112f6967将rjsf/validator-ajv8回退为rjsf/validator-v6。这是一次兼容性回退说明 ajv8 校验器在当前 rjsf 版本组合下存在兼容问题升级时应保持该依赖组合不变。Elasticsearch 搜索索引的稳定性与吞吐优化backstage/plugin-search-backend-module-elasticsearch1.1.1-next.0本次包含三个 Patch 修复见 v1.10.0-next.0-changelog.md1e1a9fe979修复索引流程可能静默失败、超时并积累陈旧索引stale indices的问题56633804dd修复索引过程中遇到客户端错误时可能导致 Backstage 后端意外终止的问题aa33a06894通过优化批量客户端可获取文档的时机与数量来提升索引吞吐。这三项修复共同提升了大规模实体入库场景下 Elasticsearch 索引任务的健壮性对部署了 Elasticsearch 搜索后端的用户尤其重要。此外backstage/plugin-search-backend1.2.1-next.0bfd66b0478允许配置搜索结果的最大分页限制搜索 API 的分页行为因此可被显式约束。Catalog 引用残留修复d136793ff0plugin-catalog-backendPatch修复了 catalog 内部引用存留时间超过预期的问题——该问题此前会导致实体无法按预期被删除或孤儿化orphaned。该修复保证引用关系的清理时机与实体生命周期一致对使用 orphan cleanup 机制参见 contrib/scripts/orphan-clean-up的部署有直接影响。CLI 与依赖治理backstage/cli0.22.1-next.0的 Patch 变更集中在依赖一致性上47c10706df修复 Yarn 3 下yarn.lock同时存在 workspace 与非 workspace 版本的同名包时 CLI 失效的问题a62a1f9dcafrontend serve任务的包检查现在与versions:bump、versions:check一致地过滤允许的重复包7c8a974515repo test/repo lint/repo build在基于--since ref寻找变更包时会分析yarn.lock的依赖变更从而在存在 lockfile 变更时也能正确限定范围e1b71e142e版本命令不再将 workspace 范围视为非法。这些改进降低了大型 monorepo 中并发升级依赖时的摩擦。升级与验证建议同步升级前后端本次catalog-client、plugin-catalog-backend、plugin-scaffolder之间存在依赖联动见 changelog 中各自的 “Updated dependencies”建议整体升级到v1.10.0-next.0对应版本避免新旧客户端与服务端对order参数理解不一致。验证排序行为升级后使用getEntities({ order: [...] })做一次冒烟测试重点验证多级排序的优先级与“缺失字段排最后”的语义是否符合预期可用 parseEntityOrderParams.test.ts 中的用例作为行为基准。迁移allowedKinds搜索仓库内模板对allowedKinds的使用逐一替换为catalogFilter并在 Scaffolder 表单中实际选择一次以验证过滤结果。留意 Elasticsearch 配置若使用 ES 搜索后端升级后观察索引任务日志确认陈旧索引清理与批量吞吐优化生效如需限制搜索分页上限可参考plugin-search-backend的新增配置项。小结v1.10.0-next.0是围绕 Catalog 数据访问能力的一次实质性增强getEntities的order指令与服务端排序让实体列表顺序变得可预期catalogFilter让 Scaffolder 的实体选择器获得与 Catalog 查询同构的过滤能力而 Elasticsearch 索引修复与 CLI 依赖治理则为生产环境的稳定性提供了保障。结合本文给出的源码路径与测试用例读者可以在升级过程中快速定位行为差异并进行验证。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考