mirror of
https://github.com/qaiu/netdisk-fast-download.git
synced 2025-12-16 12:23:03 +00:00
42b721eabf
🚀 核心功能 - 新增完整的客户端下载链接生成器系统 - 支持ARIA2、Motrix、比特彗星、迅雷、wget、cURL、IDM、FDM、PowerShell等8种客户端 - 自动处理防盗链参数（User-Agent、Referer、Cookie等） - 提供可扩展的生成器架构，支持自定义客户端 🔧 技术实现 - ClientLinkGeneratorFactory: 工厂模式管理生成器 - DownloadLinkMeta: 元数据存储下载信息 - ClientLinkUtils: 便捷工具类 - 线程安全的ConcurrentHashMap设计 🌐 前端集成 - 新增ClientLinks.vue界面，支持客户端链接展示 - Element Plus图标系统，混合图标显示 - 客户端检测逻辑优化，避免自动打开外部应用 - 移动端和PC端环境判断 📚 文档完善 - 完整的CLIENT_LINK_GENERATOR_GUIDE.md使用指南 - API文档和测试用例 - 输出示例和最佳实践 从单纯的网盘解析工具升级为完整的下载解决方案生态
317 lines
9.3 KiB
Markdown
317 lines
9.3 KiB
Markdown
# 客户端下载链接生成器使用指南
|
||
|
||
## 概述
|
||
|
||
客户端下载链接生成器是 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. 基本使用
|
||
|
||
```java
|
||
// 解析分享链接
|
||
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. 使用新的便捷方法（推荐）
|
||
|
||
```java
|
||
// 解析分享链接并自动生成客户端链接
|
||
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. 异步方式
|
||
|
||
```java
|
||
// 异步解析并生成客户端链接
|
||
tool.parseWithClientLinks()
|
||
.onSuccess(clientLinks -> {
|
||
log.info("生成的客户端链接: {}", clientLinks);
|
||
})
|
||
.onFailure(error -> {
|
||
log.error("解析失败", error);
|
||
});
|
||
```
|
||
|
||
### 4. 生成特定类型的链接
|
||
|
||
```java
|
||
// 生成 curl 命令
|
||
String curlCommand = ClientLinkGeneratorFactory.generate(info, ClientLinkType.CURL);
|
||
|
||
// 生成迅雷链接
|
||
String thunderLink = ClientLinkGeneratorFactory.generate(info, ClientLinkType.THUNDER);
|
||
|
||
// 生成 aria2 命令
|
||
String aria2Command = ClientLinkGeneratorFactory.generate(info, ClientLinkType.ARIA2);
|
||
```
|
||
|
||
### 5. 使用便捷工具类
|
||
|
||
```java
|
||
// 使用 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 命令示例
|
||
|
||
```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 命令示例
|
||
|
||
```bash
|
||
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 命令示例
|
||
|
||
```bash
|
||
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` 方法来存储下载元数据：
|
||
|
||
```java
|
||
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：
|
||
|
||
```java
|
||
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 命令
|
||
```bash
|
||
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 命令
|
||
```bash
|
||
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 命令
|
||
```bash
|
||
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` 接口：
|
||
|
||
```java
|
||
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. 注册自定义生成器
|
||
|
||
```java
|
||
// 注册自定义生成器
|
||
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版本）
|