背景：

由于插件v3改版，必须废弃webRequest API，替换成declarativeNetRequest API，而该API的说明文档过长，阅读理解都需要大量时间，因此将其做个梳理。

API简介：

chrome.declarativeNetRequest API 用于通过指定声明性规则来阻止或修改网络请求。这让扩展程序可以修改网络请求，而无需拦截它们并查看其内容，从而提供更多隐私。

使用详解：三步骤

一、添加权限

在manifest的permissions中添加以下权限：

"permissions":[
    declarativeNetRequest,
    declarativeNetRequestWithHostAccess,
    declarativeNetRequestFeedback
]
"host_permissions":[
    "<all_urls>"
]

若申请的是declarativeNetRequest权限，则阻止或升级请求不需要申请"host_permissions"，但是如果需要重定向请求，或者修改请求头，则要申请相应的"host_permissions"

若申请的是declarativeNetRequestWithHostAccess权限，则任何功能都需要申请相应的"host_permissions"。

若申请的是declarativeNetRequestFeedback，则可以使用getMatchedRules()方法。并且能够监听匹配成功事件，但是该监听仅允许用于测试环境使用。

二、添加规则集

使用declarativeNetRequest对网络请求做处理，实质上是定义一些json格式的规则，这些规则会匹配所有的网络请求，并遵从这些规则做相应处理。匹配规则有静态规则和动态规则两种。

静态规则集配置：

静态规则配置分为两步，如下：

需要创建一个配置规则集的json文件，文件存储一个数组，里面可以放置多个规则。
需要在manifest.json中添加一个包含规则集类型字典的列表，并指向配置规则集的json文件

manifest.json:

//manifest.json
{
  "name": "My extension",
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest"
  ],
  "host_permessions":[
      "*://example.com/*"
  ]
}

rule_resources中有三个参数:

id:每个规则集需要对应一个id

enabled：默认这个规则集是否启用

path：配置规则的json文件地址

rule_1.json:

[{  "id" : 1,  "priority": 1,  "action" : { "type" : "block" },  "condition" : {    "urlFilter" : "abc",    "domains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
},
{
  "id" : 2,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "domains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}]

动态规则集配置

动态规则集可以直接在js代码中配置。

chrome.declarativeNetRequest.updateDynamicRules(
    {
    addRules:[{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "domains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
},
{
  "id" : 2,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "domains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}]
    },function(){}
)

三、规则配置

一个规则以对象的格式定义，其中有四个属性：id、priority、action、condition

id:

每个规则需要对应一个id，不同的规则不能设置相同的id

priority：

优先级，填一个数字，数字越大，优先级越高

action：

如果规则匹配，则采取的操作。有以下四个参数。

type: 必填参数，操作的类型，参数为："block"（拦截请求）, "redirect"（重定向请求）, "allow"（允许请求）, "upgradeScheme"（升级请求）, "modifyHeaders"（修改请求头）, 或"allowAllRequests"（允许所有请求）。
redirect：选填，只有操作类型为redirect时才可填，描述应该如何执行重定向，标黄为重点。

extensionPath:相对于扩展目录的路径。应该以'/'开头。

regexSubstitution:指定正则表达式过滤器的规则的替换模式.

url：需要重定向到的网址，不可以重定向到javascript url

transform：url转换
requestHeaders：选填，只有操作类型为modifyHeaders时才可填，用于修改请求头
responseHeaders：选填，只有操作类型为modifyHeaders时才可填，用于修改响应头

condition：

触发此规则的条件。有以下参数，皆是选填参数，由于参数较多，标黄的五个为常用参数（域名匹配、请求方法匹配、资源类型匹配、url匹配）。

domainType：指定网络请求是发起它的域的"firstParty"（第一方）还是"thirdParty"（第三方）。如果省略，则接受所有请求。
domains：匹配域名列表，如省略则匹配所有域名的请求。
excludedDomains：和domains相反，指定一个排除匹配规则的域名列表，优先级高于domains
requestMethods：http匹配请求方法（"get"、"post"等）列表，如省略则匹配所有请求方法。
excludedRequestMethods：与requestMethods相反，排除一个请求方法列表，优先级高于requestMethods。
resourceTypes：匹配资源类型（"main_frame"、""xmlhttprequest"等）列表，如省略则匹配所有请求类型。
excludedResourceTypes：跟resourceTypes相反。
tabIds：匹配tabid列表，如省略则匹配所有tabs页。
excludedTabIds：和tabIds相反。
isUrlFilterCaseSensitive：是否区分大小写，默认是true，区分大小写
regexFilter：匹配网络请求的正则表达式
urlFilter：匹配网络请求的url

方法：

返回扩展的当前动态规则集

chrome.declarativeNetRequest.getDynamicRules(
  callback?: function,
)

返回当前启用的静态规则集的 ID

chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

返回与扩展匹配的所有规则（需要declarativeNetRequestFeedback权限和主机权限）

chrome.declarativeNetRequest.getMatchedRules(MatchedRulesFilter,function(e){
console.log(e)
})

MatchedRulesFilter:用于过滤匹配规则列表的对象,有以下参数。

minTimeStamp:如果指定，则仅匹配给定时间戳之后的规则。

tabId: 如果指定，则仅匹配给定选项卡的规则。如果设置为 -1，则匹配与任何活动选项卡无关的规则。

修改扩展的当前动态规则集

chrome.declarativeNetRequest.updateDynamicRules( options: UpdateRuleOptions, callback?: function )

UpdateRuleOptions:修改扩展的当前动态规则集，有以下参数。

addRules：要添加的规则集。

removeRuleIds：要删除的规则的 ID。任何无效的 ID 都将被忽略。

事件：

onRuleMatchedDebug：当规则与请求匹配时触发的事件。

仅适用于具有 declarativeNetRequestFeedback 权限的解压扩展，因为这仅用于调试目的。

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

优先级:

首先看规则中设置的priority数字大小
若优先级相同，则看操作类型，阻止规则的优先级高于重定向规则

常见规则：

以下是一些修改请求头、阻止请求、重定向请求的常见用法，可直接粘贴修改使用

修改请求头

规则：在header.com页面删除请求头h1；修改请求头h2，值为v2；新增请求头h3,值为v3

{
    "id": 1,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "h1", "operation": "remove" },
        { "header": "h2", "operation": "set", "value": "v2" },
        { "header": "h3", "operation": "append", "value": "v3" }
      ]
    },
    "condition": { "urlFilter": "||headers.com", "resourceTypes": ["main_frame"] }
  },

阻止请求

规则：阻止以.js结尾的script请求

  {
    "id" : 9,
    "priority": 1,
    "action" : {
      "type" : "block"
    },
    "condition" : {
      "urlFilter" : "script.js",
      "resourceTypes" : ["script"]
    }
  }

重定向请求

规则：在baidu.com页面中，把带有'/sugrec'的接口请求中，wa参数修改成"西红柿"

        {
            "id":5,
            "priority":5,
            "aciton":{"type":"redirect","redirect":{
            "transform":{
                "queryTransform":{
                    "addOrReplaceParams":[
                        {
                            "key":"wa",
                          	"replaceOnly":true,
                            "value":"西红柿"
                        }
                    ]
                }
            }
            }},
  "condition" : {
    "urlFilter" : "/sugrec",
    "domains" : ["||baidu.com"],
    "resourceTypes" : ["xmlhttprequest"]
  }
}

chrome.declarativeNetRequest API如何使用？

背景：