tech
9eddb3133c
- 修复CDN URL构建，正确处理路径重复问题
- 修复rclone路径构建，使用正确的格式: {rclone_remote}:{storage_path}/{version_path}/{filename}
- 修复CDN路径构建，使用正确的格式: {cdn_base_url}/{version_path}/{filename}
- 修复CDN内容解密处理，支持加密和解密后的内容
- 添加路径构建测试示例
- 完善错误处理和空内容处理
205 lines
5.8 KiB
Markdown
205 lines
5.8 KiB
Markdown
# 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 # 项目配置文件
|
||
├── config-man.json # 配置文件
|
||
├── 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项目的标准。 |