Backstage v1.17.0-next.0 版本速览deepVisibility 配置可见性、OpenAPI 请求校验与破坏性变更解析【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇指南以 Backstage 官方发布说明 docs/releases/v1.17.0-next.0-changelog.md 为骨架深入解读该预发布版本next.0中最值得开发者关注的三大核心变化config-loader 新增的deepVisibility模式关键字、基于backstage/backend-openapi-utils的后端 OpenAPI 请求校验落地以及plugin-catalog-backend-module-unprocessed的破坏性导出重命名。读完本文你将理解这些变更的动机、底层实现机制、对存量项目的影响以及如何安全升级迁移。版本背景next.0 发布说明的阅读方式v1.17.0-next.0是 Backstage v1.17.0 正式发布前的第一个预发布next版本用于在正式发布前收集反馈、验证变更。这类 changelog 的典型特征是Minor Changes包含新特性是升级时需要重点关注的增量变化Patch Changes多数为依赖升级Updated dependencies与小的 bug 修复例如本版本中core-app-api修复了navigate分析事件被错误归属到根路由插件的问题9ae4e7e63836search-backend-node修复了 Lunr 搜索引擎因忽略无效元数据位置而导致高亮失败的问题e3e9bc10298bBREAKING标记明确标注的破坏性变更升级时必须处理。本文聚焦其中三个具备实质技术内容的变化点展开。一、config-loader 1.4.0新增 deepVisibility 配置可见性关键字backstage/config-loader从1.3.x升级到1.4.0-next.0其核心新特性是引入了deepVisibility这个 JSON Schema 关键字变更号cd514545d1d0。1.1 背景Backstage 的配置可见性机制在 Backstage 中配置项有三类可见性见 packages/config-loader/src/schema/types.tsexport const CONFIG_VISIBILITIES [frontend, backend, secret] as const; export type ConfigVisibility frontend | backend | secret; export const DEFAULT_CONFIG_VISIBILITY: ConfigVisibility backend;frontend配置会被打包进前端 bundle暴露给浏览器如app.baseUrlbackend仅后端可见默认值secret敏感配置前端不可见且后端在输出/导出时会被脱敏处理。在引入deepVisibility之前为某个对象下的所有子字段设置secret/frontend可见性需要在每个叶子节点上重复标注visibility secret一旦新增字段忘记标注就会退化为默认的backend可能造成敏感信息外泄到前端或者期望暴露给前端的字段意外缺失。1.2 deepVisibility 的用法deepVisibility的作用是在对象层级声明一个默认可见性并递归应用到其所有后代字段同时尊重子节点已有的显式可见性标注或子节点自身的deepVisibility覆盖。官方示例——为一个对象及其所有子字段批量强制默认可见性为secretexport interface Config { /** * Enforces a default of secret instead of backend for this object. * deepVisibility secret */ mySecretProperty: { type: object; properties: { secretValue: { type: string; }; verySecretProperty: { type: string; }; }; }; }1.3 禁止的用法不允许用 deepVisibility 降级暴露出于安全考虑deepVisibility不允许将子节点可见性提升到比继承值更开放的级别。官方给出的反面示例中父级声明deepVisibility secret后子字段frontendUrl试图用visibility frontend将其重新暴露给前端这是不允许的export interface Config { /** * Set the top level property to secret, enforcing a default of secret instead of backend for this object. * deepVisibility secret */ mySecretProperty: { type: object; properties: { frontendUrl: { /** * We can NOT override the visibility to reveal a property to the front end. * visibility frontend */ type: string; }; verySecretProperty: { type: string; }; }; }; }1.4 源码级原理编译与过滤两个阶段从源码结构看deepVisibility的完整实现横跨配置 schema 的编译与过滤两个阶段位于 packages/config-loader/src/schema/compile.ts 与 packages/config-loader/src/schema/filtering.ts。编译阶段compile.ts通过 AJV 注册deepVisibility关键字其metaSchema的枚举被刻意限制为[frontend, secret]——不允许backend。源码注释解释了原因禁止backend深度可见性是为了防止权限逃逸permission escaping即避免出现deepVisibility secret - backend - frontend或deepVisibility secret - backend - visibility frontend这类逐级降级再重新暴露的链条见 compile.ts校验时把每个设置了deepVisibility的数据路径记录进deepVisibilityByDataPath映射表遍历合并后的 schema 时子节点若未显式声明则继承父节点的deepVisibilityschema[inheritedVisibility] ?? schema?.deepVisibility ?? parentSchema?.[inheritedVisibility]见 compile.ts对同一路径下同时出现frontend与secret冲突的情况直接抛错Config schema visibility is both frontend and secret for path见 compile.ts。过滤阶段filtering.tsfilterByVisibility在递归遍历配置数据时先取当前路径的显式可见性visibilityByDataPath否则取继承值随后用deepVisibilityByDataPath计算新的继承可见性传递给子节点——即遇到不同的 deepVisibility 之前用它作为所有后代的默认可见性见 filtering.ts。测试用例印证compile.test.ts覆盖了四类场景父级deepVisibility: secret时未标注的子节点a、c、数组d及其元素全部继承为secret而显式标注visibility: secret的b保持 secret显式标注visibility: backend的字段被尊重子节点试图以frontend覆盖继承的secret→ 抛错子节点设置不同的deepVisibility→ 抛错同一 schema 节点同时声明deepVisibility与冲突的visibility→ 抛错。1.5 实践建议对于插件作者如果某个配置对象整体属于敏感信息例如第三方系统的 token 集合直接在对象上标注deepVisibility secret即可避免遗漏叶子字段带来的泄露风险但注意不要试图用它降级已有安全标注。二、后端 OpenAPI 请求校验落地catalog/search/todo 三个后端同时启用本次发布中三个后端插件同时升级backstage/plugin-catalog-backend1.12.0-next.0backstage/plugin-search-backend1.4.0-next.0backstage/plugin-todo-backend0.2.0-next.0它们的 Minor Changes 均指向同一变更号ebeb77586975现在通过backstage/backend-openapi-utils基于 OpenAPI schema 执行请求校验非法输入例如本应为数字却传了字符串a的错误响应可能发生变化。2.1 backend-openapi-utils 0.0.3新增 createRouter 方法backstage/backend-openapi-utils0.0.3-next.0的 Patch Changes 披露了两件事新增createRouter方法用于生成一个基于你的 OpenAPI spec 进行请求校验的 express router修复了查询参数类型解析的一个 bug。从 packages/backend-openapi-utils/src/stub.ts 的实现可以看到createRouterWithValidation的核心机制基于express-promise-router创建 router挂载express-openapi-validator中间件默认配置为validateRequests.coerceTypes: false不隐式做类型转换所以a不会被强转成数字而是校验失败、allowUnknownQueryParameters: false、validateResponses: false任何来自校验中间件的错误都会被转换为backstage/errors中的InputError见 stub.ts同时暴露OPENAPI_SPEC_ROUTE路由通过openapi-merge把当前 spec 以 JSON 形式提供出去便于开发者直接在运行时查看该插件的 OpenAPI 文档。对外公开的两个工厂函数createValidatedOpenApiRouter与createValidatedOpenApiRouterFromGeneratedEndpointMap分别返回基于文档类型或生成端点映射的类型化 routerApiRouter/TypedRouter。TypedRouter在 router.ts 中定义为get/post/put/delete提供了按 EndpointMap 推导的请求/响应类型——这意味着调用方在编译期就能得到入参与返回值的类型检查。2.2 生成物repo-tools 的 schema openapi generate 升级配套地backstage/repo-tools0.3.3-next.0的schema openapi generate命令ebeb77586975被更新为生成一个可直接导入使用的默认 router。生成逻辑位于 packages/repo-tools/src/commands/package/schema/openapi/generate/server.ts它会在generated/router.ts中写出import {createValidatedOpenApiRouterFromGeneratedEndpointMap} from backstage/backend-openapi-utils; import {EndpointMap} from ./apis; export const spec { /* ... */ } as const; export const createOpenApiRouter async ( options?: Parameterstypeof createValidatedOpenApiRouterFromGeneratedEndpointMap[1], ) createValidatedOpenApiRouterFromGeneratedEndpointMapEndpointMap(spec, options);而 catalog-backend 的生成产物正是使用这一模式见 plugins/catalog-backend/src/schema/openapi/generated/router.tsspec 声明为openapi: 3.1.0与文件末尾导出的createOpenApiRouterrouter.ts。2.3 对开发者的影响与升级注意点错误响应格式变化非法输入的响应体由各插件自行拼装的错误信息变为统一的InputErrorHTTP 400。如果前端或其他调用方依赖旧的错误响应结构需要同步适配查询参数更严格allowUnknownQueryParameters: false意味着未在 OpenAPI spec 中声明的查询参数将被拒绝coerceTypes: false意味着?limitabc这类本应报错的请求不再被静默转换如何平滑迁移升级插件前先用backstage-repo-tools package schema openapi generate确认你的插件 spec 与生成代码一致仓库中的校验脚本见 packages/repo-tools/src/commands/package/schema/openapi/validate.ts再回归测试关键 API 的合法与非法入参。三、破坏性变更UnprocessedEntites 修正为 UnprocessedEntitiesbackstage/plugin-catalog-backend-module-unprocessed0.2.0-next.0带来本次发布中唯一明确的BREAKING变更5156a94c2e2a修正导出模块中的拼写错误UnprocessedEntites需改名为UnprocessedEntities。这意味着所有import { UnprocessedEntitesModule } from backstage/plugin-catalog-backend-module-unprocessed之类的导入必须改为正确拼写UnprocessedEntitiesModule。当前仓库源码中已统一采用正确拼写例如 plugins/catalog-backend-module-unprocessed/src/UnprocessedEntitiesModule.ts、module.ts 以及测试文件 UnprocessedEntitiesModule.test.ts。升级检查清单对升级到 v1.17.0-next.0 的项目建议按以下顺序核对搜索旧拼写在仓库内全局搜索UnprocessedEntites将引用替换为UnprocessedEntities注意仅此模块有此变更catalog 本体不受影响验证配置可见性为新增/存量配置对象补齐deepVisibility或逐一标注visibility并运行backstage-cli config:schema其--merge/--format等选项见 packages/cli/cli-report.md检查 schema 是否合法回归后端 API重点验证 catalog/search/todo 的 REST 接口在非法入参下的错误响应是否符合预期尤其是类型错误的请求是否返回 400InputError更新依赖跟随 changelog 中的 Updated dependencies 列表整体升级确保backend-openapi-utils等共享包版本一致避免类型不匹配。四、其他值得留意的细节变更除上述三大主题外本版本还有几处小改动值得记录CLI 体验backstage/cli0.22.10-next.0在 app 配置变更时会自动重载前端3f67cefb4780并支持用--no-merge标志打印未合并的配置 schemacebbf8a27f3c便于排查 schema 合并问题Home 插件plugin-home0.5.5-next.0的WelcomeTitle language{[English, Spanish]} /支持按语言渲染问候语a559ff68de7eAddWidgetDialog在标题为空时回退使用名称6743d3917a52plugin-home-react的createCardExtension中title变为可选bf67dce73174Catalog 图plugin-catalog-graph0.2.33-next.0会把 entity 的spec传播到EntityNode便于基于type等 spec 信息自定义图节点样式64ee2c0c7ca5Analytics 归属修复core-app-api修复了导航到非可路由扩展路由时navigate事件被错误归属到根路由插件如/下的 home 插件的问题9ae4e7e63836Linguist 后端修复了linguistJsOptions被linguist-js包修改后导致批量任务后续实体失败的问题ca5e591cb86a新增模块plugin-analytics-module-newrelic-browser0.0.1-next.0引入 New Relic Browser 分析模块ec7357258853。结语v1.17.0-next.0 是一个基础设施优先的预发布版本deepVisibility让配置可见性声明从逐字段标注进化为对象级递归默认显著降低敏感配置泄露风险OpenAPI 请求校验从工具链到三个后端插件全线落地配合 repo-tools 自动生成类型化 router把后端 API 的输入契约变成了编译期与运行期的双重保障。建议插件与平台维护者重点关注上述破坏性变更与错误响应变化利用 next 版本窗口提前完成迁移验证。延伸阅读配置可见性相关源码可继续阅读 packages/config-loader/src/schema/compile.ts、packages/config-loader/src/schema/filtering.ts 与 packages/config-loader/src/schema/types.tsOpenAPI 校验实现见 packages/backend-openapi-utils/src/stub.ts 与 packages/backend-openapi-utils/src/router.ts。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考