696 lines
17 KiB
Markdown
696 lines
17 KiB
Markdown
# 通用项目架构模板
|
||
|
||
## 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/
|
||
│
|
||
├── assets/ # 资产中心
|
||
│ ├── common/ # 公共模块
|
||
│ │ ├── utils/
|
||
│ │ └── models/
|
||
│ ├── repo/ # 外部仓库中心（不可修改，只调用）
|
||
│ └── 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
|