7.5 KiB
7.5 KiB
开发者指南
本文档提供了ArticleReplaceBatch项目的开发者指南。
目录
开发环境搭建
1. 克隆项目
git clone <repository-url>
cd ArticleReplaceBatch
2. 创建虚拟环境
# 使用venv
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
3. 安装依赖
# 安装核心依赖
pip install -r requirements.txt
# 安装开发依赖
pip install -e ".[dev]"
4. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写必要的配置
5. 验证安装
# 运行测试
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代码风格
项目遵循以下代码风格指南：
- PEP 8: Python代码风格指南
- 类型提示: 使用类型注解
- 文档字符串: 使用docstring
- 命名规范: 遵循PEP 8命名约定
格式化工具
# 格式化代码
python dev.py format
# 或分别运行
black .
isort .
代码检查
# 代码检查
python dev.py lint
# 类型检查
python dev.py typecheck
命名约定
- 类名: PascalCase（如
WebScrapingService） - 函数名: snake_case（如
extract_content） - 常量名: UPPER_CASE（如
MAX_THREADS） - 私有变量: _leading_underscore（如
_config）
测试指南
运行测试
# 运行所有测试
python dev.py test
# 运行特定测试
pytest tests/test_config.py -v
# 生成覆盖率报告
pytest tests/ --cov=. --cov-report=html
编写测试
测试文件应放在tests/目录下，命名为test_*.py。
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%
# 查看覆盖率报告
pytest tests/ --cov=. --cov-report=term-missing
贡献指南
提交代码
- 确保代码通过所有测试
- 确保代码通过格式检查
- 更新相关文档
- 提交Pull Request
Commit Message格式
<type>(<scope>): <subject>
<body>
<footer>
Type:
feat: 新功能fix: 修复bugdocs: 文档更新style: 代码格式（不影响功能）refactor: 重构test: 测试相关chore: 构建/工具相关
示例：
feat(services): 添加批量图片处理功能
- 新增ImageProcessingService类
- 支持异步处理多个图片
- 添加进度回调功能
Closes #123
Pull Request流程
- Fork项目
- 创建特性分支
- 提交更改
- 推送到分支
- 创建Pull Request
常见问题
Q: 如何添加新的AI服务？
A: 在src/services/ai_service.py中创建新的服务类，继承AIService基类。
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。
import logging
logging.basicConfig(level=logging.DEBUG)
Q: 如何打包应用？
A: 使用PyInstaller。
python dev.py build
Q: 性能优化建议？
A:
- 使用异步处理
- 添加缓存机制
- 批量处理数据
- 优化数据库查询
开发工具
dev.py
统一的开发工具入口。
# 查看帮助
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 # 清理构建
资源链接
联系方式
如有问题，请通过以下方式联系：
- 提交Issue
- 发送Pull Request
- 联系项目维护者
文档版本: v1.0
最后更新: 2026-03-07
维护者: opencode