fischer
/
fischerX
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fischerX/docs/architecture/adr/0001-monorepo.md

3.2 KiB
Raw Blame History

ADR-0001: 采用 Monorepo 架构

项目 内容
状态 已接受
创建日期 2026-05-25
决策者 架构师
最后更新 2026-05-25

上下文

在项目启动阶段，需要决定代码仓库的组织方式。现代软件开发中有两种主流方式：

  • Monorepo（单体仓库）: 所有相关代码放在同一个仓库中
  • Polyrepo（多仓库）: 每个模块/服务独立一个仓库

决策

决定采用 Monorepo 架构，使用 Turborepo 作为构建工具。

理由

为什么选择 Monorepo

优势 说明
代码共享 前后端可以共享类型定义、工具函数、常量等
依赖管理 统一管理依赖版本，避免版本冲突
原子提交 跨模块的修改可以在同一个提交中完成
重构方便 跨项目重构更容易，IDE 支持更好
统一工具链 统一的构建、测试、lint 配置
团队协作 团队成员可以方便地查看和修改所有代码

为什么选择 Turborepo

优势 说明
增量构建 只重新构建变更的包，提升构建速度
任务并行 并行执行独立任务，充分利用多核 CPU
远程缓存 支持远程构建缓存，团队共享
简单易用 配置简单，开箱即用
生态完善 与 Next.js、NestJS 等框架集成良好

替代方案考虑

方案 1: Polyrepo（多仓库）

优势 劣势
权限控制更精细 代码共享困难
仓库体积小 依赖版本管理复杂
独立部署 跨模块修改困难
工具链配置重复

不选择理由: 项目初期模块间耦合度高，代码共享需求强烈，Polyrepo 会增加开发成本。

方案 2: Nx

优势 劣势
功能更强大 学习曲线陡峭
插件生态丰富 配置复杂
图形化界面 对于小型项目过于重型

不选择理由: Turborepo 更轻量，满足当前需求，Nx 对于当前项目过于复杂。

后果

正面后果

  • 开发效率提升，代码共享方便
  • 统一的代码规范和工具链
  • 跨模块重构更容易
  • 依赖版本统一管理

负面后果

  • 仓库体积会逐渐增大
  • 需要配置合理的代码组织方式
  • 需要学习 Turborepo 的使用
  • CI/CD 需要针对 Monorepo 优化

实现计划

  1. 使用 pnpm 作为包管理器（已配置）
  2. 使用 turborepo 作为构建工具（已配置）
  3. 目录结构遵循： 
    apps/          # 应用
  web/         # Web 应用
  admin/       # 管理后台
packages/      # 共享包
  core/        # 核心业务逻辑
  ui/          # UI 组件库
  utils/       # 工具函数
  types/       # 类型定义
services/      # 后端服务
  api/         # API 服务

相关决策

  • ADR-0002: 采用 Next.js 作为前端框架
  • ADR-0003: 采用 NestJS 作为后端框架

参考

变更记录
2026-05-25: 初始创建，状态设为已接受