ruyiPage请求拦截与Mock实战:API Mock、改请求头与拦截图片完整指南
ruyiPage请求拦截与Mock实战:API Mock、改请求头与拦截图片完整指南
ruyiPage 是一个基于 Firefox 的 Python Web 自动化框架,内建过检测的指纹浏览器内核。它的 page.intercept 拦截器可以在请求发出前直接 Mock 接口响应、修改请求头,也可以阻止图片加载——无需外部代理,一行配置就能把任意 HTTP 请求"拦"下来。本文带你快速上手请求拦截与 API Mock 的三大核心玩法,并附上完整避坑指南。
一、三个拦截阶段,先看清"拦在哪一步"
ruyiPage 的拦截器基于下一代 WebDriver BiDi 协议实现(源码见 ruyipage/_units/interceptor.py),支持在三个不同的时机介入请求生命周期:
| 拦截阶段 | 介入时机 | 能做什么 |
|---|---|---|
beforeRequestSent |
请求发出前 | 改 URL/Method/请求头/请求体,或直接 Mock、阻止请求 |
responseStarted |
响应头到达后、响应体传输前 | 读取状态码与响应头,修改状态码/响应头 |
authRequired |
遇到 HTTP 认证挑战时 | 自动填写账号密码,或取消认证 |
💡 90% 的场景用
beforeRequestSent就够了,下面所有例子都围绕它展开。
二、API Mock:不访问真实后端,直接"伪造"响应
Mock 是拦截器最强大的能力:请求根本不离开浏览器,由你决定返回什么内容。常用于前端联调、接口不稳定的测试环境、以及绕过需要登录态的接口。
def handler(req):
if "/api/user" in req.url:
req.mock(
'{"id": 1, "name": "test"}',
status_code=200,
headers={
"content-type": "application/json",
"access-control-allow-origin": "*",
},
)
else:
req.continue_request()
page.intercept.start_requests(handler)
page.get("https://example.com")
page.intercept.stop()
两个关键注意点:
- ⚠️ 跨域 Mock 必须带
access-control-allow-origin响应头,否则浏览器会拦掉响应,前端fetch()直接看到NetworkError——这是新手踩坑率最高的一点。 - 回调里没"认领"的请求必须显式调用
req.continue_request(),否则会永久挂起。ruyiPage 有兜底机制(handler 未处理时自动放行),但显式处理更稳妥。
完整可运行的 Mock 示例在 examples/11_network_intercept.py,它用本地测试服务器验证了"页面 fetch 拿到的确实是 Mock 数据"。
三、改请求头:给接口注入 Token 和环境标记
有时你不需要 Mock,只想在请求发出前"动动手脚"——比如给所有接口加上鉴权头、替换 User-Agent、打上测试环境标记。
def handler(req):
req.continue_request(headers={
"X-Token": "abc123",
"User-Agent": "RuyiPage/1.0",
})
page.intercept.start_requests(handler)
headers 支持简洁的 dict 格式,框架会自动转换成 BiDi 协议格式(转换逻辑见 _normalize_headers),不用手写冗长的嵌套结构。
拦截器 vs 全局请求头,怎么选?
| 需求 | 推荐方式 |
|---|---|
| 只改特定接口的头(按 URL 判断) | page.intercept 拦截器 |
| 给所有请求加统一头 | page.network.set_extra_headers({"X-Test": "yes"}) |
拦截器里可以直接读取原始请求信息:req.url、req.method、req.headers、req.body(POST 请求体),配合判断条件即可精准命中目标请求。参考实现见 examples/18_advanced_network.py,它演示了修改请求头后如何从服务端回显中验证头部确实生效。
四、拦截图片:秒开页面、省流量、测错误处理
req.fail() 可以在浏览器层面直接丢弃一个请求。最典型的用法就是拦截所有图片资源——页面秒开、几乎不耗流量,同时也方便测试前端的图片加载失败兜底:
def handler(req):
if req.url.endswith((".png", ".jpg", ".gif")):
req.fail() # 请求被丢弃,前端触发 onerror
else:
req.continue_request()
page.intercept.start_requests(handler)
被 fail() 的请求对前端来说等同于网络错误:fetch() 会 reject,XMLHttpRequest 触发 onerror。你可以再订阅 network.fetchError 事件观察这些错误(示例见 examples/18_advanced_network.py)。
五、队列模式:先"扣住"请求,想怎么处理就怎么处理
前面是"回调模式"(handler 自动处理每个请求),还有另一种"队列模式":先拦截、请求入队,再手动取出来逐个处理,适合需要先看到请求再决定的场景:
page.intercept.start_requests() # handler=None,进入队列模式
req = page.intercept.wait(timeout=5) # 手动取出被拦截的请求
print(req.method, req.url, req.body) # 读取方法、URL、请求体
req.continue_request() # 处理完必须放行!
page.intercept.stop()
⚠️ 队列模式下每个 wait() 取出的请求必须手动调用 continue_request() / fail() / mock() 之一,否则请求永久悬挂。
六、进阶:读取响应体、改写状态码
如果想观察服务端真实返回了什么,或者"篡改"响应,用 responseStarted 阶段:
def handler(req):
print(f"状态码: {req.response_status}")
req.continue_response()
print(req.response_body) # 一步读取解码后的响应体
page.intercept.start_responses(handler)
start_responses 默认启用响应体采集,req.response_body 会自动等待响应完成并解码,不用手动编排 DataCollector。也可以反过来——把 403 改成 200 让前端"以为"请求成功:
req.continue_response(status_code=200, reason_phrase="OK")
对应测试见 tests/features/test_interceptor_responses.py,Mock 请求头的回归测试见 tests/features/test_interceptor_requests.py。
七、新手避坑清单 📋
- ✅ 每个被拦截的请求都必须有个交代:
continue_request()、mock()、fail()三选一,漏掉就挂起。 - ✅ 跨域 Mock 记得加 CORS 头:
access-control-allow-origin: *。 - ✅ 用
try/finally保护stop():page.intercept.stop()幂等、可安全重复调用,放在finally里是最佳实践。 - ✅ headers 直接传 dict:框架自动转协议格式,别手写 BiDi 嵌套结构。
- ✅ 被动观察优先用
page.capture:只想抓包、不想干预请求时,page.capture被动抓取更简单,不影响请求执行。
八、延伸阅读
- 拦截器完整实现:ruyipage/_units/interceptor.py
- 基础示例(Mock / 阻止 / 改头 / 队列 / 响应阶段):examples/11_network_intercept.py
- 高级网络场景合集:examples/18_advanced_network.py
- 被动抓包(不拦截版):examples/40_scraper_packet_capture.py
掌握请求拦截与 Mock 之后,你可以让前端在没有后端的情况下完整跑通、给接口任意注入测试数据、或者用秒开页面大幅提速自动化流程。配合 ruyiPage 自带的过检测 Firefox 指纹内核,这些网络能力在真实站点上同样稳定可用。

