refactor: restructure project to modern Python layout, separate src, tests, docs, examples
This commit is contained in:
204
PROJECT_STRUCTURE.md
Normal file
204
PROJECT_STRUCTURE.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# Config-Man 项目结构
|
||||
|
||||
## 概述
|
||||
|
||||
Config-Man 项目采用现代Python项目标准结构，将源代码、测试、文档和示例分开组织，便于维护和扩展。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
config-man/
|
||||
├── src/ # 源代码目录
|
||||
│ └── config_man/ # 主包
|
||||
│ ├── __init__.py # 包初始化文件
|
||||
│ ├── cli/ # CLI模块
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── main.py # CLI主程序
|
||||
│ ├── core/ # 核心功能模块
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── config_manager.py # 配置管理器
|
||||
│ │ ├── display_manager.py # 显示管理器
|
||||
│ │ └── view_command.py # 查看命令处理器
|
||||
│ └── utils/ # 工具模块
|
||||
│ ├── __init__.py
|
||||
│ ├── crypto.py # 加密解密工具
|
||||
│ └── mock_rclone.py # 模拟rclone环境
|
||||
├── tests/ # 测试目录
|
||||
│ ├── __init__.py
|
||||
│ ├── unit/ # 单元测试
|
||||
│ │ └── __init__.py
|
||||
│ ├── integration/ # 集成测试
|
||||
│ │ └── __init__.py
|
||||
│ └── fixtures/ # 测试工具和数据
|
||||
│ ├── __init__.py
|
||||
│ ├── test_configs.py # 测试配置生成器
|
||||
│ └── test_data/ # 测试数据目录
|
||||
├── docs/ # 文档目录
|
||||
│ ├── README.md # 文档说明
|
||||
│ ├── USAGE.md # 使用说明
|
||||
│ ├── progress-tracker.md # 进度跟踪
|
||||
│ ├── requirements.md # 需求文档
|
||||
│ └── workplan.md # 工作计划
|
||||
├── examples/ # 示例目录
|
||||
│ └── basic_usage.py # 基本使用示例
|
||||
├── main.py # 主入口文件
|
||||
├── pyproject.toml # 项目配置文件
|
||||
├── README.md # 项目主文档
|
||||
├── .gitignore # Git忽略文件
|
||||
└── PROJECT_STRUCTURE.md # 项目结构说明（本文件）
|
||||
```
|
||||
|
||||
## 模块说明
|
||||
|
||||
### 源代码模块 (src/config_man/)
|
||||
|
||||
#### CLI模块 (cli/)
|
||||
- **main.py**: CLI主程序，包含所有命令行命令的定义
|
||||
- 使用Click框架实现命令行界面
|
||||
- 支持view、suggest-update、force-update等命令
|
||||
|
||||
#### 核心模块 (core/)
|
||||
- **config_manager.py**: 配置管理器，负责文件下载、解密、比较等核心功能
|
||||
- **display_manager.py**: 显示管理器，负责格式化输出和表格显示
|
||||
- **view_command.py**: 查看命令处理器，实现查看功能的核心逻辑
|
||||
|
||||
#### 工具模块 (utils/)
|
||||
- **crypto.py**: 加密解密工具，提供DES加密解密功能
|
||||
- **mock_rclone.py**: 模拟rclone环境，用于测试和开发
|
||||
|
||||
### 测试模块 (tests/)
|
||||
|
||||
#### 单元测试 (unit/)
|
||||
- 测试各个模块的独立功能
|
||||
- 测试边界条件和错误处理
|
||||
|
||||
#### 集成测试 (integration/)
|
||||
- 测试模块间的集成功能
|
||||
- 测试完整的工作流程
|
||||
|
||||
#### 测试工具 (fixtures/)
|
||||
- **test_configs.py**: 测试配置生成器
|
||||
- **test_data/**: 测试数据目录，包含模拟的配置文件
|
||||
|
||||
### 文档模块 (docs/)
|
||||
- 包含所有项目文档
|
||||
- 使用说明、需求文档、工作计划等
|
||||
|
||||
### 示例模块 (examples/)
|
||||
- 提供使用示例和代码示例
|
||||
- 帮助用户快速上手
|
||||
|
||||
## 设计原则
|
||||
|
||||
### 1. 分离关注点
|
||||
- **源代码**: 只包含业务逻辑
|
||||
- **测试**: 独立的测试代码和数据
|
||||
- **文档**: 完整的使用和开发文档
|
||||
- **示例**: 实际的使用示例
|
||||
|
||||
### 2. 模块化设计
|
||||
- 每个模块职责单一
|
||||
- 模块间依赖关系清晰
|
||||
- 便于独立测试和维护
|
||||
|
||||
### 3. 可扩展性
|
||||
- 新功能可以轻松添加到对应模块
|
||||
- 测试可以独立添加
|
||||
- 文档结构清晰，便于更新
|
||||
|
||||
### 4. 标准化
|
||||
- 遵循Python项目标准结构
|
||||
- 使用现代Python工具链
|
||||
- 支持pip安装和开发模式
|
||||
|
||||
## 开发工作流
|
||||
|
||||
### 1. 开发新功能
|
||||
```bash
|
||||
# 在src/config_man/对应模块中添加代码
|
||||
# 在tests/对应目录中添加测试
|
||||
# 在docs/中添加文档
|
||||
# 在examples/中添加示例
|
||||
```
|
||||
|
||||
### 2. 运行测试
|
||||
```bash
|
||||
# 运行所有测试
|
||||
pytest
|
||||
|
||||
# 运行单元测试
|
||||
pytest tests/unit/
|
||||
|
||||
# 运行集成测试
|
||||
pytest tests/integration/
|
||||
|
||||
# 生成覆盖率报告
|
||||
pytest --cov=src/config_man
|
||||
```
|
||||
|
||||
### 3. 代码质量检查
|
||||
```bash
|
||||
# 代码格式化
|
||||
black src/ tests/
|
||||
|
||||
# 类型检查
|
||||
mypy src/
|
||||
|
||||
# 代码检查
|
||||
flake8 src/ tests/
|
||||
```
|
||||
|
||||
### 4. 安装和发布
|
||||
```bash
|
||||
# 开发模式安装
|
||||
pip install -e .
|
||||
|
||||
# 构建包
|
||||
python -m build
|
||||
|
||||
# 发布到PyPI
|
||||
twine upload dist/
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 导入路径
|
||||
- 使用相对导入在包内部
|
||||
- 使用绝对导入从外部访问
|
||||
- 避免循环导入
|
||||
|
||||
### 2. 测试组织
|
||||
- 单元测试测试独立功能
|
||||
- 集成测试测试模块协作
|
||||
- 使用fixtures提供测试数据
|
||||
|
||||
### 3. 文档维护
|
||||
- 代码和文档同步更新
|
||||
- 提供完整的使用示例
|
||||
- 保持文档结构清晰
|
||||
|
||||
### 4. 版本控制
|
||||
- 合理的.gitignore配置
|
||||
- 清晰的提交信息
|
||||
- 版本号管理
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 添加新功能
|
||||
1. 在`src/config_man/core/`中添加核心逻辑
|
||||
2. 在`src/config_man/cli/main.py`中添加CLI命令
|
||||
3. 在`tests/`中添加对应测试
|
||||
4. 在`docs/`中更新文档
|
||||
5. 在`examples/`中添加使用示例
|
||||
|
||||
### 添加新工具
|
||||
1. 在`src/config_man/utils/`中添加工具函数
|
||||
2. 在`tests/unit/`中添加单元测试
|
||||
3. 在`docs/`中添加使用说明
|
||||
|
||||
### 添加新测试
|
||||
1. 根据测试类型选择`tests/unit/`或`tests/integration/`
|
||||
2. 使用`tests/fixtures/`中的测试数据
|
||||
3. 遵循pytest最佳实践
|
||||
|
||||
这种项目结构确保了代码的可维护性、可测试性和可扩展性，符合现代Python项目的标准。
|
||||
Reference in New Issue
Block a user