Route

当使用 Page.route() 或 BrowserContext.route() 设置网络路由时，Route 对象允许处理该路由。

了解更多关于网络。

方法

中止 (abort)

v1.9 之前添加

route.abort

中止路由请求。

用法

Route.abort();
Route.abort(errorCode);

参数

errorCode String （可选）#

可选的错误代码。默认为 failed，可以是以下之一
- 'aborted' - 操作被中止（由于用户操作）
- 'accessdenied' - 访问除网络外的资源权限被拒绝
- 'addressunreachable' - IP 地址无法访问。这通常意味着没有到指定主机或网络的路由。
- 'blockedbyclient' - 客户端选择阻止请求。
- 'blockedbyresponse' - 请求失败，因为响应与未满足的要求一起交付（例如，'X-Frame-Options' 和 'Content-Security-Policy' 祖先检查）。
- 'connectionaborted' - 由于未收到已发送数据的 ACK，连接超时。
- 'connectionclosed' - 连接已关闭（对应于 TCP FIN）。
- 'connectionfailed' - 连接尝试失败。
- 'connectionrefused' - 连接尝试被拒绝。
- 'connectionreset' - 连接被重置（对应于 TCP RST）。
- 'internetdisconnected' - 互联网连接已断开。
- 'namenotresolved' - 主机名无法解析。
- 'timedout' - 操作超时。
- 'failed' - 发生一般性故障。

void #

回退 (fallback)

添加于：v1.23

route.fallback

使用可选的覆盖项继续路由的请求。此方法与 Route.resume() 类似，不同之处在于在发送请求之前会调用其他匹配的处理程序。

用法

当多个路由匹配给定模式时，它们按与注册顺序相反的顺序执行。这样，最后注册的路由始终可以覆盖所有先前的路由。在下面的示例中，请求将首先由最底部的处理程序处理，然后回退到前一个处理程序，最后将被第一个注册的路由中止。

page.route("**/*", route -> {
  // Runs last.
  route.abort();
});

page.route("**/*", route -> {
  // Runs second.
  route.fallback();
});

page.route("**/*", route -> {
  // Runs first.
  route.fallback();
});

注册多个路由很有用，当您希望不同的处理程序处理不同类型的请求时，例如 API 调用与页面资源，或 GET 请求与 POST 请求，如下面的示例所示。

// Handle GET requests.
page.route("**/*", route -> {
  if (!route.request().method().equals("GET")) {
    route.fallback();
    return;
  }
  // Handling GET only.
  // ...
});

// Handle POST requests.
page.route("**/*", route -> {
  if (!route.request().method().equals("POST")) {
    route.fallback();
    return;
  }
  // Handling POST only.
  // ...
});

还可以修改请求，同时回退到后续处理程序，这样中间路由处理程序可以修改请求的 url、方法、头和 postData。

page.route("**/*", route -> {
  // Override headers
  Map<String, String> headers = new HashMap<>(route.request().headers());
  headers.put("foo", "foo-value"); // set "foo" header
  headers.remove("bar"); // remove "bar" header
  route.fallback(new Route.ResumeOptions().setHeaders(headers));
});

使用 Route.resume() 立即将请求发送到网络，在这种情况下不会调用其他匹配的处理程序。

参数

options Route.FallbackOptions （可选）
- setHeaders Map<String, String> （可选）#
  
  如果设置，则更改请求 HTTP 头。头值将转换为字符串。
- setMethod String （可选）#
  
  如果设置，则更改请求方法（例如 GET 或 POST）。
- setPostData String | byte[] （可选）#
  
  如果设置，则更改请求的 post 数据。
- setUrl String （可选）#
  
  如果设置，则更改请求 URL。新 URL 必须与原始 URL 具有相同的协议。更改 URL 不会影响路由匹配，所有路由都使用原始请求 URL 进行匹配。

void #

抓取 (fetch)

新增于: v1.29

route.fetch

执行请求并抓取结果而不满足它，以便可以修改响应然后满足它。

用法

page.route("https://dog.ceo/api/breeds/list/all", route -> {
  APIResponse response = route.fetch();
  JsonObject json = new Gson().fromJson(response.text(), JsonObject.class);
  JsonObject message = itemObj.get("json").getAsJsonObject();
  message.set("big_red_dog", new JsonArray());
  route.fulfill(new Route.FulfillOptions()
    .setResponse(response)
    .setBody(json.toString()));
});

参数

options Route.FetchOptions （可选）
- setHeaders Map<String, String> （可选）#
  
  如果设置，则更改请求 HTTP 头。头值将转换为字符串。
- setMaxRedirects int （可选）添加于：v1.31#
  
  将自动遵循的最大请求重定向次数。如果超过此数字，将抛出错误。默认为 20。传递 0 表示不遵循重定向。
- setMaxRetries int （可选）新增于: v1.46#
  
  网络错误的最大重试次数。目前只重试 ECONNRESET 错误。不根据 HTTP 响应代码重试。如果超过限制，将抛出错误。默认为 0 - 不重试。
- setMethod String （可选）#
  
  如果设置，则更改请求方法（例如 GET 或 POST）。
- setPostData String | byte[] （可选）#
  
  如果设置，则更改请求的 post 数据。
- setTimeout 双精度浮点数 (可选)新增于：v1.33#
  
  请求超时时间（毫秒）。默认为 30000 (30 秒)。传递 0 表示禁用超时。
- setUrl String （可选）#
  
  如果设置，则更改请求 URL。新 URL 必须与原始 URL 具有相同的协议。

APIResponse #

详情

请注意，setHeaders 选项将应用于获取的请求以及它发起的任何重定向。如果要仅将 setHeaders 应用于原始请求，而不是重定向，请查看 Route.resume()。

满足 (fulfill)

v1.9 之前添加

route.fulfill

使用给定响应满足路由请求。

用法

一个用 404 响应满足所有请求的示例

page.route("**/*", route -> {
  route.fulfill(new Route.FulfillOptions()
    .setStatus(404)
    .setContentType("text/plain")
    .setBody("Not Found!"));
});

一个提供静态文件的示例

page.route("**/xhr_endpoint", route -> route.fulfill(
  new Route.FulfillOptions().setPath(Paths.get("mock_data.json"))));

参数

options Route.FulfillOptions （可选）
- setBody String （可选）#
  
  可选的响应体（文本形式）。
- setBodyBytes byte[] （可选）添加于：v1.9#
  
  可选的响应体（原始字节形式）。
- setContentType String （可选）#
  
  如果设置，等同于设置 Content-Type 响应头。
- setHeaders Map<String, String> （可选）#
  
  响应头。头值将转换为字符串。
- setPath Path （可选）#
  
  用于响应的文件路径。内容类型将从文件扩展名推断。如果 path 是相对路径，则它相对于当前工作目录解析。
- setResponse APIResponse （可选）新增于: v1.15#
  
  用于满足路由请求的 APIResponse。可以通过满足选项覆盖响应的各个字段（例如标头）。
- setStatus int （可选）#
  
  响应状态码，默认为 200。

void #

请求 (request)

v1.9 之前添加

route.request

待路由的请求。

用法

Route.request();

Request #

resume

v1.9 之前添加

route.resume

发送路由请求到网络，可选择覆盖。

用法

page.route("**/*", route -> {
  // Override headers
  Map<String, String> headers = new HashMap<>(route.request().headers());
  headers.put("foo", "foo-value"); // set "foo" header
  headers.remove("bar"); // remove "bar" header
  route.resume(new Route.ResumeOptions().setHeaders(headers));
});

参数

options Route.ResumeOptions （可选）
- setHeaders Map<String, String> （可选）#
  
  如果设置，则更改请求 HTTP 头。头值将转换为字符串。
- setMethod String （可选）#
  
  如果设置，则更改请求方法（例如 GET 或 POST）。
- setPostData String | byte[] （可选）#
  
  如果设置，则更改请求的 post 数据。
- setUrl String （可选）#
  
  如果设置，则更改请求 URL。新 URL 必须与原始 URL 具有相同的协议。

void #

详情

setHeaders 选项适用于路由的请求及其发起的任何重定向。但是，setUrl、setMethod 和 setPostData 只适用于原始请求，不会传递给重定向的请求。

Route.resume() 将立即把请求发送到网络，不会调用其他匹配的处理程序。如果你想调用链中的下一个匹配处理程序，请使用 Route.fallback()。

警告

某些请求头是禁止的，不能被覆盖（例如，Cookie、Host、Content-Length 等，请参阅此 MDN 页面获取完整列表）。如果为禁止的头提供了覆盖，它将被忽略并使用原始请求头。

要设置自定义 cookie，请使用 BrowserContext.addCookies()。

方法​

中止 (abort)​

回退 (fallback)​

抓取 (fetch)​

满足 (fulfill)​

请求 (request)​

resume​

方法

中止 (abort)

回退 (fallback)

抓取 (fetch)

满足 (fulfill)

请求 (request)

resume