124 lines
3.1 KiB
Markdown
124 lines
3.1 KiB
Markdown
|
# Python 项目模板
|
|||
|
|
|
|||
|
|
一个标准化的 Python 项目开发模板，集成了配置管理、日志系统和 Pydantic 数据验证。
|
|||
|
|
|
|||
|
|
## 特性
|
|||
|
|
|
|||
|
|
- 🔧 **配置管理**: 基于 YAML 的配置文件，使用 Pydantic 进行数据验证
|
|||
|
|
- 📝 **日志系统**: 集成 Loguru，支持控制台和文件输出，自动轮转和压缩
|
|||
|
|
- 🏗️ **标准结构**: 清晰的项目目录结构，便于维护和扩展
|
|||
|
|
- ✅ **类型安全**: 使用 Pydantic 模型确保配置数据的类型安全
|
|||
|
|
- 🔄 **单例模式**: 日志管理器采用单例模式，确保全局唯一实例
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
├── config/ # 配置文件
|
|||
|
|
│ └── config.yaml # 主配置文件
|
|||
|
|
├── examples/ # 使用示例
|
|||
|
|
│ ├── example_config_loader.py
|
|||
|
|
│ └── example_logger.py
|
|||
|
|
├── src/ # 源代码
|
|||
|
|
│ ├── core/ # 核心功能模块
|
|||
|
|
│ ├── models/ # 数据模型
|
|||
|
|
│ │ ├── __init__.py
|
|||
|
|
│ │ └── config_models.py # 配置数据模型
|
|||
|
|
│ ├── modules/ # 业务模块
|
|||
|
|
│ └── utils/ # 工具类
|
|||
|
|
│ ├── config_loader.py # 配置加载器
|
|||
|
|
│ └── logger.py # 日志管理器
|
|||
|
|
├── tmp/ # 临时文件
|
|||
|
|
│ └── log/ # 日志文件
|
|||
|
|
├── main.py # 程序入口
|
|||
|
|
├── pyproject.toml # 项目配置
|
|||
|
|
└── README.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
### 环境要求
|
|||
|
|
|
|||
|
|
- Python >= 3.12
|
|||
|
|
- uv (推荐) 或 pip
|
|||
|
|
|
|||
|
|
### 安装依赖
|
|||
|
|
|
|||
|
|
使用 uv (推荐):
|
|||
|
|
```bash
|
|||
|
|
uv sync
|
|||
|
|
pre-commit install # 可选
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
或使用 pip:
|
|||
|
|
```bash
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 运行项目
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python main.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心组件
|
|||
|
|
|
|||
|
|
### 1. 配置管理
|
|||
|
|
|
|||
|
|
配置系统使用 Pydantic 进行数据验证，确保配置的正确性。
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from src.utils.config_loader import get_config_loader
|
|||
|
|
|
|||
|
|
# 获取配置加载器
|
|||
|
|
loader = get_config_loader()
|
|||
|
|
|
|||
|
|
# 验证并加载配置
|
|||
|
|
config = loader.validate_config()
|
|||
|
|
|
|||
|
|
# 获取日志配置
|
|||
|
|
log_config = loader.get_log_config()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 日志系统
|
|||
|
|
|
|||
|
|
基于 Loguru 的日志系统，支持多种输出格式和自动轮转。
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from src.utils.logger import get_logger
|
|||
|
|
|
|||
|
|
# 获取日志记录器
|
|||
|
|
logger = get_logger("MODULE_NAME")
|
|||
|
|
|
|||
|
|
# 记录日志
|
|||
|
|
logger.info("这是一条信息日志")
|
|||
|
|
logger.error("这是一条错误日志")
|
|||
|
|
```
|
|||
|
|
## 开发
|
|||
|
|
|
|||
|
|
### 添加新模块
|
|||
|
|
|
|||
|
|
1. 在 `src/modules/` 下创建新的业务模块
|
|||
|
|
2. 在 `src/core/` 下添加核心功能
|
|||
|
|
3. 在 `src/utils/` 下添加工具函数
|
|||
|
|
|
|||
|
|
### 添加新配置
|
|||
|
|
|
|||
|
|
1. 在 `src/models/config_models.py` 中定义新的配置模型
|
|||
|
|
2. 在 `config/config.yaml` 中添加对应配置
|
|||
|
|
3. 更新配置加载器以支持新配置
|
|||
|
|
|
|||
|
|
### 日志使用规范
|
|||
|
|
|
|||
|
|
- 使用有意义的模块标签: `get_logger("API")`, `get_logger("DATABASE")`
|
|||
|
|
- 合理使用日志级别: DEBUG < INFO < WARNING < ERROR < CRITICAL
|
|||
|
|
- 记录关键操作和错误信息
|
|||
|
|
|
|||
|
|
### 代码风格
|
|||
|
|
|
|||
|
|
遵循 PEP 8 代码风格指南，保持代码整洁和一致性。基于ruff进行代码检查和格式化。
|
|||
|
|
|
|||
|
|
|
|||
|
|
## 作者
|
|||
|
|
|
|||
|
|
wds @ (wdsnpshy@163.com)
|