ruyiPage请求拦截与Mock实战:API Mock、改请求头与拦截图片完整指南

原创2026-10-10 16:41:211,719 阅读

ruyiPage请求拦截与Mock实战:API Mock、改请求头与拦截图片完整指南

ruyiPage 是一个基于 Firefox 的 Python Web 自动化框架,内建过检测的指纹浏览器内核。它的 page.intercept 拦截器可以在请求发出前直接 Mock 接口响应、修改请求头,也可以阻止图片加载——无需外部代理,一行配置就能把任意 HTTP 请求"拦"下来。本文带你快速上手请求拦截与 API Mock 的三大核心玩法,并附上完整避坑指南。

ruyiPage 指纹浏览器请求拦截实战:浏览器检测工具页面

一、三个拦截阶段,先看清"拦在哪一步"

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()

两个关键注意点:

  1. ⚠️ 跨域 Mock 必须带 access-control-allow-origin 响应头,否则浏览器会拦掉响应,前端 fetch() 直接看到 NetworkError——这是新手踩坑率最高的一点。
  2. 回调里没"认领"的请求必须显式调用 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,它演示了修改请求头后如何从服务端回显中验证头部确实生效。

ruyiPage 请求拦截实战:真实站点请求拦截与自动化操作

四、拦截图片:秒开页面、省流量、测错误处理

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 被动抓取更简单,不影响请求执行。

八、延伸阅读

掌握请求拦截与 Mock 之后,你可以让前端在没有后端的情况下完整跑通、给接口任意注入测试数据、或者用秒开页面大幅提速自动化流程。配合 ruyiPage 自带的过检测 Firefox 指纹内核,这些网络能力在真实站点上同样稳定可用。

登录后查看全文
ruyipage