Go 封装 SerpBase 生产客户端备忘录:限速、重试边界与指针类型核账
11 月 21 日下午把一个 Python 采集脚本重写成 Go 常驻服务时,我在 encoding/json 建模阶段栽了个很隐蔽的小跟头:顺手把 SerpBase 响应信封里的 credits_charged 声明成了普通 int。写单测 mock 一条超时结算中("credits_charged": null)的回执时,Go 静默把它反序列化成了 0,让对账逻辑把「仍在结算中」误判成了「确定未扣费」。
趁着今天把整套 Go 客户端的封装细节整理成一份生产备忘录,重点记下 Go 语言里对接 SerpBase 必须提前卡死的几个类型与并发边界。
一、响应信封建模:credits_charged 必须用 *int
SerpBase 所有标准 POST 端点在 HTTP 层都返回 200,业务成败由 JSON 顶层的 status 决定(0 为成功,非 0 时查看 error 与响应头 X-SerpBase-Retryable)。其中 credits_charged 在官方文档里有明确的三态语义:0 表示未扣费(如参数校验拦截、限流、通道忙),正整数表示本次实扣 credits,null 表示连接中断或超时后进入事后结算状态(失败退、成功扣)。
在 Go 里用 *int 承接这个字段,才能在落库对账时把 nil(待对账)和 0(零扣费)干净分开:
package serpbase
import "encoding/json"
type Envelope struct {
Status int `json:"status"`
RequestID string `json:"request_id"`
ElapsedMS int `json:"elapsed_ms"`
CreditsCharged *int `json:"credits_charged"` // nil=结算中, 0=未扣费, >0=实扣
Error string `json:"error,omitempty"`
Organic json.RawMessage `json:"organic,omitempty"`
}
func (e *Envelope) ChargeState() string {
if e.CreditsCharged == nil {
return "settling"
}
if *e.CreditsCharged == 0 {
return "uncharged"
}
return "charged"
}
二、客户端核心:共享账号 QPS 限速 + Retryable 退避重试
在 Go 里开几十个 goroutine 并发调搜索接口非常顺手,但写客户端前要先对齐 SerpBase 的限流规则:同一个账号下的所有 API Key 和端点共享同一个 QPS 上限(按累计 USD 预付包与自动充值自动升档:$3→2、$50→5、$100→10、$200→15、$1,000→50、$10,000→500 QPS,只升不降,订阅与赠送不计入)。
因此 rate.Limiter 应该绑定在全局单例 Client 上,而不是按请求或按协程各自创建。另外,服务端文档说明请求在 30 秒内完成(部分上游重试可能耗到 15–20 秒),客户端 http.Client 的超时建议设在 35s 左右,配合 X-SerpBase-Retryable 和 Retry-After 做退避重试——SerpBase 的计费规则保证了重试安全,只计成功的那一次:
package serpbase
import (
"bytes"
"context"
"encoding/json"
"fmt"
"net/http"
"strconv"
"time"
"golang.org/x/time/rate"
)
type Client struct {
apiKey string
baseURL string
http *http.Client
limiter *rate.Limiter
}
func NewClient(apiKey string, accountQPS float64) *Client {
return &Client{
apiKey: apiKey,
baseURL: "https://api.serpbase.dev",
http: &http.Client{Timeout: 35 * time.Second},
limiter: rate.NewLimiter(rate.Limit(accountQPS*0.85), 1), // 留 15% 余量防瞬时撞 1029
}
}
func (c *Client) PostJSON(ctx context.Context, path string, body any, maxRetries int) (*Envelope, error) {
raw, err := json.Marshal(body)
if err != nil {
return nil, err
}
for attempt := 0; attempt <= maxRetries; attempt++ {
if err := c.limiter.Wait(ctx); err != nil {
return nil, err
}
req, _ := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, bytes.NewReader(raw))
req.Header.Set("X-API-Key", c.apiKey)
req.Header.Set("Content-Type", "application/json")
resp, err := c.http.Do(req)
if err != nil {
if attempt == maxRetries {
return nil, err
}
time.Sleep(time.Duration(attempt+1) * time.Second)
continue
}
var env Envelope
decErr := json.NewDecoder(resp.Body).Decode(&env)
resp.Body.Close()
if decErr != nil {
return nil, decErr
}
if env.Status == 0 {
return &env, nil
}
retryable := resp.Header.Get("X-SerpBase-Retryable") == "true"
if !retryable || attempt == maxRetries {
return &env, fmt.Errorf("serpbase status=%d req=%s err=%s", env.Status, env.RequestID, env.Error)
}
waitSec, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
if waitSec <= 0 {
waitSec = attempt + 1
}
time.Sleep(time.Duration(waitSec) * time.Second)
}
return nil, fmt.Errorf("unreachable")
}
如果调用 POST /google/search 时传了 "format": "markdown",记得不要走上面这套 JSON 解码路径——Markdown 模式直接返回纯 text/markdown(不带 JSON 信封),单独写一个返回 string 的 PostMarkdown 方法读取即可。
三、顺手把两个 0 credit 辅助接口和指标挂进客户端
生产服务跑起来之后,有两个免费辅助端点非常值得直接封进同一个 Go 客户端,省得运维写一堆零散 shell 脚本:
GET /account/credits(0 credits,60 次/分):在服务里的 Prometheus Collector 里每 5 分钟拉一次,把permanent_credits和expiring_credits暴露成 Gauge 指标,余额低于阈值自动发告警。POST /google/resolve(0 credits,30 次/分,单次最多 50 条):采集结果里带google.com/goto或/url包装的链接,攒够一批直接发过去洗成真实目标 URL,不额外花额度。
这里同步记录一份 2026-11-20 核对过的 SerpBase 核心口径供团队评审参考:目录共 49 个端点(44 个当前可用),按端点固定 0–3 credits/请求;新账号注册送 500 免费 credits 且不绑卡;标准预付包从 $10/20k($0.50/1k)到 $1,000/3.3M($0.30/1k)且 credits 不过期,月订阅 Pro Monthly 为 $100/400k($0.25/1k);只为成功请求付费、失败自动退款、重试只计成功那次;另内置 27 个 engine 的 SerpApi 兼容端点(GET /google/serpapi/search.json),存量 SerpApi 项目改 base URL 即可迁移。
四、上线前拿 500 免费额度跑通三类单测
把上面这个 Client 放进仓库后,上线前建议直接用 SerpBase 文档 注册送的 500 免费 credits 跑通三项核验:一条正常 POST /google/search 确认 status == 0 且 *env.CreditsCharged == 1,一条 mock 的 null 响应确认 ChargeState() == "settling",以及一条 GET /account/credits 确认监控指标能正确读到剩余额度。这三关过了,后面并发放大到 15 QPS 或 50 QPS 基本不会在客户端层出幺蛾子。
透明度声明:文中端点路径、状态码、QPS 升档规则与价格均按
serpbase.dev2026-11-20 官网与文档核对,最新参数以官网为准。

浙公网安备 33010602011771号