process-urls 接口文档

接口概述

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

接口信息

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

请求参数

请求体格式

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

参数说明

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

参数验证规则

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

响应格式

成功响应 (200/206)

{
  "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)

{
  "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)

{
  "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 (前端)

// 使用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 (后端)

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 命令行

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	初始版本，支持基本的网页爬取功能

技术支持

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

process_urls_api_documentation.md 8.4 KB Verlauf Originalformat

process-urls 接口文档

接口概述

接口信息

请求参数

请求体格式

参数说明

参数验证规则

响应格式

成功响应 (200/206)

部分成功响应 (206)

错误响应 (400/500)

响应字段说明

顶层字段

data 对象字段

contents 数组元素字段

failed_items 数组元素字段

HTTP状态码

使用示例

JavaScript (前端)

Python (后端)

cURL 命令行

功能特性

1. 批量处理

2. 智能重试

3. 内容解析

4. 反爬虫保护

5. 详细日志

注意事项

1. 性能考虑

2. 网络限制

3. 内容大小

4. 错误处理

错误码说明

更新日志

技术支持

process_urls_api_documentation.md 8.4 KB

Verlauf Originalformat