Backstage 后端系统命名规范从插件、模块到扩展点与服务的统一命名模式指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南系统讲解 Backstage 后端系统Backend System中的命名模式Naming Patterns。这些模式统一了跨包的导出命名方式让开发者仅凭名称即可判断导出物的类型、归属与用途——例如看到xxxPlugin即可确认是后端插件实例看到xxxExtensionPoint即知是扩展点接口或引用。读完本文你将掌握插件、模块、扩展点、服务四类核心构件的标准命名格式与 ID 规则并能在自己的 Backstage 插件与模块开发中直接套用。命名总原则camelCase 与 kebab-case 的分工Backstage 后端系统对命名有一条总体规则所有名称导出标识符一律使用camelCase唯一例外是插件与模块的ID它们使用kebab-case连字符分隔的小写形式。这一规则的目的在于保持各包导出的一致性降低理解成本。当你在代码库中看到形如catalogModuleGithubEntityProvider的标识符时可以立即推断出这是一个属于catalog插件的、名为github-entity-provider的模块而catalogProcessingExtensionPoint则表明它是 catalog 插件的 processing 扩展点引用。ID 的字符集约束为仅允许字母、数字与连字符dash且必须以字母开头。例如user-settings、github-entity-provider、catalog.processing均合法而2fa、-foo、foo_bar这类形式不合规。下文将按四类核心构件逐一展开每类都给出格式表、命名示例与仓库中的真实实现佐证。插件PluginscamelIdPlugin与kebab-id命名格式描述模式示例备注导出名camelIdPlugincatalogPlugin、userSettingsPlugin—插件 IDkebab-idcatalog、user-settings仅含字母、数字与连字符且以字母开头标准写法export const userSettingsPlugin createBackendPlugin({ pluginId: user-settings, ... })后端插件的导出常量以Plugin结尾插件 ID 使用 kebab-case 并在pluginId字段中声明。仓库中的真实实现在 plugins/catalog-backend/src/service/CatalogPlugin.ts 中catalog 插件正是以catalogPlugin createBackendPlugin(...)的方式导出plugins/auth-backend/src/authPlugin.ts 与 plugins/app-backend/src/service/appPlugin.ts 也严格遵循camelIdPlugin模式。这些常量随后通过包的公共入口统一向外导出保证了消费方命名体验的一致。值得留意的是前端插件的命名遵循相同逻辑。例如 plugins/user-settings/src/plugin.ts 中userSettingsPlugin createPlugin({ id: user-settings, ... })并在 plugins/user-settings/src/index.ts 中作为userSettingsPlugin导出。这说明camelIdPlugin kebab-case ID 的组合是整个 Backstage前端与后端共享的心智模型。模块ModulespluginIdModuleModuleId与module-id命名格式描述模式示例备注导出名pluginIdModuleModuleIdcatalogModuleGithubEntityProvider—模块 IDmodule-idgithub-entity-provider仅含字母、数字与连字符且以字母开头标准写法export const catalogModuleGithubEntityProvider createBackendModule({ pluginId: catalog, moduleId: github-entity-provider, ... })模块导出名由「插件 ID 的 camelCase 化 Module 模块自身的 camelCase ID」三段拼接而成。这一命名天然携带了模块归属关系catalogModuleGithubEntityProvider一眼可知它属于 catalog 插件服务于 GitHub 实体提供者场景。仓库中的真实实现auth 系列模块是这一模式最集中的体现。在 plugins/auth-backend-module-atlassian-provider/src/module.ts 中模块被命名为authModuleAtlassianProvider createBackendModule(...)同理还有authModuleAuth0Providerauth-backend-module-auth0-provider/src/module.ts、authModuleAwsAlbProviderauth-backend-module-aws-alb-provider/src/module.ts等。它们统一遵循pluginIdModuleModuleId规则全部归属于 auth 插件。关于createBackendModule的底层契约如registerExtensionPoint如何将模块与扩展点绑定可进一步阅读 packages/backend-plugin-api/src/wiring/createBackendModule.ts。扩展点Extension PointsInterface 与 Reference 的成对命名命名格式描述模式示例接口InterfacePluginIdNameExtensionPointCatalogProcessingExtensionPoint引用ReferencepluginIdNameExtensionPointcatalogProcessingExtensionPoint扩展点 IDpluginId.namecatalog.processing、foo.barBaz扩展点的三个命名要素接口类型使用 PascalCasePluginIdNameExtensionPoint引用常量使用 camelCasepluginIdNameExtensionPointID使用pluginId.name点分形式。注意 ID 中name部分允许 camelCase如foo.barBaz这是扩展点 ID 与插件/模块 ID 的一个差异点。标准写法export interface CatalogProcessingExtensionPoint { ... } export const catalogProcessingExtensionPoint createExtensionPointCatalogProcessingExtensionPoint({ id: catalog.processing, ... })接口与引用成对出现接口描述扩展点对外暴露的 API 形状引用则是模块在注册时用于「指向」该扩展点的令牌。仓库中的真实实现catalog 插件完整实现了这一命名在 plugins/catalog-backend/src/service/CatalogPlugin.ts 中导入了catalogProcessingExtensionPoint并在插件内部通过extensionPoint: catalogProcessingExtensionPoint完成注册见同文件 L121。扩展点的定义来源是backstage/plugin-catalog-node包性能测试中也直接引用了该扩展点见 plugins/catalog-backend/src/tests/performance/getEntitiesPerformance.test.ts。createExtensionPoint本身的实现与类型定义可参考 packages/backend-plugin-api/src/wiring/createExtensionPoint.ts其测试用例 packages/backend-plugin-api/src/wiring/createBackendModule.test.ts 也展示了createExtensionPointstring({ id: point })的用法。服务ServicesService / ServiceRef / ServiceFactory 的三件套命名格式描述模式示例接口InterfaceNameServiceLoggerService、DatabaseService引用ReferencenameServiceRefloggerServiceRef、databaseServiceRef服务 IDpluginId.namecore.rootHttpRouter、catalog.catalogClient工厂FactorynameServiceFactoryloggerServiceFactory、databaseServiceFactory服务是后端系统中组件间解耦的核心机制其命名由四件套构成接口NameService、引用nameServiceRef、IDpluginId.name与工厂nameServiceFactory。标准写法export interface CatalogClientService { ... } export const catalogClientServiceRef createServiceRefCatalogClientService({ id: catalog.catalogClient, ... }) export const catalogClientServiceFactory createServiceFactory({ service: catalogClientServiceRef, ... })三者的职责边界CatalogClientService定义服务能力catalogClientServiceRef是服务在依赖注入系统中的唯一令牌catalogClientServiceFactory则负责实例化该服务并在插件启动时按需装配。核心服务Core Services的例外coreServices 与 mockServices上述「每个服务引用都导出为独立xxxServiceRef常量」的模式对核心服务存在一个例外backstage/backend-plugin-api将所有核心服务的引用统一收纳进单个coreServices集合backstage/backend-test-utils将所有 mock 服务实现统一收纳进单个mockServices集合。因此在真实代码中loggerServiceRef与databaseServiceRef并不存在取而代之的是coreServices.logger与coreServices.database。文档建议除非你需要导出的服务数量非常多否则普通插件应避免逐个导出xxxServiceRef的模式优先复用coreServices。仓库证据清晰可见packages/backend-plugin-api/src/services/definitions/coreServices.ts 中export namespace coreServices { ... }收纳了auth、userInfo、cache、rootConfig等引用例如auth createServiceRefAuthService({ id: core.auth })服务 ID 全部采用core.name点分形式packages/backend-test-utils/src/services/mockServices.ts 中同样以export namespace mockServices { ... }形式导出全部 mock 实现供测试场景直接注入。此外backstage/backend-plugin-api的 alpha 入口 packages/backend-plugin-api/src/alpha/refs.ts 中actionsServiceRef、metricsServiceRef、tracingServiceRef等仍是逐个导出的形态可作为「插件自有服务引用」命名方式的参考样例。Root 前缀推荐而非强制对于 root 作用域scope: root的服务通常推荐在接口命名上以Root作为前缀但并非强制要求遵循该模式的例子RootHttpRouterService、RootLifecycleService反例ConfigService同样是 root 作用域服务在 coreServices.ts 中可见其引用rootConfig createServiceRefRootConfigService({ id: core.rootConfig, scope: root })却没有Root前缀。从命名一致性的角度新服务建议优先考虑Root前缀以快速识别生命周期语义但这不是硬性约束接口的实际命名可结合服务定位与既有约定权衡。命名模式速查与实战建议| 构件 | 导出名 | ID | 示例 | | ---- | ------ | -- | ---- | | 插件 |camelIdPlugin|kebab-id|catalogPlugin/catalog| | 模块 |pluginIdModuleModuleId|module-id|catalogModuleGithubEntityProvider/github-entity-provider| | 扩展点接口 |PluginIdNameExtensionPoint| — |CatalogProcessingExtensionPoint| | 扩展点引用 |pluginIdNameExtensionPoint|pluginId.name|catalogProcessingExtensionPoint/catalog.processing| | 服务接口 |NameService| — |CatalogClientService| | 服务引用 |nameServiceRef|pluginId.name|catalogClientServiceRef/catalog.catalogClient| | 服务工厂 |nameServiceFactory| — |catalogClientServiceFactory|实战中的三条建议先查命名再写代码在创建新插件、模块或扩展点之前先对照上表确定导出名与 ID避免后续重构成本。ID 一经发布即成为面向用户的稳定标识改动会破坏既有配置与依赖关系。优先复用核心服务需要日志、数据库、配置等能力时直接通过coreServices.xxx注入不要重复导出xxxServiceRef仅在服务数量庞大或属于插件自有领域时才考虑xxxServiceFactory独立导出。让测试保持同构测试中注入 mock 服务时使用mockServices.xxx集合见 packages/backend-test-utils/src/services/mockServices.ts与coreServices的命名一一对应降低读写测试的心理负担。延伸阅读命名模式属于 Backstage 后端系统架构文档体系的一部分建议按顺序结合阅读后端系统架构总览、后端Backends、服务Services、插件Plugins、扩展点Extension Points、模块Modules 与功能加载器Feature Loaders。本篇命名规范正是这些架构概念在代码层面的「落地语言」——理解它们你就能更顺畅地阅读和编写符合 Backstage 社区标准的后端代码。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考