在开发 Backstage 插件时，你可能会陷入这样的困境：“前端使用的这个 TypeScript 接口，后端也需要一模一样的，该怎么办？”
在两个包之间重复编写代码不仅违反了 DRY (Don’t Repeat Yourself) 原则，而且当只修改其中一方时，也容易导致运行时错误。现在，我们将揭示 Backstage 维护团队推荐的“通用库包”方法！🛠️
1. 推荐解决方案：分离 common 包 📦
在 Backstage 架构中，如果存在前端 (-frontend) 和后端 (-backend) 都需要引用的代码，那么创建独立的通用包 (Common Package) 是标准做法。
通常使用以下命名约定：
- 前端： plugins/my-plugin
- 后端： plugins/my-plugin-backend
- 通用： plugins/my-plugin-common ✨
2. 为什么要这样做？(优点分析) 💡
- 类型安全 (Type Safety)： 通过将 API 请求/响应结构定义为接口并共享，可以确保前端和后端之间的数据规范始终一致。
- 优化打包大小： 防止后端专用库被包含在前端打包文件中。
- 防止循环引用： 保持清晰的依赖结构，避免前端引用后端或反之的情况发生。🛡️
3. 通用包中应包含的内容 📂
通常，以下类型的代码是 common 包的常客：
- API 实体和接口： 服务器和客户端之间交换的 JSON 数据格式。
- 权限定义 (Permissions)： Backstage 权限系统中使用的权限对象。
- 常量 (Constants)： 插件 ID、特定错误代码、路由路径等。
- 通用工具函数： 日期计算、字符串处理等不依赖于环境（Node.js vs 浏览器）的纯函数。
4. 实战！分步构建指南 🛠️
第 1 步：创建包
使用 Backstage CLI 创建一个新的通用包，或者模仿现有结构创建 plugins/my-plugin-common 目录。
第 2 步：package.json 配置
此包应具有适当的名称和元数据，以便可以在任何地方导入。
第 3 步：添加依赖 (Dependency)
将我们创建的通用包添加到前端和后端的 package.json 中。
JSON
// plugins/my-plugin/package.json (前端)
"dependencies": {
"@internal/backstage-plugin-my-plugin-common": "workspace:^"
}
// plugins/my-plugin-backend/package.json (后端)
"dependencies": {
"@internal/backstage-plugin-my-plugin-common": "workspace:^"
}5. 注意事项：浏览器与 Node 之间的平衡 ⚖️
编写通用包时最需要注意的是“环境中立性”。
- 禁止： 使用 fs、path 等 Node.js 专用模块（会导致前端报错）
- 禁止： 使用 window、document 等浏览器专用 API（会导致后端报错）
- 推荐： 仅使用纯 TypeScript 代码和不依赖于环境的通用库。
🏁 总结
随着 Backstage 插件复杂度的增加，common 包的价值愈发凸显。这种减少代码重复、提高类型安全性的策略，也是大型平台团队稳定运营 Backstage 的关键秘诀。🌟
如果你正在开发插件，何不今天就引入 common 包呢？
标签： Backstage, PluginDevelopment, CodeSharing, TypeScript, Architecture, Frontend, Backend, SoftwareEngineering
发表回复