parser发布到maven central方便开发者依赖, pom文件结构调整

2025-12-17 12:53:02 +00:00 · 2025-10-16 18:08:03 +08:00
parent eb06eb9f3d
commit c16bde6bb8
9 changed files with 642 additions and 101 deletions
--- a/parser/doc/README.md
+++ b/parser/doc/README.md
@@ -0,0 +1,282 @@
+# parser 开发文档
+
+面向开发者的解析器实现说明：约定、数据映射、HTTP 调试与示例代码。
+
+- 语言/构建：Java 17 / Maven
+- 关键接口：cn.qaiu.parser.IPanTool（返回 Future<List<FileInfo>>），各站点位于 parser/src/main/java/cn/qaiu/parser/impl
+- 数据模型：cn.qaiu.entity.FileInfo（统一对外文件项）
+
+---
+
+## 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.parseFileList()
+                .toCompletionStage().toCompletableFuture().join();
+        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) 生成 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.parseFileList().toCompletionStage().toCompletableFuture().join();
+```
+
+要点：
+- 必须先 WebClientVertxInit.init(Vertx)；若未显式初始化，内部将懒加载 Vertx.vertx()，建议显式注入以统一生命周期。
+- parseFileList 返回 Future<List<FileInfo>>，可直接 join/await；parseSync 仅针对 parse() 的 String 结果。
+- 生成短链 path：ParserCreate.genPathSuffix()（用于页面/服务端聚合）。
+
+---
+
+## 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. 文件列表解析规范（按给定 JSON）
+目标 JSON（摘要）：
+- 列表路径：data.data[]
+- 每项结构：item.data（含 attributes、id、type、relationships）
+- type："file" 或 "folder"
+
+字段映射建议：
+- 通用
+  - fileId ← data.id
+  - createTime ← data.attributes.created_at（若格式不一致，上层再统一格式化）
+  - updateTime ← data.attributes.updated_at
+  - fileType：
+    - 对文件用 data.attributes.mimetype 或固定 "file"
+    - 对目录固定 "folder"
+- 文件（type="file"）
+  - fileName ← 优先 attributes.basename（示例："GBT+28448-2019.pdf"），无则用 attributes.name
+  - sizeStr ← attributes.filesize（示例："18MB"）
+  - size ← 尝试用 FileSizeConverter.convertToBytes(sizeStr)，失败则置空
+  - parserUrl ← attributes.file_url（示例：BilPan://downLoad?id=...）
+  - filePath/parentId ← relationships.parent.data.id（可放到 extParameters.parentId）
+  - previewUrl/thumbnail ← attributes.thumbnail（可选）
+- 目录（type="folder"）
+  - fileName ← attributes.name
+  - size/sizeStr ← 置空
+  - 统计字段（如 items/trashed_items）可入 extParameters
+
+边界与兼容：
+- attributes.filesize 可能为空或为非标准字符串；转换失败时保留 sizeStr，忽略 size。
+- attributes.file_url 可能为占位协议（BilPan://），直链转换在下载阶段处理。
+- relationships.* 可能为空，读取前需判空。
+
+伪代码（parseFileList 核心片段）：
+```java
+// 仅示意，按项目 Json 工具替换
+JsonObject root = ...; // 接口返回
+JsonArray arr = root.getJsonObject("data").getJsonArray("data");
+List<FileInfo> list = new ArrayList<>();
+for (JsonObject wrap : arr) {
+  JsonObject d = wrap.getJsonObject("data");
+  String type = d.getString("type");
+  JsonObject attrs = d.getJsonObject("attributes");
+  FileInfo fi = new FileInfo();
+  fi.setFileId(d.getString("id"));
+  fi.setCreateTime(attrs.getString("created_at"));
+  fi.setUpdateTime(attrs.getString("updated_at"));
+  if ("file".equals(type)) {
+    String basename = attrs.getString("basename");
+    fi.setFileName(basename != null ? basename : attrs.getString("name"));
+    fi.setFileType(attrs.getString("mimetype", "file"));
+    String sizeStr = attrs.getString("filesize");
+    fi.setSizeStr(sizeStr);
+    try { if (sizeStr != null) fi.setSize(FileSizeConverter.convertToBytes(sizeStr)); } catch (Exception ignore) {}
+    fi.setParserUrl(attrs.getString("file_url"));
+    // parentId（可选）
+    JsonObject rel = d.getJsonObject("relationships");
+    if (rel != null) {
+      JsonObject p = rel.getJsonObject("parent");
+      if (p != null && p.getJsonObject("data") != null) {
+        String pid = p.getJsonObject("data").getString("id");
+        Map<String,Object> ext = new HashMap<>();
+        ext.put("parentId", pid);
+        fi.setExtParameters(ext);
+      }
+    }
+  } else {
+    fi.setFileName(attrs.getString("name"));
+    fi.setFileType("folder");
+  }
+  list.add(fi);
+}
+return Future.succeededFuture(list);
+```
+
+---
+
+## 3. curl 转 Java 11 HttpClient 示例
+以 GET 为例（来源：developer-oss.lanrar.com）：
+```java
+HttpClient client = HttpClient.newHttpClient();
+String q = "<替换为长查询串>";
+String url = "https://developer-oss.lanrar.com/file/?" + URLEncoder.encode(q, StandardCharsets.UTF_8);
+HttpRequest req = HttpRequest.newBuilder(URI.create(url))
+    .header("accept", "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7")
+    .header("accept-language", "zh-CN,zh;q=0.9")
+    .header("cache-control", "max-age=0")
+    .header("dnt", "1")
+    .header("priority", "u=0, i")
+    .header("referer", "https://developer-oss.lanrar.com/file/?" + q)
+    .header("sec-ch-ua", "\"Chromium\";v=\"140\", \"Not=A?Brand\";v=\"24\", \"Microsoft Edge\";v=\"140\"")
+    .header("sec-ch-ua-mobile", "?0")
+    .header("sec-ch-ua-platform", "\"macOS\"")
+    .header("sec-fetch-dest", "document")
+    .header("sec-fetch-mode", "navigate")
+    .header("sec-fetch-site", "same-origin")
+    .header("upgrade-insecure-requests", "1")
+    .header("user-agent", "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36 Edg/140.0.0.0")
+    .header("Cookie", "acw_tc=<acw_tc>; cdn_sec_tc=<cdn_sec_tc>; acw_sc__v2=<acw_sc__v2>")
+    .GET()
+    .build();
+HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
+System.out.println(resp.statusCode());
+System.out.println(resp.body());
+```
+
+POST 示例（来源：Weiyun Share BatchDownload，使用 JSON）：
+```java
+HttpClient client = HttpClient.newHttpClient();
+String url = "https://share.weiyun.com/webapp/json/weiyunShare/WeiyunShareBatchDownload?refer=chrome_mac&g_tk=1399845656&r=0.3925692266635241";
+String json = "{...与 curl/requests 等价 JSON 负载，使用占位参数...}";
+HttpRequest req = HttpRequest.newBuilder(URI.create(url))
+    .header("accept", "application/json, text/plain, */*")
+    .header("content-type", "application/json;charset=UTF-8")
+    .header("origin", "https://share.weiyun.com")
+    .header("referer", "https://share.weiyun.com/<shareKey>")
+    .header("user-agent", "Mozilla/5.0 ...")
+    .header("Cookie", "uin=<uin>; skey=<skey>; p_skey=<p_skey>; ...")
+    .POST(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8))
+    .build();
+HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
+```
+提示：
+- Cookie/Token 使用占位并从外部注入，避免硬编码与泄露。
+- r/g_tk 等参数如需计算，请在实现类中封装。
+
+---
+
+## 4. IntelliJ IDEA `.http` 调试样例
+保存为 `requests.http`，可配合环境变量使用。
+
+GET：
+```http
+### 开发者资源 GET 示例
+GET https://developer-oss.lanrar.com/file/?{{q}}
+accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7
+accept-language: zh-CN,zh;q=0.9
+cache-control: max-age=0
+dnt: 1
+priority: u=0, i
+referer: https://developer-oss.lanrar.com/file/?{{q}}
+sec-ch-ua: "Chromium";v="140", "Not=A?Brand";v="24", "Microsoft Edge";v="140"
+sec-ch-ua-mobile: ?0
+sec-ch-ua-platform: "macOS"
+sec-fetch-dest: document
+sec-fetch-mode: navigate
+sec-fetch-site: same-origin
+upgrade-insecure-requests: 1
+user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36 Edg/140.0.0.0
+Cookie: acw_tc={{acw_tc}}; cdn_sec_tc={{cdn_sec_tc}}; acw_sc__v2={{acw_sc_v2}}
+
+> {% client.log("status: " + response.status); %}
+
+### 环境变量（可在 HTTP Client Environment 中配置）
+@q=替换为实际长查询串
+@acw_tc=your_acw_tc
+@cdn_sec_tc=your_cdn_sec_tc
+@acw_sc_v2=your_acw_sc__v2
+```
+
+POST：
+```http
+### Weiyun 批量下载 POST 示例
+POST https://share.weiyun.com/webapp/json/weiyunShare/WeiyunShareBatchDownload?refer=chrome_mac&g_tk={{g_tk}}&r={{r}}
+accept: application/json, text/plain, */*
+content-type: application/json;charset=UTF-8
+origin: https://share.weiyun.com
+referer: https://share.weiyun.com/{{share_key}}
+user-agent: Mozilla/5.0 ...
+Cookie: uin={{uin}}; skey={{skey}}; p_skey={{p_skey}}; p_uin={{p_uin}}; wyctoken={{wyctoken}}
+
+{
+  "req_header": "{...}",
+  "req_body": "{...}"
+}
+```
+
+---
+
+## 5. 开发流程建议
+- 新增站点：在 impl 下新增 Tool，实现 IPanTool，复用 PanBase/模板类；补充单测。
+- 字段不全：尽量回填 sizeStr/createTime 等便于前端展示；不可用字段置空。
+- 单测：放置于 parser/src/test/java，尽量添加 1-2 个 happy path + 1 个边界用例。
+
+## 6. 常见问题
+- 容量解析失败：保留 sizeStr，并忽略 size；避免抛出异常影响整体列表。
+- 协议占位下载链接：统一放至 parserUrl，直链转换由下载阶段处理。
+- 鉴权：Cookie/Token 过期问题由上层刷新或外部注入处理；解析器保持无状态最佳。
+
+---
+
+## 7. 参考
+- 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