如何解决ScriptCat中GM.xmlHttpRequest异步兼容性问题

如何解决ScriptCat中GM.xmlHttpRequest异步兼容性问题

【免费下载链接】scriptcatScriptCat, a browser extension that can execute userscript; 脚本猫，一个可以执行用户脚本的浏览器扩展项目地址: https://gitcode.com/gh_mirrors/sc/scriptcat

ScriptCat作为一款功能强大的用户脚本管理器，其核心目标之一就是提供与主流脚本管理器（如Tampermonkey）完全兼容的API接口。然而，在早期的版本中，我们遇到了一个关键的兼容性问题：GM.xmlHttpRequest API的异步处理机制与标准实现存在差异，导致某些依赖此API的用户脚本无法正常工作。

问题现象：为什么我的脚本无法获取数据？

很多用户在使用ScriptCat时可能会遇到这样的情况：一个在其他脚本管理器上运行良好的用户脚本，在ScriptCat中却无法正常获取远程数据并渲染页面内容。特别是在处理金融数据、社交媒体信息或其他需要从API获取数据的场景下，脚本可能会"静默失败"，页面上预期的数据表格或内容始终无法显示。

典型的问题场景

1. 雪球行情数据脚本：尝试获取股票行情数据，但页面始终空白
2. 社交媒体内容抓取：无法加载动态内容，脚本似乎"卡住"了
3. API数据展示：依赖外部API的脚本无法正确显示数据
4. 定时更新脚本：数据更新逻辑失效，页面内容陈旧

根本原因：Promise机制的缺失

通过深入分析用户反馈和代码实现，我们发现了问题的核心所在：ScriptCat的GM.xmlHttpRequest实现最初没有完全遵循标准的Promise处理机制。

技术差异对比

在标准的用户脚本生态中，GM.xmlHttpRequest应该返回一个Promise对象，允许开发者使用现代的async/await语法：

// 标准使用方式 try { const response = await GM.xmlHttpRequest({ method: 'GET', url: 'https://api.example.com/data', onload: (resp) => console.log(resp.responseText) }); // 处理响应数据 } catch (error) { // 错误处理 }

然而，ScriptCat的早期实现采用了回调函数模式，没有正确返回Promise对象。这导致当开发者使用await等待请求完成时，实际上并没有等待异步操作，脚本会立即继续执行后续代码。

异步执行的"时间差"问题

想象一下这样的场景：你去餐厅点餐，服务员记下你的订单后立即告诉你"菜已经准备好了"，但实际上厨房还没开始做。这就是ScriptCat早期版本中GM.xmlHttpRequest的行为——它立即"返回"，但实际的网络请求还在进行中。

解决方案：三步优化异步兼容性

为了解决这个问题，我们对ScriptCat的GM.xmlHttpRequest实现进行了全面的优化，确保与主流脚本管理器保持完全兼容。

第一步：重构Promise返回机制

我们在src/app/service/content/gm_api/gm_xhr.ts文件中重构了GM.xmlHttpRequest的核心逻辑。关键改进包括：

1. 统一返回类型：无论是否提供回调函数，都返回包含abort方法的控制对象
2. Promise封装：将原有的回调机制封装在Promise内部
3. 错误处理增强：确保异步错误能够正确传播

第二步：保持向后兼容性

在改进的同时，我们特别注重保持向后兼容性：

// 仍然支持传统的回调方式 GM.xmlHttpRequest({ method: 'GET', url: 'https://api.github.com/repos/scriptscat/scriptcat', onload: function(response) { console.log('请求成功:', response.status); }, onerror: function(error) { console.error('请求失败:', error); } }); // 同时支持Promise方式 const controller = GM.xmlHttpRequest({ method: 'GET', url: 'https://api.github.com/repos/scriptscat/scriptcat' }); // 可以使用await等待 try { await controller; console.log('请求完成'); } catch (error) { console.error('请求失败:', error); }

第三步：全面测试验证

我们在example/tests/gm_api_async_test.js中添加了完整的异步API测试用例，确保：

1. GET请求测试：验证基本的异步请求功能
2. Promise兼容性：确保await语法正常工作
3. 错误处理：验证异常情况的正确处理
4. 控制对象：确保abort方法可用

影响评估：改进带来的实际好处

这次优化不仅解决了一个技术问题，更重要的是提升了ScriptCat的整体用户体验和生态兼容性。

对用户脚本开发者的影响

1. 代码可移植性增强：开发者可以编写一次代码，在多个脚本管理器上运行
2. 开发体验改善：可以使用现代的async/await语法，代码更简洁易读
3. 错误处理更可靠：Promise机制提供了更好的错误捕获和处理能力

对普通用户的影响

1. 脚本兼容性提升：更多的第三方脚本可以在ScriptCat中正常运行
2. 功能稳定性增强：依赖网络请求的脚本不再出现"静默失败"
3. 使用门槛降低：无需担心脚本在不同管理器间的兼容性问题

对ScriptCat生态的影响

1. 社区信任度提升：展示了我们对API规范兼容性的重视
2. 开发者吸引力增强：更友好的开发环境吸引更多贡献者
3. 长期维护性改善：标准化的实现减少了未来的维护成本

技术实现细节

核心改进点

在src/app/service/content/gm_api/gm_xhr.ts中，我们对GM_xmlhttpRequest函数进行了关键修改：

export function GM_xmlhttpRequest( a: GMApi, details: GMTypes.XHRDetails, requirePromise: boolean, isDownload: boolean = false ) { // ... 参数验证和初始化 // 关键改进：统一返回包含Promise的控制对象 const retPromise = requirePromise ? new Promise((resolve, reject) => { retPromiseResolve = resolve; retPromiseReject = reject; }) : null; // ... 请求处理逻辑 return { retPromise, // 返回Promise对象 abort: () => { /* 中止逻辑 */ } }; }

异步测试用例

我们创建了全面的测试用例来验证改进效果：

// 测试GM.xmlHttpRequest的异步功能 await testAsync("GM.xmlHttpRequest - GET 请求", async () => { return new Promise((resolve, reject) => { GM.xmlHttpRequest({ method: "GET", url: "https://api.github.com/repos/scriptscat/scriptcat", timeout: 10000, onload: (response) => { assert(200, response.status, `请求状态码应该是 200`); assert(true, !!response.responseText, "响应内容不应为空"); resolve(); }, onerror: (error) => { reject(new Error("请求失败: " + error)); } }); }); });

使用建议和最佳实践

版本检查

建议用户更新到ScriptCat 1.3.2或更高版本，这些版本已经包含了完整的异步兼容性改进。

代码迁移指南

如果你现有的脚本在其他管理器中运行正常但在ScriptCat中有问题，可以：

1. 检查异步使用方式：确保正确使用await或Promise.then()
2. 添加错误处理：使用try-catch包装异步操作
3. 验证兼容性：使用我们提供的测试脚本验证API功能

开发建议

对于新脚本开发，我们建议：

1. 优先使用async/await：这是现代JavaScript的标准做法
2. 添加兼容性检查：可以在脚本开头检查GM.xmlHttpRequest的返回类型
3. 提供降级方案：对于关键功能，考虑提供回调函数作为备选

总结与展望

这次GM.xmlHttpRequest异步兼容性问题的解决，体现了ScriptCat项目对用户体验和生态建设的重视。我们不仅修复了一个技术问题，更重要的是建立了一套持续改进的机制：

1. 标准遵循：我们承诺严格遵循用户脚本API规范
2. 兼容性优先：确保与现有生态系统的无缝对接
3. 持续改进：通过用户反馈和自动化测试不断优化

ScriptCat将继续致力于为用户脚本开发者提供最稳定、最兼容的开发环境。如果你在使用过程中遇到任何兼容性问题，欢迎通过项目的问题追踪系统反馈，我们将第一时间响应和处理。

通过这次改进，ScriptCat进一步巩固了其作为现代化、专业化的用户脚本管理器的地位，为用户和开发者提供了更可靠、更强大的脚本运行平台。

【免费下载链接】scriptcatScriptCat, a browser extension that can execute userscript; 脚本猫，一个可以执行用户脚本的浏览器扩展项目地址: https://gitcode.com/gh_mirrors/sc/scriptcat