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' - 由于未收到已发送数据的确认，连接超时。
- 'connectionclosed' - 连接已关闭（对应于 TCP FIN）。
- 'connectionfailed' - 连接尝试失败。
- 'connectionrefused' - 连接尝试被拒绝。
- 'connectionreset' - 连接被重置（对应于 TCP RST）。
- 'internetdisconnected' - 网络连接已丢失。
- 'namenotresolved' - 主机名无法解析。
- 'timedout' - 操作超时。
- 'failed' - 发生了一般故障。

返回值

void #

fallback

新增于：v1.23

route.fallback

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

用法

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

page.route("**/*", route -> {
  // 最后运行。
  route.abort();
});

page.route("**/*", route -> {
  // 第二个运行。
  route.fallback();
});

page.route("**/*", route -> {
  // 首先运行。
  route.fallback();
});

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

// 处理 GET 请求。
page.route("**/*", route -> {
  if (!route.request().method().equals("GET")) {
    route.fallback();
    return;
  }
  // 仅处理 GET 请求。
  // ...
});

// 处理 POST 请求。
page.route("**/*", route -> {
  if (!route.request().method().equals("POST")) {
    route.fallback();
    return;
  }
  // 仅处理 POST 请求。
  // ...
});

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

page.route("**/*", route -> {
  // 覆盖标头
  Map<String, String> headers = new HashMap<>(route.request().headers());
  headers.put("foo", "foo-value"); // 设置 "foo" 标头
  headers.remove("bar"); // 删除 "bar" 标头
  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 double（可选）新增于：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 -> {
  // 覆盖请求头
  Map<String, String> headers = new HashMap<>(route.request().headers());
  headers.put("foo", "foo-value"); // 设置 "foo" 请求头
  headers.remove("bar"); // 移除 "bar" 请求头
  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 标头。如果提供了一个值，它将被忽略，并且 cookie 将从浏览器的 cookie 存储中加载。要设置自定义 cookie，请使用 BrowserContext.addCookies()。

方法​

abort​

fallback​

用法​

fetch​

fulfill​

request​

resume​

详细信息​

方法

abort

fallback

用法

fetch

fulfill

request

resume

详细信息