# 通用项目架构模板 ## 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持久上下文 ├── .日志 # 放需求和注意事项，给自己看的，和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持久上下文 ├── .日志 # 放需求和注意事项，给自己看的，和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持久上下文 ├── .日志 # 这个是文件，放需求和注意事项，给自己看的，和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持久上下文 ├── .日志 # 放需求和注意事项，给自己看的，和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，记录版本变更 --- **版本**: 1.0 **更新日期**: 2025-11-24 **维护**: CLAUDE，CODEX，KIMI