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
|