用途:在业务代码与 SerpAPI 官方客户端之间建立一层应用自有的窄网关,隔离厂商参数、凭证和可变结果结构,使调用可测试、可维护。
主要能力:定义仅接受受支持引擎及应用可控的 locale、安全、分页、输出选项的请求类型;定义带显式可选段、将厂商元数据与领域数据分离的规范响应类型;把官方客户端注入到小接口后方,便于用固定数据替换而无需拦截网络;集中处理超时、瞬态故障的有界重试、429 分类、脱敏和搜索 ID 日志。
使用方式:用 Read、Glob、Grep 梳理现有调用点与类型,用 WebFetch 核对官方客户端接口,再用 Write 或 Edit 编写网关、schema、fixture 和测试。认证上在服务端最外层组合根注入 SERPAPI_KEY,不把它放入领域类型、缓存键、错误对象、遥测或序列化请求参数。Python 客户端返回 SerpResults 映射并提供 next_page() 与 yield_pages(),使用 yield_pages() 时必须配合页数或搜索预算;JavaScript 客户端提供 promise 与回调形式(getJson、getJsonBySearchId、getAccount),但不含内置分页,需按引擎用文档给出的 token 或 offset 手动分页。输出可选 JSON、HTML 或 Markdown,已知字段时可用 json_restrictor 精简 JSON 载荷。
适用场景:需要把 SerpAPI 调用收敛到可测试网关的生产项目,尤其是多引擎、需要分页预算与统一错误分类的服务端集成。
限制:未提供具体价格、免费额度或性能数据;需先选定并锁定官方依赖版本,准备好各响应结构的脱敏 fixture;错误处理需将 Python 的 HTTPError 或 TimeoutError 映射为类型化应用错误,JavaScript 拒绝需规范化状态与消息;分页达到预算时返回显式部分结果与续传状态;未知引擎或参数应在发起请求前本地拒绝。代码示例中 JSON 键名、函数名和输出结构保持原样,实际字段与返回格式以官方文档为准。