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

客户端下载链接生成器使用指南

概述

客户端下载链接生成器是 parser 模块的新功能，用于将解析得到的直链转换为各种下载客户端可识别的格式，包括 curl、wget、aria2、IDM、迅雷、比特彗星、Motrix、FDM 等主流下载工具。

核心特性

• 多客户端支持：支持 8 种主流下载客户端格式
• 防盗链处理：自动处理请求头、Referer 等防盗链参数
• 可扩展设计：支持注册自定义生成器
• 元数据存储：通过 ShareLinkInfo.otherParam 存储下载元数据
• 线程安全：工厂类使用 ConcurrentHashMap 保证线程安全

支持的客户端类型

客户端类型	代码	说明	输出格式
Aria2	ARIA2	命令行/RPC	aria2c 命令
Motrix	MOTRIX	跨平台下载工具	JSON 格式
比特彗星	BITCOMET	BT 下载工具	bitcomet:// 协议链接
迅雷	THUNDER	国内主流下载工具	thunder:// 协议链接
wget	WGET	命令行工具	wget 命令
cURL	CURL	命令行工具	curl 命令
IDM	IDM	Windows 下载管理器	idm:// 协议链接
FDM	FDM	Free Download Manager	文本格式
PowerShell	POWERSHELL	Windows PowerShell	PowerShell 命令

快速开始

1. 基本使用

// 解析分享链接
IPanTool tool = ParserCreate.fromShareUrl("https://example.com/share/abc123")
    .createTool();
String directLink = tool.parseSync();

// 获取 ShareLinkInfo
ShareLinkInfo info = tool.getShareLinkInfo();

// 生成所有类型的客户端链接
Map<ClientLinkType, String> clientLinks = ClientLinkGeneratorFactory.generateAll(info);

// 使用生成的链接
String curlCommand = clientLinks.get(ClientLinkType.CURL);
String thunderLink = clientLinks.get(ClientLinkType.THUNDER);

2. 使用新的便捷方法（推荐）

// 解析分享链接并自动生成客户端链接
IPanTool tool = ParserCreate.fromShareUrl("https://example.com/share/abc123")
    .createTool();

// 一步完成解析和客户端链接生成
Map<ClientLinkType, String> clientLinks = tool.parseWithClientLinksSync();

// 使用生成的链接
String curlCommand = clientLinks.get(ClientLinkType.CURL);
String thunderLink = clientLinks.get(ClientLinkType.THUNDER);

3. 异步方式

// 异步解析并生成客户端链接
tool.parseWithClientLinks()
    .onSuccess(clientLinks -> {
        log.info("生成的客户端链接: {}", clientLinks);
    })
    .onFailure(error -> {
        log.error("解析失败", error);
    });

4. 生成特定类型的链接

// 生成 curl 命令
String curlCommand = ClientLinkGeneratorFactory.generate(info, ClientLinkType.CURL);

// 生成迅雷链接
String thunderLink = ClientLinkGeneratorFactory.generate(info, ClientLinkType.THUNDER);

// 生成 aria2 命令
String aria2Command = ClientLinkGeneratorFactory.generate(info, ClientLinkType.ARIA2);

5. 使用便捷工具类

// 使用 ClientLinkUtils 工具类
String curlCommand = ClientLinkUtils.generateCurlCommand(info);
String wgetCommand = ClientLinkUtils.generateWgetCommand(info);
String thunderLink = ClientLinkUtils.generateThunderLink(info);
String powershellCommand = ClientLinkUtils.generatePowerShellCommand(info);

// 检查是否有有效的下载元数据
boolean hasValidMeta = ClientLinkUtils.hasValidDownloadMeta(info);

输出示例

PowerShell 命令示例

$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
Invoke-WebRequest `
-UseBasicParsing `
-Uri "https://example.com/file.zip" `
-WebSession $session `
-Headers @{`
  "Cookie"="session=abc123"`
`
  "Accept"="text/html,application/xhtml+xml"`
`
  "User-Agent"="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"`
`
  "Referer"="https://example.com/share/test"`
} `
-OutFile "test-file.zip"

cURL 命令示例

curl \
  -L \
  -H \
  "Cookie: session=abc123" \
  -H \
  "User-Agent: Mozilla/5.0 (Test Browser)" \
  -H \
  "Referer: https://example.com/share/test" \
  -o \
  "test-file.zip" \
  "https://example.com/file.zip"

迅雷链接示例

thunder://QUFodHRwczovL2V4YW1wbGUuY29tL2ZpbGUuemlwWlo=

Aria2 命令示例

aria2c \
--header="Cookie: session=abc123" \
--header="User-Agent: Mozilla/5.0 (Test Browser)" \
--header="Referer: https://example.com/share/test" \
--out="test-file.zip" \
--continue \
--max-tries=3 \
--retry-wait=5 \
"https://example.com/file.zip"

解析器集成

1. 使用 completeWithMeta 方法

在解析器实现中，使用 PanBase 提供的 completeWithMeta 方法来存储下载元数据：

public class MyPanTool extends PanBase {
    
    @Override
    public Future<String> parse() {
        // ... 解析逻辑 ...
        
        // 获取下载链接
        String downloadUrl = "https://example.com/file.zip";
        
        // 准备请求头
        Map<String, String> headers = new HashMap<>();
        headers.put("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36");
        headers.put("Referer", shareLinkInfo.getShareUrl());
        headers.put("Cookie", "session=abc123");
        
        // 使用 completeWithMeta 存储元数据
        completeWithMeta(downloadUrl, headers);
        
        return future();
    }
}

2. 使用 MultiMap 版本

如果使用 Vert.x 的 MultiMap：

MultiMap headers = MultiMap.caseInsensitiveMultiMap();
headers.set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36");
headers.set("Referer", shareLinkInfo.getShareUrl());

// 使用 MultiMap 版本
completeWithMeta(downloadUrl, headers);

输出示例

curl 命令

curl -L "https://example.com/file.zip" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -H "Referer: https://example.com/share/abc123" \
  -H "Cookie: session=abc123" \
  -o "file.zip"

wget 命令

wget --header="User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
     --header="Referer: https://example.com/share/abc123" \
     --header="Cookie: session=abc123" \
     -O "file.zip" \
     "https://example.com/file.zip"

aria2 命令

aria2c --header="User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
       --header="Referer: https://example.com/share/abc123" \
       --header="Cookie: session=abc123" \
       --out="file.zip" \
       --continue \
       --max-tries=3 \
       --retry-wait=5 \
       "https://example.com/file.zip"

迅雷链接

thunder://QUFodHRwczovL2V4YW1wbGUuY29tL2ZpbGUuemlwWlo=

IDM 链接

idm:///?url=aHR0cHM6Ly9leGFtcGxlLmNvbS9maWxlLnppcA==&header=UmVmZXJlcjogaHR0cHM6Ly9leGFtcGxlLmNvbS9zaGFyZS9hYmMxMjMK

扩展开发

1. 自定义生成器

实现 ClientLinkGenerator 接口：

public class MyCustomGenerator implements ClientLinkGenerator {
    
    @Override
    public String generate(DownloadLinkMeta meta) {
        // 自定义生成逻辑
        return "myapp://download?url=" + meta.getUrl();
    }
    
    @Override
    public ClientLinkType getType() {
        return ClientLinkType.CURL; // 或者定义新的类型
    }
}

2. 注册自定义生成器

// 注册自定义生成器
ClientLinkGeneratorFactory.register(new MyCustomGenerator());

// 使用自定义生成器
String customLink = ClientLinkGeneratorFactory.generate(info, ClientLinkType.CURL);

注意事项

1. 防盗链处理：不同网盘的防盗链策略不同，需要在元数据中完整保存所需的 headers
2. URL 编码：生成客户端链接时注意 URL 和参数的正确编码（Base64、URLEncode 等）
3. 兼容性：确保生成的命令/协议在主流客户端中可用
4. 可选特性：元数据存储和客户端链接生成均为可选，不影响现有解析器功能
5. 线程安全：工厂类使用 ConcurrentHashMap 存储生成器，支持多线程环境

API 参考

IPanTool 接口新增方法

• parseWithClientLinks() - 解析文件并生成客户端下载链接（异步）
• parseWithClientLinksSync() - 解析文件并生成客户端下载链接（同步）
• getShareLinkInfo() - 获取 ShareLinkInfo 对象

ClientLinkGeneratorFactory

• generateAll(ShareLinkInfo info) - 生成所有类型的客户端链接
• generate(ShareLinkInfo info, ClientLinkType type) - 生成指定类型的链接
• register(ClientLinkGenerator generator) - 注册自定义生成器
• unregister(ClientLinkType type) - 注销生成器
• isRegistered(ClientLinkType type) - 检查是否已注册

ClientLinkUtils

• generateAllClientLinks(ShareLinkInfo info) - 生成所有客户端链接
• generateCurlCommand(ShareLinkInfo info) - 生成 curl 命令
• generateWgetCommand(ShareLinkInfo info) - 生成 wget 命令
• generateThunderLink(ShareLinkInfo info) - 生成迅雷链接
• generatePowerShellCommand(ShareLinkInfo info) - 生成 PowerShell 命令
• hasValidDownloadMeta(ShareLinkInfo info) - 检查元数据有效性

PanBase

• completeWithMeta(String url, Map<String, String> headers) - 完成解析并存储元数据
• completeWithMeta(String url, MultiMap headers) - 完成解析并存储元数据（MultiMap版本）