WebExtensions开发进阶：Declarative Net Request API拦截网络请求实战

【免费下载链接】webextensionsCharter and administrivia for the WebExtensions Community Group (WECG)项目地址: https://gitcode.com/gh_mirrors/we/webextensions

Declarative Net Request API是WebExtensions开发中的强大工具，它允许开发者通过声明式规则来拦截和修改网络请求。本文将为你提供一个完整的实战指南，帮助你快速掌握这一API的使用方法。

一、什么是Declarative Net Request API？

Declarative Net Request API是WebExtensions API的一部分，它提供了一种声明式的方式来拦截和修改网络请求。与传统的webRequest API相比，它具有更高的性能和更强的安全性。

使用Declarative Net Request API，开发者可以定义一系列规则，这些规则会被浏览器高效地执行。这些规则可以用于阻止广告、跟踪器，修改请求头，重定向请求等。

二、开始使用Declarative Net Request API

2.1 配置manifest.json

要使用Declarative Net Request API，首先需要在manifest.json中添加相应的权限和配置。

{ "manifest_version": 3, "name": "我的网络请求拦截器", "version": "1.0", "permissions": ["declarativeNetRequest", "declarativeNetRequestWithHostAccess"], "declarative_net_request": { "rule_resources": [ { "id": "ruleset_1", "enabled": true, "path": "rules.json" } ] } }

在这个配置中，我们声明了需要使用的权限，并定义了一个规则集。规则集包含一个唯一的ID、是否启用以及规则文件的路径。

2.2 创建规则文件

接下来，我们需要创建规则文件。在上面的配置中，我们指定了规则文件的路径为"rules.json"。下面是一个简单的规则文件示例：

[ { "id": 1, "priority": 1, "condition": { "urlFilter": "||example.com/*", "resourceTypes": ["script", "image"] }, "action": { "type": "block" } } ]

这个规则会阻止所有来自example.com的脚本和图片请求。

三、规则的结构和类型

3.1 规则的基本结构

每个规则由以下几个部分组成：

• id: 规则的唯一标识符，必须是大于等于1的整数。
• priority: 规则的优先级，默认为1，数值越大优先级越高。
• condition: 规则的触发条件。
• action: 当规则被触发时执行的操作。

3.2 条件(condition)的属性

条件部分可以包含以下属性：

• urlFilter: 用于匹配请求URL的模式。
• regexFilter: 用于匹配请求URL的正则表达式。
• isUrlFilterCaseSensitive: urlFilter或regexFilter是否区分大小写。
• initiatorDomains: 规则仅匹配来自这些域名的请求。
• excludedInitiatorDomains: 规则不匹配来自这些域名的请求。
• requestDomains: 规则仅匹配这些域名的请求。
• excludedRequestDomains: 规则不匹配这些域名的请求。
• resourceTypes: 规则匹配的资源类型列表。
• excludedResourceTypes: 规则不匹配的资源类型列表。
• requestMethods: 规则匹配的HTTP请求方法列表。
• excludedRequestMethods: 规则不匹配的HTTP请求方法列表。
• domainType: 指定请求是第一方还是第三方。
• tabIds: 规则匹配的标签ID列表。
• excludedTabIds: 规则不匹配的标签ID列表。

3.3 操作(action)的类型

操作类型包括：

• block: 阻止请求。
• redirect: 重定向请求。
• allow: 允许请求。
• upgradeScheme: 将HTTP请求升级为HTTPS。
• modifyHeaders: 修改请求头或响应头。
• allowAllRequests: 允许所有请求。

四、动态规则和会话规则

除了在manifest.json中定义的静态规则外，Declarative Net Request API还支持动态规则和会话规则。

4.1 动态规则

动态规则可以在运行时添加和删除，并且会在浏览器会话之间保持。使用updateDynamicRules方法可以更新动态规则：

chrome.declarativeNetRequest.updateDynamicRules({ removeRuleIds: [1, 2], addRules: [ { id: 3, priority: 1, condition: { urlFilter: "||example.net/*", resourceTypes: ["script"] }, action: { type: "block" } } ] }, () => { console.log("动态规则已更新"); });

4.2 会话规则

会话规则也可以在运行时添加和删除，但不会在浏览器会话之间保持。使用updateSessionRules方法可以更新会话规则：

chrome.declarativeNetRequest.updateSessionRules({ removeRuleIds: [3], addRules: [ { id: 4, priority: 2, condition: { urlFilter: "||example.org/*", resourceTypes: ["image"] }, action: { type: "block" } } ] }, () => { console.log("会话规则已更新"); });

五、高级用法：修改请求头和响应头

Declarative Net Request API不仅可以阻止和重定向请求，还可以修改请求头和响应头。下面是一个修改请求头的示例：

{ "id": 5, "priority": 1, "condition": { "urlFilter": "||example.com/*", "resourceTypes": ["main_frame"] }, "action": { "type": "modifyHeaders", "requestHeaders": [ { "header": "User-Agent", "operation": "set", "value": "My Custom User Agent" } ] } }

这个规则会将所有访问example.com的主框架请求的User-Agent头设置为"My Custom User Agent"。

六、测试和调试规则

为了帮助开发者测试和调试规则，Declarative Net Request API提供了testMatchOutcome方法。这个方法可以检查一个假设的请求是否会被任何规则匹配：

chrome.declarativeNetRequest.testMatchOutcome({ url: "https://example.com/script.js", type: "script" }, (result) => { console.log("匹配的规则:", result.matchedRules); });

此外，API还提供了isRegexSupported方法来检查一个正则表达式是否被支持：

chrome.declarativeNetRequest.isRegexSupported({ regex: "^https://example\\.com/.*$" }, (result) => { if (result.isSupported) { console.log("正则表达式被支持"); } else { console.log("正则表达式不被支持，原因:", result.reason); } });

七、性能和限制

虽然Declarative Net Request API非常强大，但也有一些性能考虑和限制需要注意：

• 静态规则、动态规则和会话规则都有各自的数量限制。
• 正则表达式规则也有数量限制，并且某些复杂的正则表达式可能不被支持。
• 规则的优先级很重要，高优先级的规则会覆盖低优先级的规则。

关于具体的限制数值，可以参考API的属性，如MAX_NUMBER_OF_STATIC_RULESETS、MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES等。

八、总结

Declarative Net Request API为WebExtensions开发者提供了一种高效、安全的方式来拦截和修改网络请求。通过本文的介绍，你应该已经掌握了该API的基本使用方法和一些高级技巧。

无论是开发广告拦截器、隐私保护工具，还是其他需要控制网络请求的扩展，Declarative Net Request API都是一个非常有价值的工具。希望本文能够帮助你更好地利用这一API，开发出功能强大的WebExtensions扩展。

要开始使用Declarative Net Request API，你可以克隆WebExtensions项目仓库：https://gitcode.com/gh_mirrors/we/webextensions，其中包含了丰富的API文档和示例代码，如接口定义文件interfaces/firefox/schemas/declarative_net_request.json。

祝你在WebExtensions开发的道路上取得成功！🚀

【免费下载链接】webextensionsCharter and administrivia for the WebExtensions Community Group (WECG)项目地址: https://gitcode.com/gh_mirrors/we/webextensions