Go API 接收分页参数如何防整数溢出：strconv、边界值与数据库 LIMIT

线上列表接口最容易被大家低估风险的输入，往往是两个看起来毫不起眼的参数：page 和 size。如果直接把请求里的字符串裸转成整数，再用 (page-1)*size 计算偏移量，负数、超大数字和整数溢出就可能把一次轻量查询变成全表扫描，甚至让服务在参数解析阶段就直接崩掉。处理这类接口，我更建议把“解析、边界、计算、查询”拆成四个独立可检查的关口。

先把分页接口要保护的资产说清楚

分页参数本身不是敏感数据，但它决定了数据库一次要读取多少行、服务端要序列化多少对象，以及单个请求能占用连接的时长。以 GET /api/orders?page=2&size=20 为例，接口真正要保护的是数据库查询配额、响应体大小和请求处理时长。

因此，合法输入不应该只定义成“能转成整数”。在这个接口里，可以先约定 page >= 1、1 ，并把二者的乘积限制在 int64 能安全表达的范围内。超过范围时直接返回 400，而不是默默把参数改成第一页的默认值。

攻击路径通常从一次简单的乘法开始

最早期的实现代码往往只有寥寥几行：

page, _ := strconv.Atoi(r.URL.Query().Get("page"))
size, _ := strconv.Atoi(r.URL.Query().Get("size"))
offset := (page - 1) * size
rows, err := db.QueryContext(ctx,
    "SELECT id, amount FROM orders ORDER BY id DESC LIMIT ? OFFSET ?", size, offset)

这里堆了四个很容易踩的问题：解析错误直接被丢弃，空字符串会落到类型零值；size 没有设置业务上限；page-1 和乘法在不同平台的 int 宽度下还存在溢出风险。就算数据库驱动最终拒绝了负的 OFFSET，请求也已经走完了不必要的解析和日志链路。

这类输入不需要很高的请求量就能触发问题。一个超大的 size 可能让数据库准备超大结果集，一个接近整数上限的 page 可能让偏移量直接回绕成负数或者完全不符合预期的数值。问题的核心从来不是“攻击者能不能查到数据”，而是服务是否允许客户端随意改写服务端的资源使用配额。

解析和业务边界要分成两道门

strconv.ParseInt 能帮我们判断字符串是不是合法整数，以及它有没有超出指定位宽的取值范围；但它不会替接口决定业务层面允许多大的页码。下面的解析函数就把这两个责任完全分开：

type PageInput struct {
    Page   int64
    Size   int64
    Offset int64
}

func parsePage(r *http.Request) (PageInput, error) {
    q := r.URL.Query()
    page, err := strconv.ParseInt(q.Get("page"), 10, 64)
    if err != nil || page  100 {
        return PageInput{}, fmt.Errorf("invalid size")
    }

    maxInt64 := int64(^uint64(0) >> 1)
    if page-1 > maxInt64/size {
        return PageInput{}, fmt.Errorf("page offset too large")
    }
    return PageInput{Page: page, Size: size, Offset: (page - 1) * size}, nil
}

这里的除法检查比“先乘再看结果是否异常”更可靠：(page-1) 成立时，乘法结果才不会超过 int64 上限。size 已经限制到 100 时，数据库压力仍然需要额外的业务判断：如果业务数据只保留最近 90 天，页码过大的情况可以直接返回空列表或业务错误，没必要让数据库跳过海量历史记录。

空参数和非法参数不要伪装成第一页

如果产品约定分页参数是可选的，要在代码里明确定义默认值，比如缺少 page 时默认用 1、缺少 size 时默认用 20；但如果参数已经传了但值为空、带小数、带空格或者超出约定范围，就要直接返回 400。这样日志才能清晰区分“客户端没传这个参数”和“客户端传了个错误值”两种场景。

数据库层只接收规范化后的 LIMIT 和 OFFSET

解析成功不代表生成的 SQL 就绝对安全。表名、排序字段这类结构类参数不能直接从请求里读取，分页数值则要通过驱动的参数绑定功能传入。下面的示例查询仍然固定了排序字段，并且只把已经完成校验的两个整数传给数据库：

input, err := parsePage(r)
if err != nil {
    http.Error(w, "bad pagination", http.StatusBadRequest)
    return
}

rows, err := db.QueryContext(r.Context(), `
    SELECT id, amount, created_at
    FROM orders
    ORDER BY created_at DESC, id DESC
    LIMIT ? OFFSET ?`, input.Size, input.Offset)
if err != nil {
    // 记录查询模板和规范化参数，不记录完整请求头
    http.Error(w, "query failed", http.StatusInternalServerError)
    return
}
defer rows.Close()

如果驱动或者数据库对 LIMIT 参数有特殊语法要求，要以目标数据库和驱动的实际测试结果为准，不能为了临时跑通就直接把数值拼进 SQL 字符串。分页输入的边界校验和 SQL 参数化是两件独立的事，缺哪件都不行。

把拒绝原因写进日志，验收才有证据

安全校验最后要落到可观测层面。建议被拒绝的请求要记录接口名、参数是否存在、解析结果、拒绝原因和请求耗时，参考格式如下：

日志里不要把完整 Cookie、Authorization 或者原始请求头全部打出来。分页参数属于低敏感输入，但审计日志仍然要遵守最小记录的原则。指标层面至少要观察 400 请求占比、查询耗时、返回行数和数据库连接等待时长；修复完成后，异常参数应该在 HTTP 层就被直接拦住，不会出现在慢查询列表里。

一组边界测试比手工点几次更可靠

可以把输入校验逻辑直接写到表驱动测试里，重点覆盖空字符串、负数、最大值和乘法边界场景：

func TestParsePage(t *testing.T) {
    cases := []struct {
        name, page, size string
        wantErr          bool
    }{
        {"default-like values", "1", "20", false},
        {"negative page", "-1", "20", true},
        {"size too large", "1", "101", true},
        {"offset overflow", "9223372036854775807", "100", true},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            req := httptest.NewRequest(http.MethodGet,
                "/orders?page="+tc.page+"&size="+tc.size, nil)
            _, err := parsePage(req)
            if (err != nil) != tc.wantErr {
                t.Fatalf("err=%v wantErr=%v", err, tc.wantErr)
            }
        })
    }
}

测试名称可以按照团队的接口约定调整；上面的重点不是固定某个默认值，而是保证校验拒绝逻辑不会被后续的重构操作悄悄删掉。如果换成 uint，也不能省略负数输入的处理，因为负号在解析阶段仍然是完全来自外部的不可信数据。

相关问题

为什么不直接把 page 和 size 解析成 int？

int 适合索引和切片下标场景，但对外接口协议更适合明确指定位宽。用 int64 解析完成后，再在靠近数据库调用的位置转换成驱动需要的类型，边界逻辑会更容易做单元测试。

size 设置成 100 就不会有慢查询了吗？

不会。深分页场景下数据库仍然需要跳过大量行，排序和过滤条件也会直接影响查询耗时。数据量较大时，要另行评估基于游标的分页方案或者补充合适的索引。

遇到非法 page 时返回第一页可以吗？

不建议。这么做会把调用方的 bug 直接隐藏掉，也可能让重试逻辑或者爬虫反复命中第一页。参数存在但非法时返回 400，只有参数完全没传的时候才按协议走默认值。

发布前的分页安全清单

• 解析错误、负数、空值和超大整数都有明确的处理结果。
• size 有产品级的硬上限，page*size 有专门的溢出检查逻辑。
• 排序字段固定，数值通过 SQL 参数绑定，不会手动拼接查询字符串。
• 400 请求、慢查询、返回行数和数据库等待都配置了可观测指标。
• 边界测试覆盖正常、非法和接近最大整数的各类输入。

分页接口的安全边界从来不是一行简单的校验代码。把输入解析、资源配额控制、SQL 参数化和验收日志拆开之后，异常请求会在最靠近入口的位置被拦截，数据库也能只处理真正符合协议规范的查询。