# process-urls 接口文档

## 接口概述

`process-urls` 是一个用于批量爬取网页内容的REST API接口，支持POST方式访问，能够处理包含多个URL地址的请求，并返回结构化的网页爬取结果。

## 接口信息

- **接口路径**: `/api/data-parse/process-urls`
- **请求方法**: `POST`
- **内容类型**: `application/json`
- **功能描述**: 批量爬取网页内容，支持多种网页格式

## 请求参数

### 请求体格式

```json
{
  "urlArr": [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://mp.weixin.qq.com/s/4yz-kNAWAlF36aeQ_cgQQg"
  ]
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| urlArr | array | 是 | 包含网页URL地址的字符串数组 |

### 参数验证规则

1. **urlArr字段**: 必须存在且为数组类型
2. **数组内容**: 不能为空数组
3. **URL格式**: 每个元素必须为字符串类型
4. **URL有效性**: 支持http和https协议

## 响应格式

### 成功响应 (200/206)

```json
{
  "success": true,
  "message": "成功爬取所有 3 个URL",
  "data": {
    "total_urls": 3,
    "success_count": 3,
    "failed_count": 0,
    "contents": [
      {
        "url": "https://mp.weixin.qq.com/s/4yz-kNAWAlF36aeQ_cgQQg",
        "data": "新任命 | 宜宾产城竹颂万怡酒店任命王刚先生（John Wang）出任运营总监...",
        "status": "success",
        "content_length": 748,
        "original_length": 2006415,
        "status_code": 200,
        "encoding": "UTF-8"
      }
    ],
    "failed_items": []
  }
}
```

### 部分成功响应 (206)

```json
{
  "success": true,
  "message": "部分成功: 成功爬取 2 个URL，失败 1 个URL",
  "data": {
    "total_urls": 3,
    "success_count": 2,
    "failed_count": 1,
    "contents": [
      {
        "url": "https://example.com/page1",
        "data": "页面内容...",
        "status": "success",
        "content_length": 1500,
        "original_length": 2000,
        "status_code": 200,
        "encoding": "UTF-8"
      }
    ],
    "failed_items": [
      {
        "url": "https://invalid-url.com",
        "error": "连接超时",
        "status": "failed"
      }
    ]
  }
}
```

### 错误响应 (400/500)

```json
{
  "success": false,
  "message": "请求参数错误",
  "data": {
    "total_urls": 0,
    "success_count": 0,
    "failed_count": 0,
    "contents": [],
    "failed_items": []
  }
}
```

## 响应字段说明

### 顶层字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| success | boolean | 请求是否成功 |
| message | string | 处理结果描述 |
| data | object | 详细数据对象 |

### data 对象字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| total_urls | integer | 总URL数量 |
| success_count | integer | 成功爬取的URL数量 |
| failed_count | integer | 失败的URL数量 |
| contents | array | 成功爬取的内容列表 |
| failed_items | array | 失败的URL列表 |

### contents 数组元素字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| url | string | 网页URL地址 |
| data | string | 爬取到的网页内容（清理后的文本） |
| status | string | 状态标识，固定为 "success" |
| content_length | integer | 清理后内容的字符长度 |
| original_length | integer | 原始HTML内容的字符长度 |
| status_code | integer | HTTP响应状态码 |
| encoding | string | 网页编码格式 |

### failed_items 数组元素字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| url | string | 失败的网页URL地址 |
| error | string | 失败原因描述 |
| status | string | 状态标识，固定为 "failed" |

## HTTP状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 完全成功，所有URL都成功爬取 |
| 206 | 部分成功，部分URL成功爬取 |
| 400 | 请求参数错误（参数格式、类型、缺失等） |
| 500 | 服务器内部错误 |

## 使用示例

### JavaScript (前端)

```javascript
// 使用fetch API
async function crawlWebsites(urls) {
  try {
    const response = await fetch('/api/data-parse/process-urls', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        urlArr: urls
      })
    });
    
    const result = await response.json();
    
    if (result.success) {
      console.log(`成功爬取 ${result.data.success_count} 个网页`);
      
      // 处理成功爬取的内容
      result.data.contents.forEach(content => {
        console.log(`URL: ${content.url}`);
        console.log(`内容: ${content.data.substring(0, 100)}...`);
      });
      
      // 处理失败的URL
      if (result.data.failed_count > 0) {
        console.log(`有 ${result.data.failed_count} 个URL爬取失败`);
        result.data.failed_items.forEach(failed => {
          console.log(`失败URL: ${failed.url}, 原因: ${failed.error}`);
        });
      }
    } else {
      console.error(`爬取失败: ${result.message}`);
    }
  } catch (error) {
    console.error('请求异常:', error);
  }
}

// 调用示例
const urls = [
  'https://mp.weixin.qq.com/s/4yz-kNAWAlF36aeQ_cgQQg',
  'https://example.com/page1'
];

crawlWebsites(urls);
```

### Python (后端)

```python
import requests
import json

def test_process_urls_api():
    api_url = "http://localhost:5000/api/data-parse/process-urls"
    
    test_data = {
        "urlArr": [
            "https://mp.weixin.qq.com/s/4yz-kNAWAlF36aeQ_cgQQg",
            "https://httpbin.org/html"
        ]
    }
    
    try:
        response = requests.post(
            api_url,
            json=test_data,
            headers={'Content-Type': 'application/json'},
            timeout=120
        )
        
        if response.status_code in [200, 206]:
            result = response.json()
            print(f"爬取成功: {result['message']}")
            
            # 处理结果
            for content in result['data']['contents']:
                print(f"URL: {content['url']}")
                print(f"内容长度: {content['content_length']}")
                
        else:
            print(f"请求失败: {response.status_code}")
            print(response.text)
            
    except Exception as e:
        print(f"异常: {e}")

# 运行测试
test_process_urls_api()
```

### cURL 命令行

```bash
curl -X POST \
  http://localhost:5000/api/data-parse/process-urls \
  -H "Content-Type: application/json" \
  -d '{
    "urlArr": [
      "https://mp.weixin.qq.com/s/4yz-kNAWAlF36aeQ_cgQQg",
      "https://httpbin.org/html"
    ]
  }'
```

## 功能特性

### 1. 批量处理
- 支持同时处理多个URL
- 自动管理请求队列和延迟
- 提供整体处理统计

### 2. 智能重试
- 自动重试失败的请求
- 最多重试3次
- 不同类型的错误采用不同的重试策略

### 3. 内容解析
- 使用BeautifulSoup自动解析HTML
- 提取纯文本内容，去除HTML标签
- 智能内容清理和格式化

### 4. 反爬虫保护
- 模拟真实浏览器请求头
- 随机延迟机制
- 支持重定向和超时处理

### 5. 详细日志
- 完整的处理过程日志
- 错误分类和统计
- 便于调试和监控

## 注意事项

### 1. 性能考虑
- 每个URL处理时间取决于网页大小和网络状况
- 建议单次请求的URL数量不超过20个
- 接口设置了120秒超时时间

### 2. 网络限制
- 某些网站可能有反爬虫机制
- 建议在稳定的网络环境下使用
- 遵守目标网站的robots.txt规则

### 3. 内容大小
- 大型网页可能产生大量文本内容
- 注意前端显示时的内存使用
- 建议对长内容进行分页或截断显示

### 4. 错误处理
- 接口会返回详细的错误信息
- 建议前端实现适当的错误提示
- 部分失败时仍可处理成功的内容

## 错误码说明

| 错误类型 | 说明 | 处理建议 |
|----------|------|----------|
| 连接超时 | 网络连接超时 | 检查网络状况，稍后重试 |
| HTTP状态码错误 | 服务器返回非200状态码 | 检查URL有效性，确认网站可访问 |
| 内容解析失败 | HTML解析异常 | 系统会自动使用原始内容 |
| 编码错误 | 字符编码不支持 | 系统会自动处理编码转换 |

## 更新日志

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| 1.0.0 | 2025-08-18 | 初始版本，支持基本的网页爬取功能 |

## 技术支持

如有问题或建议，请联系开发团队或查看相关日志文件。