# 通用项目架构模板

## 1️⃣ Python Web/API 项目标准结构

```
项目名称/
├── README.md                 # 项目说明文档
├── LICENSE                   # 开源协议
├── requirements.txt          # 依赖管理（pip）
├── pyproject.toml           # 现代Python项目配置（推荐）
├── setup.py                 # 包安装脚本（如果做成库）
├── .gitignore              # Git忽略文件
├── .env                    # 环境变量（不提交到Git）
├── .env.example            # 环境变量示例
├── CLAUDE.md              # claude持久上下文
├── AGENTS.md              # codex持久上下文
├── Sublime-Text.txt                   # 放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
│
├── docs/                   # 文档目录
│   ├── api.md             # API文档
│   ├── development.md     # 开发指南
│   └── architecture.md    # 架构说明
│
├── scripts/               # 脚本工具
│   ├── deploy.sh          # 部署脚本
│   ├── backup.sh          # 备份脚本
│   └── init_db.sh         # 数据库初始化
│
├── tests/                 # 测试代码
│   ├── __init__.py
│   ├── conftest.py        # pytest配置
│   ├── unit/              # 单元测试
│   ├── integration/       # 集成测试
│   └── test_config.py     # 配置测试
│
├── src/                   # 源代码（推荐方式）
│   ├── __init__.py
│   ├── main.py           # 程序入口
│   ├── app.py            # Flask/FastAPI应用
│   ├── config.py         # 配置管理
│   │
│   ├── core/             # 核心业务逻辑
│   │   ├── __init__.py
│   │   ├── models/       # 数据模型
│   │   ├── services/     # 业务服务
│   │   └── utils/        # 工具函数
│   │
│   ├── api/              # API接口层
│   │   ├── __init__.py
│   │   ├── v1/           # 版本1
│   │   └── dependencies.py
│   │
│   ├── data/             # 数据处理
│   │   ├── __init__.py
│   │   ├── repository/   # 数据访问层
│   │   └── migrations/   # 数据库迁移
│   │
│   └── external/         # 外部服务
│       ├── __init__.py
│       ├── clients/      # API客户端
│       └── integrations/ # 集成服务
│
├── logs/                  # 日志目录（不提交到Git）
│   ├── app.log
│   └── error.log
│
└── data/                  # 数据目录（不提交到Git）
    ├── raw/               # 原始数据
    ├── processed/         # 处理后的数据
    └── cache/             # 缓存
```

**使用场景**：Flask/FastAPI Web应用、RESTful API服务、Web后端

---

## 2️⃣ 数据科学/量化项目标准结构

```
项目名称/
├── README.md
├── LICENSE
├── requirements.txt
├── .gitignore
├── .env
├── .env.example
├── CLAUDE.md              # claude持久上下文
├── AGENTS.md              # codex持久上下文
├── Sublime-Text.txt                   # 放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
│
├── docs/                   # 文档目录
│   ├── notebooks/         # Jupyter文档
│   └── reports/           # 分析报告
│
├── notebooks/             # Jupyter Notebook
│   ├── 01_data_exploration.ipynb
│   ├── 02_feature_engineering.ipynb
│   └── 03_model_training.ipynb
│
├── scripts/               # 脚本工具
│   ├── train_model.py     # 训练脚本
│   ├── backtest.py        # 回测脚本
│   ├── collect_data.py    # 数据采集
│   └── deploy_model.py    # 模型部署
│
├── tests/                 # 测试
│   ├── test_data/
│   └── test_models/
│
├── configs/               # 配置文件
│   ├── model.yaml
│   ├── database.yaml
│   └── trading.yaml
│
├── src/                   # 源代码
│   ├── __init__.py
│   │
│   ├── data/              # 数据处理模块
│   │   ├── __init__.py
│   │   ├── collectors/    # 数据采集器
│   │   ├── processors/    # 数据清洗
│   │   ├── features/      # 特征工程
│   │   └── loaders.py     # 数据加载
│   │
│   ├── models/            # 模型模块
│   │   ├── __init__.py
│   │   ├── strategies/    # 交易策略
│   │   ├── backtest/      # 回测引擎
│   │   └── risk/          # 风险管理
│   │
│   ├── utils/             # 工具模块
│   │   ├── __init__.py
│   │   ├── logging.py     # 日志配置
│   │   ├── database.py    # 数据库工具
│   │   └── api_client.py  # API客户端
│   │
│   └── core/              # 核心模块
│       ├── __init__.py
│       ├── config.py      # 配置管理
│       ├── signals.py     # 信号生成
│       └── portfolio.py   # 投资组合
│
├── data/                  # 数据目录（Git忽略）
│   ├── raw/               # 原始数据
│   ├── processed/         # 处理后数据
│   ├── external/          # 外部数据
│   └── cache/             # 缓存
│
├── models/                # 模型文件（Git忽略）
│   ├── checkpoints/       # 检查点
│   └── exports/           # 导出模型
│
└── logs/                  # 日志（Git忽略）
    ├── trading.log
    └── errors.log
```

**使用场景**：量化交易、机器学习、数据分析、AI研究

---

## 3️⃣ Monorepo（多项目仓库）标准结构

```
项目名称-monorepo/
├── README.md
├── LICENSE
├── .gitignore
├── .gitmodules           # Git子模块
├── docker-compose.yml    # Docker编排
├── CLAUDE.md              # claude持久上下文
├── AGENTS.md              # codex持久上下文
├── Sublime-Text.txt                   # 这个是文件，放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
│
├── docs/                 # 全局文档
│   ├── architecture.md
│   └── deployment.md
│
├── scripts/              # 全局脚本
│   ├── build_all.sh
│   ├── test_all.sh
│   └── deploy.sh
│
├── backups/                 #  放备份文件
│   ├── archive/             #  放旧的备份文件
│   └── gz/                  #  放备份文件的gz
│
├── services/             # 微服务目录
│   │
│   ├── user-service/     # 用户服务
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   ├── src/
│   │   └── tests/
│   │
│   ├── trading-service/  # 交易服务
│   │   ├── Dockerfile
│   │   ├── requirements.txt
│   │   ├── src/
│   │   └── tests/
│   ...
│   └── data-service/     # 数据服务
│       ├── Dockerfile
│       ├── requirements.txt
│       ├── src/
│       └── tests/
│
├── libs/                 # 共享库
│   ├── common/           # 公共模块
│   │   ├── utils/
│   │   └── models/
│   ├── external/         # 第三方库（不可修改，只调用）
│   └── database/         # 数据库访问库
│
├── infrastructure/       # 基础设施
│   ├── terraform/        # 云资源定义
│   ├── kubernetes/       # K8s配置
│   └── nginx/            # 反向代理配置
│
└── monitoring/           # 监控系统
    ├── prometheus/       # 指标收集
    ├── grafana/          # 可视化
    └── alertmanager/     # 告警
```

**使用场景**：微服务架构、大型项目、团队协作

---

## 4️⃣ Full-Stack Web 应用标准结构

```
项目名称/
├── README.md
├── LICENSE
├── .gitignore
├── docker-compose.yml    # 前后端一起编排
├── CLAUDE.md              # claude持久上下文
├── AGENTS.md              # codex持久上下文
├── Sublime-Text.txt                   # 放需求和注意事项，给自己看的，和cli的会话恢复指令^_^
│
├── frontend/             # 前端目录
│   ├── public/           # 静态资源
│   ├── src/              # 源码
│   │   ├── components/   # React/Vue组件
│   │   ├── pages/        # 页面
│   │   ├── store/        # 状态管理
│   │   └── utils/        # 工具
│   ├── package.json      # NPM依赖
│   └── vite.config.js    # 构建配置
│
└── backend/              # 后端目录
    ├── requirements.txt
    ├── Dockerfile
    ├── src/
    │   ├── api/          # API接口
    │   ├── core/         # 业务逻辑
│   │   └── models/       # 数据模型
    └── tests/
```

**使用场景**：全栈应用、SPA单页应用、前后端分离项目

---

## 📌 核心设计原则

### 1. 关注点分离（Separation of Concerns）
```
API → 服务 → 数据访问 → 数据库
一目了然，层级清晰
```

### 2. 可测试性（Testability）
```
每个模块可独立测试
依赖可mock
```

### 3. 可配置性（Configurability）
```
配置与代码分离
环境变量 > 配置文件 > 默认值
```

### 4. 可维护性（Maintainability）
```
代码自解释
合理的文件命名
清晰的目录结构
```

### 5. 版本控制友好（Git-Friendly）
```
data/、logs/、models/ 添加到 .gitignore
只提交源代码和配置示例
```

---

## 🎯 最佳实践建议

1. **使用 `src/` 目录**：把源代码放在专门的src目录，避免顶级目录混乱
2. **相对导入**：统一使用 `from src.module import thing` 的导入方式
3. **测试覆盖**：保证核心业务逻辑有单元测试和集成测试
4. **文档先行**：重要模块都要写README.md说明
5. **环境隔离**：使用virtualenv或conda创建独立环境
6. **依赖明确**：所有依赖都写入requirements.txt，并锁定版本
7. **配置管理**：使用环境变量 + 配置文件的组合方式
8. **日志分级**：DEBUG、INFO、WARNING、ERROR、FATAL
9. **错误处理**：不要吞掉异常，要有完整的错误链
10. **代码规范**：使用black格式化，flake8检查

---

## 🔥 .gitignore 推荐模板

```gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
*.egg-info/
dist/
build/

# 环境
.env
.venv/
env/
venv/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# 数据
data/
*.csv
*.json
*.db
*.sqlite
*.duckdb

# 日志
logs/
*.log

# 模型
models/
*.h5
*.pkl

# 临时文件
tmp/
temp/
*.tmp
.DS_Store
```

---

## 📚 技术选型参考

| 场景 | 推荐技术栈 |
|-----|----------|
| Web API | FastAPI + Pydantic + SQLAlchemy |
| 数据处理 | Pandas + NumPy + Polars |
| 机器学习 | Scikit-learn + XGBoost + LightGBM |
| 深度学习 | PyTorch + TensorFlow |
| 数据库 | PostgreSQL + Redis |
| 消息队列 | RabbitMQ / Kafka |
| 任务队列 | Celery |
| 监控 | Prometheus + Grafana |
| 部署 | Docker + Docker Compose |
| CI/CD | GitHub Actions / GitLab CI |

---

## 📝 文件模板示例

### requirements.txt
```txt
# 核心依赖
fastapi==0.104.1
uvicorn[standard]==0.24.0
pydantic==2.5.0

# 数据库
sqlalchemy==2.0.23
alembic==1.12.1
psycopg2-binary==2.9.9

# 测试
pytest==7.4.3
pytest-cov==4.1.0
pytest-asyncio==0.21.1

# 工具
python-dotenv==1.0.0
loguru==0.7.2

# 开发（可选）
black==23.11.0
flake8==6.1.0
mypy==1.7.1
```

### pyproject.toml（现代Python项目推荐）
```toml
[project]
name = "项目名称"
version = "0.1.0"
description = "项目描述"
authors = [{name = "作者", email = "邮箱@example.com"}]
dependencies = [
    "fastapi>=0.104.0",
    "uvicorn[standard]>=0.24.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = ["pytest", "black", "flake8", "mypy"]

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"
```

---

## ✅ 新项目检查清单

启动新项目时，确保完成以下事项：

- [ ] 创建README.md，包含项目简介和使用说明
- [ ] 创建LICENSE文件，明确开源协议
- [ ] 设置Python虚拟环境（venv/conda）
- [ ] 创建requirements.txt并锁定依赖版本
- [ ] 创建.gitignore，排除敏感和不必要的文件
- [ ] 创建.env.example，说明需要的环境变量
- [ ] 设计目录结构，符合关注点分离原则
- [ ] 创建基础的配置文件
- [ ] 设置代码格式化工具（black）
- [ ] 设置代码检查工具（flake8/ruff）
- [ ] 编写第一个测试用例
- [ ] 设置Git仓库并提交初始代码
- [ ] 创建CHANGELOG.md，记录版本变更

---

在**编程 / 软件开发**里，**项目架构（Project Architecture / Software Architecture）**指的是：

> **一个项目在“整体层面”是如何被拆分、组织、通信和演进的设计方案**
> ——它决定了代码怎么分层、模块怎么分工、数据怎么流动、系统如何扩展和维护。

---

## 一句话理解

**项目架构 = 不写具体业务代码之前，就先决定“代码怎么放、模块怎么连、职责怎么分”。**

---

## 一、项目架构主要解决什么问题？

项目架构不是“写代码的技巧”，而是解决这些**更高层问题**：

* 📦 代码怎么组织才不乱？
* 🔁 模块之间怎么通信？
* 🧱 哪些地方可以独立修改而不影响全局？
* 🚀 项目以后怎么扩展？
* 🧪 如何方便测试、调试、部署？
* 👥 多人协作如何不互相踩代码？

---

## 二、项目架构一般包含哪些内容？

### 1️⃣ 目录结构（最直观）

```text
project/
├── src/
│   ├── main/
│   ├── services/
│   ├── models/
│   ├── utils/
│   └── config/
├── tests/
├── docs/
└── README.md
```

👉 决定 **“不同类型代码放哪里”**

---

### 2️⃣ 分层设计（核心）

最常见的是 **分层架构（Layered Architecture）**：

```text
表示层（UI / API）
   ↓
业务逻辑层（Service）
   ↓
数据访问层（DAO / Repository）
   ↓
数据库 / 外部系统
```

**规则：**

* 上层可以调用下层
* 下层不能反过来依赖上层

---

### 3️⃣ 模块划分（职责边界）

比如一个交易系统：

```text
- market_data   # 行情
- strategy      # 策略
- risk          # 风控
- order         # 下单
- account       # 账户
```

👉 每个模块：

* 只做一类事情
* 尽量低耦合、高内聚

---

### 4️⃣ 数据与控制流

* 数据从哪里来？
* 谁负责处理？
* 谁负责存储？
* 谁负责对外输出？

例如：

```text
WebSocket → 数据清洗 → 指标计算 → AI评分 → SQLite → API → 前端
```

---

### 5️⃣ 技术选型（架构的一部分）

* 编程语言（Python / Java / Go）
* 框架（FastAPI / Spring / Django）
* 通信方式（HTTP / WebSocket / MQ）
* 存储（SQLite / Redis / PostgreSQL）
* 部署（本地 / Docker / 云）

---

## 三、常见项目架构类型（入门必懂）

### 1️⃣ 单体架构（Monolith）

```text
一个项目，一个进程
```

**适合：**

* 个人项目
* 原型
* 小系统

**优点：**

* 简单
* 好调试

**缺点：**

* 后期难扩展

---

### 2️⃣ 分层架构（最常见）

```text
Controller → Service → Repository
```

**适合：**

* Web 后端
* 业务系统

---

### 3️⃣ 模块化架构

```text
core + plugins
```

**适合：**

* 可插拔系统
* 策略 / 指标系统

👉 **你做量化、AI分析，非常适合这个**

---

### 4️⃣ 微服务架构（进阶）

```text
每个服务一个独立进程 + API 通信
```

**适合：**

* 大团队
* 高并发
* 长期演进

❌ **新手不建议一开始用**

---

## 四、用一个“真实例子”理解（贴近你现在做的）

假设你做 **币安永续 AI 分析系统**：

```text
backend/
├── data/
│   └── binance_ws.py        # 行情订阅
├── indicators/
│   └── vpvr.py
├── strategy/
│   └── signal_score.py
├── storage/
│   └── sqlite_writer.py
├── api/
│   └── http_server.py
└── main.py
```

这就是**项目架构设计**：

* 每个文件夹只负责一件事
* 可替换、可测试
* 后面想接 Telegram Bot / Web 前端都不用重写核心

---

## 五、初学者常见误区 ⚠️

❌ 一开始就搞微服务
❌ 所有代码写在一个文件
❌ 架构追求“高级感”，而不是“可维护”
❌ 没想清楚数据流就开始写

---

## 六、学习路线建议（很重要）

你现在学 CS，很推荐这个顺序：

1. **先写能跑的项目（不完美）**
2. **代码开始乱 → 才学架构**
3. 学会：

   * 模块拆分
   * 分层
   * 依赖方向
4. 再学：

   * 设计模式
   * 微服务 / 消息队列

---

**版本**: 1.0
**更新日期**: 2025-11-24
**维护**: CLAUDE，CODEX，KIMI
