JavaScript回调函数生成器

函数定义

/**
 * onUploadFinished
 * 异步上传完成后的回调函数（Promise 风格），对参数进行严格校验并提供增强的错误处理。
 *
 * 约定：
 * - 若 err 存在则立刻短路（不再处理 result），并返回一个被拒绝的 Promise。
 * - 若 result 存在则校验 result.url 必须以 "https://" 开头，result.size 必须为正数。
 * - durationMs（上传耗时，毫秒）可选，若提供必须为非负有限数。
 *
 * @param {Error|null} err - 必填。错误对象；若不为 null/undefined 即表示上传失败。
 * @param {{url: string, size: number}|undefined|null} result - 选填。上传结果对象，包含资源 URL 与大小。
 * @param {number|undefined|null} durationMs - 选填。上传耗时（毫秒）。
 * @returns {Promise<void>} - Promise<void>，成功时 resolve；校验失败或上传失败时 reject。
 */
async function onUploadFinished(err, result, durationMs) {
  // --- 基本参数存在性与类型校验 ---
  if (typeof err === 'undefined') {
    throw new TypeError('缺少必填参数 "err"（Error|null）。');
  }

  // 若存在错误则短路：不再处理 result，直接拒绝 Promise
  if (err !== null && err !== undefined) {
    const isValidDuration =
      typeof durationMs === 'number' && Number.isFinite(durationMs) && durationMs >= 0;

    const normalized = err instanceof Error
      ? err
      : new Error(`上传失败${isValidDuration ? `（耗时 ${durationMs} ms）` : ''}：${String(err)}`);

    // 为调试增强上下文信息（不影响错误堆栈）
    if (isValidDuration) {
      // 附加只读上下文，避免污染原型链或引入安全风险
      Object.defineProperty(normalized, 'context', {
        value: { durationMs },
        enumerable: false,
        configurable: false,
        writable: false
      });
    }

    throw normalized; // async 函数中 throw => 返回被拒绝的 Promise
  }

  // 校验 durationMs（若提供）
  if (durationMs !== undefined && durationMs !== null) {
    if (typeof durationMs !== 'number' || !Number.isFinite(durationMs) || durationMs < 0) {
      throw new TypeError('参数 "durationMs" 必须为非负的有限数。');
    }
  }

  // 若 result 未提供，按约定可正常结束（无更多信息可处理）
  if (result === undefined || result === null) {
    return;
  }

  // --- 对 result 的结构与字段进行严格校验 ---
  if (typeof result !== 'object' || Array.isArray(result)) {
    throw new TypeError('参数 "result" 必须为对象 { url: string, size: number }。');
  }

  const { url, size } = result;

  if (typeof url !== 'string') {
    throw new TypeError('result.url 必须为字符串。');
  }

  const trimmedUrl = url.trim();
  if (!trimmedUrl.startsWith('https://')) {
    throw new Error('result.url 必须以 "https://" 开头。');
  }

  // 进一步保证 URL 合法性（防止不可解析的 URL）
  try {
    // 若不可解析将抛错
    new URL(trimmedUrl);
  } catch {
    throw new Error('result.url 不是一个可解析的合法 URL。');
  }

  if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0) {
    throw new TypeError('result.size 必须为一个大于 0 的有限数。');
  }

  // 至此所有校验通过；此处可以安全地进行后续异步处理（如统计/通知等）
  // 该示例不做外部副作用以避免环境不兼容，仅完成回调职责。
  return;
}

参数说明

• err
  • 类型：Error|null（必填）
  • 作用：表示上传是否失败。若不为 null/undefined，则视为失败并短路，立即返回被拒绝的 Promise。
• result
  • 类型：object（选填），结构为 { url: string, size: number }
  • 作用：上传成功的结果。
  • 校验：url 必须以 "https://" 开头且可被 URL 解析；size 必须为大于 0 的有限数。
• durationMs
  • 类型：number（选填）
  • 作用：上传耗时（毫秒）。
  • 校验：若提供，必须为非负的有限数。

使用示例

// 示例 1：在 async/await 流程中使用
async function handleUpload() {
  try {
    // 假设外部上传得到如下结果
    const err = null;
    const result = { url: 'https://cdn.example.com/file.png', size: 24567 };
    const durationMs = 1320;

    await onUploadFinished(err, result, durationMs);
    console.log('上传完成并通过校验，后续处理...');
  } catch (e) {
    console.error('上传失败或结果不合法：', e);
    // 根据业务进行错误上报/提示等
  }
}

// 示例 2：上传失败的场景
onUploadFinished(new Error('网络异常'), null, 980)
  .then(() => {
    // 正常不会进到这里，因为会被拒绝
  })
  .catch((e) => {
    console.error('捕获到失败：', e);
  });

// 示例 3：与传统回调风格库配合（确保消费返回的 Promise，避免未处理的拒绝）
function someUploadLibrary(file, cb) {
  // 模拟：1 秒后触发回调
  setTimeout(() => {
    cb(null, { url: 'https://cdn.example.com/a.mp4', size: 1024 * 1024 }, 1000);
  }, 1000);
}

someUploadLibrary({/* ... */}, (err, result, durationMs) => {
  // 一定要消费 Promise（then/catch 或 await），避免未处理的 Promise 拒绝
  onUploadFinished(err, result, durationMs)
    .then(() => {
      console.log('库回调处理成功');
    })
    .catch((e) => {
      console.error('库回调处理失败：', e);
    });
});

注意事项

• 函数返回 Promise，请务必使用 await 或 .then/.catch 消费返回的 Promise，避免产生未处理的 Promise 拒绝。
• 当 err 存在时会短路并拒绝 Promise；result 在该情况下会被忽略。
• URL 校验要求以 https 开头并可被 URL 构造器解析；请确保上传服务返回的是合法的 HTTPS 地址。
• size 必须为正数且有限；durationMs（若提供）必须为非负有限数。
• 函数不引入外部副作用（如网络请求或环境特定操作），以保证在浏览器与 Node.js 环境均可安全使用。

函数定义

/**
 * onCsvParsed
 * 回调函数：在CSV解析完成后执行，进行基础参数校验与警告处理。
 *
 * 约束校验：
 * - summary.rows 必须等于 records.length
 * - summary.columns 必须为 > 0 的正整数
 *
 * 返回：
 * - { ok: boolean }：校验成功为 true，失败为 false
 *
 * @param {string[]} records - 必填。CSV的每一行字符串组成的数组。
 * @param {{rows:number, columns:number}} summary - 必填。解析结果摘要信息。
 * @param {string[]} [warnings] - 选填。解析过程中产生的警告信息列表。
 * @returns {{ok:boolean}}
 */
function onCsvParsed(records, summary, warnings) {
  'use strict';

  try {
    // 参数基本类型校验
    if (!Array.isArray(records)) {
      console.error('[onCsvParsed] 参数错误：records 必须为数组。');
      return { ok: false };
    }

    // records 元素类型校验（string[]）
    const invalidRecordIndex = records.findIndex(r => typeof r !== 'string');
    if (invalidRecordIndex !== -1) {
      console.error(`[onCsvParsed] 参数错误：records[${invalidRecordIndex}] 不是字符串。`);
      return { ok: false };
    }

    // summary 结构与数值校验
    if (summary == null || typeof summary !== 'object') {
      console.error('[onCsvParsed] 参数错误：summary 必须为对象。');
      return { ok: false };
    }

    const { rows, columns } = summary;

    if (!Number.isInteger(rows) || rows < 0) {
      console.error('[onCsvParsed] 参数错误：summary.rows 必须为非负整数。');
      return { ok: false };
    }

    if (!Number.isInteger(columns) || columns <= 0) {
      console.error('[onCsvParsed] 参数错误：summary.columns 必须为大于 0 的正整数。');
      return { ok: false };
    }

    // 业务校验：rows 等于 records.length
    if (rows !== records.length) {
      console.error(
        `[onCsvParsed] 校验失败：summary.rows(${rows}) 与 records.length(${records.length}) 不一致。`
      );
      return { ok: false };
    }

    // warnings 选填校验与处理
    if (warnings !== undefined) {
      if (!Array.isArray(warnings)) {
        console.error('[onCsvParsed] 参数错误：warnings（若提供）必须为字符串数组。');
        return { ok: false };
      }
      const invalidWarningIndex = warnings.findIndex(w => typeof w !== 'string');
      if (invalidWarningIndex !== -1) {
        console.error(`[onCsvParsed] 参数错误：warnings[${invalidWarningIndex}] 不是字符串。`);
        return { ok: false };
      }

      if (warnings.length > 0) {
        // 基础级别处理：输出警告日志
        console.warn('[onCsvParsed] 警告：', warnings.join(' | '));
      }
    }

    // 所有校验通过
    return { ok: true };
  } catch (err) {
    // 基础错误处理：捕获异常并输出日志
    console.error('[onCsvParsed] 执行异常：', err);
    return { ok: false };
  }
}

参数说明

• records (array, 必填, string[]): CSV解析得到的每一行字符串的数组。必须是纯字符串数组。
• summary (object, 必填, { rows:number, columns:number }): 解析摘要信息。
  • rows: 解析到的行数，必须为非负整数，且必须等于 records.length。
  • columns: 每行的列数，必须为大于 0 的正整数。
• warnings (string[], 选填): 解析过程中产生的文本警告信息列表。若提供，必须为字符串数组。

使用示例

// 假设 parseCsv 是某个解析函数，解析完成后调用回调 onCsvParsed
function parseCsv(csvText, callback) {
  // 伪代码：按行拆分
  const lines = csvText.split('\n').map(s => s.trim()).filter(Boolean);

  // 简单计算列数（以第一行的逗号数量 + 1 为列数）
  const columns = lines.length > 0 ? (lines[0].split(',').length) : 0;

  // 模拟警告：如果存在空行或列数不一致
  const warnings = [];
  const inconsistentRowIndex = lines.findIndex(
    line => line.split(',').length !== columns
  );
  if (inconsistentRowIndex !== -1) {
    warnings.push(`第 ${inconsistentRowIndex + 1} 行列数不一致`);
  }

  const summary = { rows: lines.length, columns };

  // 调用回调进行校验
  const result = callback(lines, summary, warnings);
  return result;
}

// 使用演示
const csv = 'a,b,c\n1,2,3\nx,y,z';
const result = parseCsv(csv, onCsvParsed);

if (result.ok) {
  console.log('CSV 解析与校验成功。');
} else {
  console.log('CSV 解析或校验失败，请检查输入与摘要信息。');
}

注意事项

• 本回调为同步执行，返回简单的 {ok:boolean}。若需要异步处理（如网络上报），请在外层封装为 Promise 或使用异步API。
• 参数校验为基础级别，默认通过 console 输出错误与警告，不会抛出异常以避免中断调用方流程。
• 请确保传入的 summary 与 records 来源一致，尤其是 rows 与 records.length 的一致性。
• columns 的计算应在解析阶段完成并保证为正整数；当列数为 0 时视为非法输入。
• 函数不修改传入的 records 与 warnings，若需要清洗数据，请在解析阶段或另行处理。