# parser 开发文档

面向开发者的解析器实现说明：约定、数据映射、HTTP 调试与示例代码。

- 语言/构建：Java 17 / Maven
- 关键接口：cn.qaiu.parser.IPanTool（返回 Future<List<FileInfo>>），各站点位于 parser/src/main/java/cn/qaiu/parser/impl
- 数据模型：cn.qaiu.entity.FileInfo（统一对外文件项）
- JavaScript解析器：支持使用JavaScript编写自定义解析器，位于 parser/src/main/resources/custom-parsers/

---

## 0. 快速调用示例（最小可运行）
```java
import cn.qaiu.WebClientVertxInit;
import cn.qaiu.entity.FileInfo;
import cn.qaiu.parser.IPanTool;
import cn.qaiu.parser.ParserCreate;
import io.vertx.core.Vertx;
import java.util.List;

public class ParserQuickStart {
    public static void main(String[] args) {
        // 1) 初始化 Vert.x（parser 内部 WebClient 依赖它）
        Vertx vertx = Vertx.vertx();
        WebClientVertxInit.init(vertx);

        // 2) 从分享链接自动识别网盘类型并创建解析器
        String shareUrl = "https://www.ilanzou.com/s/xxxx"; // 替换为实际分享链接
        IPanTool tool = ParserCreate.fromShareUrl(shareUrl)
                // .setShareLinkInfoPwd("1234") // 如有提取码可设置
                .createTool();

        // 3) 使用同步方法获取文件列表（推荐）
        List<FileInfo> files = tool.parseFileListSync();
        for (FileInfo f : files) {
            System.out.printf("%s\t%s\t%s\n",
                f.getFileName(), f.getSizeStr(), f.getParserUrl());
        }

        // 4) 使用同步方法获取原始解析输出（不同盘实现差异较大，仅供调试）
        String raw = tool.parseSync();
        System.out.println("raw: " + (raw == null ? "null" : raw.substring(0, Math.min(raw.length(), 200)) + "..."));
        
        // 5) 使用同步方法根据文件ID获取下载链接（可选）
        if (!files.isEmpty()) {
            String fileId = files.get(0).getFileId();
            String downloadUrl = tool.parseByIdSync();
            System.out.println("文件下载链接: " + downloadUrl);
        }

        // 6) 生成 parser 短链 path（可用于上层路由聚合显示）
        String path = ParserCreate.fromShareUrl(shareUrl).genPathSuffix();
        System.out.println("path suffix: /" + path);

        vertx.close();
    }
}
```

等价用法：已知网盘类型 + shareKey 构造
```java
IPanTool tool = ParserCreate.fromType("lz") // 对应 PanDomainTemplate.LZ
        .shareKey("abcd12")                   // 必填：分享 key
        .setShareLinkInfoPwd("1234")         // 可选：提取码
        .createTool();
// 获取文件列表（使用同步方法）
List<FileInfo> files = tool.parseFileListSync();
```

要点：
- 必须先 WebClientVertxInit.init(Vertx)；若未显式初始化，内部将懒加载 Vertx.vertx()，建议显式注入以统一生命周期。
- 支持三种同步方法：
  - `parseSync()`: 解析单个文件下载链接
  - `parseFileListSync()`: 解析文件列表
  - `parseByIdSync()`: 根据文件ID获取下载链接
- 异步方法仍可用：parse()、parseFileList()、parseById() 返回 Future 对象
- 生成短链 path：ParserCreate.genPathSuffix()（用于页面/服务端聚合）。

## JavaScript解析器快速开始

除了Java解析器，还支持使用JavaScript编写自定义解析器：

### 1. 创建JavaScript解析器

在 `parser/src/main/resources/custom-parsers/` 目录下创建 `.js` 文件：

```javascript
// ==UserScript==
// @name         我的解析器
// @type         my_parser
// @displayName  我的网盘
// @description  使用JavaScript实现的网盘解析器
// @match        https?://example\.com/s/(?<KEY>\w+)
// @author       yourname
// @version      1.0.0
// ==/UserScript==

/**
 * 解析单个文件下载链接
 * @param {ShareLinkInfo} shareLinkInfo - 分享链接信息
 * @param {JsHttpClient} http - HTTP客户端
 * @param {JsLogger} logger - 日志对象
 * @returns {string} 下载链接
 */
function parse(shareLinkInfo, http, logger) {
    var url = shareLinkInfo.getShareUrl();
    var response = http.get(url);
    return response.body();
}
```

### 2. JavaScript解析器特性

- **重定向处理**：支持`getNoRedirect()`方法获取302重定向的真实链接
- **代理支持**：自动支持HTTP/SOCKS代理配置
- **类型提示**：提供完整的JSDoc类型定义
- **热加载**：修改后重启应用即可生效

### 3. 详细文档

- **[JavaScript解析器开发指南](JAVASCRIPT_PARSER_GUIDE.md)** - 完整的JavaScript解析器开发文档，包含API参考、示例代码和最佳实践
- **[自定义解析器扩展指南](CUSTOM_PARSER_GUIDE.md)** - Java自定义解析器扩展完整指南
- **[自定义解析器快速开始](CUSTOM_PARSER_QUICKSTART.md)** - 快速上手自定义解析器开发

---

## 1. 解析器约定
- 输入：目标分享/目录页或接口的上下文（通常在实现类构造或初始化时已注入必要参数，如 shareKey、cookie、headers）。
- 输出：Future<List<FileInfo>>（文件/目录混合列表，必要时区分 file/folder）。
- 错误：失败场景通过 Future 失败或返回空列表；日志由上层统一处理。
- 并发：尽量使用 Vert.x Web Client 异步请求；注意限流与重试策略由实现类自定。

FileInfo 关键字段（节选）：
- fileId：唯一标识
- fileName：展示名（建议带扩展名，如 basename）
- fileType：如 "file"/"folder" 或 mime（实现自定，保持一致即可）
- size（Long, 字节）/ sizeStr（原文字符串）
- createTime / updateTime：格式 yyyy-MM-dd HH:mm:ss（如源为时间戳或 yyyy-MM-dd 需转）
- parserUrl：非直连下载的中间链接或协议占位（如 BilPan://）
- filePath / previewUrl / extParameters：按需补充

工具类：
- FileSizeConverter：字符串容量转字节、字节转可读容量

---

## 2. 文件列表解析规范

### 通用解析原则

1. **数据结构识别**：根据网盘API响应结构确定文件列表的路径
2. **字段映射**：将网盘特定字段映射到统一的`FileInfo`对象
3. **类型区分**：正确识别文件和文件夹类型
4. **数据转换**：处理时间格式、文件大小等数据格式转换

### FileInfo字段映射指南

| FileInfo字段 | 说明 | 映射建议 |
|-------------|------|----------|
| `fileName` | 文件名 | 优先使用文件名字段，无则使用标题字段 |
| `fileId` | 文件ID | 使用网盘提供的唯一标识符 |
| `fileType` | 文件类型 | "file"或"folder" |
| `size` | 文件大小(字节) | 转换为字节数，文件夹可为0 |
| `sizeStr` | 文件大小(可读) | 保持网盘原始格式或转换 |
| `createTime` | 创建时间 | 统一时间格式 |
| `updateTime` | 更新时间 | 统一时间格式 |
| `parserUrl` | 下载链接 | 网盘提供的下载URL |
| `previewUrl` | 预览链接 | 可选，网盘提供的预览URL |

### 常见数据转换

- **文件大小**：使用`FileSizeConverter`进行字符串与字节数转换
- **时间格式**：统一转换为标准时间格式
- **文件类型**：根据网盘API判断文件/文件夹类型

### 解析注意事项

- **数据验证**：检查必要字段是否存在，避免空指针异常
- **格式兼容**：处理不同网盘的数据格式差异
- **错误处理**：转换失败时提供合理的默认值
- **扩展字段**：额外信息可存储在`extParameters`中

### 解析示例

```java
// 通用解析模式示例
JsonObject root = response.json(); // 获取API响应
JsonArray fileList = root.getJsonArray("files"); // 根据实际API调整路径
List<FileInfo> result = new ArrayList<>();

for (JsonObject item : fileList) {
    FileInfo fileInfo = new FileInfo();
    
    // 基本字段映射
    fileInfo.setFileName(item.getString("name"));
    fileInfo.setFileId(item.getString("id"));
    fileInfo.setFileType(item.getString("type").equals("file") ? "file" : "folder");
    
    // 文件大小处理
    String sizeStr = item.getString("size");
    if (sizeStr != null) {
        fileInfo.setSizeStr(sizeStr);
        try {
            fileInfo.setSize(FileSizeConverter.convertToBytes(sizeStr));
        } catch (Exception e) {
            // 转换失败时保持sizeStr，size为0
        }
    }
    
    // 时间处理
    fileInfo.setCreateTime(formatTime(item.getString("createTime")));
    fileInfo.setUpdateTime(formatTime(item.getString("updateTime")));
    
    // 下载链接
    fileInfo.setParserUrl(item.getString("downloadUrl"));
    
    result.add(fileInfo);
}
```

### JavaScript解析器示例

```javascript
function parseFileList(shareLinkInfo, http, logger) {
    var response = http.get(shareLinkInfo.getShareUrl());
    var data = response.json();
    
    var fileList = [];
    var files = data.files || data.data || data.items; // 根据实际API调整
    
    for (var i = 0; i < files.length; i++) {
        var file = files[i];
        var fileInfo = {
            fileName: file.name || file.title,
            fileId: file.id,
            fileType: file.type === "file" ? "file" : "folder",
            size: file.size || 0,
            sizeStr: file.sizeStr || formatSize(file.size),
            createTime: file.createTime,
            updateTime: file.updateTime,
            parserUrl: file.downloadUrl || file.url
        };
        
        fileList.push(fileInfo);
    }
    
    return fileList;
}
```

---

## 3. 开发流程建议
- 新增站点：在 impl 下新增 Tool，实现 IPanTool，复用 PanBase/模板类；补充单测。
- 字段不全：尽量回填 sizeStr/createTime 等便于前端展示；不可用字段置空。
- 单测：放置于 parser/src/test/java，尽量添加 1-2 个 happy path + 1 个边界用例。

## 4. 常见问题
- 容量解析失败：保留 sizeStr，并忽略 size；避免抛出异常影响整体列表。
- 协议占位下载链接：统一放至 parserUrl，直链转换由下载阶段处理。
- 鉴权：Cookie/Token 过期问题由上层刷新或外部注入处理；解析器保持无状态最佳。

---

## 5. 参考
- FileInfo：parser/src/main/java/cn/qaiu/entity/FileInfo.java
- IPanTool：parser/src/main/java/cn/qaiu/parser/IPanTool.java
- FileSizeConverter：parser/src/main/java/cn/qaiu/util/FileSizeConverter.java