Backstage v1.53.0-next.2 版本解读代理与 OpenAPI 工具链的破坏性变更迁移指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文聚焦 Backstage 发布说明 docs/releases/v1.53.0-next.2-changelog.md 中的核心变更围绕两大主题展开一是企业代理支持全面切换到 Node.js 内建方案移除global-agent/undici依赖二是 OpenAPI 工具链从 Optic 迁移到oasdiff含wrapServer测试方案。同时覆盖 Redis 缓存连接配置扩展、CIMD token 撤销、Auth0prompt参数、scaffolder 数据库计数修复等值得关注的补丁。读完本文你将掌握该版本的升级要点、迁移步骤及底层实现原理。一、版本概览与升级背景v1.53.0-next.2 是 Backstage v1.53.0 的第二个预发布next版本属于发布周期中的迭代快照包含多个包的 Minor功能性/破坏性与 Patch修复变更。涉及的核心包包括backstage/backend-openapi-utils0.7.0-next.1backstage/cli-common0.3.0-next.0backstage/cli-module-migrate0.2.0-next.0backstage/create-app0.9.0-next.2backstage/repo-tools0.18.0-next.1backstage/backend-defaults0.17.5-next.2backstage/backend-plugin-api1.9.3-next.1backstage/plugin-auth-backend0.29.2-next.1backstage/plugin-scaffolder-backend4.0.2-next.1需要注意的是next版本通常用于正式发布前的验证与集成测试生产环境升级建议等待正式版本stable发布后再执行。升级时可通过官方 Upgrade Helper 工具选择目标版本进行依赖比对。二、破坏性变更一代理支持迁移到 Node.js 内建方案变更内容本次发布中最具全局影响的破坏性变更由提交39deda4引入涉及backstage/cli-common、backstage/cli-module-migrate、backstage/create-app三个包backstage/cli-common0.3.0-next.0移除了已被弃用的bootstrapEnvProxyAgents导出同时删除了global-agent与undici两个依赖。backstage/cli-module-migrate0.2.0-next.0versions:bump命令不再启动旧的代理 agent。backstage/create-app0.9.0-next.2新创建的应用不再引导bootstrap旧版代理 agent。迁移方式替代方案是使用 Node.js 内建代理支持。在启动 Backstage 时设置环境变量export NODE_USE_ENV_PROXY1 export HTTP_PROXYhttp://proxy.example.com:8080 export HTTPS_PROXYhttp://proxy.example.com:8080 export NO_PROXYlocalhost,127.0.0.1,.internal.example.com关键点说明NODE_USE_ENV_PROXY1是启用 Node.js 从环境变量读取代理配置的开关必须显式开启HTTP_PROXY/HTTPS_PROXY分别指定 HTTP 与 HTTPS 流量的代理地址NO_PROXY用于列出不走代理的主机或域如本地回环地址、内网域名这一机制仅影响通过 Node.js 内建fetch发起的网络请求global-agent时代对第三方 HTTP 客户端库的全局拦截行为不再存在因此依赖非内建请求库的代码需要单独配置代理。底层影响从源码结构看cli-common的变更会向上游传播cli、cli-node、config-loader、codemods、devtools-backend、techdocs-cli、e2e-test、yarn-plugin-backstage等多个包均通过 Updated dependencies 继承此变更见 packages/cli-common/CHANGELOG.md。这意味着升级后整个 CLI 工具链与后端运行时都统一使用 Node.js 的原生代理能力减少了第三方 agent 的运行时开销与版本兼容风险。三、破坏性变更二OpenAPI 工具链从 Optic 迁移到 oasdiff变更内容提交84171b3重构了backstage/repo-tools0.18.0-next.1的 OpenAPI 相关命令核心变化是将底层的useoptic/optic与useoptic/openapi-utilities替换为oasdiff用于 OpenAPI 破坏性变更检测package schema openapi diff命令底层改为调用oasdiff原有--since、--json、--ignore参数继续可用但 JSON 与文本输出格式变为oasdiff的原生格式repo schema openapi diff命令现在会自动检测所有src/schema/openapi.yaml发生变更的包并直接对这些包运行oasdiff包不再需要在package.json中配置diff脚本移除了package schema openapi init与repo schema openapi test两个依赖 Opticcapture工作流的命令。迁移步骤对于使用旧命令的开发者需要执行# 1. 从根 package.json 中移除 useoptic/optic 依赖 # 2. 在系统上安装 oasdiff CLI参考官方 oasdiff 仓库的安装说明 # 3. 使用新命令进行破坏性变更检测 backstage-repo-tools package schema openapi diff backstage-repo-tools repo schema openapi diff底层实现原理package schema openapi diff的实现位于 packages/repo-tools/src/commands/package/schema/openapi/diff.ts先通过ensureOasdiffInstalled()检查oasdiff是否已安装见 packages/repo-tools/src/commands/util.ts未安装时会报错并给出安装指引默认以git merge-base --fork-point计算出基准提交DEFAULT_BASE_REF若不传--since则自动定位到分支分叉点以${baseRef}:${relativeSpecPath}形式指定基准 spec当前工作区 spec 作为新版本调用oasdiff的changelog--json时或breaking子命令非--json模式默认追加--fail-on ERR检测到破坏性变更时进程退出码为 1。repo schema openapi diff的实现位于 packages/repo-tools/src/commands/repo/schema/openapi/diff.ts通过PackageGraph.listTargetPackages()枚举所有包若指定--since会执行git diff --name-only找出变更文件中匹配src/schema/openapi.yaml的包并过滤对每个存在 spec 的包运行oasdiff changelog并使用仓库内置的 templates/oasdiff-changelog.tmpl 生成 Markdown 格式的变更报告适合直接作为 PR 评审输出。运行时验证的替代方案移除 Opticcapture工作流后运行时对 API 与 OpenAPI spec 的一致性校验仍然可用入口是wrapServer来自backstage/backend-openapi-utils/testUtils。其实现见 packages/backend-openapi-utils/src/testUtils.ts它会启动一个基于mockttp的本地代理将所有请求/响应转发给 Express 应用同时通过OpenApiProxyValidator校验每个请求/响应是否与openapi.json规范相符并在afterAll钩子中统一清理代理资源。wrapInOpenApiTestServer的移除backstage/backend-openapi-utils0.7.0-next.1的 Minor 变更移除了wrapInOpenApiTestServer。该函数此前通过OPTIC_PROXY环境变量把测试流量导向 Optic 的capture代理随着 Optic 依赖被移除已失去意义。迁移方式非常直接在测试中将wrapInOpenApiTestServer替换为wrapServer两者 API 形态一致接收 Express 应用返回供 supertest 使用的 HTTP Server因此通常只需修改导入与调用名即可完成迁移。四、功能增强Redis 缓存连接配置支持对象形式变更内容backstage/backend-defaults0.17.5-next.2提交a624fa3扩展了 Redis 缓存存储的connection配置项现在既可以传入字符串 URL也可以传入携带额外连接选项的对象这些选项会直接透传给底层 Redis 客户端。例如可以在不新增专用配置字段的情况下配置pingInterval。配置示例backend: cache: store: redis connection: url: redis://user:passcache.example.com:6379 pingInterval: 60000 # 底层客户端连接选项直接透传 defaultTtl: 3600000约束条件对象形式仅在backend.cache.store为redis时受支持其他存储如memory、valkey仍要求使用纯字符串连接对于 Redis 集群cluster场景connection对象的属性会合并进集群默认配置cluster defaults中该变更修复了 issue #31813 与 #31742 相关的连接配置问题。底层实现与配置定义配置 schema 定义见 packages/backend-defaults/config.d.tsconnection字段的类型为string | { url: string; [key: string]: unknown }其中url为必填的 Redis 连接 URL其余键值对作为连接设置透传redis.client与redis.cluster子配置则分别控制keyv/redis客户端选项如namespace、keyPrefixSeparator、clearBatchSize、useUnlink、noNamespaceAffectsAll与集群节点/默认配置。单元测试见 packages/backend-defaults/src/entrypoints/cache/CacheManager.test.ts其中覆盖了字符串连接、对象连接含pingInterval透传以及非 redis 存储拒绝对象连接等场景。五、值得关注的功能与修复1. CIMD token 撤销支持backstage/plugin-auth-backend提交2aeb246为使用 client ID metadata documentsCIMD的客户端新增了 token 撤销能力只要启用了动态客户端注册或 CIMD/v1/revoke端点即可用该端点会通过 OpenID provider 配置中的revocation_endpoint对外通告。这使 Backstage 的 OIDC 身份提供方能力更完整客户端可以按标准流程主动撤销 token。2. Auth0 provider 新增prompt参数backstage/plugin-auth-backend-module-auth0-provider提交5446838为 Auth0 授权请求增加了可选的prompt设置设置为auto时由 Auth0 自行判断用户是否需要被提示如会话已存在则免登录现有配置默认继续使用consent行为因此升级后行为不变。配置方式是在 provider 配置中补充prompt: auto或保留默认。3. Catalog 类型过滤器回归修复backstage/plugin-catalog-react提交8a500d5修复了一个回归当EntityTypePicker的initialFilter与EntityKindPicker同时在EntityListProvider内使用时类型过滤器此前会在所选 kind 的类型加载完成后被清空现在该过滤器能够被正确保留。4. Scaffolder 任务计数在 PostgreSQL 下返回字符串的修复backstage/plugin-scaffolder-backend提交55902bb修复了DatabaseTaskStore.list在 PostgreSQL 下返回totalTasks为字符串的问题knex 在 PostgreSQL 上返回的COUNT(*)聚合是字符串bigint 列而 better-sqlite3 返回数字现在使用Number(...)强制转换并以Number.isSafeInteger(...)做安全校验这修复了list-scaffolder-tasksaction 在生产环境报Invalid output ... totalTasks: Expected number, received string的校验失败。5. Yeoman 模块兼容 ESMbackstage/plugin-scaffolder-backend-module-yeoman提交5e92512修复了与 yeoman-environment v4纯 ESM的兼容性将原先会抛出ERR_REQUIRE_ESM的require()调用替换为动态import()并更新注册逻辑以匹配 v4 API。6. UI 组件内部迁移backstage/core-components提交7ceeaad将CopyTextButton从 Material-UI 迁移到 Backstage UIBUI用ButtonIcon与TooltipTrigger/Tooltip替换了 MUI 的IconButton与Tooltip。这是一次纯内部重构组件对外 API 保持不变不影响使用方代码。7. Connections 服务默认实现backstage/connections提交ec96761为 connections 服务提供了默认实现使后端模块可以直接依赖该服务而无需应用显式安装 connections 服务工厂降低了接入门槛。六、升级建议与注意事项重点处理破坏性变更升级前先处理两类 BREAKING 变更——代理配置切换到NODE_USE_ENV_PROXY1环境变量方案OpenAPI 工具链迁移到oasdiff移除useoptic/optic、安装oasdiffCLI、用wrapServer替换wrapInOpenApiTestServer。检查自定义 OpenAPI 脚本若 CI 中使用了package schema openapi init或repo schema openapi test需改走oasdiff或wrapServer路径diff命令的输出格式变化需要同步调整结果解析逻辑。验证缓存配置使用 Redis 缓存的部署可检查connection是否可受益于对象形式如pingInterval注意对象形式仅适用于 redis 存储。关注依赖传播cli-common、backend-plugin-api、config-loader、cli-node等基础包的更新会通过依赖关系传播到大量插件包本次 changelog 中绝大多数 Updated dependencies 均指向这几个包升级时建议一次性同步所有next版本避免版本错配。预发布版本定位本 changelog 针对next预发布版本正式迁移请以对应的 stable 版本发布说明为准。相关代码可进一步查阅testUtils.ts、Proxy 实现、package diff 命令、repo diff 命令、Redis 缓存配置定义、缓存管理器测试。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage v1.53.0-next.2 版本解读：代理与 OpenAPI 工具链的破坏性变更迁移指南
Backstage v1.53.0-next.2 版本解读代理与 OpenAPI 工具链的破坏性变更迁移指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文聚焦 Backstage 发布说明 docs/releases/v1.53.0-next.2-changelog.md 中的核心变更围绕两大主题展开一是企业代理支持全面切换到 Node.js 内建方案移除global-agent/undici依赖二是 OpenAPI 工具链从 Optic 迁移到oasdiff含wrapServer测试方案。同时覆盖 Redis 缓存连接配置扩展、CIMD token 撤销、Auth0prompt参数、scaffolder 数据库计数修复等值得关注的补丁。读完本文你将掌握该版本的升级要点、迁移步骤及底层实现原理。一、版本概览与升级背景v1.53.0-next.2 是 Backstage v1.53.0 的第二个预发布next版本属于发布周期中的迭代快照包含多个包的 Minor功能性/破坏性与 Patch修复变更。涉及的核心包包括backstage/backend-openapi-utils0.7.0-next.1backstage/cli-common0.3.0-next.0backstage/cli-module-migrate0.2.0-next.0backstage/create-app0.9.0-next.2backstage/repo-tools0.18.0-next.1backstage/backend-defaults0.17.5-next.2backstage/backend-plugin-api1.9.3-next.1backstage/plugin-auth-backend0.29.2-next.1backstage/plugin-scaffolder-backend4.0.2-next.1需要注意的是next版本通常用于正式发布前的验证与集成测试生产环境升级建议等待正式版本stable发布后再执行。升级时可通过官方 Upgrade Helper 工具选择目标版本进行依赖比对。二、破坏性变更一代理支持迁移到 Node.js 内建方案变更内容本次发布中最具全局影响的破坏性变更由提交39deda4引入涉及backstage/cli-common、backstage/cli-module-migrate、backstage/create-app三个包backstage/cli-common0.3.0-next.0移除了已被弃用的bootstrapEnvProxyAgents导出同时删除了global-agent与undici两个依赖。backstage/cli-module-migrate0.2.0-next.0versions:bump命令不再启动旧的代理 agent。backstage/create-app0.9.0-next.2新创建的应用不再引导bootstrap旧版代理 agent。迁移方式替代方案是使用 Node.js 内建代理支持。在启动 Backstage 时设置环境变量export NODE_USE_ENV_PROXY1 export HTTP_PROXYhttp://proxy.example.com:8080 export HTTPS_PROXYhttp://proxy.example.com:8080 export NO_PROXYlocalhost,127.0.0.1,.internal.example.com关键点说明NODE_USE_ENV_PROXY1是启用 Node.js 从环境变量读取代理配置的开关必须显式开启HTTP_PROXY/HTTPS_PROXY分别指定 HTTP 与 HTTPS 流量的代理地址NO_PROXY用于列出不走代理的主机或域如本地回环地址、内网域名这一机制仅影响通过 Node.js 内建fetch发起的网络请求global-agent时代对第三方 HTTP 客户端库的全局拦截行为不再存在因此依赖非内建请求库的代码需要单独配置代理。底层影响从源码结构看cli-common的变更会向上游传播cli、cli-node、config-loader、codemods、devtools-backend、techdocs-cli、e2e-test、yarn-plugin-backstage等多个包均通过 Updated dependencies 继承此变更见 packages/cli-common/CHANGELOG.md。这意味着升级后整个 CLI 工具链与后端运行时都统一使用 Node.js 的原生代理能力减少了第三方 agent 的运行时开销与版本兼容风险。三、破坏性变更二OpenAPI 工具链从 Optic 迁移到 oasdiff变更内容提交84171b3重构了backstage/repo-tools0.18.0-next.1的 OpenAPI 相关命令核心变化是将底层的useoptic/optic与useoptic/openapi-utilities替换为oasdiff用于 OpenAPI 破坏性变更检测package schema openapi diff命令底层改为调用oasdiff原有--since、--json、--ignore参数继续可用但 JSON 与文本输出格式变为oasdiff的原生格式repo schema openapi diff命令现在会自动检测所有src/schema/openapi.yaml发生变更的包并直接对这些包运行oasdiff包不再需要在package.json中配置diff脚本移除了package schema openapi init与repo schema openapi test两个依赖 Opticcapture工作流的命令。迁移步骤对于使用旧命令的开发者需要执行# 1. 从根 package.json 中移除 useoptic/optic 依赖 # 2. 在系统上安装 oasdiff CLI参考官方 oasdiff 仓库的安装说明 # 3. 使用新命令进行破坏性变更检测 backstage-repo-tools package schema openapi diff backstage-repo-tools repo schema openapi diff底层实现原理package schema openapi diff的实现位于 packages/repo-tools/src/commands/package/schema/openapi/diff.ts先通过ensureOasdiffInstalled()检查oasdiff是否已安装见 packages/repo-tools/src/commands/util.ts未安装时会报错并给出安装指引默认以git merge-base --fork-point计算出基准提交DEFAULT_BASE_REF若不传--since则自动定位到分支分叉点以${baseRef}:${relativeSpecPath}形式指定基准 spec当前工作区 spec 作为新版本调用oasdiff的changelog--json时或breaking子命令非--json模式默认追加--fail-on ERR检测到破坏性变更时进程退出码为 1。repo schema openapi diff的实现位于 packages/repo-tools/src/commands/repo/schema/openapi/diff.ts通过PackageGraph.listTargetPackages()枚举所有包若指定--since会执行git diff --name-only找出变更文件中匹配src/schema/openapi.yaml的包并过滤对每个存在 spec 的包运行oasdiff changelog并使用仓库内置的 templates/oasdiff-changelog.tmpl 生成 Markdown 格式的变更报告适合直接作为 PR 评审输出。运行时验证的替代方案移除 Opticcapture工作流后运行时对 API 与 OpenAPI spec 的一致性校验仍然可用入口是wrapServer来自backstage/backend-openapi-utils/testUtils。其实现见 packages/backend-openapi-utils/src/testUtils.ts它会启动一个基于mockttp的本地代理将所有请求/响应转发给 Express 应用同时通过OpenApiProxyValidator校验每个请求/响应是否与openapi.json规范相符并在afterAll钩子中统一清理代理资源。wrapInOpenApiTestServer的移除backstage/backend-openapi-utils0.7.0-next.1的 Minor 变更移除了wrapInOpenApiTestServer。该函数此前通过OPTIC_PROXY环境变量把测试流量导向 Optic 的capture代理随着 Optic 依赖被移除已失去意义。迁移方式非常直接在测试中将wrapInOpenApiTestServer替换为wrapServer两者 API 形态一致接收 Express 应用返回供 supertest 使用的 HTTP Server因此通常只需修改导入与调用名即可完成迁移。四、功能增强Redis 缓存连接配置支持对象形式变更内容backstage/backend-defaults0.17.5-next.2提交a624fa3扩展了 Redis 缓存存储的connection配置项现在既可以传入字符串 URL也可以传入携带额外连接选项的对象这些选项会直接透传给底层 Redis 客户端。例如可以在不新增专用配置字段的情况下配置pingInterval。配置示例backend: cache: store: redis connection: url: redis://user:passcache.example.com:6379 pingInterval: 60000 # 底层客户端连接选项直接透传 defaultTtl: 3600000约束条件对象形式仅在backend.cache.store为redis时受支持其他存储如memory、valkey仍要求使用纯字符串连接对于 Redis 集群cluster场景connection对象的属性会合并进集群默认配置cluster defaults中该变更修复了 issue #31813 与 #31742 相关的连接配置问题。底层实现与配置定义配置 schema 定义见 packages/backend-defaults/config.d.tsconnection字段的类型为string | { url: string; [key: string]: unknown }其中url为必填的 Redis 连接 URL其余键值对作为连接设置透传redis.client与redis.cluster子配置则分别控制keyv/redis客户端选项如namespace、keyPrefixSeparator、clearBatchSize、useUnlink、noNamespaceAffectsAll与集群节点/默认配置。单元测试见 packages/backend-defaults/src/entrypoints/cache/CacheManager.test.ts其中覆盖了字符串连接、对象连接含pingInterval透传以及非 redis 存储拒绝对象连接等场景。五、值得关注的功能与修复1. CIMD token 撤销支持backstage/plugin-auth-backend提交2aeb246为使用 client ID metadata documentsCIMD的客户端新增了 token 撤销能力只要启用了动态客户端注册或 CIMD/v1/revoke端点即可用该端点会通过 OpenID provider 配置中的revocation_endpoint对外通告。这使 Backstage 的 OIDC 身份提供方能力更完整客户端可以按标准流程主动撤销 token。2. Auth0 provider 新增prompt参数backstage/plugin-auth-backend-module-auth0-provider提交5446838为 Auth0 授权请求增加了可选的prompt设置设置为auto时由 Auth0 自行判断用户是否需要被提示如会话已存在则免登录现有配置默认继续使用consent行为因此升级后行为不变。配置方式是在 provider 配置中补充prompt: auto或保留默认。3. Catalog 类型过滤器回归修复backstage/plugin-catalog-react提交8a500d5修复了一个回归当EntityTypePicker的initialFilter与EntityKindPicker同时在EntityListProvider内使用时类型过滤器此前会在所选 kind 的类型加载完成后被清空现在该过滤器能够被正确保留。4. Scaffolder 任务计数在 PostgreSQL 下返回字符串的修复backstage/plugin-scaffolder-backend提交55902bb修复了DatabaseTaskStore.list在 PostgreSQL 下返回totalTasks为字符串的问题knex 在 PostgreSQL 上返回的COUNT(*)聚合是字符串bigint 列而 better-sqlite3 返回数字现在使用Number(...)强制转换并以Number.isSafeInteger(...)做安全校验这修复了list-scaffolder-tasksaction 在生产环境报Invalid output ... totalTasks: Expected number, received string的校验失败。5. Yeoman 模块兼容 ESMbackstage/plugin-scaffolder-backend-module-yeoman提交5e92512修复了与 yeoman-environment v4纯 ESM的兼容性将原先会抛出ERR_REQUIRE_ESM的require()调用替换为动态import()并更新注册逻辑以匹配 v4 API。6. UI 组件内部迁移backstage/core-components提交7ceeaad将CopyTextButton从 Material-UI 迁移到 Backstage UIBUI用ButtonIcon与TooltipTrigger/Tooltip替换了 MUI 的IconButton与Tooltip。这是一次纯内部重构组件对外 API 保持不变不影响使用方代码。7. Connections 服务默认实现backstage/connections提交ec96761为 connections 服务提供了默认实现使后端模块可以直接依赖该服务而无需应用显式安装 connections 服务工厂降低了接入门槛。六、升级建议与注意事项重点处理破坏性变更升级前先处理两类 BREAKING 变更——代理配置切换到NODE_USE_ENV_PROXY1环境变量方案OpenAPI 工具链迁移到oasdiff移除useoptic/optic、安装oasdiffCLI、用wrapServer替换wrapInOpenApiTestServer。检查自定义 OpenAPI 脚本若 CI 中使用了package schema openapi init或repo schema openapi test需改走oasdiff或wrapServer路径diff命令的输出格式变化需要同步调整结果解析逻辑。验证缓存配置使用 Redis 缓存的部署可检查connection是否可受益于对象形式如pingInterval注意对象形式仅适用于 redis 存储。关注依赖传播cli-common、backend-plugin-api、config-loader、cli-node等基础包的更新会通过依赖关系传播到大量插件包本次 changelog 中绝大多数 Updated dependencies 均指向这几个包升级时建议一次性同步所有next版本避免版本错配。预发布版本定位本 changelog 针对next预发布版本正式迁移请以对应的 stable 版本发布说明为准。相关代码可进一步查阅testUtils.ts、Proxy 实现、package diff 命令、repo diff 命令、Redis 缓存配置定义、缓存管理器测试。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考