BackGen

# BackGen [](https://github.com/IbrahimKhaled19/BackGen/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@ibrahimkhaled19/backgen) [](https://opensource.org/licenses/MIT) [](https://www.npmjs.com/package/@ibrahimkhaled19/backgen) [](https://github.com/IbrahimKhaled19/BackGen) ## 人工智能就绪 [](https://glama.ai/mcp/servers/IbrahimKhaled19/BackGen) [](https://glama.ai/mcp/servers/IbrahimKhaled19/BackGen) BackGen 配备了一个内置的 **MCP（模型上下文协议）服务器**，AI 助手（如 Claude、Cursor、GitHub Copilot、VS Code）可以使用它来为您搭建项目。 ```json { "mcpServers": { "backgen": { "command": "npx", "args": ["-y", "@ibrahimkhaled19/backgen", "backgen-mcp"] } } } ``` **可用的 MCP 工具：** | 工具 | 描述 | |------|-------------| | `init_project` | 使用选择的 ORM、预设和插件搭建一个新的生产就绪的后端项目 | | `add_plugin` | 安装插件（jwt、clerk、stripe、s3、ratelimit、ci-github、dependabot、codeql、docker-registry、release） | | `remove_plugin` | 删除以前安装的插件 | | `generate_resource` | 生成具有字段、关系、验证和 Swagger 的 CRUD 资源 | | `generate_seed` | 为资源生成数据库种子文件 | | `generate_factory` | 为资源生成测试工厂 | | `doctor` | 验证现有 BackGen 项目的配置问题 | | `list_plugins` | 列出所有可用的插件及其描述 | | `list_presets` | 列出所有可用的领域预设 | | `project_info` | 显示项目元数据 | 然后只需询问： *"使用 Prisma、JWT 认证和 Stripe 支付搭建一个 SaaS 后端"* --- <img width="1600" height="900" alt="BackGen CLI 生成具有 Prisma、Drizzle 和 Mongoose 的 Express.js 后端 — Swagger 文档、Docker、认证和多租户 SaaS 预设" src="https://github.com/user-attachments/assets/cd3888d3-fa9d-4e4e-a595-4f10ae039871" /> > 生成生产就绪的后端基础，以便开发人员可以专注于业务逻辑，而不是样板代码。 BackGen 是一个 CLI 工具，它生成完整的 Express.js 后端项目，支持 **Prisma、Drizzle 或 Mongoose** — 具有认证、多租户基础设施、生产强化、Docker 和测试 — 所有这些都开箱即用。 ```bash npx @ibrahimkhaled19/backgen init my-api --orm drizzle cd my-api npm run dev ``` `http://localhost:3000/docs` 处的 Swagger 文档，时间不到 60 秒。选择您的 ORM，其他保持不变。 --- ## 功能 - **Express + TypeScript** — 严格模式，ESLint 9（扁平配置），Vitest - **多 ORM** — Prisma、Drizzle 或 Mongoose。在 `init` 时选择，后续通过清单切换 - **SaaS 就绪** — `saas-core` 预设提供组织、成员资格、邀请、RBAC、租户范围查询 - **默认强化** — helmet、严格 CORS、请求 ID、请求超时、xss + mongo-sanitize、优雅关闭、`/health` + `/ready`、错误信封 - **插件系统** — JWT、Clerk、Stripe、S3、ratelimit 通过 `backgen add` - **资源生成器** — 具有关系、验证、Swagger 的 CRUD 模块 - **领域预设** — saas-core、healthcare、SaaS、ecommerce、CRM、LMS — 一个命令生成完整领域 - **种子和工厂生成器** — 开发数据和测试工厂 - **Docker** — 多阶段 Dockerfile + docker-compose - **Swagger/OpenAPI** — 自动生成的 API 文档 - **清单** — `.backgenrc.json` 跟踪 ORM、插件、版本和所有权以进行 **升级/回滚** --- ## 快速入门 ```bash # 全局安装 npm install -g @ibrahimkhaled19/backgen # 创建项目（选择您的 ORM） backgen init my-api --orm prisma backgen init my-api --orm drizzle backgen init my-api --orm mongoose # 创建完整的多个租户领域 backgen init my-saas --preset saas-core --defaults # 添加认证 backgen add jwt backgen add clerk # 添加生产强化 backgen add ratelimit # 生成资源 backgen generate resource Product name:string price:number stock:number # 开始开发 cd my-api npm run dev ``` --- ## 命令 ### `backgen init [name]` 生成一个新的后端项目。 ```bash backgen init my-api # 交互式 ORM 选择器 backgen init my-api --orm prisma # 显式 ORM backgen init my-api --orm drizzle --defaults # Drizzle，非交互式 backgen init my-api --orm mongoose --skip-install backgen init my-api --preset saas-core --defaults # 完整的多个租户领域 backgen init my-api --preset healthcare # 医疗领域 ``` **输出：** - 具有 TypeScript 严格模式的 Express 应用程序 - 特定于 ORM 的数据层（Prisma / Drizzle / Mongoose） - 环境验证（Zod） - Swagger/OpenAPI 文档 - Docker + docker-compose - 默认强化：helmet、 CORS、请求 ID、超时、xss + mongo-sanitize、优雅关闭、健康检查 - ESLint 9 + Vitest - `.backgenrc.json` 清单（记录 `project.orm` + 插件） 默认情况下没有身份验证 — 使用 `backgen add` 选择您的身份验证提供商。 --- ### `backgen add [plugin]` 安装插件。交互式多选，如果没有参数。 ```bash backgen add # 交互式多选 backgen add jwt # JWT 认证 backgen add clerk # Clerk 认证即服务 backgen add stripe # Stripe 支付 backgen add s3 # AWS S3 存储 backgen add ratelimit # 每 IP / 每用户速率限制 backgen add devops # 一次安装所有 DevOps 插件 ``` **可用插件：** | 插件 | 类别 | 描述 | |--------|----------|-------------| | `jwt` | 认证 | 具有刷新令牌的 JWT 认证 | | `clerk` | 认证 | Clerk 认证即服务（与 jwt 冲突） | | `stripe` | 支付 | Stripe 结账、Webhook、客户 | | `s3` | 存储 | AWS S3 上传、下载、预签名 URL | | `ratelimit` | 生产 | 每 IP 速率限制，带有 Redis-ready 存储 | | `ci-github` | DevOps | GitHub Actions CI 管道（lint、类型检查、测试、构建、可选部署） | | `dependabot` | DevOps | 通过 Dependabot 自动更新依赖项 | | `codeql` | DevOps | 在推送和计划上进行 CodeQL 安全分析 | | `docker-registry` | DevOps | Docker 镜像构建和发布到 GHCR | | `release` | DevOps | 带有 npm 发布和 GitHub 发行的语义发布 | **冲突检测：** `jwt` 和 `clerk` 不能一起安装。 --- ## 领域预设 通过一个命令生成一个完整的领域。每个预设都创建多个资源，具有关系，自动安装 JWT 认证，并将所有内容连接起来。 ```bash backgen init my-api --preset healthcare backgen init my-api --preset saas --defaults ``` ### healthcare 患者、医生、预约、处方、医疗记录 — 患者和医生之间的预约，患者的处方，患者的医疗记录。 ### saas 组织、团队、成员资格、订阅、发票 — 具有团队和成员资格的组织，具有发票的订阅。 ### ecommerce 类别、产品、购物车、订单、订单项目、支付 — 类别中的产品，购物车中的项目，带有行项目的订单和支付。 ### crm 联系人、公司、交易、活动 — 具有联系人的公司，通过管道跟踪的交易，活动日志。 ### lms 课程、课程、注册、进度、证书 — 具有课程的课程，学生注册，进度跟踪，证书。 --- ### `backgen remove [plugin]` 删除插件。交互式多选，如果没有参数。支持 `devops` 缩写以删除所有 DevOps 插件。 ```bash backgen remove # 交互式多选 backgen remove stripe # 删除特定插件 backgen remove devops # 删除所有 DevOps 插件 ``` --- ### `backgen generate resource <name> [fields...]` 生成 CRUD 资源模块。 ```bash # 交互式 backgen generate resource Product # 非交互式 backgen generate resource Product name:string price:number stock:number # 具有关系 backgen generate resource Appointment date:datetime status:string \ --relations "doctor:Doctor,patient:Patient" # 具有 --fields 标志 backgen generate resource Product --fields "name:string,price:number" ``` **生成的文件：** ``` src/modules/product/ product.controller.ts # CRUD 端点 product.service.ts # 业务逻辑 product.repository.ts # 数据库操作 product.validation.ts # Zod 模式 product.types.ts # TypeScript 接口 product.routes.ts # 路由定义 + Swagger product.test.ts # 测试占位符 ``` **字段类型：** `string`, `number`, `boolean`, `date`, `datetime` **关系：** `doctor:Doctor`（属于），`patients:Patient`（拥有多个） --- ### `backgen generate seed <resource>` 为开发生成种子数据。 ```bash backgen generate seed Product --count 10 ``` 输出：`prisma/seeds/product.ts`（Prisma），`db/seeds/product.ts`（Drizzle），或 `seeds/product.ts`（Mongoose） --- ### `backgen generate factory <resource>` 生成测试工厂。 ```bash backgen generate factory Product ``` 输出：`src/factories/product.factory.ts` 用法： ```ts import { createProduct } from "./factories/product.factory.js"; const product = await createProduct({ name: "Widget" }); ``` --- ### `backgen generate migration [name]` 生成数据库迁移（ORM 感知）。 ```bash backgen generate migration add-product-table # 运行 prisma migrate dev / drizzle-kit generate / Mongoose 的 noop ``` --- ### `backgen sync` 使 `.backgenrc.json` 与项目同步。重新生成缺失的插件文件。 ```bash backgen sync ``` --- ### `backgen health` 显示系统健康信息。 ```bash backgen health ``` **显示：** - Node.js 版本 - 平台和架构 - BackGen 版本 --- ### `backgen doctor` 通过所有权完整性诊断检查项目健康状况。 ```bash backgen doctor # 健康检查 + 所有权审计 backgen doctor --fix # 自动修复缺失的清单条目 ``` **检查：** - Node.js 版本（>= 18） - npm 可用性 - .env 文件 - DATABASE_URL - Prisma 模式 / Drizzle 配置 / Mongoose 连接 - 依赖项 - 包管理器版本 - **文件完整性** — 所有清单跟踪的文件存在于磁盘上 - **所有权完整性** — 框架 vs 用户文件分类 --- ### `backgen upgrade` 将生成的项目升级到最新的模板版本。创建备份，然后顺序应用待处理的迁移。 ```bash backgen upgrade # 显示待处理迁移，提示后再应用 backgen upgrade --yes # 跳过确认，应用所有待处理迁移 ``` **发生了什么：** - 读取 `.backgenrc.json` 中的当前 `generatedVersion` - 加载待处理的内核 + 插件迁移 - 在 `.backgen/backups/pre-<version>/` 中创建备份 - 按顺序应用迁移（semver 排序） - 更新所有权注册表 + 清单中的 `generatedVersion` --- ### `backgen rollback` 从最近的备份恢复项目到其预升级状态。 ```bash backgen rollback # 显示最新备份，提示后再恢复 backgen rollback --yes # 跳过确认 ``` **发生了什么：** - 列出 `.backgen/backups/` 中的可用备份 - 恢复最近的备份（所有跟踪的文件 + 清单） - 项目返回到确切的预升级状态 --- ## 插件系统 每个插件都实现了 `BackGenPlugin` 接口： ```ts interface BackGenPlugin { name: string; category: string; description: string; version: string; dependencies?: string[]; devDependencies?: string[]; requires?: string[]; conflicts?: string[]; env?: Record<string, string>; templates: string[]; migrations?: PluginMigration[]; // 版本化的插件迁移脚本 install(ctx: InstallContext): Promise<void>; uninstall?(ctx: InstallContext): Promise<void>; } ``` 插件可以： - 安装 npm 依赖项 - 注入环境变量 - 在 app.ts 中注册路由 - 替换现有中间件 - 添加数据库模型（Prisma / Drizzle / Mongoose） - 携带版本化的迁移用于自己的升级 --- ## 项目清单 `.backgenrc.json` 跟踪插件、版本、生成的版本和文件所有权： ```json { "version": "1.0.0", "generatedVersion": "1.9.0", "project": { "name": "my-api", "framework": "express", "database": "postgresql", "orm": "prisma", "preset": "saas-core" }, "plugins": { "jwt": { "version": "1.0.0", "installedAt": "2026-06-01", "source": "core" } }, "files": { "src/app.ts": { "owner": "shared", "version": "1.9.0" }, "src/server.ts": { "owner": "framework", "version": "1.9.0" }, "src/config/env.ts": { "owner": "framework-editable", "version": "1.9.0" }, "prisma/schema.prisma": { "owner": "user" }, "src/modules/user/user.service.ts": { "owner": "user" }, "docker-compose.yml": { "owner": "shared", "version": "1.9.0" } } } ``` **所有权级别：** | 级别 | 描述 | 升级行为 | |-------|-------------|-----------------| | `framework` | BackGen 完全拥有 | 可以安全覆盖 | | `framework-editable` | 生成但用户可以自定义 | 通过迁移进行智能合并 | | `shared` | 生成的骨架，用户扩展（例如 docker-compose） | 迁移感知更新 | | `user` | 用户完全拥有 | 永远不会触及 | --- ## 生成的项目结构 ``` my-api/ ├── prisma/ # 仅限 Prisma ORM │ ├── schema.prisma │ └── seeds/ ├── src/db/ # 仅限 Drizzle ORM │ ├── schema/ │ │ └── index.ts │ └── seeds/ ├── src/models/ # 仅限 Mongoose ORM │ └── seeds/ ├── src/ │ ├── app.ts # Express 应用程序设置 │ ├── server.ts # 服务器入口点 │ ├── config/ │ │ ├── env.ts # Zod 环境验证 │ │ ├── database.ts # Prisma 客户端 / Drizzle 数据库 / Mongoose 连接 │ │ └── swagger.ts # Swagger 配置 │ ├── middleware/ │ │ ├── auth.ts # JWT/Clerk 身份验证 │ │ ├── validate.ts # Zod 验证 │ │ ├── error.ts # 全局错误处理程序 │ │ └── logger.ts # 请求日志记录 │ ├── modules/ │ │ ├── auth/ # 身份验证模块（如果安装了 jwt） │ │ ├── stripe/ # Stripe 模块（如果安装了） │ │ └── <resource>/ # 生成的资源 │ ├── services/ │ │ └── logger.service.ts # Winston 日志记录器 │ ├── utils/ │ │ ├── api-error.ts # 错误类 │ │ ├── async-handler.ts # 异步包装器 │ │ └── response.ts # 响应格式化程序 │ └── factories/ # 测试工厂 ├── .env.example ├── .backgenrc.json # 清单 ├── Dockerfile ├── docker-compose.yml ├── package.json └── tsconfig.json ``` --- ## 开发 ```bash # 克隆 git clone https://github.com/your-username/backgen.git cd backgen # 安装 npm install # 构建 npm run build # 测试 npm run test # Lint npm run lint ``` ### 测试套件 277+ 测试覆盖： - CLI 帮助和版本 - Init：项目结构、配置、清单（所有 3 种 ORM） - 具有领域预设的 Init：预设特定的资源和关系 - 具有 saas-core 预设的 Init：多租户组织、成员资格、RBAC - 添加插件：文件、路由、环境变量、清单（V4.6 插件套件） - 生成资源：模块文件、ORM 模型、路由、验证 - 具有关系的生成：外键、ORM 包含 - 种子和工厂生成器（所有 3 种 ORM） - Drizzle：模式生成、客户端设置、代码生成 - Mongoose：模型生成、模式定义、连接 - 删除插件：文件 + 依赖项 + 清单清理 - 同步：文件恢复 - 医生：健康检查、所有权完整性 - 升级：迁移引擎、待处理检测、备份创建 - 回滚：备份列表、文件恢复、清单恢复 - 错误处理：未知插件、非空目录 --- ## 技术栈 | 层 | 技术 | |-------|------------| | CLI | Commander.js | | 提示 | Inquirer.js | | 模板 | Handlebars | | 进度条 | Ora | | 颜色 | Chalk | | 测试 | Vitest | | Linting | ESLint 9（扁平配置） | | 语言 | TypeScript（严格） | ### 生成的项目 | 层 | 技术 | |-------|------------| | 框架 | Express.js | | 语言 | TypeScript（严格） | | 数据库 | PostgreSQL | | ORM | Prisma / Drizzle / Mongoose | | 验证 | Zod | | 身份验证 | JWT 或 Clerk | | 支付 | Stripe | | 存储 | AWS S3 | | 文档 | Swagger/OpenAPI | | 日志 | Winston + Morgan | | 测试 | Vitest | | 部署 | Docker | --- ## BackGen 与替代方案 | 工具 | ORM 选择 | 身份验证 | 插件系统 | 预设 | 升级引擎 | 文档站点 | |------|-----------|------|---------------|---------|----------------|-----------| | **BackGen** | Prisma, Drizzle, Mongoose | JWT, Clerk | ◈ 7+ 插件 | 5 个领域 | ◈ 备份 + 回滚 | — | | NestJS CLI | 无（固定 NestJS） | 内置 | ◈ 模块 | — | — | ◈ | | Express 生成器 | 无（固定纯 JS） | — | — | — | — | — | | T3 堆栈 | Prisma | NextAuth | — | — | — | ◈ | | AdonisJS | Lucid ORM | 内置 | ◈ Ace | — | — | ◈ | | LoopBack | 内置 | 内置 | ◈ | — | — | ◈ | **关键区别：** - ◈ **可切换 ORM** — 通过清单更改 Prisma ↔ Drizzle ↔ Mongoose，而无需重写 - ◈ **领域预设** — 通过一个命令获取医疗保健、SaaS、电子商务、CRM、LMS - ◈ **升级引擎** — 版本化迁移 + 备份 + 回滚用于生成的项目 - ◈ **从第一天起支持多种 ORM** — 不局限于一种数据层 --- ## 路线图 | 版本 | 焦点 | 状态 | |---------|-------|--------| | V1 | 基础 | 完成 | | V2 | 插件系统 | 完成 | | V3 | 资源生成器 | 完成 | | V4 | 领域预设 | 完成 | | V4.5 | SaaS 基础知识 | 完成 | | V4.6 | 生产强化 | 完成 | | V4.6.1 | 基础强化默认开启 | 完成 | | V5 | 多 ORM（Prisma、Drizzle、Mongoose） | 完成 | | V6 | DevOps 和基础设施 | 完成 | | V6.1 | 所有权跟踪和医生 --fix | 完成 | | V6.2 | 升级引擎和迁移运行器 | 完成 | | V6.3 | 备份和回滚 | 完成 | | V6.4 | 插件迁移 | 完成 | | V7 | 升级润色和差异 | 进行中 | | V8 | 基于模式的开发 | 计划中 | | V9 | 企业功能 | 计划中 | | V10 | 插件作者 SDK | 计划中 | | V11 | 市场 | 计划中 | | V12 | AI 上下文层 | 计划中 | 查看 [docs/ROADMAP.md](docs/ROADMAP.md) 获取详细信息。 --- ## 许可证 MIT