Backstage v1.40.0-next.0 版本解析分布式 Actions、TechDocs 深度链接与插件元数据加载器【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文基于 Backstage 开源仓库的 v1.40.0-next.0 变更日志聚焦该预发布版本中最具技术分量的三项新能力面向后端插件体系的分布式 Actions 注册与调用服务、借助backstage.io/techdocs-entity-path注解实现的跨实体 TechDocs 深度链接以及新前端系统中面向插件元数据的info.packageJson/info.manifest加载器。阅读完成后你将掌握这些特性的 API 形态、配置方式、默认实现与测试手段并了解本版本其余重要的破坏性与修复性变更为实际升级评估和插件开发做好准备。版本概览一次以能力扩展为主的 next.0 发布v1.40.0-next.0是 Backstage 1.40 系列的首个预发布版本共涉及 60 余个backstage/*包以及techdocs/cli、example-app、example-backend、e2e-test等示例/工具工程。其中携带Minor Changes新特性的包包括包新版本核心变更backstage/backend-plugin-api1.4.0-next.0新增coreServices.actionsRegistry与coreServices.actions分布式 Actions 服务backstage/backend-test-utils1.6.0-next.0为ActionsService与ActionsRegistryService提供 Mock 实现backstage/canon0.5.0-next.0Grid 组件根节点改名为Grid.Root /修复布局组件 spacing 属性backstage/create-app0.7.0-next.0向生成的工程内置.gitignore追加.cache目录backstage/repo-tools0.14.0-next.0package-docs命令支持按包缓存输出backstage/plugin-catalog1.31.0-next.0引入backstage.io/techdocs-entity-path注解backstage/plugin-techdocs1.13.0-next.0同上支持跨实体 TechDocs 深度链接backstage/plugin-techdocs-react1.3.0-next.0同上React 侧支持其余包均为 Patch Changes以依赖更新为主同时夹杂若干行为修复详见后文值得关注的 Patch Changes一节。新特性一分布式 Actions ——coreServices.actionsRegistry与coreServices.actions本次发布最核心的后端变更来自backstage/backend-plugin-api1.4.0-next.0变更集664c07a新增coreServices.actionsRegistry和coreServices.actions用于允许插件注册分布式 actions并具备调用这些 actions 的能力。这意味着 Actions可执行的操作单元不再局限于 Scaffolder 内部任何后端插件都可以注册自己的 action其他插件或服务则可以通过统一的入口发现并调用它们。服务引用与依赖注入两个服务的引用定义在 packages/backend-plugin-api/src/alpha/refs.tsactionsServiceRefid 为alpha.core.actions类型为ActionsService用途是调用分布式 actionsactionsRegistryServiceRefid 为alpha.core.actionsRegistry类型为ActionsRegistryService用途是注册并管理分布式 actions。二者均以coreServices形式暴露插件后端可在startup或插件实例的依赖声明中直接引用例如import { coreServices, createBackendPlugin } from backstage/backend-plugin-api; export const examplePlugin createBackendPlugin({ pluginId: example, register(env) { env.registerInit({ deps: { actionsRegistry: coreServices.actionsRegistry, actions: coreServices.actions, }, async init({ actionsRegistry, actions }) { // 注册 action actionsRegistry.register({ name: example.sayHello, title: Say Hello, description: A distributed action example, schema: { input: z z.object({ name: z.string() }), output: z z.object({ message: z.string() }), }, async action({ input }) { return { output: { message: Hello, ${input.name} } }; }, }); // 调用其他插件注册的 action const { output } await actions.invoke({ id: some-plugin.someAction, input: { foo: bar }, credentials: await auth.getPluginRequestToken({ onBehalfOf: await auth.getOwnServiceCredentials() }), }); }, }); }, });注册侧 APIActionsRegistryService注册服务的接口定义在 packages/backend-plugin-api/src/alpha/ActionsRegistryService.ts其register()接受一个ActionsRegistryActionOptions关键字段如下字段类型说明namestringaction 唯一名称如example.deploytitlestring人类可读标题descriptionstring详细说明schema.input/schema.output(zod) AnyZodObject输入/输出 JSON Schema基于 zod 定义schema.secrets(zod) AnyZodObject可选声明 action 需要的敏感参数examplesArray{ title, description?, input, output? }示例输入输出便于 UI 呈现与测试visibilityPermissionBasicPermission可选控制 action 的可见性attributes.destructiveboolean是否可能执行破坏性更新readOnly为true时默认false否则默认trueattributes.idempotentboolean是否幂等attributes.readOnlyboolean是否只读环境默认falseaction(context) Promise...执行函数接收{ input, secrets, logger, credentials }上下文调用侧 APIActionsService调用服务接口定义在 packages/backend-plugin-api/src/alpha/ActionsService.ts提供两个方法list({ credentials })返回{ actions: ActionsServiceAction[] }其中每个 action 描述包含id、pluginId来源插件、name、title、description、schema已转换为 JSON Schema 7 格式的 input/output/secrets、examples与attributesreadOnly/destructive/idempotentinvoke({ id, input?, secrets?, credentials })按 action 的全局id执行返回{ output: JsonValue }。id与name的区别在于id是注册后生成的全局限定标识绑定来源pluginId而name是插件内定义的短名称——这正体现了分布式注册模型跨插件调用通过全局id路由。默认实现backend-defaults与backend-app-api默认实现位于backstage/backend-defaults0.10.1-next.0。在 packages/backend-defaults/src/alpha/entrypoints/actionsRegistry/actionsRegistryServiceFactory.ts 中actionsRegistryServiceFactory通过createServiceFactory构建DefaultActionsRegistryService依赖包括pluginMetadata、httpRouter、httpAuth、logger、auth、rootConfig、permissions与permissionsRegistry并将注册路由挂载到httpRouter上——说明 Actions 注册表对外也暴露了 HTTP 端点。其对应的单元测试见 actionsRegistryServiceFactory.test.ts 与 actionsServiceFactory.test.ts。测试支撑backend-test-utils的 Mockbackstage/backend-test-utils1.6.0-next.0同步提供了两个服务的 Mock 实现ActionsRegistryServiceMock.ts 暴露actionsRegistryServiceMock其mock形态将register包装为jest.fn()方便断言注册调用MockActionsRegistry.ts 提供可用的内存版注册表配套测试见 MockActionsRegistry.test.ts。在测试后端时可以直接用mockServices/actionsRegistryServiceMock.factory()替换默认实现从而隔离对真实注册表与 HTTP 路由的依赖。新特性二跨实体 TechDocs 深度链接 ——backstage.io/techdocs-entity-path变更集ec7b35d同时落在plugin-catalog、plugin-techdocs、plugin-techdocs-react与新的plugin-techdocs-common上引入backstage.io/techdocs-entity-path注解与backstage.io/techdocs-entity配合可深度链接到另一个实体的 TechDocs。此前backstage.io/techdocs-entity已允许一个实体例如一个 System 或 API引用另一个实体的 TechDocs 站点techdocs-entity-path进一步把链接精确到目标站点内的具体文档页面例如某个子目录下的 Markdown 文档从而在 Catalog 卡片或 About 区域直接跳转到最相关的文档位置。注解常量定义在 plugins/techdocs-common/src/constants.tsexport const TECHDOCS_ANNOTATION backstage.io/techdocs-ref; export const TECHDOCS_EXTERNAL_ANNOTATION backstage.io/techdocs-entity; export const TECHDOCS_EXTERNAL_PATH_ANNOTATION backstage.io/techdocs-entity-path;在实体清单catalog-info.yaml中的典型用法如下apiVersion: backstage.io/v1alpha1 kind: System metadata: name: payment-system annotations: backstage.io/techdocs-entity: system:default/payment-core backstage.io/techdocs-entity-path: docs/payment/architecture.md前端在渲染 TechDocs 阅读页时读取该注解并据此解析重定向目标相关实现位于 plugins/techdocs/src/reader/components/TechDocsReaderPageContent/TechDocsReaderPageContent.tsx其行为由 useExternalRedirect.test.tsx 等测试覆盖。仓库自带的示例实体 plugins/techdocs-backend/examples/documented-component/catalog-info.yaml 也演示了外部 TechDocs 注解的配置形态。关于注解语义的完整说明可参考 软件目录的 well-known annotations 与 TechDocs 使用指南。新特性三新前端系统的插件元数据加载器 ——info.packageJson与info.manifestbackstage/frontend-plugin-api0.10.3-next.0通过9e3868f为createFrontendPlugin新增了可选的info选项用于为插件附加不同来源的元数据信息并配套两个加载器info.packageJson指向插件自身的package.json。变更日志明确建议凡是定义在独立包中、尤其是发布到包仓库的插件都应使用该加载器。典型用法export default createFrontendPlugin({ pluginId: ..., info: { packageJson: () import(../package.json), }, });info.manifest指向一个不透明的插件 manifest。仅限单一组织内部使用的插件使用发布到开放包仓库的插件不应使用该加载器。它用于携带与插件关联的额外内部元数据解析与使用方式完全由 App 决定使用backstage/frontend-defaults中createApp创建的默认 App其 manifest 解析器能够解析默认的catalog-info.yaml格式及内置字段如spec.owner。典型用法export default createFrontendPlugin({ pluginId: ..., info: { manifest: () import(../catalog-info.yaml), }, });info选项在类型层面的定义位于 packages/frontend-plugin-api/src/wiring/createFrontendPlugin.tsFrontendPluginInfoOptions。消费侧plugin.info()与解析覆盖backstage/frontend-app-api0.11.3-next.0c38c9e8为专门化 Appspecialized apps实现了plugin.info()方法支持默认从package.json与catalog-info.yaml解析元数据默认解析逻辑可通过传给createSpecializedApp的pluginInfoResolver选项覆盖也可以通过在静态配置中新增app.pluginOverrides键对特定插件做覆盖。backstage/frontend-defaults0.2.3-next.0fa5650c则将该pluginInfoResolver选项透传给了createApp。本版本中包括plugin-catalog、plugin-techdocs、plugin-api-docs、plugin-home、plugin-kubernetes、plugin-notifications、plugin-org、plugin-scaffolder、plugin-search、plugin-signals、plugin-user-settings、plugin-app、plugin-devtools、plugin-catalog-graph、plugin-catalog-import、plugin-catalog-unprocessed-entities、plugin-app-visualizer等一批前端插件均通过18c64e9接入了info.packageJson。其余 Minor Changes 速览canon 0.5.0Grid 根组件命名对齐backstage/canon0.5.0-next.024b45ef修复了布局组件的 spacing 属性并统一 Grid 组件命名——Grid 根组件现在应使用Grid.Root /而非Grid /即根组件作为命名空间成员的约定同时移除了 Container 组件中遗留的console.log269316d。升级后若代码中使用旧写法会出现编译或运行告警需批量替换。create-app 0.7.0内置 .gitignore 追加 .cachebackstage/create-app0.7.0-next.030474c4向脚手架生成的工程gitignore中加入了.cache目录避免本地缓存目录被误提交。repo-tools 0.14.0package-docs 缓存backstage/repo-tools0.14.0-next.0bf9a173为package-docs命令增加了按包缓存输出的能力可显著减少重复文档生成的开销同时修复了两个问题schema openapi generate在未加--watch时错误信息不打印到控制台2d20024以及package-docs缺失高亮语言支持e643ee4。值得关注的 Patch Changes除依赖更新外本版本还有若干功能性修复Catalog 后端plugin-catalog-backend2.0.1-next.04654a78将refresh_state_references.id列更新为 big int应对大表自增主键溢出问题GitLab Scaffolder 模块plugin-scaffolder-backend-module-gitlab0.9.2-next.03d6493apublish:gitlab:merge-request动作新增对合并请求标签merge request labels的支持Bitbucket Cloud / Server 模块3d6493a关联的9c8ff0c更新拉取请求创建过滤器使.gitignore文件也能被纳入新创建的 PRScaffolder 前端plugin-scaffolder1.31.1-next.0d781b33为复合属性 schemacomposite property schemas渲染细节信息改善模板表单的可读性新前端系统 Hookfrontend-plugin-api0.10.3-next.06f48f71新增useAppNodeHook可在ExtensionBoundary内获取最近的AppNode引用便于扩展组件感知自身在应用树中的位置测试见 AppNodeProvider.test.tsx依赖升级整个next.0版本的 Patch Changes 大量围绕backend-plugin-api1.4.0-next.0、frontend-plugin-api0.10.3-next.0、plugin-auth-node0.6.4-next.0、plugin-permission-node0.10.1-next.0、plugin-catalog-node1.17.1-next.0等基础包展开建议按依赖拓扑自底向上升级。升级建议与验证方式本版本为-next.0预发布版本适合在开发/预发环境先行验证可使用 Backstage 官方的 Upgrade Helper 工具?to1.40.0-next.0自动生成升级说明若升级后需要立即使用分布式 Actions请确认后端代码从backstage/backend-plugin-api/alpha导入actionsServiceRef/actionsRegistryServiceRef对应的coreServices字段当前 API 标注为alpha后续版本可能调整前端插件若打算发布到开放包仓库应优先采用info.packageJson而非info.manifestmanifest加载器仅限组织内部插件使用 Canon 的工程请检查所有Grid根组件写法替换为Grid.Root /需要为注册/调用 Actions 的插件编写测试时可直接使用backstage/backend-test-utils提供的actionsRegistryServiceMock与MockActionsRegistry。小结v1.40.0-next.0的发布主线清晰后端以分布式 ActionsactionsRegistryactions为 Scaffolder 之外的新动作生态打下服务化基础前端以info.packageJson/info.manifest元数据加载器补齐新前端系统的插件自描述能力文档与导航层面则以techdocs-entity-path打通了跨实体的文档深链。三者分别对应能力注册与调用、插件元数据、内容导航三条链路是 1.40 正式版发布前值得重点关注的演进方向。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考