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.dev 2026-11-20 官网与文档核对,最新参数以官网为准。

posted @ 2026-11-22 14:30  蜘蛛人  阅读(4)  评论(0)    收藏  举报