深入 domharvest-playwright：我如何构建一个生产就绪的网页抓取工具

抱歉，我目前无法直接访问外部链接获取文章内容。请您把需要翻译的文本粘贴在这里，我会按照您的要求将其翻译成简体中文并保留原有的格式。

核心架构

domharvest-playwright 基于三个主要组件构建：

• DOMHarvester Class – 主要协调者
• Browser Management – Playwright 生命周期管理
• Data Extraction Pipeline – 基于选择器的采集

设计原则

简单至上

每个架构决策都把简洁放在聪明之上。避免过度抽象，避免不必要的模式。

快速失败，明确失败

错误应当显而易见且可操作。不要出现静默失败。

可组合性

小而专注的方法，可组合以实现复杂的工作流。

浏览器生命周期管理

class DOMHarvester {
  async init(options = {}) {
    this.browser = await playwright.chromium.launch({
      headless: options.headless ?? true,
      ...options.browserOptions
    })
    this.context = await this.browser.newContext(options.contextOptions)
  }

  async close() {
    await this.context?.close()
    await this.browser?.close()
  }
}

为什么采用这种方法？

• 显式初始化让用户拥有控制权。
• 独立的上下文管理支持多个会话。
• 干净的关闭可防止资源泄漏。

Source: …

收割管道

核心的 harvest() 方法遵循一个直接的流程：

async harvest(url, selector, extractor) {
  const page = await this.context.newPage()

  try {
    await page.goto(url, { waitUntil: 'networkidle' })

    const elements = await page.$$(selector)
    const results = []

    for (const element of elements) {
      const data = await element.evaluate(extractor)
      results.push(data)
    }

    return results
  } finally {
    await page.close()
  }
}

关键决策

• waitUntil: 'networkidle' 在速度和可靠性之间取得平衡。
• 顺序处理可防止竞争条件。
• finally 块确保即使出现错误也能进行清理。
• 提取函数在浏览器上下文中运行，以提升性能。

错误处理策略

try {
  await page.goto(url, {
    waitUntil: 'networkidle',
    timeout: 30000
  })
} catch (error) {
  if (error.name === 'TimeoutError') {
    throw new Error(`Failed to load ${url}: timeout after 30s`)
  }
  throw error
}

我用带有上下文的特定信息包装 Playwright 错误，以帮助用户在不深入堆栈跟踪的情况下进行调试。

自定义提取支持

除了基于选择器的采集之外，harvestCustom() 允许任意页面评估：

async harvestCustom(url, evaluator) {
  const page = await this.context.newPage()

  try {
    await page.goto(url, { waitUntil: 'networkidle' })
    return await page.evaluate(evaluator)
  } finally {
    await page.close()
  }
}

这使得以下复杂场景成为可能：

• 多步骤交互
• 基于页面状态的条件逻辑
• 从多个来源聚合数据

测试架构

测试按关注点组织：

test/
├── unit/
│   ├── harvester.test.js
│   └── browser-management.test.js
├── integration/
│   └── harvest-workflow.test.js
└── fixtures/
    └── sample-pages/

使用真实的 HTML 固件而不是模拟，可确保测试捕获真实世界的问题。

性能考虑

页面复用 vs. 干净状态

我为每次抓取创建新页面以实现隔离。略有性能成本，但它消除了整类错误。

并行 vs. 顺序

顺序处理是默认的，以确保可预测性。用户如有需要可以在应用层面并行化。

内存管理

在 finally 块中显式清理页面，可防止长时间运行会话中的内存泄漏。

代码组织

src/
├── index.js          # Public API
├── harvester.js      # DOMHarvester class
└── utils/
    ├── validators.js # Input validation
    └── errors.js     # Custom error types

扁平结构，没有深层嵌套——易于导航。

Lessons Learned

1. 不要过早抽象 – 抵制了针对不同抓取模式的“Strategy Pattern”；YAGNI（You Aren’t Gonna Need It）是对的。
2. 显式 > 隐式 – 在使用前要求 init() 看似冗长，但能防止令人困惑的初始化错误。
3. 浏览器自动化是 I/O 密集型 – 网络延迟占主导；应关注可靠性而非微观优化。
4. 错误信息很重要 – 用户看到的错误多于代码；要让错误信息有帮助。

接下来是什么？

考虑中的未来架构改进：

• 用于自定义中间件的插件系统
• 带指数退避的内置重试逻辑
• 请求/响应拦截钩子
• 大数据集的流式结果

Try It Yourself

npm install domharvest-playwright

架构有意保持简洁。阅读源码——它不到 500 行。

链接

• GitHub 仓库
• 完整文档
• npm 包