Playwright APIRequestContext 详解：Web API 测试、Cookie 双向同步与请求生命周期管理

Playwright 的 APIRequestContext（自 v1.16 引入）是面向 Web API 测试的高层请求句柄：既能独立于浏览器发起 HTTP(S) 请求，又能与 BrowserContext 共享同一份 Cookie 仓库，实现"通过 API 登录、在页面里直接用"或反之的天然联动。读完本文，你将掌握 APIRequestContext 的三种获取方式、Cookie 双向同步的底层原理、fetch/get/post/put/delete/patch/head 全部方法及其 data/form/multipart/params 等请求体与查询参数用法、APIResponse 响应读取、dispose 生命周期管理、storageState 状态快照与基于请求的 tracing，并能直接上手文档与示例仓库提供的 GitHub REST API 完整用例。

APIRequestContext 是什么：为 Web API 测试而生的请求句柄

APIRequestContext 用于 Web API 测试。官方文档给出的典型定位是：触发 API 端点、配置微服务、为端到端测试准备环境或服务状态。在测试前置阶段通过 API 造数据、清数据，可以让用例更稳定、更快速，减少对 UI 操作的依赖。

它的"请求上下文"语义与浏览器上下文一一对应，体现在三类获取途径上：

• 每个 Playwright BrowserContext 都关联一个 APIRequestContext，通过 [property: BrowserContext.request] 或 [property: Page.request] 访问；
• page.request 是 page.context().request 的快捷写法，二者返回同一个实例；
• 也可以调用 playwright.request.new_context()（Python 同步 API 中为 p.request.new_context(...)）创建独立的、与浏览器无关的隔离实例。

从源码结构看，客户端侧这一关系在 客户端 fetch.ts 中实现得十分直白：APIRequest（对应 playwright.request）维护一个 _contexts 集合，newContext() 通过驱动层 _playwright._channel.newRequest(...) 创建通道对象并用 APIRequestContext.from(...) 包装，随后把该实例注册进 _contexts 并设置默认超时（见 fetch.ts#L65-L93）。浏览器上下文与请求上下文之间的"关联/隔离"关系，正是由二者是否共享 Cookie 存储来定义的。

理解 Cookie 同步模型：API 与浏览器共享同一份登录态

这是 APIRequestContext 与普通 HTTP 客户端（如 Python requests、Node fetch）最核心的区别。当通过 BrowserContext.request / page.request 发起 API 请求时，该请求与 BrowserContext 使用同一个 Cookie jar，具体表现为三条规则：

1. 每个外发请求自动携带上下文中的 Cookie 头——无需手动从上下文读取 Cookie 再拼接；
2. API 响应里的 Set-Cookie 会被写回 BrowserContext——后续的页面导航与 API 调用都能取到；
3. 通过 API 登录即等价于在浏览器里登录，反之亦然——身份状态在协议层天然打通。

若希望请求不共享浏览器 Cookie，则用 APIRequest.newContext() 创建隔离上下文，该对象拥有自己独立的 Cookie 存储。

源码视角：Cookie 的双向管道

上述行为的底层实现在服务端 server/fetch.ts：

• 发送前注入：_updateRequestCookieHeader() 先检查调用方是否已显式设置 cookie 头，若没有，则从上下文取回 Cookie，按 RFC 6265 的域匹配规则过滤后拼成 name=value; name=value 写入请求头（fetch.ts#L293-L305）。注释特别指出：浏览器上下文返回的 Cookie 同时覆盖 example.com 与 .example.com，而无前导点的 Cookie 只发给严格等价的域，不会发给子域。
• 响应写回：响应中的每个 Set-Cookie 经 _parseSetCookieHeader() 按 RFC 6265 规则解析——默认 Path、域匹配校验、域默认取响应 URL 主机名（fetch.ts#L266-L291），随后逐条 addCookies() 写回上下文；单条失败会被单独吞掉以容忍部分脏 Cookie（fetch.ts#L449-L456）。
• 隔离实例的实现：与 BrowserContext 关联的请求上下文把 addCookies/cookies 转发给浏览器上下文；而独立请求上下文则持有私有的 CookieStore，并在构造时用 options.storageState.cookies 预填充（fetch.ts#L742-L808）。这正是"隔离 = 独立 cookie 仓库"的源码级证据。

实战：用 GitHub API 打通"建仓即验证"

文档以 GitHub REST API 为例演示了这套模型：创建仓库、断言、删除仓库，全程带着个人访问令牌。下文的 Python 异步版本完整取自文档并保持可运行：

import os
import asyncio
from playwright.async_api import async_playwright, Playwright

REPO = "test-repo-1"
USER = "github-username"
API_TOKEN = os.getenv("GITHUB_API_TOKEN")

async def run(playwright: Playwright):
    # 启动浏览器、创建 context 与 page。通过 context.request / page.request
    # 发起 HTTP 请求时，Cookie 会自动在浏览器页面与 API 请求之间双向同步。
    browser = await playwright.chromium.launch()
    context = await browser.new_context(base_url="https://api.github.com")
    api_request_context = context.request
    page = await context.new_page()

    # 也可以不绑定浏览器上下文，手动创建隔离的请求上下文：
    # api_request_context = await playwright.request.new_context(base_url="https://api.github.com")

    # 创建一个仓库。
    response = await api_request_context.post(
        "/user/repos",
        headers={
            "Accept": "application/vnd.github.v3+json",
            # 传入 GitHub personal access token。
            "Authorization": f"token {API_TOKEN}",
        },
        data={"name": REPO},
    )
    assert response.ok
    assert response.json()["name"] == REPO

    # 删除该仓库。
    response = await api_request_context.delete(
        f"/repos/{USER}/{REPO}",
        headers={
            "Accept": "application/vnd.github.v3+json",
            "Authorization": f"token {API_TOKEN}",
        },
    )
    assert response.ok
    assert await response.body() == b'{"status": "ok"}'

async def main():
    async with async_playwright() as playwright:
        await run(playwright)

asyncio.run(main())

两点说明：其一，base_url 使后续 "/user/repos" 这类相对路径自动拼上主机，代码可读性与可移植性更好；其二，同步 API 版本与此逻辑完全一致（用 sync_playwright() 与 with 块组织），只是不再需要 async/await——注意 response.body() 在同步 API 下返回普通字节串，无需 await。

发送请求：fetch 通用方法与 get/post/put 等便捷方法

APIRequestContext 暴露的方法包括 fetch、get、post、put、delete、patch、head。其中 fetch 是通用方法，接受 urlOrRequest 参数——既可以传 URL 字符串，也可以传一个已存在的 Request 对象以复用其全部参数；其余六个方法则分别绑定固定 HTTP 动词。

文档逐一对每个便捷方法说明了三点共同行为：

• 请求时会从上下文填充 Cookie，并从响应更新上下文 Cookie；
• 请求会自动跟随重定向；
• 所有请求均返回 APIResponse。

在客户端源码中，这些便捷方法确实是"语法糖"——delete/head/get/patch/post/put 六个方法内部一律转发给 this.fetch(url, { ...options, method: 'XXX' })（见 fetch.ts#L131-L171）。所有动词共用同一套请求参数选项，因此下文选项说明对全部方法通用。

查询参数 params：三种写法殊途同归

以 GET 为例，文档展示了 params 选项的三种形式，它们会被序列化进 URL 查询串：

// 写法一：对象
await request.get('https://example.com/api/getText', {
  params: { 'isbn': '1234', 'page': 23 }
});

// 写法二：URLSearchParams（支持同名多值）
const searchParams = new URLSearchParams();
searchParams.set('isbn', '1234');
searchParams.append('page', 23);
searchParams.append('page', 24);
await request.get('https://example.com/api/getText', { params: searchParams });

// 写法三：裸字符串
const queryString = 'isbn=1234&page=23&page=24';
await request.get('https://example.com/api/getText', { params: queryString });

Python 与 C# 对应写法为对象/字典与 paramsString：

query_params = {"isbn": "1234", "page": "23"}
api_request_context.get("https://example.com/api/getText", params=query_params)

var queryParams = new Dictionary<string, object>() { { "isbn", "1234" }, { "page", 23 } };
await request.GetAsync("https://example.com/api/getText", new() { Params = queryParams });

Java 则通过 RequestOptions.create().setQueryParam(...) 链式累积。客户端对 params 的处理在 _innerFetch 中完成：字符串原样透传、URLSearchParams 转 toString()、对象转键值数组后，分别以 params/encodedParams 通道字段发给驱动（fetch.ts#L189-L193）。

请求体三选一：data、form 与 multipart

当携带请求体时，data、form、multipart 三者只能指定一个，否则客户端会直接抛出 Only one of 'data', 'form' or 'multipart' can be specified（fetch.ts#L184）。三者的 Content-Type 与序列化规则如下：

选项	编码/Content-Type	说明
data	JSON 对象 → application/json；否则 → application/octet-stream	对象被自动序列化为 JSON 字符串；也可直接传字符串或 Buffer
form	application/x-www-form-urlencoded	键值对以 HTML 表单 URL 编码序列化；未显式给 content-type 时自动设置
multipart	multipart/form-data	以表单字段方式上传文件；未显式给 content-type 时自动设置

参数模板的完整权威定义统一维护在 公共参数模板 docs/src/api/params.md（js-python-csharp-fetch-option-data、js-fetch-option-form、js-fetch-option-multipart 等小节），本文其余选项均以此为准。

data：直接提交 JSON 对象

JSON 对象可以直接传给 fetch/post 等，无需手动 json.dumps/JSON.stringify：

data = {"title": "Book Title", "body": "John Doe"}
api_request_context.fetch("https://example.com/api/createBook", method="post", data=data)

await request.fetch('https://example.com/api/createBook', {
  method: 'post',
  data: { title: 'Book Title', author: 'John Doe' }
});

客户端源码中的处理逻辑（fetch.ts#L201-L213）区分三种情况：字符串 data 若 content-type 为 application/json 且内容可被 JSON.parse，则按 JSON 语义原样发送，否则按 UTF-8 Buffer 发送；Buffer 直接透传；对象/数字/布尔则 JSON.stringify 为 JSON 数据。服务端接收后统一以 jsonData/postData 字段落盘。

form：URL 编码表单

需要发送键值对表单（典型如搜索、登录表单）时用 form：

form_data = {"title": "Book Title", "body": "John Doe"}
api_request_context.post("https://example.com/api/findBook", form=form_data)

var formData = Context.APIRequest.CreateFormData();
formData.Set("title", "Book Title");
formData.Set("body", "John Doe");
await request.PostAsync("https://example.com/api/findBook", new() { Form = formData });

需发送"同一字段多个值"（如多选）时，Python/JS 侧建议使用 FormData（JS 原生 FormData 或 Playwright FormData）；注意 JS 中若 form 值出现 File 对象，客户端会明确报错要求改用 multipart（fetch.ts#L214-L224）。

multipart：以表单字段上传文件

上传文件最通用的做法是 multipart/form-data 表单字段，文件内容既可来自磁盘路径，也可直接以"文件名 + MIME 类型 + 字节内容"构造：

api_request_context.fetch(
  "https://example.com/api/uploadScript", method="post",
  multipart={
    "fileField": {
      "name": "f.js",
      "mimeType": "text/javascript",
      "buffer": b"console.log(2022);",
    },
  })

JS 可用原生 FormData 一次性追加多个同名文件字段：

const form = new FormData();
form.set('name', 'John');
form.append('name', 'Doe');
// 同一字段发送两个文件。
form.append('file', new File(['console.log(2024);'], 'f1.js', { type: 'text/javascript' }));
form.append('file', new File(['hello'], 'f2.txt', { type: 'text/plain' }));
await request.fetch('https://example.com/api/uploadForm', { multipart: form });

Java/C# 场景支持把本地路径塞进表单（FormData.create().set("fileField", file) / multipart.Set("fileField", file)），或用 FilePayload 承载内存字节（文档原文 Java/C# 小节）。C# 侧对应构造方法为 APIRequestContext.createFormData（v1.23 起）。客户端在转换时会识别 FilePayload（含 name/mimeType/buffer）与 fs.ReadStream 并统一转为服务端字段结构（fetch.ts#L282-L294）。

公共请求选项：超时、重定向、重试与断言开关

除请求体与查询参数外，get/post/fetch 等所有方法共享以下选项，默认值以 params.md 为准：

选项	类型	默认值	说明
headers	对象	—	设置 HTTP 头；对初始请求及其触发的所有重定向同样生效
timeout	float（毫秒）	30000（30 秒）	请求超时；传 0 表示禁用超时
failOnStatusCode	boolean	false	是否在状态码非 2xx/3xx 时抛错；默认对所有状态码都返回响应对象
ignoreHTTPSErrors	boolean	false	发送请求时是否忽略 HTTPS 证书错误
maxRedirects	int	20	自动跟随重定向的最大次数，超限抛错；传 0 表示不跟随
maxRetries	int	0	网络错误重试次数（仅重试 ECONNRESET，不按 HTTP 状态码重试），超限抛错
signal	AbortSignal	—	用于取消请求的 AbortSignal

其中几个选项在源码中有直接的校验与实现印证：

• 参数合法性：客户端对 maxRedirects、maxRetries 断言必须 >= 0，越界直接抛错（fetch.ts#L185-L186）。
• failOnStatusCode：服务端在状态码 status < 200 || status >= 400 且开关打开时抛错，并把至多 1000 字节的响应体作为 Response text: 附进错误信息便于排查（server/fetch.ts#L250-L260）。
• 重试退避：_sendRequestWithRetries 从 250ms 起步、逐次翻倍做指数退避；只有 ECONNRESET 会被重试，其余异常立即抛出（server/fetch.ts#L307-L333）。
• HTTPS 错误：ignoreHTTPSErrors 在服务端映射为 Node https 请求的 rejectUnauthorized = false（server/fetch.ts#L242-L244）。

读取响应：APIResponse

所有请求方法都返回 APIResponse 对象。常用读取手段包括：ok()（状态码是否落在 200–299）、status()/statusText()、url()、headers()/headersArray()、body()（返回原始字节）、text()（按 UTF-8 解码）与 json()（解析 JSON）。ok() 与 status() 的实现可在客户端源码中直接看到（fetch.ts#L325-L338）。

关键设计是：所有响应体都被暂存在内存中，以便事后调用 APIResponse.body()/text()/json() 按需读取；文档同时提示，读完即可 dispose() 释放。响应读取经 fetchUid 从驱动拉取响应体，若响应已被释放或上下文已关闭，会得到明确的 Response has been disposed 错误（fetch.ts#L372-L385）。

生命周期管理：dispose 与关闭原因

APIRequestContext 的请求与响应都会暂存资源，用完应调用 dispose() 释放。释放之后再对该上下文调用任何方法都会抛出异常。从 v1.45 起，dispose() 支持 reason 参数，该原因会被上报给因上下文释放而被中断的操作（如进行中的请求）。

客户端 dispose() 的完整流程是：记录关闭原因 → 触发关闭前 instrumentation 钩子 → 把尚未导出的 HAR 全部导出（tracing._exportAllHars()，配合 request 的 tracing 能力）→ 通知驱动释放并静默容忍 TargetClosedError → 从 APIRequest._contexts 集合中注销自己（fetch.ts#L116-L129）。代码同时提供 Symbol.asyncDispose，因此在支持异步可迭代释放的环境中可以配合 await using 语法自动释放。释放后若继续发请求，_innerFetch 会先检查 _closeReason 并抛出 TargetClosedError（fetch.ts#L181-L182）。

状态快照：storageState 复用登录态

storageState() 返回当前请求上下文的存储状态快照，结构为：

• cookies：数组，每项含 name、value、domain、path、expires（Unix 秒）、httpOnly、secure、sameSite（"Strict"/"Lax"/"None"）；
• origins：数组，每项含 origin 与 localStorage（name/value 列表）。

可选参数方面：path 可直接把状态写入 JSON 文件（Java/C# 语言中 storageState 亦提供仅返回路径字符串的重载）；indexedDB（v1.51 起）置 true 时把 IndexedDB 纳入快照；opfs（v1.63 起）置 true 时纳入 Origin Private File System 快照。

客户端实现表明，path 实际是"顺手写盘"：先调用驱动取回状态对象，若给了 path 则自动创建父目录并以 2 空格缩进写入 JSON（fetch.ts#L272-L279）。

这一能力最常见的用法是把"API 登录得到的 Cookie/存储"固化为 JSON，在测试夹具中注入新的 BrowserContext，从而免去重复登录。仓库测试 tests/library/browsercontext-storage-state.spec.ts 就大量覆盖了这类场景，例如通过 context.request.storageState({ opfs: true }) 与 page.context().storageState({ opfs: true }) 互相印证快照一致性（参见该文件 opfs 相关用例）。

请求级追踪：tracing 属性

APIRequestContext.tracing（v1.60 起）返回该请求上下文专属的 Tracing 记录器，用于记录经由该请求上下文发出的请求。在客户端构造函数中，this.tracing = Tracing.from(initializer.tracing) 直接取自驱动初始化数据，二者天然关联（fetch.ts#L106-L110）；dispose() 阶段执行 tracing._exportAllHars() 则保证未及时导出的 HAR 在释放前被兜底写出。据此可推断：当 API 请求与页面导航混杂在同一个流程中时，可分别通过 page/context 的 tracing 与 request context 的 tracing 独立还原两类活动的网络细节。

场景选择：绑定上下文还是隔离上下文

场景	推荐方式
E2E 测试中先用 API 造数/登录，再驱动页面验证	context.request（共享 Cookie，登录态自动互通）
纯接口冒烟、不关心浏览器状态	playwright.request.new_context()（隔离、轻量、无浏览器依赖）
并行测试间互不污染身份状态	每用例新建隔离 APIRequestContext
需要把 API 登录态持久化复用到后续浏览器上下文	context.request.storageState({ path })

需要留意的是：隔离上下文虽然不共享浏览器 Cookie，但仍可通过构造参数（如 baseURL、extraHTTPHeaders、storageState、ignoreHTTPSErrors、客户端证书 clientCertificates 等）自主配置；这些选项在 APIRequest.newContext 的客户端实现中会被归一化后送入驱动（fetch.ts#L73-L93）。

仓库内的直接参考资源

• 文档正文：docs/src/api/class-apirequestcontext.md（方法签名、引入版本、多语言用法示例）
• 选项权威定义：docs/src/api/params.md（fetch-param-url 与全部 *-fetch-option-*/*-fetch-params* 模板，含各语言类型与默认值）
• 客户端实现：packages/playwright-core/src/client/fetch.ts（APIRequest/APIRequestContext/APIResponse 三个类的完整行为）
• 服务端实现：packages/playwright-core/src/server/fetch.ts（Cookie 双向同步、重定向跟随、ECONNRESET 重试、failOnStatusCode 抛错的落点）
• 存储状态测试：tests/library/browsercontext-storage-state.spec.ts（request.storageState 与上下文状态一致性的实证）
• 端到端示例：仓库 examples/github-api 目录提供了基于 GitHub API 的完整 Playwright Test 工程（含 playwright.config.ts 与测试用例），与本文文首的 GitHub 演示相互印证。