# 开发者指南本文档提供了ArticleReplaceBatch项目的开发者指南。 --- ## 目录 - [开发环境搭建](#开发环境搭建) - [项目结构](#项目结构) - [代码规范](#代码规范) - [测试指南](#测试指南) - [贡献指南](#贡献指南) - [常见问题](#常见问题) --- ## 开发环境搭建 ### 1. 克隆项目 ```bash git clone 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格式 ``` ():