Crawlee项目中防止全局SDK方法在副作用自由上下文中被调用的检测机制

在Web爬虫开发中，Crawlee项目提供了一个强大的框架来处理各种爬取场景。最近项目中引入的AdaptivePlaywrightCrawler带来了一些新的技术挑战，特别是在处理存储操作时需要特别注意上下文环境。

问题背景

当开发者在使用AdaptivePlaywrightCrawler时，如果在请求处理函数中直接调用全局SDK方法如Actor.pushData，而不是使用相应的上下文辅助方法，会导致功能失效，甚至可能造成数据集损坏。这是因为自适应爬虫需要在特定上下文中管理存储操作，而直接调用全局方法会绕过这些管理机制。

技术解决方案

为了解决这个问题，我们设计了一套检测机制来警告或阻止开发者在错误上下文中调用存储方法：

1. 核心检测工具：在@crawlee/utils中新增checkStorageWrite辅助函数，配合AsyncLocalStorage实例(如storageWriteChecker)使用。这个实例包含一个回调函数，当检测到存储写入操作时会被触发。

2. 上下文隔离：当AdaptivePlaywrightCrawler调用请求处理函数时，会将其包裹在storageWriteChecker.run中，并设置一个抛出异常的回调函数。这确保了请求处理函数不能直接向存储写入数据。

3. 存储操作拦截：在MemoryStorage和ApifyClient的每个方法中添加checkStorageWrite调用，或者在StorageManager中通过动态方式(如猴子补丁)实现。更简单的方案是只在storages.Dataset等关键位置进行检查。

实现细节

这种机制利用了Node.js的AsyncLocalStorage特性，它能够在异步调用链中保持上下文状态。当爬虫执行请求处理函数时：

• 进入处理函数前，设置一个特定的存储写入检查上下文
• 任何尝试直接调用存储API的操作都会被检测到并阻止
• 只有通过爬虫提供的上下文辅助方法(commitResult)才能正常执行存储操作

开发者影响

对于使用Crawlee的开发者来说，这种机制意味着：

1. 更安全的代码：系统会自动检测并阻止可能导致数据损坏的操作模式
2. 更清晰的错误提示：当错误发生时，开发者会立即得到明确的反馈，而不是遇到难以调试的数据问题
3. 更好的实践引导：鼓励开发者使用框架推荐的上下文相关方法，而不是全局API

技术优势

这种解决方案具有几个显著优势：

1. 低侵入性：不需要大规模修改现有代码结构
2. 高性能：AsyncLocalStorage在现代Node.js版本中性能良好
3. 可扩展性：同样的机制可以应用于其他需要上下文隔离的场景
4. 开发友好：在开发阶段就能捕获问题，而不是等到运行时才发现数据异常

通过实现这种检测机制，Crawlee项目能够更好地支持AdaptivePlaywrightCrawler等高级功能，同时保持开发者体验和数据完整性。