4. 项目结构解析：packages/app、packages/backend、plugins 目录作用

Backstage 基线项目采用 monorepo 架构，由三个核心目录构成项目骨架。理解 packages/app、packages/backend 和 plugins 的分工，是进行控制平面接口调用与插件集成的第一步。这三个目录分别对应前端展示层、后端服务层和功能扩展层，形成清晰的关注点分离。

4.1 三层架构总览

下图展示了 Backstage 基线项目的核心目录结构与数据流向。控制平面接口的调用请求从前端发起，经过后端代理，最终由插件处理并返回结果。

4.2 packages/app：前端展示层

packages/app 是 Backstage 的前端应用入口，负责 UI 渲染、路由管理和插件前端组件的挂载。在控制平面接口调用场景中，该层负责发起 API 请求并展示返回数据。

文件/目录	作用	与控制平面接口的关系
App.tsx	应用根组件，配置全局路由和插件注册	定义插件页面路由，挂载调用接口的组件
apis.ts	API 客户端配置，注册 API 工厂	配置控制平面接口的 baseUrl 和认证
plugins/	插件前端扩展点，导入插件组件	每个插件可包含独立的接口调用逻辑
package.json	前端依赖声明，包括 @backstage/core 等	引入接口调用所需的 HTTP 客户端库

4.3 packages/backend：后端服务层

packages/backend 是 Backstage 的后端服务入口，基于 Express 框架运行。该层是控制平面接口调用的核心代理层，负责转发前端请求、处理认证鉴权、聚合多源数据。

文件/目录	作用	与控制平面接口的关系
index.ts	后端服务启动入口，初始化插件后端	启动 HTTP 服务，加载所有插件后端模块
plugins/	插件后端路由注册目录	每个插件在此注册其控制平面接口路由
auth/	认证中间件配置	为控制平面接口调用注入 JWT 或
catalog.ts	服务目录后端处理器	从控制平面拉取实体数据并缓存

4.4 plugins：功能扩展层

plugins 目录是 Backstage 的扩展核心，每个插件通常包含前端组件和后端路由两部分。在控制平面接口调用场景中，插件是接口调用的具体执行单元。

一个标准插件的目录结构如下：

plugins/
├── my-plugin/                    # 自定义插件目录
│   ├── src/
│   │   ├── index.ts              # 插件导出入口
│   │   ├── plugin.ts             # 插件定义，注册路由和组件
│   │   ├── components/           # 前端 UI 组件
│   │   │   ├── MyPluginPage.tsx  # 插件主页面
│   │   │   └── MyPluginTable.tsx # 数据展示表格
│   │   ├── api/                  # API 客户端定义
│   │   │   ├── MyPluginApi.ts    # 接口类型定义
│   │   │   └── MyPluginClient.ts # 接口调用实现
│   │   └── routes.ts             # 前端路由配置
│   ├── backend/                  # 插件后端（可选）
│   │   ├── index.ts              # 后端路由注册
│   │   └── router.ts             # 控制平面接口代理路由
│   ├── package.json
│   └── README.md
└── catalog/                      # 内置插件示例
└── scaffolder/                   # 内置插件示例

4.5 三目录协作流程

以下步骤描述一次完整的控制平面接口调用在三层之间的流转过程：

1. 前端发起请求：packages/app 中的组件调用插件提供的 API 客户端方法。
2. 后端接收代理：请求到达 packages/backend 中对应插件的后端路由。
3. 认证注入：后端中间件从环境变量或配置中读取控制平面凭据，附加到请求头。
4. 转发至控制平面：后端使用 HTTP 客户端（如 node-fetch）向目标控制平面发送请求。
5. 响应处理：后端接收响应，进行数据清洗、错误处理，返回给前端。
6. 前端渲染：packages/app 中的组件接收数据并更新 UI。

4.6 目录职责对比

对比维度	packages/app	packages/backend	plugins
主要职责	UI 渲染与路由	服务代理与认证	业务逻辑扩展
技术栈	React + Material UI	Express + Node.js	前后端均可
接口调用方式	调用内部 API 客户端	代理转发至外部	定义接口调用逻辑
认证管理	无直接认证	集中管理凭据	可配置独立认证
扩展方式	注册插件组件	注册插件路由	独立开发部署

4.7 基线集成中的目录配置要点

在将控制平面接口调用集成到 Backstage 基线项目时，需要关注以下配置点：

• packages/app/package.json：添加插件前端依赖，如 @backstage/plugin-catalog。
• packages/app/src/App.tsx：使用 FlatRoutes 注册插件页面路由。
• packages/backend/src/index.ts：调用 createBackend 并添加插件后端模块。
• packages/backend/src/plugins/：为每个需要调用控制平面接口的插件创建后端路由文件。
• plugins/your-plugin/src/api/：定义类型安全的 API 客户端，封装接口调用细节。