taiyi/ArticleReplaceBatch

Template

Fork 0

Files

wsb1224 93c2cebc94 更新验证器提价

2026-03-25 15:17:18 +08:00

7.5 KiB

Raw Permalink Blame History

开发者指南

本文档提供了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: 修复bug
docs: 文档更新
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: 性能优化建议？

使用异步处理
添加缓存机制
批量处理数据
优化数据库查询

开发工具

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

7.5 KiB Raw Permalink Blame History Unescape Escape