{"record":{"id":"69fe49c3a737703c","repo":"hmjz100/LinkSwift","slug":"extra","errorCode":null,"errorMessage":"extra 缺少内容。","messagePattern":"extra 缺少内容。","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"（改）网盘直链下载助手.user.js","lineNumber":1345,"sourceCode":"\t\t/**\r\n\t\t * 下载文件\r\n\t\t * @author hmjz100\r\n\t\t * @description 发送 GET 请求，一般用于文件下载，支持进度监控、自动重试、断点续传、非断回退\r\n\t\t * @param {String} url - 请求地址\r\n\t\t * @param {Object} headers - 请求头配置\r\n\t\t * @param {Number} [size=0] - 响应类型\r\n\t\t * @param {Object} [extra] - 附加参数（必须 `name`、`index`、`size` 属性；可选 `thread`、`retry` 属性）\r\n\t\t * @returns {Promise} 包含响应数据的 `Promise` 对象\r\n\t\t */\r\n\t\tasync download(url, headers, extra) {\r\n\t\t\theaders = this.standHeaders(headers);\r\n\t\t\t// 初始化全局共享状态\r\n\t\t\tthis.download.active = this.download.active || 0; // 全局活跃线程数\r\n\t\t\tthis.download.taskCount = this.download.taskCount || 0; // 当前正在运行的 download 任务数\r\n\t\t\tconst global_maxThreads = 10; // 整个允许的最大并发数\r\n\r\n\t\t\tif (extra) base.console.info(`【LinkSwift】Download\\n收到数据：`, extra);\r\n\t\t\tif (!extra || !extra.index || !extra.name || !extra.size) throw new Error(\"extra 缺少内容。\");\r\n\r\n\t\t\tconst status = {\r\n\t\t\t\taborted: false,\r\n\t\t\t\trequests: new Set(),\r\n\t\t\t\tresults: [],\r\n\t\t\t\tactive: 0,\r\n\t\t\t\tmaxSpeed: 0,\r\n\t\t\t\tlastSampleTime: Date.now(),\r\n\t\t\t\tlastSampleLoaded: 0,\r\n\t\t\t\tcurrentSpeed: 0,\r\n\t\t\t\ttotalLoaded: 0\r\n\t\t\t};\r\n\r\n\t\t\tconst promise = new Promise((resolve, reject) => {\r\n\t\t\t\t(async () => {\r\n\t\t\t\t\tthis.download.taskCount++; // 任务进入\r\n\r\n\t\t\t\t\ttry {\r","sourceCodeStart":1327,"sourceCodeEnd":1363,"githubUrl":"https://github.com/hmjz100/LinkSwift/blob/417ea5e28a3e1a90339710e17356e9fd22b8a34b/（改）网盘直链下载助手.user.js#L1327-L1363","documentation":"Thrown by the concurrent download manager (网盘直链下载助手.user.js:1345) when the caller passes an `extra` object that is missing or lacks the required fields `index`, `name`, and `size`. These fields drive task queueing and progress accounting, so the download is refused before starting. It is a strict input-shape validation of the download task descriptor.","triggerScenarios":"Calling the chunked download function with `extra` being undefined/null, or an object missing any of `index`, `name`, or `size` — e.g. building the descriptor manually from a file-list parser that omitted `size`, or passing an entry whose fields use different names (e.g. `fileName` instead of `name`).","commonSituations":"Custom/modified script forks that feed download tasks from a differently shaped data source; a network drive listing API change that returns items without `size`; calling the downloader programmatically with a partially initialized task object.","solutions":["Ensure every task passed to the downloader includes non-empty `index`, `name`, and `size` fields.","Normalize the data source: map API/parse results into the expected shape before calling the downloader.","Log/guard the upstream list construction; filter out entries lacking these fields before enqueueing.","If fields use alternate names, rename them to match the expected descriptor (`name`, `size`, `index`)."],"exampleFix":"// before\nnetdisk.download({ extra: { index: i, fileName: item.server_filename } })\n\n// after\nnetdisk.download({ extra: { index: i, name: item.server_filename, size: Number(item.size) } })","handlingStrategy":"validation","validationCode":"function isValidDownloadExtra(extra) {\n  return !!extra && Number.isInteger(extra.index) && typeof extra.name === \"string\" && extra.name.length > 0 && typeof extra.size === \"number\" && extra.size > 0;\n}\n// call only if isValidDownloadExtra(extra)","typeGuard":"function isDownloadExtra(x) {\n  return typeof x === \"object\" && x !== null\n    && \"index\" in x && \"name\" in x && \"size\" in x\n    && typeof x.index === \"number\" && typeof x.name === \"string\" && typeof x.size === \"number\";\n}","tryCatchPattern":"try {\n  await downloader.download({ extra });\n} catch (e) {\n  if (String(e.message).includes(\"extra 缺少内容\")) {\n    console.error(\"任务描述缺少 index/name/size:\", extra); // fix the descriptor source\n  } else throw e;\n}","preventionTips":["Normalize every file entry into { index, name, size } before enqueueing downloads.","Validate the upstream file-list response shape (especially that size exists) before mapping to tasks.","Filter out malformed entries with a guard function instead of passing them through.","When modifying the script or its data source, re-check the expected `extra` field names (name/size, not fileName/fileSize)."],"tags":["validation","missing-field","download"],"backgroundTag":"missing-required-argument","analyzedSha":"417ea5e28a3e1a90339710e17356e9fd22b8a34b","analyzedAt":"2026-09-02T18:13:32.837Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}