115 lines
3.2 KiB
Markdown
115 lines
3.2 KiB
Markdown
# 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 作为后端框架
|
||
|
||
## 参考
|
||
|
||
- [Turborepo 官方文档](https://turbo.build/repo)
|
||
- [Monorepo vs Polyrepo](https://semaphoreci.com/blog/monorepo-vs-polyrepo)
|
||
- [pnpm workspaces](https://pnpm.io/workspaces)
|
||
|
||
---
|
||
|
||
> **变更记录**
|
||
> 2026-05-25: 初始创建，状态设为已接受
|