异步函数生成器

函数定义

async function scrapeArticles(urls, { concurrency = 5, timeoutMs = 6000, cacheTTL = 600000, signal } = {})

• 参数说明

  • urls: string[]，待抓取的 URL 列表（仅支持 http/https）
  • concurrency: number，并发上限（默认 5）
  • timeoutMs: number，单请求超时毫秒数（默认 6000ms）
  • cacheTTL: number，内存缓存 TTL（默认 10 分钟 = 600000ms）
  • signal: AbortSignal，可选的外部取消信号，用于整体任务取消

• 返回值

  • Promise<{ list: Array<{ url: string; title: string | null; publishedAt: string | null; length: number }>, failed: Array<{ url: string; reason: string }> }>
  • list：去重后的成功结果集合（依据 canonical 或规范化 URL）
  • failed：失败的 URL 与失败原因

注意：若传入的 AbortSignal 触发，将尽可能中止正在执行的请求；函数不会抛错而是把已完成和失败的请求通过 allSettled 汇总并返回（失败中会标记 Abort）。

代码实现

// 模块级内存缓存（基于 TTL）。键为规范化 URL 或 canonical 规范化 URL。
const __articleCache = new Map(); // key -> { value, expiresAt }

/**
 * 规范化 URL：
 * - 只接受 http/https
 * - 小写协议与主机名，移除 hash
 * - 清理默认端口（:80 / :443）
 * - 规范路径（去除多余斜杠与根路径尾部斜杠）
 * - 搜索参数排序且移除常见追踪参数
 */
function normalizeUrl(input) {
  let u;
  try {
    u = new URL(input);
  } catch {
    throw new Error(`Invalid URL: ${input}`);
  }
  if (!/^https?:$/.test(u.protocol)) {
    throw new Error(`Unsupported protocol (only http/https): ${input}`);
  }
  u.protocol = u.protocol.toLowerCase();
  u.hostname = u.hostname.toLowerCase();

  // remove default ports
  if ((u.protocol === 'http:' && u.port === '80') || (u.protocol === 'https:' && u.port === '443')) {
    u.port = '';
  }

  // remove hash
  u.hash = '';

  // normalize path: collapse multiple slashes
  u.pathname = u.pathname.replace(/\/{2,}/g, '/');
  // remove trailing slash except root
  if (u.pathname.length > 1 && u.pathname.endsWith('/')) {
    u.pathname = u.pathname.slice(0, -1);
  }

  // clean & sort search params
  const trackingParams = new Set([
    'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
    'fbclid', 'gclid', 'yclid', 'mc_cid', 'mc_eid'
  ]);
  const params = Array.from(u.searchParams.entries())
    .filter(([k]) => !trackingParams.has(k.toLowerCase()))
    .sort(([a], [b]) => a.localeCompare(b));
  u.search = '';
  for (const [k, v] of params) u.searchParams.append(k, v);

  return u.toString();
}

/** 简易 HTML 实体解码（覆盖常见实体与数字实体） */
function decodeHtmlEntities(str) {
  if (!str) return str;
  const map = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
  return str
    .replace(/&(#\d+|#x[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, t) => {
      if (t[0] === '#') {
        const code = t[1].toLowerCase() === 'x' ? parseInt(t.slice(2), 16) : parseInt(t.slice(1), 10);
        if (!Number.isNaN(code)) return String.fromCodePoint(code);
        return m;
      }
      return map[t] ?? m;
    })
    .trim();
}

/** 从标签中提取纯文本（粗略移除内部标签） */
function stripTags(html) {
  return decodeHtmlEntities(
    html
      .replace(/<script[\s\S]*?<\/script>/gi, '')
      .replace(/<style[\s\S]*?<\/style>/gi, '')
      .replace(/<[^>]+>/g, ' ')
      .replace(/\s+/g, ' ')
      .trim()
  );
}

/** 获取首个匹配的开始/结束标签内容 */
function getFirstTagInnerHTML(html, tag) {
  const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`, 'i');
  const m = html.match(re);
  return m ? m[1] : null;
}

/** 解析 <title> 与 <h1> */
function extractTitle(html) {
  const titleRaw = getFirstTagInnerHTML(html, 'title');
  if (titleRaw) {
    const t = stripTags(titleRaw);
    if (t) return t;
  }
  const h1Raw = getFirstTagInnerHTML(html, 'h1');
  if (h1Raw) {
    const t = stripTags(h1Raw);
    if (t) return t;
  }
  return null;
}

/** 解析 <link rel="canonical" href="...">（返回相对或绝对 URL 字符串） */
function extractCanonical(html) {
  // 捕获所有 link 标签，解析 rel 和 href
  const links = html.match(/<link\b[^>]*>/gi) || [];
  for (const tag of links) {
    // 解析属性
    const attrs = {};
    tag.replace(/(\w[\w:-]*)\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+))/g, (_, name, _v, v1, v2, v3) => {
      attrs[name.toLowerCase()] = (v1 ?? v2 ?? v3 ?? '').trim();
      return _;
    });
    const rel = (attrs.rel || '').toLowerCase();
    if (rel.split(/\s+/).includes('canonical') && attrs.href) {
      return attrs.href.trim();
    }
  }
  return null;
}

/** 解析 meta[property="article:published_time"] 或 meta[name="article:published_time"] */
function extractPublishedTimeFromMeta(html) {
  const metas = html.match(/<meta\b[^>]*>/gi) || [];
  for (const tag of metas) {
    const attrs = {};
    tag.replace(/(\w[\w:-]*)\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+))/g, (_, name, _v, v1, v2, v3) => {
      attrs[name.toLowerCase()] = (v1 ?? v2 ?? v3 ?? '').trim();
      return _;
    });
    const prop = (attrs.property || attrs.name || '').toLowerCase();
    if (prop === 'article:published_time' && attrs.content) {
      return attrs.content.trim();
    }
  }
  return null;
}

/** 从首个 <p> 文本中尽力提取日期时间（支持 ISO 与常见中文格式） */
function extractPublishedTimeFromFirstParagraph(html) {
  const p = getFirstTagInnerHTML(html, 'p');
  if (!p) return null;
  const text = stripTags(p);

  // 1) 直接尝试 Date.parse 可识别格式（包含 ISO/RFC）
  const direct = Date.parse(text);
  if (!Number.isNaN(direct)) return new Date(direct).toISOString();

  // 2) 匹配 YYYY-MM-DD( HH:MM(:SS)?(Z|±HH:MM)?)
  const isoLike = text.match(/(\d{4})-(\d{1,2})-(\d{1,2})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2}))?(?:Z|([+-]\d{2}:?\d{2}))?)?/);
  if (isoLike) {
    const [ , Y, M, D, h='0', m='0', s='0', tz] = isoLike;
    const base = new Date(Date.UTC(+Y, +M - 1, +D, +h, +m, +s));
    if (tz && tz !== 'Z') {
      // 处理时区偏移
      const m2 = tz.match(/([+-]\d{2}):?(\d{2})/);
      if (m2) {
        const offsetMin = (parseInt(m2[1], 10) * 60) + parseInt(m2[2], 10);
        // UTC = local - offset => 已按 UTC 构建了 base，无需额外处理
        // 但 isoLike 在无 tz 时按 UTC 处理；有 tz 时我们已用 UTC 构造，再按 offset 调整
        base.setUTCMinutes(base.getUTCMinutes() - offsetMin);
      }
    }
    return base.toISOString();
  }

  // 3) 中文日期：YYYY年MM月DD日 HH:MM(:SS)?
  const zh = text.match(/(\d{4})年(\d{1,2})月(\d{1,2})日(?:\s+(\d{1,2}):(\d{2})(?::(\d{2}))?)?/);
  if (zh) {
    const [ , Y, M, D, h='0', m='0', s='0'] = zh;
    const d = new Date(+Y, +M - 1, +D, +h, +m, +s);
    return new Date(d.getTime()).toISOString();
  }

  return null;
}

/** 提取 HTML 信息：title、canonical、publishedAt（ISO string 或 null） */
function parseHtml(html, baseUrl) {
  const title = extractTitle(html);

  let publishedAt = extractPublishedTimeFromMeta(html);
  if (publishedAt) {
    const ts = Date.parse(publishedAt);
    publishedAt = Number.isNaN(ts) ? null : new Date(ts).toISOString();
  } else {
    publishedAt = extractPublishedTimeFromFirstParagraph(html);
  }

  const canonicalHref = extractCanonical(html);
  let canonical = null;
  if (canonicalHref) {
    try {
      const abs = new URL(canonicalHref, baseUrl).toString();
      canonical = abs;
    } catch {
      // ignore bad canonical
    }
  }

  return { title, canonical, publishedAt };
}

/** TTL 缓存：读取 */
function cacheGet(key) {
  const hit = __articleCache.get(key);
  if (hit && hit.expiresAt > Date.now()) return hit.value;
  if (hit) __articleCache.delete(key);
  return null;
}

/** TTL 缓存：写入 */
function cacheSet(key, value, ttl) {
  __articleCache.set(key, { value, expiresAt: Date.now() + ttl });
}

/** 组合多个 AbortSignal（支持 AbortSignal.any 的环境；无则降级） */
function combineSignals(signals) {
  const valid = signals.filter(Boolean);
  if (valid.length === 0) return undefined;
  if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.any === 'function') {
    return AbortSignal.any(valid);
  }
  const controller = new AbortController();
  const onAbort = (e) => {
    try { controller.abort(e?.target?.reason); } catch { controller.abort(); }
    cleanup();
  };
  const cleanup = () => valid.forEach(s => s.removeEventListener('abort', onAbort));
  let alreadyAborted = false;
  for (const s of valid) {
    if (s.aborted) {
      alreadyAborted = true;
      try { controller.abort(s.reason); } catch { controller.abort(); }
      break;
    }
  }
  if (!alreadyAborted) valid.forEach(s => s.addEventListener('abort', onAbort, { once: true }));
  return controller.signal;
}

/** 基于并发的 limiter */
function createLimiter(limit, outerSignal) {
  let active = 0;
  const queue = [];
  const runNext = () => {
    if (outerSignal?.aborted) return;
    if (active >= limit || queue.length === 0) return;
    const task = queue.shift();
    active++;
    task().finally(() => {
      active--;
      runNext();
    });
  };
  return (fn) => new Promise((resolve) => {
    const wrapped = () => fn().then(resolve, resolve); // 将错误留待 allSettled 处理
    queue.push(wrapped);
    runNext();
  });
}

/** 单 URL 抓取与解析 */
async function fetchOne(originalUrl, { timeoutMs, cacheTTL, outerSignal }) {
  const normInput = normalizeUrl(originalUrl);

  // 命中缓存
  const cached = cacheGet(normInput);
  if (cached) return cached;

  // 每请求单独超时控制
  const timeoutCtrl = new AbortController();
  const tId = setTimeout(() => {
    try { timeoutCtrl.abort(new Error('Timeout')); } catch { timeoutCtrl.abort(); }
  }, timeoutMs);

  const combinedSignal = combineSignals([timeoutCtrl.signal, outerSignal]);

  try {
    const res = await fetch(originalUrl, {
      method: 'GET',
      headers: {
        'Accept': 'text/html,application/xhtml+xml;q=0.9,*/*;q=0.8',
        // 可选 UA，部分站点对默认 UA 严格
        'User-Agent': 'scrapeArticles/1.0 (+https://example.com)'
      },
      redirect: 'follow',
      // gzip/br/deflate 由 fetch 实现自动协商与解压
      signal: combinedSignal
    });

    if (!res.ok) {
      throw new Error(`HTTP ${res.status} ${res.statusText}`);
    }

    const finalUrl = res.url || originalUrl;
    const html = await res.text();

    const { title, canonical, publishedAt } = parseHtml(html, finalUrl);

    // 使用 canonical 或最终跳转后的 URL 进行规范化
    const finalNorm = normalizeUrl(canonical ? new URL(canonical, finalUrl).toString() : finalUrl);

    const result = {
      url: finalNorm,
      title: title || null,
      publishedAt: publishedAt || null,
      // 以字符长度衡量，如需字节可用 Buffer.byteLength(html, 'utf8')（Node 环境）
      length: html.length
    };

    // 写入缓存（输入规范化 URL 与 canonical 规范化 URL 都写入，提升命中率）
    cacheSet(normInput, result, cacheTTL);
    cacheSet(finalNorm, result, cacheTTL);

    return result;
  } finally {
    clearTimeout(tId);
  }
}

/**
 * 主函数：批量抓取文章标题与时间（限流、超时、缓存、去重、allSettled 汇总）
 */
async function scrapeArticles(urls, { concurrency = 5, timeoutMs = 6000, cacheTTL = 600000, signal } = {}) {
  if (!Array.isArray(urls)) throw new Error('urls must be an array of strings');
  if (concurrency <= 0) throw new Error('concurrency must be > 0');

  // 预过滤非法/重复输入（按规范化 URL 去重）
  const uniqueInputs = [];
  const seen = new Set();
  for (const u of urls) {
    if (typeof u !== 'string' || !u.trim()) continue;
    try {
      const n = normalizeUrl(u);
      if (!seen.has(n)) {
        seen.add(n);
        uniqueInputs.push({ original: u, normalized: n });
      }
    } catch {
      // 跳过非法 URL（最终会在 failed 中体现）
      uniqueInputs.push({ original: u, normalized: null });
    }
  }

  const limiter = createLimiter(concurrency, signal);
  const tasks = uniqueInputs.map(({ original, normalized }) =>
    limiter(async () => {
      if (!normalized) {
        // 预规范化失败
        return { status: 'rejected', reason: new Error('Invalid URL'), original };
      }
      try {
        const value = await fetchOne(original, { timeoutMs, cacheTTL, outerSignal: signal });
        return { status: 'fulfilled', value, original };
      } catch (err) {
        return { status: 'rejected', reason: err, original };
      }
    })
  );

  // 等待任务全部 settle（内部每项已包装为 fulfilled/rejected 结构）
  const settled = await Promise.all(tasks);

  // 汇总：去重（基于 canonical 或规范化 URL）
  const finalList = [];
  const finalFailed = [];

  const dedupe = new Set();
  for (const s of settled) {
    if (s.status === 'fulfilled') {
      const item = s.value;
      const key = normalizeUrl(item.url);
      if (!dedupe.has(key)) {
        dedupe.add(key);
        finalList.push(item);
      }
    } else {
      const reason = s.reason;
      const msg = (reason && (reason.message || String(reason))) || 'Unknown error';
      finalFailed.push({
        url: s.original,
        reason: msg
      });
    }
  }

  return { list: finalList, failed: finalFailed };
}

错误处理

• 输入校验：urls 必须为字符串数组；concurrency > 0；不支持非 http/https 协议
• 超时控制：每个请求通过 AbortController 实现 timeoutMs 超时，中止 fetch
• 取消控制：可接收外部 AbortSignal；与超时信号组合，任一触发即中止请求
• 网络/HTTP 错误：非 2xx/3xx 响应抛出 HTTP 错误并记入 failed
• HTML 解析容错：采用健壮的正则提取，若 title 或时间缺失，返回 null 而非抛错
• 缓存过期：TTL 到期自动清理；命中后直接返回缓存结果，减少重复请求

注意：函数最终使用 allSettled 风格汇总，无论个别请求失败或被中止，均返回 { list, failed }，不会整体抛错（除非参数校验失败）。

使用示例

(async () => {
  const urls = [
    'https://example.com/article/123',
    'https://example.com/article/123?utm_source=twitter',
    'https://blog.example.org/post/abc',
    'https://news.example.com/path#section',
    'invalid-url'
  ];

  const controller = new AbortController();
  // 可选：在 10 秒后取消整个批量任务
  // setTimeout(() => controller.abort(new Error('User aborted')), 10000);

  const { list, failed } = await scrapeArticles(urls, {
    concurrency: 4,
    timeoutMs: 6000,
    cacheTTL: 10 * 60 * 1000,
    signal: controller.signal
  });

  console.log('Success:', list);
  console.log('Failed:', failed);
})();

• 预期输出说明
  • list 中每项包含：
    • url：canonical 规范化 URL（若页面提供），否则为最终跳转后的规范化 URL
    • title：页面标题或首个 h1（若 title 缺失）
    • publishedAt：优先取 meta[property="article:published_time"]，否则尝试从首个段落解析时间（ISO 字符串）
    • length：HTML 文本的字符长度
  • failed 包含无法请求/解析的 URL 与失败原因（如超时、HTTP 错误、无效 URL、被取消等）

技术要点

• 并发控制：自实现轻量 limiter，避免额外依赖；保证同一时间最多 concurrency 个请求
• 取消与超时：使用 AbortController；通过 combineSignals 合并外部 signal 与超时 signal，任一触发即中断 fetch
• allSettled 汇总：每个任务内部已包裹为 fulfilled/rejected 结构，最终统一汇总为 { list, failed }
• 去重策略：优先使用页面 canonical 链接规范化；无 canonical 时以最终跳转 URL 的规范化结果为去重键
• 规范化 URL：去除 hash、处理默认端口、排序查询参数、清理常见追踪参数，尽量将等价 URL 归一
• 内存缓存（TTL）：输入规范化 URL 与 canonical 规范化 URL 同步写入缓存，提升命中率；减少重复抓取与压力
• 解析策略：
  • 标题：先取