netdisk-fast-download/parser/doc/API_USAGE.md

自定义解析器API使用指南

📡 API端点

当你在演练场发布自定义解析器后，可以通过以下API端点使用：

---

1️⃣ 302重定向（直接下载）

端点: /parser

方法: GET

描述: 返回302重定向到实际下载地址，适合浏览器直接访问下载

请求参数

参数	类型	必填	说明
url	string	✅ 是	分享链接（需URL编码）
pwd	string	❌ 否	分享密码

请求示例

# 基本请求
GET http://localhost:6400/parser?url=https://lanzoui.com/i7Aq12ab3cd

# 带密码
GET http://localhost:6400/parser?url=https://lanzoui.com/i7Aq12ab3cd&pwd=1234

# curl命令
curl -L "http://localhost:6400/parser?url=https://lanzoui.com/i7Aq12ab3cd"

响应

HTTP/1.1 302 Found
Location: https://download-server.com/file/xxx

浏览器会自动跳转到下载地址。

---

2️⃣ JSON响应（获取解析结果）

端点: /json/parser

方法: GET

描述: 返回JSON格式的解析结果，包含下载链接等详细信息

请求参数

参数	类型	必填	说明
url	string	✅ 是	分享链接（需URL编码）
pwd	string	❌ 否	分享密码

请求示例

# 基本请求
GET http://localhost:6400/json/parser?url=https://lanzoui.com/i7Aq12ab3cd

# 带密码
GET http://localhost:6400/json/parser?url=https://lanzoui.com/i7Aq12ab3cd&pwd=1234

# curl命令
curl "http://localhost:6400/json/parser?url=https://lanzoui.com/i7Aq12ab3cd"

响应格式

{
  "code": 200,
  "msg": "success",
  "data": {
    "url": "https://download-server.com/file/xxx",
    "fileName": "example.zip",
    "fileSize": "10MB",
    "parseTime": 1234
  }
}

---

🔧 使用场景

场景1: 浏览器直接下载

用户点击链接直接下载：

<a href="http://localhost:6400/parser?url=https://lanzoui.com/i7Aq12ab3cd">
  点击下载
</a>

场景2: 获取下载信息

JavaScript获取下载链接：

fetch('http://localhost:6400/json/parser?url=https://lanzoui.com/i7Aq12ab3cd')
  .then(res => res.json())
  .then(data => {
    console.log('下载链接:', data.data.url);
    console.log('文件名:', data.data.fileName);
  });

场景3: 命令行下载

# 方式1: 直接下载
curl -L -O "http://localhost:6400/parser?url=https://lanzoui.com/i7Aq12ab3cd"

# 方式2: 先获取链接再下载
DOWNLOAD_URL=$(curl -s "http://localhost:6400/json/parser?url=https://lanzoui.com/i7Aq12ab3cd" | jq -r '.data.url')
curl -L -O "$DOWNLOAD_URL"

场景4: Python脚本

import requests

# 获取解析结果
response = requests.get(
    'http://localhost:6400/json/parser',
    params={
        'url': 'https://lanzoui.com/i7Aq12ab3cd',
        'pwd': '1234'
    }
)

result = response.json()
if result['code'] == 200:
    download_url = result['data']['url']
    print(f'下载链接: {download_url}')
    
    # 下载文件
    file_response = requests.get(download_url)
    with open('download.file', 'wb') as f:
        f.write(file_response.content)

---

🎯 解析器匹配规则

系统会根据分享链接的URL自动选择合适的解析器：

1. 优先匹配自定义解析器

   • 检查演练场发布的解析器
   • 使用 @match 正则表达式匹配

2. 内置解析器

   • 如果没有匹配的自定义解析器
   • 使用系统内置的解析器

示例

假设你发布了蓝奏云解析器：

// @match https?://lanzou[a-z]{1,2}\.com/(?<KEY>[a-zA-Z0-9]+)

当请求以下链接时会使用你的解析器：

• ✅ https://lanzoui.com/i7Aq12ab3cd
• ✅ https://lanzoux.com/i7Aq12ab3cd
• ✅ http://lanzouy.com/i7Aq12ab3cd

---

⚙️ 高级用法

1. 指定解析器类型

# 通过type参数指定解析器
GET http://localhost:6400/parser?url=https://example.com/s/abc&type=custom_parser

2. 获取文件列表

对于支持文件夹的网盘：

# 获取文件列表
GET http://localhost:6400/json/parser/list?url=https://example.com/s/abc

# 按文件ID获取下载链接
GET http://localhost:6400/json/parser/file?url=https://example.com/s/abc&fileId=123

3. 批量解析

const urls = [
  'https://lanzoui.com/i7Aq12ab3cd',
  'https://lanzoui.com/i8Bq34ef5gh'
];

const results = await Promise.all(
  urls.map(url => 
    fetch(`http://localhost:6400/json/parser?url=${encodeURIComponent(url)}`)
      .then(res => res.json())
  )
);

---

🔒 安全注意事项

1. SSRF防护

系统已实施SSRF防护，以下请求会被拦截：

❌ 内网地址：

# 这些会被拦截
http://127.0.0.1:8080/admin
http://192.168.1.1/config
http://169.254.169.254/latest/meta-data/

✅ 公网地址：

# 这些是允许的
https://lanzoui.com/xxx
https://pan.baidu.com/s/xxx

2. 速率限制

建议添加速率限制，避免滥用：

// 使用节流
import { throttle } from 'lodash';

const parseUrl = throttle((url) => {
  return fetch(`/json/parser?url=${encodeURIComponent(url)}`);
}, 1000); // 每秒最多1次请求

---

📊 错误处理

常见错误码

错误码	说明	解决方法
400	参数错误	检查url参数是否正确编码
404	未找到解析器	确认链接格式是否匹配解析器规则
500	解析失败	查看日志，可能是解析器代码错误
503	服务不可用	稍后重试

错误响应示例

{
  "code": 500,
  "msg": "解析失败: 无法提取下载参数",
  "data": null
}

错误处理示例

fetch('/json/parser?url=' + encodeURIComponent(shareUrl))
  .then(res => res.json())
  .then(data => {
    if (data.code === 200) {
      console.log('成功:', data.data.url);
    } else {
      console.error('失败:', data.msg);
    }
  })
  .catch(error => {
    console.error('请求失败:', error.message);
  });

---

💡 最佳实践

1. URL编码

始终对分享链接进行URL编码：

// ✅ 正确
const encodedUrl = encodeURIComponent('https://lanzoui.com/i7Aq12ab3cd');
fetch(`/json/parser?url=${encodedUrl}`);

// ❌ 错误
fetch('/json/parser?url=https://lanzoui.com/i7Aq12ab3cd');

2. 错误重试

实现指数退避重试：

async function parseWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(`/json/parser?url=${encodeURIComponent(url)}`);
      const data = await response.json();
      
      if (data.code === 200) {
        return data;
      }
      
      // 如果是服务器错误，重试
      if (data.code >= 500 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }
      
      throw new Error(data.msg);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

3. 超时处理

设置请求超时：

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000); // 30秒超时

fetch('/json/parser?url=' + encodeURIComponent(url), {
  signal: controller.signal
})
  .then(res => res.json())
  .finally(() => clearTimeout(timeout));

---

📚 更多资源

• 演练场文档: /parser/doc/JAVASCRIPT_PARSER_GUIDE.md
• 自定义解析器: /parser/doc/CUSTOM_PARSER_GUIDE.md
• 安全指南: /parser/doc/security/

---

最后更新: 2025-11-29
版本: v1.0