483 lines
9.1 KiB
Markdown
483 lines
9.1 KiB
Markdown
# API文档
|
||
|
||
本文档提供了ArticleReplaceBatch系统的API参考。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [配置管理器 API](#配置管理器-api)
|
||
- [服务层 API](#服务层-api)
|
||
- [工具 API](#工具-api)
|
||
- [UI组件 API](#ui组件-api)
|
||
- [命令行接口](#命令行接口)
|
||
|
||
---
|
||
|
||
## 配置管理器 API
|
||
|
||
### ConfigManager
|
||
|
||
配置管理器单例类，用于统一管理应用配置。
|
||
|
||
#### 类方法
|
||
|
||
##### `__new__(cls) -> ConfigManager`
|
||
创建或返回ConfigManager单例实例。
|
||
|
||
**返回值：**
|
||
- `ConfigManager`: 单例实例
|
||
|
||
**示例：**
|
||
```python
|
||
from config_manager import config_manager
|
||
|
||
# 获取单例实例
|
||
manager = config_manager
|
||
```
|
||
|
||
##### `get(section: str, option: str, fallback: str = '') -> str`
|
||
获取配置值。
|
||
|
||
**参数：**
|
||
- `section`: 配置节名称
|
||
- `option`: 配置项名称
|
||
- `fallback`: 默认值（默认为空字符串）
|
||
|
||
**返回值：**
|
||
- `str`: 配置值
|
||
|
||
**示例：**
|
||
```python
|
||
workflow_id = config_manager.get('Coze', 'workflow_id')
|
||
```
|
||
|
||
##### `get_int(section: str, option: str, fallback: int = 0) -> int`
|
||
获取整数配置值。
|
||
|
||
**参数：**
|
||
- `section`: 配置节名称
|
||
- `option`: 配置项名称
|
||
- `fallback`: 默认值（默认为0）
|
||
|
||
**返回值：**
|
||
- `int`: 整数配置值
|
||
|
||
**示例：**
|
||
```python
|
||
max_threads = config_manager.get_int('General', 'max_threads')
|
||
```
|
||
|
||
##### `set(section: str, option: str, value: Any) -> None`
|
||
设置配置值。
|
||
|
||
**参数：**
|
||
- `section`: 配置节名称
|
||
- `option`: 配置项名称
|
||
- `value`: 配置值
|
||
|
||
**示例：**
|
||
```python
|
||
config_manager.set('General', 'max_threads', '5')
|
||
```
|
||
|
||
##### `save() -> None`
|
||
保存配置到文件。
|
||
|
||
**示例：**
|
||
```python
|
||
config_manager.save()
|
||
```
|
||
|
||
##### `reload() -> None`
|
||
重新加载配置文件。
|
||
|
||
**示例：**
|
||
```python
|
||
config_manager.reload()
|
||
```
|
||
|
||
---
|
||
|
||
## 服务层 API
|
||
|
||
### WebScrapingService
|
||
|
||
网页抓取服务，提供异步网页内容提取功能。
|
||
|
||
#### 类方法
|
||
|
||
##### `__init__(self, max_workers: int = 3)`
|
||
初始化网页抓取服务。
|
||
|
||
**参数：**
|
||
- `max_workers`: 最大工作线程数（默认为3）
|
||
|
||
**示例：**
|
||
```python
|
||
from src.services.web_scraping import WebScrapingService
|
||
|
||
service = WebScrapingService(max_workers=5)
|
||
```
|
||
|
||
##### `extract_content_async(self, links: List[str], max_retries: int = 3) -> List[Tuple[str, str, List[str]]]`
|
||
异步提取多个链接的内容。
|
||
|
||
**参数：**
|
||
- `links`: 链接列表
|
||
- `max_retries`: 最大重试次数（默认为3）
|
||
|
||
**返回值：**
|
||
- `List[Tuple[str, str, List[str]]]`: 提取结果列表，每个元组包含（标题、内容、图片URLs）
|
||
|
||
**示例：**
|
||
```python
|
||
links = [
|
||
"https://www.toutiao.com/article/123",
|
||
"https://www.toutiao.com/article/456"
|
||
]
|
||
results = service.extract_content_async(links)
|
||
for title, content, images in results:
|
||
print(f"标题: {title}")
|
||
print(f"内容长度: {len(content)}")
|
||
print(f"图片数量: {len(images)}")
|
||
```
|
||
|
||
---
|
||
|
||
### ImageProcessingService
|
||
|
||
图片处理服务，提供异步图片下载和处理功能。
|
||
|
||
#### 类方法
|
||
|
||
##### `__init__(self, max_workers: int = 5)`
|
||
初始化图片处理服务。
|
||
|
||
**参数：**
|
||
- `max_workers`: 最大工作线程数（默认为5）
|
||
|
||
**示例：**
|
||
```python
|
||
from src.services.image_processing import ImageProcessingService
|
||
|
||
service = ImageProcessingService(max_workers=5)
|
||
```
|
||
|
||
##### `process_images_async(self, image_urls: List[str], base_filename: str, save_dir: str) -> bool`
|
||
异步处理多个图片。
|
||
|
||
**参数：**
|
||
- `image_urls`: 图片URL列表
|
||
- `base_filename`: 基础文件名
|
||
- `save_dir`: 保存目录
|
||
|
||
**返回值：**
|
||
- `bool`: 是否全部成功
|
||
|
||
**示例：**
|
||
```python
|
||
image_urls = [
|
||
"https://example.com/img1.jpg",
|
||
"https://example.com/img2.jpg"
|
||
]
|
||
success = service.process_images_async(image_urls, "test", "output")
|
||
```
|
||
|
||
---
|
||
|
||
### AIService
|
||
|
||
AI服务基类，提供AI调用功能。
|
||
|
||
#### CozeAIService
|
||
|
||
Coze AI服务实现。
|
||
|
||
#### 类方法
|
||
|
||
##### `__init__(self)`
|
||
初始化Coze AI服务。
|
||
|
||
**示例：**
|
||
```python
|
||
from src.services.ai_service import CozeAIService
|
||
|
||
service = CozeAIService()
|
||
```
|
||
|
||
##### `call_article_workflow(self, parameters: Dict[str, Any]) -> str`
|
||
调用Coze文章工作流。
|
||
|
||
**参数：**
|
||
- `parameters`: 参数字典
|
||
|
||
**返回值：**
|
||
- `str`: AI生成的结果
|
||
|
||
**示例：**
|
||
```python
|
||
result = service.call_article_workflow({"article": "测试文章内容"})
|
||
```
|
||
|
||
##### `get_stats(self) -> Dict[str, Any]`
|
||
获取服务统计信息。
|
||
|
||
**返回值：**
|
||
- `Dict[str, Any]`: 包含调用次数、总时间、平均时间的统计信息
|
||
|
||
**示例：**
|
||
```python
|
||
stats = service.get_stats()
|
||
print(f"调用次数: {stats['call_count']}")
|
||
print(f"平均时间: {stats['avg_time']:.2f}s")
|
||
```
|
||
|
||
---
|
||
|
||
## 工具 API
|
||
|
||
### Validator
|
||
|
||
数据验证器，提供各种数据验证功能。
|
||
|
||
#### 静态方法
|
||
|
||
##### `validate_url(url: str) -> bool`
|
||
验证URL格式。
|
||
|
||
**参数：**
|
||
- `url`: URL字符串
|
||
|
||
**返回值：**
|
||
- `bool`: URL是否有效
|
||
|
||
**示例：**
|
||
```python
|
||
from src.utils.validation import Validator
|
||
|
||
is_valid = Validator.validate_url("https://www.example.com")
|
||
```
|
||
|
||
##### `validate_article_url(url: str) -> bool`
|
||
验证文章URL（头条、微信、网易等）。
|
||
|
||
**参数：**
|
||
- `url`: 文章URL
|
||
|
||
**返回值：**
|
||
- `bool`: URL是否为支持的文章链接
|
||
|
||
**示例：**
|
||
```python
|
||
is_valid = Validator.validate_article_url("https://www.toutiao.com/article/123")
|
||
```
|
||
|
||
##### `validate_string(value: Any, min_length: int = 0, max_length: Optional[int] = None) -> bool`
|
||
验证字符串。
|
||
|
||
**参数：**
|
||
- `value`: 待验证的值
|
||
- `min_length`: 最小长度（默认为0）
|
||
- `max_length`: 最大长度（可选）
|
||
|
||
**返回值：**
|
||
- `bool`: 字符串是否有效
|
||
|
||
**示例：**
|
||
```python
|
||
is_valid = Validator.validate_string("测试", min_length=1, max_length=10)
|
||
```
|
||
|
||
---
|
||
|
||
### ArticleValidator
|
||
|
||
文章数据验证器。
|
||
|
||
#### 静态方法
|
||
|
||
##### `validate_title(title: str) -> bool`
|
||
验证文章标题。
|
||
|
||
**参数：**
|
||
- `title`: 文章标题
|
||
|
||
**返回值：**
|
||
- `bool`: 标题是否有效
|
||
|
||
**示例：**
|
||
```python
|
||
from src.utils.validation import ArticleValidator
|
||
|
||
is_valid = ArticleValidator.validate_title("测试标题")
|
||
```
|
||
|
||
##### `validate_content(content: str, min_length: int = 100) -> bool`
|
||
验证文章内容。
|
||
|
||
**参数：**
|
||
- `content`: 文章内容
|
||
- `min_length`: 最小长度（默认为100）
|
||
|
||
**返回值：**
|
||
- `bool`: 内容是否有效
|
||
|
||
**示例：**
|
||
```python
|
||
is_valid = ArticleValidator.validate_content("测试内容...", min_length=50)
|
||
```
|
||
|
||
---
|
||
|
||
## UI组件 API
|
||
|
||
### LogTextHandler
|
||
|
||
自定义日志处理器，将日志输出到CustomTkinter文本框。
|
||
|
||
#### 类方法
|
||
|
||
##### `__init__(self, text_widget, level=logging.NOTSET)`
|
||
初始化日志处理器。
|
||
|
||
**参数：**
|
||
- `text_widget`: CustomTkinter文本框组件
|
||
- `level`: 日志级别（默认为NOTSET）
|
||
|
||
**示例：**
|
||
```python
|
||
from src.ui.log_handler import LogTextHandler
|
||
|
||
handler = LogTextHandler(text_widget)
|
||
```
|
||
|
||
---
|
||
|
||
## 命令行接口
|
||
|
||
### CLI Usage
|
||
|
||
使用`cli.py`提供的命令行接口。
|
||
|
||
#### 基本用法
|
||
|
||
```bash
|
||
python cli.py --excel 文章链接.xlsx --threads 3
|
||
```
|
||
|
||
#### 参数说明
|
||
|
||
- `--excel`, `-e`: Excel文件路径（包含文章链接）
|
||
- `--link`, `-l`: 单个文章链接
|
||
- `--threads`, `-t`: 线程数（默认为1）
|
||
- `--service`, `-s`: AI服务（默认为coze）
|
||
- `--type`, `-T`: 生成类型（"短篇"或"文章"）
|
||
- `--template`: 使用的模板名称
|
||
- `--verbose`, `-v`: 显示详细日志
|
||
- `--config`: 配置文件路径
|
||
|
||
#### 示例
|
||
|
||
**处理Excel文件：**
|
||
```bash
|
||
python cli.py --excel 文章链接.xlsx --threads 3 --type 文章
|
||
```
|
||
|
||
**处理单个链接：**
|
||
```bash
|
||
python cli.py --link https://www.toutiao.com/article/123
|
||
```
|
||
|
||
**使用详细日志：**
|
||
```bash
|
||
python cli.py --excel 文章链接.xlsx --verbose
|
||
```
|
||
|
||
**使用自定义配置：**
|
||
```bash
|
||
python cli.py --excel 文章链接.xlsx --config custom_config.ini
|
||
```
|
||
|
||
---
|
||
|
||
## 异常处理
|
||
|
||
### ValidationError
|
||
|
||
数据验证错误异常。
|
||
|
||
**示例：**
|
||
```python
|
||
from src.utils.validation import validate_and_raise, ArticleValidator
|
||
|
||
try:
|
||
validate_and_raise(data, ArticleValidator.validate_article_data, "文章数据验证失败")
|
||
except ValidationError as e:
|
||
print(f"验证失败: {e}")
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 使用配置管理器
|
||
|
||
```python
|
||
# 推荐：使用ConfigManager
|
||
from config_manager import config_manager
|
||
|
||
workflow_id = config_manager.get('Coze', 'workflow_id')
|
||
|
||
# 不推荐：直接访问CONFIG
|
||
from config import CONFIG
|
||
workflow_id = CONFIG['Coze']['workflow_id']
|
||
```
|
||
|
||
### 2. 使用服务层
|
||
|
||
```python
|
||
# 推荐：使用服务层
|
||
from src.services.web_scraping import web_scraping_service
|
||
|
||
results = web_scraping_service.extract_content_async(links)
|
||
|
||
# 不推荐：直接调用底层函数
|
||
from get_web_content import extract_content_with_retry
|
||
results = [extract_content_with_retry(link) for link in links]
|
||
```
|
||
|
||
### 3. 验证输入数据
|
||
|
||
```python
|
||
# 推荐：使用验证器
|
||
from src.utils.validation import Validator
|
||
|
||
if Validator.validate_article_url(url):
|
||
process_url(url)
|
||
|
||
# 不推荐：不验证直接使用
|
||
process_url(url)
|
||
```
|
||
|
||
---
|
||
|
||
## 版本信息
|
||
|
||
- **当前版本**: 1.0.0
|
||
- **Python版本**: 3.10+
|
||
- **最后更新**: 2026-03-07
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
- 提交Issue
|
||
- 发送Pull Request
|
||
- 联系项目维护者
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**维护者**: opencode |