361 lines
7.5 KiB
Markdown
361 lines
7.5 KiB
Markdown
# 开发者指南
|
||
|
||
本文档提供了ArticleReplaceBatch项目的开发者指南。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [开发环境搭建](#开发环境搭建)
|
||
- [项目结构](#项目结构)
|
||
- [代码规范](#代码规范)
|
||
- [测试指南](#测试指南)
|
||
- [贡献指南](#贡献指南)
|
||
- [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 开发环境搭建
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd ArticleReplaceBatch
|
||
```
|
||
|
||
### 2. 创建虚拟环境
|
||
|
||
```bash
|
||
# 使用venv
|
||
python -m venv venv
|
||
|
||
# Windows
|
||
venv\Scripts\activate
|
||
|
||
# Linux/Mac
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### 3. 安装依赖
|
||
|
||
```bash
|
||
# 安装核心依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 安装开发依赖
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
### 4. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填写必要的配置
|
||
```
|
||
|
||
### 5. 验证安装
|
||
|
||
```bash
|
||
# 运行测试
|
||
python dev.py test
|
||
|
||
# 检查代码
|
||
python dev.py lint
|
||
```
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ArticleReplaceBatch/
|
||
├── src/ # 源代码
|
||
│ ├── ui/ # UI组件
|
||
│ │ ├── __init__.py
|
||
│ │ ├── main_window.py # 主窗口
|
||
│ │ ├── main_frame.py # 主页面
|
||
│ │ ├── config_frame.py # 配置页面
|
||
│ │ ├── disclaimer_frame.py # 免责声明
|
||
│ │ └── log_handler.py # 日志处理器
|
||
│ ├── services/ # 服务层
|
||
│ │ ├── __init__.py
|
||
│ │ ├── web_scraping.py # 网页抓取服务
|
||
│ │ ├── image_processing.py # 图片处理服务
|
||
│ │ └── ai_service.py # AI服务
|
||
│ └── utils/ # 工具
|
||
│ ├── __init__.py
|
||
│ └── validation.py # 数据验证
|
||
├── tests/ # 测试
|
||
│ ├── __init__.py
|
||
│ ├── conftest.py # pytest配置
|
||
│ ├── test_config.py # 配置测试
|
||
│ ├── test_main_process.py # 主流程测试
|
||
│ ├── test_images_edit.py # 图片处理测试
|
||
│ ├── test_config_manager.py # 配置管理器测试
|
||
│ ├── test_ui.py # UI测试
|
||
│ ├── test_integration.py # 集成测试
|
||
│ ├── test_services.py # 服务测试
|
||
│ └── test_performance.py # 性能测试
|
||
├── scripts/ # 开发脚本
|
||
│ ├── __init__.py
|
||
│ ├── format_code.py # 代码格式化
|
||
│ └── run_tests.py # 测试运行
|
||
├── docs/ # 文档
|
||
│ └── API.md # API文档
|
||
├── examples/ # 示例
|
||
│ └── sample_data.json # 示例数据
|
||
├── archive/ # 备份归档
|
||
├── backups/ # 备份文件
|
||
├── logs/ # 日志文件
|
||
├── .env.example # 环境变量模板
|
||
├── .gitignore # Git配置
|
||
├── pyproject.toml # 项目配置
|
||
├── requirements.txt # 依赖列表
|
||
├── config_manager.py # 配置管理器
|
||
├── cli.py # 命令行接口
|
||
├── dev.py # 开发工具
|
||
├── ArticleReplace.py # GUI应用
|
||
├── README.md # 项目说明
|
||
├── CHANGELOG.md # 更新日志
|
||
└── DEVELOPER_GUIDE.md # 开发者指南
|
||
```
|
||
|
||
---
|
||
|
||
## 代码规范
|
||
|
||
### Python代码风格
|
||
|
||
项目遵循以下代码风格指南：
|
||
|
||
1. **PEP 8**: Python代码风格指南
|
||
2. **类型提示**: 使用类型注解
|
||
3. **文档字符串**: 使用docstring
|
||
4. **命名规范**: 遵循PEP 8命名约定
|
||
|
||
### 格式化工具
|
||
|
||
```bash
|
||
# 格式化代码
|
||
python dev.py format
|
||
|
||
# 或分别运行
|
||
black .
|
||
isort .
|
||
```
|
||
|
||
### 代码检查
|
||
|
||
```bash
|
||
# 代码检查
|
||
python dev.py lint
|
||
|
||
# 类型检查
|
||
python dev.py typecheck
|
||
```
|
||
|
||
### 命名约定
|
||
|
||
- **类名**: PascalCase（如`WebScrapingService`）
|
||
- **函数名**: snake_case（如`extract_content`）
|
||
- **常量名**: UPPER_CASE（如`MAX_THREADS`）
|
||
- **私有变量**: _leading_underscore（如`_config`）
|
||
|
||
---
|
||
|
||
## 测试指南
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
python dev.py test
|
||
|
||
# 运行特定测试
|
||
pytest tests/test_config.py -v
|
||
|
||
# 生成覆盖率报告
|
||
pytest tests/ --cov=. --cov-report=html
|
||
```
|
||
|
||
### 编写测试
|
||
|
||
测试文件应放在`tests/`目录下，命名为`test_*.py`。
|
||
|
||
```python
|
||
import pytest
|
||
from src.services.web_scraping import WebScrapingService
|
||
|
||
class TestWebScrapingService:
|
||
"""测试网页抓取服务"""
|
||
|
||
def test_service_creation(self):
|
||
"""测试创建服务"""
|
||
service = WebScrapingService(max_workers=5)
|
||
assert service.max_workers == 5
|
||
|
||
def test_extract_content(self):
|
||
"""测试提取内容"""
|
||
from unittest.mock import patch
|
||
|
||
service = WebScrapingService()
|
||
|
||
with patch('src.services.web_scraping.extract_content_with_retry') as mock:
|
||
mock.return_value = ("标题", "内容", [])
|
||
|
||
results = service.extract_content_async(["http://example.com"])
|
||
|
||
assert len(results) == 1
|
||
```
|
||
|
||
### 测试覆盖率
|
||
|
||
目标测试覆盖率：> 70%
|
||
|
||
```bash
|
||
# 查看覆盖率报告
|
||
pytest tests/ --cov=. --cov-report=term-missing
|
||
```
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
### 提交代码
|
||
|
||
1. 确保代码通过所有测试
|
||
2. 确保代码通过格式检查
|
||
3. 更新相关文档
|
||
4. 提交Pull Request
|
||
|
||
### Commit Message格式
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
**Type:**
|
||
- `feat`: 新功能
|
||
- `fix`: 修复bug
|
||
- `docs`: 文档更新
|
||
- `style`: 代码格式（不影响功能）
|
||
- `refactor`: 重构
|
||
- `test`: 测试相关
|
||
- `chore`: 构建/工具相关
|
||
|
||
**示例：**
|
||
```
|
||
feat(services): 添加批量图片处理功能
|
||
|
||
- 新增ImageProcessingService类
|
||
- 支持异步处理多个图片
|
||
- 添加进度回调功能
|
||
|
||
Closes #123
|
||
```
|
||
|
||
### Pull Request流程
|
||
|
||
1. Fork项目
|
||
2. 创建特性分支
|
||
3. 提交更改
|
||
4. 推送到分支
|
||
5. 创建Pull Request
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何添加新的AI服务？
|
||
|
||
A: 在`src/services/ai_service.py`中创建新的服务类，继承`AIService`基类。
|
||
|
||
```python
|
||
class CustomAIService(AIService):
|
||
def __init__(self):
|
||
super().__init__("custom")
|
||
|
||
def call(self, parameters):
|
||
# 实现自定义AI调用
|
||
pass
|
||
```
|
||
|
||
### Q: 如何添加新的UI组件？
|
||
|
||
A: 在`src/ui/`中创建新的模块，然后在`main_window.py`中引入使用。
|
||
|
||
### Q: 如何调试问题？
|
||
|
||
A: 使用日志系统，设置日志级别为DEBUG。
|
||
|
||
```python
|
||
import logging
|
||
logging.basicConfig(level=logging.DEBUG)
|
||
```
|
||
|
||
### Q: 如何打包应用？
|
||
|
||
A: 使用PyInstaller。
|
||
|
||
```bash
|
||
python dev.py build
|
||
```
|
||
|
||
### Q: 性能优化建议？
|
||
|
||
A:
|
||
1. 使用异步处理
|
||
2. 添加缓存机制
|
||
3. 批量处理数据
|
||
4. 优化数据库查询
|
||
|
||
---
|
||
|
||
## 开发工具
|
||
|
||
### dev.py
|
||
|
||
统一的开发工具入口。
|
||
|
||
```bash
|
||
# 查看帮助
|
||
python dev.py --help
|
||
|
||
# 可用命令
|
||
python dev.py format # 格式化代码
|
||
python dev.py test # 运行测试
|
||
python dev.py lint # 代码检查
|
||
python dev.py typecheck # 类型检查
|
||
python dev.py build # 打包应用
|
||
python dev.py clean # 清理构建
|
||
```
|
||
|
||
---
|
||
|
||
## 资源链接
|
||
|
||
- [Python文档](https://docs.python.org/3/)
|
||
- [pytest文档](https://docs.pytest.org/)
|
||
- [CustomTkinter文档](https://customtkinter.com/)
|
||
- [项目CHANGELOG](../CHANGELOG.md)
|
||
- [API文档](./API.md)
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
如有问题，请通过以下方式联系：
|
||
- 提交Issue
|
||
- 发送Pull Request
|
||
- 联系项目维护者
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**最后更新**: 2026-03-07
|
||
**维护者**: opencode |