Backstage v1.12.0-next.0 版本解读Catalog 游标分页查询、新插件与后端系统演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术解读以仓库中的官方发布记录 docs/releases/v1.12.0-next.0-changelog.md 为主体结合仓库内对应源码如 CatalogClient 与 createRouter逐一剖析 v1.12.0-next.0 这个预发布版本的核心变更。读完本文你将掌握如何通过新的queryEntitiesAPI 与/entities/by-query端点实现游标分页与服务端排序、两个全新插件Octopus Deploy 与 StackStorm的接入方式、linguist-backend的破坏性变更迁移方法以及proxy-backend请求体恢复、CLI 新增命令等一批值得关注的能力升级。版本概览一次小而美的预发布v1.12.0-next.0是 Backstage 在正式 v1.12.0对应发布说明见 docs/releases/v1.12.0.md之前的首个预发布next版本采用标准的逐包per-package变更记录格式覆盖从backstage/catalog-client、backstage/plugin-catalog-backend到example-app、example-backend在内的全部工作区包。该版本没有包含安全修复正式版说明中明确 This release does not contain any security fixes。从变更记录看本次发布的核心增量集中在四个方面变更类型涉及包内容Minor新能力backstage/catalog-client在CatalogApi中新增queryEntities方法Minor新能力backstage/plugin-catalog-backend新增/entities/by-query端点支持游标分页与服务端排序MinorUI 增强backstage/plugin-catalog、backstage/plugin-techdocs支持把 icon 作为函数传入按搜索结果项动态定制MinorUI 增强backstage/plugin-catalog-reactEntityPicker支持多选 filtersMinor破坏性backstage/plugin-linguist-backendcreateRouter必须显式传入tokenManagerMinor新插件backstage/plugin-octopus-deploy、backstage/plugin-stackstorm全新前端插件初始版本 0.1.0Patch重要backstage/plugin-proxy-backend新增reviveConsumedRequestBodies选项Patch重要backstage/cli新增migrate package-exports命令下面逐项深入。核心能力从 Catalog 读取分页数据本次发布最重磅的功能是给 Catalog 补齐了基于游标cursor的分页查询能力前后端配套落地客户端侧backstage/catalog-client在CatalogApi接口中新增queryEntities方法服务端侧backstage/plugin-catalog-backend新增/entities/by-query端点支持游标分页与服务端排序。官方发布说明将其定位为用于定向优化前端等场景中的性能热点hot-spots——过去一次性拉取全量实体再在浏览器端过滤排序的做法从此可以替换为按需、分页的服务端查询。客户端 APIqueryEntities 的设计在 packages/catalog-client/src/types/api.ts 中queryEntities的类型体系由三类请求/响应类型组成QueryEntitiesRequest联合类型等于QueryEntitiesInitialRequest | QueryEntitiesCursorRequest即首次请求与翻页请求两种形态QueryEntitiesInitialRequest首次请求携带fields、limit、offset、filter、query、orderFields、fullTextFilter、totalItems等参数。其中filter与query可以单独使用也可以同时使用filter传统的 key-value 过滤语法对应 GET 端点query基于谓词predicate的过滤语法支持$all、$any、$not逻辑操作符与$exists、$in、$hasPrefix、$contains匹配操作符QueryEntitiesCursorRequest翻页请求只携带fields、limit与cursor后续批次完全由服务端返回的游标驱动QueryEntitiesResponse包含items当前批次实体列表、totalItems全量总数与pageInfonextCursor/prevCursor用于前后翻页。值得注意的细节是首次请求中的filter、query、sortField、sortFieldOrder等属性在整条分页链路的后续请求中是**不可变immutable**的翻页请求只能通过 cursor 延续从而保证分页期间过滤与排序条件的一致性。totalItems字段还支持include | exclude两档控制——exclude时跳过全量计数、响应中totalItems为0适合只把计数当装饰的游标分页 UI可显著降低查询成本。从接口注释api.ts还可以看到后续的流式接口streamEntities正是基于queryEntities实现的印证了这套分页原语在整个 Catalog 客户端中的基础地位。服务端端点/entities/by-query 的实现在 plugins/catalog-backend/src/service/createRouter.ts 中/entities/by-query端点同时支持两种请求方式POST /entities/by-query从req.body解析查询参数parseEntityQuery适合承载复杂的谓词过滤query语法GET /entities/by-query从 query string 解析limit、offset等参数适合简单场景。两种方式最终都调用entitiesCatalog.queryEntities({ credentials, fields, ...parsed })返回{ items, pageInfo, totalItems }其中pageInfo.nextCursor/pageInfo.prevCursor在响应前会经过encodeCursor编码后交给客户端——客户端在翻页请求中直接回传该 cursor 字符串即可。端点的所有请求还会通过 auditor 记录审计事件entity-fetch/by-query便于追踪查询行为。配合 OpenAPI 定义plugins/catalog-backend/src/schema/openapi.yaml该端点在版本中即具备完整的契约描述可供生成客户端与服务端类型见schema/openapi/generated/下的自动生成文件。实战要点何时用 queryEntities需要大列表分页渲染如 Catalog 页面、实体表格时用queryEntities替代一次性全量拉取配合totalItems: exclude可进一步降低计数开销需要服务端排序/过滤时把orderFields、filter/query传给首次请求之后一律用 cursor 翻页需要谓词组合过滤时如kind 为 component 且 spec.type 为 service 或 website使用query语法const response await catalogClient.queryEntities({ query: { $all: [ { kind: component }, { spec.type: { $in: [service, website] } }, ], }, orderFields: [{ field: metadata.name, order: asc }], }); // 翻页response.pageInfo.nextCursorUI 增强icon 函数化与 EntityPicker 多选搜索结果项图标动态定制backstage/plugin-catalog与backstage/plugin-techdocs同时获得一个 UI 能力允许把 icon 作为函数传入从而根据搜索结果项search item动态定制图标commit3f75b7607c。backstage/plugin-explore同样受益于此变更在 Patch Changes 中同步升级。这意味着搜索结果列表可以根据命中项的类别、状态等元数据渲染不同图标而不是使用单一静态图标。EntityPicker 支持多选 filtersbackstage/plugin-catalog-react允许在多选multiple select场景下复用EntityPicker作为过滤器组件commit0a5b73b292。配合上面的谓词过滤能力开发者可以在 Catalog 页面用多个可多选的实体选择器组合出灵活的筛选面板这是对 Catalog UI 交互体验的一次实用补强。新插件Octopus Deploy 与 StackStormbackstage/plugin-octopus-deploy0.1.0Octopus Deploy 部署插件首次亮相初始版本0.1.0-next.0为 Catalog 实体提供 Octopus Deploy 部署信息视图。它属于典型的依赖plugin-catalog-react的前端插件可通过在实体的catalog-info.yaml中配置对应注解并在应用packages/app中注册插件路由与卡片使用。backstage/plugin-stackstorm0.1.0StackStorm 插件初始版本0.1.0-next.0与 StackStorm API 对接允许用户直接在 Backstage 中查看工作流执行workflow executions、packs 与 actions官方变更说明见 docs/releases/v1.12.0-next.0-changelog.md 中backstage/plugin-stackstorm一节。该插件同样已被纳入example-app的依赖可在示例应用中直接体验。正式版补充catalog-backend 的 puppetdb 模块虽然puppetdb模块不在本 next 版本变更记录中但配套的正式版说明 docs/releases/v1.12.0.md 确认本发布周期内plugin-catalog-backend还新增了catalogModulePuppetDbEntityProvider这一 alpha 导出用于在新后端系统中通过 PuppetDB 提供实体数据。新插件与这一模块共同构成了本次发布插件生态扩充的主题。破坏性变更与迁移指南linguist-backendcreateRouter 必须传入 tokenManagerbackstage/plugin-linguist-backend0.2.0-next.0是本次唯一标注BREAKING的变更createRouter现在要求显式传入tokenManager用于后端服务间认证。如果你的代码调用了createRouter必须补充该参数否则会运行时报错。同时该包修复了LinguistBackendApi中首批实体被跳过的 bugcommit2ea5782162升级后建议验证首次批量处理是否正常。const router await createRouter({ discovery, logger, ... tokenManager, });后端系统导出重命名本次发布对多个插件的新后端系统相关导出进行了重命名以匹配新后端系统的推荐命名规范详见 docs/backend-system/architecture 目录下的命名约定文档。典型示例githubEntityProviderCatalogModule更名为catalogModuleGithubEntityProvider。由于这些导出仍处于 alpha 阶段官方视其为非破坏性变更但如果你已经在使用新后端系统升级时需要同步更新 import 语句。proxy-backendreviveConsumedRequestBodies 选项backstage/plugin-proxy-backend新增reviveConsumedRequestBodies选项当请求体已被某个 express 中间件如express.json()消费后代理默认无法再把请求体转发给上游。开启该选项即可恢复revive已被消费的请求体。默认关闭以保持既有行为需要时在createRouter调用中显式开启const router await createRouter({ config, logger, discovery, reviveConsumedRequestBodies: true, });对应源码位于 plugins/proxy-backend/src/service/router.tsRouterOptions中声明了reviveConsumedRequestBodies?: boolean路由处理时依据该开关决定是否重建请求体同时它也支持通过配置项proxy.reviveConsumedRequestBodiesgetOptionalBoolean从app-config中读取相关测试见 plugins/proxy-backend/src/service/router.test.ts。其余值得关注的 Patch 变更CLI新增 migrate package-exports 命令backstage/cli新增migrate package-exports命令commitb4cd145b57用于同步所有package.json中的exports字段帮助 monorepo 保持模块导出的一致性同时更新了前端插件模板以使用更新的特性commit17271841de并统一了 express 相关依赖版本。认证与后端插件backstage/plugin-auth-backend新增Azure Easy Authentication认证 providercommit529de8c421在 Azure App Service 场景下可直接复用平台级认证backstage/plugin-todo-backend以新插件系统插件的形式重新暴露commit4120513412标志着todo-backend正式接入新的 backend plugin 体系。性能与稳定性backstage/plugin-tech-insights-backend新增 DB 索引降低最新 fact 查询的延迟commitf244b58916backstage/backend-tasks针对 MySQL 与 SQLite 调整查询写法避免日志告警commitf0685193efbackstage/plugin-techdocs在注入 shadow DOM 的文档内容中保留 HTML 标签属性改善可访问性commitf320c299c6backstage/plugin-scaffolder-backend的catalog:fetchaction 在实体为 null 且optional为 false 时改为直接抛错commitc6c78b4acb避免静默失败。贯穿全局/alpha 导出内部重构本次发布有大量包plugin-catalog-backend、backend-app-api、backend-common、core-plugin-api、plugin-events-backend等数十个标记了同一项内部重构Internal refactor of /alpha exportscommit928a12a9b3。这说明团队正在系统性地梳理 alpha 导出面为后续新后端系统稳定化做准备。对普通使用方而言若没有直接 import 这些/alpha路径升级通常无感。升级建议v1.12.0-next.0 属于预发布版本主要面向希望在正式版发布前验证兼容性的用户。升级时建议按以下顺序自查检查破坏性变更若使用backstage/plugin-linguist-backend务必为createRouter传入tokenManager检查 alpha 导入若使用新后端系统且直接 import 了各插件的/alpha导出核对是否受导出重命名如catalogModule*系列影响体验新能力在example-app中验证plugin-octopus-deploy、plugin-stackstorm等新插件的接入效果并将 Catalog 列表类页面迁移到queryEntities/entities/by-query以观察性能收益关注配置项proxy 需要转发已消费请求体时显式设置reviveConsumedRequestBodies代码或proxy.reviveConsumedRequestBodies配置。本发布周期对应的正式版说明、逐包完整变更清单与后续版本记录可分别查阅 docs/releases/v1.12.0.md 与 docs/releases/v1.12.0-changelog.md后端系统命名约定与迁移背景可参阅 docs/backend-system 文档目录。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage v1.12.0-next.0 版本解读：Catalog 游标分页查询、新插件与后端系统演进
Backstage v1.12.0-next.0 版本解读Catalog 游标分页查询、新插件与后端系统演进【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术解读以仓库中的官方发布记录 docs/releases/v1.12.0-next.0-changelog.md 为主体结合仓库内对应源码如 CatalogClient 与 createRouter逐一剖析 v1.12.0-next.0 这个预发布版本的核心变更。读完本文你将掌握如何通过新的queryEntitiesAPI 与/entities/by-query端点实现游标分页与服务端排序、两个全新插件Octopus Deploy 与 StackStorm的接入方式、linguist-backend的破坏性变更迁移方法以及proxy-backend请求体恢复、CLI 新增命令等一批值得关注的能力升级。版本概览一次小而美的预发布v1.12.0-next.0是 Backstage 在正式 v1.12.0对应发布说明见 docs/releases/v1.12.0.md之前的首个预发布next版本采用标准的逐包per-package变更记录格式覆盖从backstage/catalog-client、backstage/plugin-catalog-backend到example-app、example-backend在内的全部工作区包。该版本没有包含安全修复正式版说明中明确 This release does not contain any security fixes。从变更记录看本次发布的核心增量集中在四个方面变更类型涉及包内容Minor新能力backstage/catalog-client在CatalogApi中新增queryEntities方法Minor新能力backstage/plugin-catalog-backend新增/entities/by-query端点支持游标分页与服务端排序MinorUI 增强backstage/plugin-catalog、backstage/plugin-techdocs支持把 icon 作为函数传入按搜索结果项动态定制MinorUI 增强backstage/plugin-catalog-reactEntityPicker支持多选 filtersMinor破坏性backstage/plugin-linguist-backendcreateRouter必须显式传入tokenManagerMinor新插件backstage/plugin-octopus-deploy、backstage/plugin-stackstorm全新前端插件初始版本 0.1.0Patch重要backstage/plugin-proxy-backend新增reviveConsumedRequestBodies选项Patch重要backstage/cli新增migrate package-exports命令下面逐项深入。核心能力从 Catalog 读取分页数据本次发布最重磅的功能是给 Catalog 补齐了基于游标cursor的分页查询能力前后端配套落地客户端侧backstage/catalog-client在CatalogApi接口中新增queryEntities方法服务端侧backstage/plugin-catalog-backend新增/entities/by-query端点支持游标分页与服务端排序。官方发布说明将其定位为用于定向优化前端等场景中的性能热点hot-spots——过去一次性拉取全量实体再在浏览器端过滤排序的做法从此可以替换为按需、分页的服务端查询。客户端 APIqueryEntities 的设计在 packages/catalog-client/src/types/api.ts 中queryEntities的类型体系由三类请求/响应类型组成QueryEntitiesRequest联合类型等于QueryEntitiesInitialRequest | QueryEntitiesCursorRequest即首次请求与翻页请求两种形态QueryEntitiesInitialRequest首次请求携带fields、limit、offset、filter、query、orderFields、fullTextFilter、totalItems等参数。其中filter与query可以单独使用也可以同时使用filter传统的 key-value 过滤语法对应 GET 端点query基于谓词predicate的过滤语法支持$all、$any、$not逻辑操作符与$exists、$in、$hasPrefix、$contains匹配操作符QueryEntitiesCursorRequest翻页请求只携带fields、limit与cursor后续批次完全由服务端返回的游标驱动QueryEntitiesResponse包含items当前批次实体列表、totalItems全量总数与pageInfonextCursor/prevCursor用于前后翻页。值得注意的细节是首次请求中的filter、query、sortField、sortFieldOrder等属性在整条分页链路的后续请求中是**不可变immutable**的翻页请求只能通过 cursor 延续从而保证分页期间过滤与排序条件的一致性。totalItems字段还支持include | exclude两档控制——exclude时跳过全量计数、响应中totalItems为0适合只把计数当装饰的游标分页 UI可显著降低查询成本。从接口注释api.ts还可以看到后续的流式接口streamEntities正是基于queryEntities实现的印证了这套分页原语在整个 Catalog 客户端中的基础地位。服务端端点/entities/by-query 的实现在 plugins/catalog-backend/src/service/createRouter.ts 中/entities/by-query端点同时支持两种请求方式POST /entities/by-query从req.body解析查询参数parseEntityQuery适合承载复杂的谓词过滤query语法GET /entities/by-query从 query string 解析limit、offset等参数适合简单场景。两种方式最终都调用entitiesCatalog.queryEntities({ credentials, fields, ...parsed })返回{ items, pageInfo, totalItems }其中pageInfo.nextCursor/pageInfo.prevCursor在响应前会经过encodeCursor编码后交给客户端——客户端在翻页请求中直接回传该 cursor 字符串即可。端点的所有请求还会通过 auditor 记录审计事件entity-fetch/by-query便于追踪查询行为。配合 OpenAPI 定义plugins/catalog-backend/src/schema/openapi.yaml该端点在版本中即具备完整的契约描述可供生成客户端与服务端类型见schema/openapi/generated/下的自动生成文件。实战要点何时用 queryEntities需要大列表分页渲染如 Catalog 页面、实体表格时用queryEntities替代一次性全量拉取配合totalItems: exclude可进一步降低计数开销需要服务端排序/过滤时把orderFields、filter/query传给首次请求之后一律用 cursor 翻页需要谓词组合过滤时如kind 为 component 且 spec.type 为 service 或 website使用query语法const response await catalogClient.queryEntities({ query: { $all: [ { kind: component }, { spec.type: { $in: [service, website] } }, ], }, orderFields: [{ field: metadata.name, order: asc }], }); // 翻页response.pageInfo.nextCursorUI 增强icon 函数化与 EntityPicker 多选搜索结果项图标动态定制backstage/plugin-catalog与backstage/plugin-techdocs同时获得一个 UI 能力允许把 icon 作为函数传入从而根据搜索结果项search item动态定制图标commit3f75b7607c。backstage/plugin-explore同样受益于此变更在 Patch Changes 中同步升级。这意味着搜索结果列表可以根据命中项的类别、状态等元数据渲染不同图标而不是使用单一静态图标。EntityPicker 支持多选 filtersbackstage/plugin-catalog-react允许在多选multiple select场景下复用EntityPicker作为过滤器组件commit0a5b73b292。配合上面的谓词过滤能力开发者可以在 Catalog 页面用多个可多选的实体选择器组合出灵活的筛选面板这是对 Catalog UI 交互体验的一次实用补强。新插件Octopus Deploy 与 StackStormbackstage/plugin-octopus-deploy0.1.0Octopus Deploy 部署插件首次亮相初始版本0.1.0-next.0为 Catalog 实体提供 Octopus Deploy 部署信息视图。它属于典型的依赖plugin-catalog-react的前端插件可通过在实体的catalog-info.yaml中配置对应注解并在应用packages/app中注册插件路由与卡片使用。backstage/plugin-stackstorm0.1.0StackStorm 插件初始版本0.1.0-next.0与 StackStorm API 对接允许用户直接在 Backstage 中查看工作流执行workflow executions、packs 与 actions官方变更说明见 docs/releases/v1.12.0-next.0-changelog.md 中backstage/plugin-stackstorm一节。该插件同样已被纳入example-app的依赖可在示例应用中直接体验。正式版补充catalog-backend 的 puppetdb 模块虽然puppetdb模块不在本 next 版本变更记录中但配套的正式版说明 docs/releases/v1.12.0.md 确认本发布周期内plugin-catalog-backend还新增了catalogModulePuppetDbEntityProvider这一 alpha 导出用于在新后端系统中通过 PuppetDB 提供实体数据。新插件与这一模块共同构成了本次发布插件生态扩充的主题。破坏性变更与迁移指南linguist-backendcreateRouter 必须传入 tokenManagerbackstage/plugin-linguist-backend0.2.0-next.0是本次唯一标注BREAKING的变更createRouter现在要求显式传入tokenManager用于后端服务间认证。如果你的代码调用了createRouter必须补充该参数否则会运行时报错。同时该包修复了LinguistBackendApi中首批实体被跳过的 bugcommit2ea5782162升级后建议验证首次批量处理是否正常。const router await createRouter({ discovery, logger, ... tokenManager, });后端系统导出重命名本次发布对多个插件的新后端系统相关导出进行了重命名以匹配新后端系统的推荐命名规范详见 docs/backend-system/architecture 目录下的命名约定文档。典型示例githubEntityProviderCatalogModule更名为catalogModuleGithubEntityProvider。由于这些导出仍处于 alpha 阶段官方视其为非破坏性变更但如果你已经在使用新后端系统升级时需要同步更新 import 语句。proxy-backendreviveConsumedRequestBodies 选项backstage/plugin-proxy-backend新增reviveConsumedRequestBodies选项当请求体已被某个 express 中间件如express.json()消费后代理默认无法再把请求体转发给上游。开启该选项即可恢复revive已被消费的请求体。默认关闭以保持既有行为需要时在createRouter调用中显式开启const router await createRouter({ config, logger, discovery, reviveConsumedRequestBodies: true, });对应源码位于 plugins/proxy-backend/src/service/router.tsRouterOptions中声明了reviveConsumedRequestBodies?: boolean路由处理时依据该开关决定是否重建请求体同时它也支持通过配置项proxy.reviveConsumedRequestBodiesgetOptionalBoolean从app-config中读取相关测试见 plugins/proxy-backend/src/service/router.test.ts。其余值得关注的 Patch 变更CLI新增 migrate package-exports 命令backstage/cli新增migrate package-exports命令commitb4cd145b57用于同步所有package.json中的exports字段帮助 monorepo 保持模块导出的一致性同时更新了前端插件模板以使用更新的特性commit17271841de并统一了 express 相关依赖版本。认证与后端插件backstage/plugin-auth-backend新增Azure Easy Authentication认证 providercommit529de8c421在 Azure App Service 场景下可直接复用平台级认证backstage/plugin-todo-backend以新插件系统插件的形式重新暴露commit4120513412标志着todo-backend正式接入新的 backend plugin 体系。性能与稳定性backstage/plugin-tech-insights-backend新增 DB 索引降低最新 fact 查询的延迟commitf244b58916backstage/backend-tasks针对 MySQL 与 SQLite 调整查询写法避免日志告警commitf0685193efbackstage/plugin-techdocs在注入 shadow DOM 的文档内容中保留 HTML 标签属性改善可访问性commitf320c299c6backstage/plugin-scaffolder-backend的catalog:fetchaction 在实体为 null 且optional为 false 时改为直接抛错commitc6c78b4acb避免静默失败。贯穿全局/alpha 导出内部重构本次发布有大量包plugin-catalog-backend、backend-app-api、backend-common、core-plugin-api、plugin-events-backend等数十个标记了同一项内部重构Internal refactor of /alpha exportscommit928a12a9b3。这说明团队正在系统性地梳理 alpha 导出面为后续新后端系统稳定化做准备。对普通使用方而言若没有直接 import 这些/alpha路径升级通常无感。升级建议v1.12.0-next.0 属于预发布版本主要面向希望在正式版发布前验证兼容性的用户。升级时建议按以下顺序自查检查破坏性变更若使用backstage/plugin-linguist-backend务必为createRouter传入tokenManager检查 alpha 导入若使用新后端系统且直接 import 了各插件的/alpha导出核对是否受导出重命名如catalogModule*系列影响体验新能力在example-app中验证plugin-octopus-deploy、plugin-stackstorm等新插件的接入效果并将 Catalog 列表类页面迁移到queryEntities/entities/by-query以观察性能收益关注配置项proxy 需要转发已消费请求体时显式设置reviveConsumedRequestBodies代码或proxy.reviveConsumedRequestBodies配置。本发布周期对应的正式版说明、逐包完整变更清单与后续版本记录可分别查阅 docs/releases/v1.12.0.md 与 docs/releases/v1.12.0-changelog.md后端系统命名约定与迁移背景可参阅 docs/backend-system 文档目录。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考