Go 分页接口怎么设计：游标参数、错误码与兼容返回

订单列表接口最初用 page=1&size=20，数据量上来后，用户连续翻页时开始遇到重复记录和漏记录。把参数名改成 cursor 只是表面动作，接口真正要稳定下来，还得先定清游标代表什么、错误如何返回，以及旧客户端能不能继续按原方式请求。

先把列表接口的目标说清楚

这个接口面向后台订单列表，默认按创建时间倒序。同一秒内可能写入多条订单，所以排序键不能只用 created_at。我们把 created_at 和递增的 id 组成稳定顺序，游标只负责记住上一页最后一条记录。

调用方关心的是三件事：这一页拿到哪些订单、下一页从哪里开始、还有没有下一页。数据库使用的复合键、编码方式和签名细节都属于服务端实现，不应该泄漏到前端。

游标参数要能表达边界，而不是只做字符串传递

接口参数可以先保持小而明确：

游标建议使用 Base64URL 编码后的 JSON，例如内部数据是 {"created_at":"2026-07-26T08:00:00Z","id":391}。生产环境还应增加签名，防止调用方伪造位置或篡改筛选条件。代码部分先省略签名，参数语义更容易看懂。

用 Go net/http 固定返回结构和参数校验

参数校验应尽量靠近 HTTP 边界完成。这样仓储层收到的就是已经归一化的 ListOrdersInput，不会在 SQL、缓存和接口层重复判断。

type ListOrdersInput struct {
    Cursor string
    Limit  int
    Status string
}

type ListOrdersResponse struct {
    Items      []Order `json:"items"`
    NextCursor string  `json:"next_cursor,omitempty"`
    HasMore    bool    `json:"has_more"`
}

type APIError struct {
    Code    string `json:"code"`
    Message string `json:"message"`
    Field   string `json:"field,omitempty"`
}

func parseListOrders(r *http.Request) (ListOrdersInput, *APIError) {
    q := r.URL.Query()
    limit := 20
    if raw := q.Get("limit"); raw != "" {
        n, err := strconv.Atoi(raw)
        if err != nil || n  100 {
            return ListOrdersInput{}, &APIError{
                Code: "invalid_limit", Message: "limit 必须在 1 到 100 之间", Field: "limit",
            }
        }
        limit = n
    }
    status := q.Get("status")
    if status != "" && !allowedStatus(status) {
        return ListOrdersInput{}, &APIError{
            Code: "invalid_status", Message: "不支持的订单状态", Field: "status",
        }
    }
    return ListOrdersInput{Cursor: q.Get("cursor"), Limit: limit, Status: status}, nil
}

这里故意把 limit=0 和 limit=101 都视为客户端错误，而不是悄悄修正。悄悄改值会让调用方误以为服务端接受了它的配置，问题通常会在压测或分页计数时才暴露。

错误码要让调用方知道下一步怎么做

分页接口常见错误至少分两类：参数本身不合法，以及游标已经失效。前者适合返回 400，后者也不要返回一段 HTML 或空列表，否则客户端无法判断是“没有数据”还是“需要从第一页重试”。

func writeAPIError(w http.ResponseWriter, status int, e APIError) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(e)
}

func ordersHandler(repo OrderRepository) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        input, apiErr := parseListOrders(r)
        if apiErr != nil {
            writeAPIError(w, http.StatusBadRequest, *apiErr)
            return
        }
        result, err := repo.List(r.Context(), input)
        if errors.Is(err, ErrCursorExpired) {
            writeAPIError(w, http.StatusBadRequest, APIError{
                Code: "cursor_expired", Message: "游标已失效，请重新加载第一页",
            })
            return
        }
        if err != nil {
            writeAPIError(w, http.StatusInternalServerError, APIError{
                Code: "internal_error", Message: "订单列表暂时不可用",
            })
            return
        }
        writeJSON(w, http.StatusOK, result)
    }
}

对外错误信息保持稳定，日志里再记录仓储错误和请求追踪号。不要把 SQL、数据库地址或内部堆栈直接放进 message，它们既帮不上调用方，也会扩大信息泄露面。

兼容旧分页客户端时，给迁移留一条窄通道

旧客户端一时不能升级时，可以在过渡期接受 page，但要明确规则：请求同时带有 page 和 cursor 时直接返回 mixed_pagination_mode。两套语义混在一起，最容易产生“第一页看起来正常，第二页开始漂移”的问题。

更稳妥的做法是让旧模式继续走原查询，新模式走游标查询，并在响应头中给旧模式加上迁移提示。等客户端覆盖率达到目标，再删除 page 分支。不要把 page 换算成一个假游标：偏移量越大，查询成本越高，而且数据插入时仍然会漂移。

测试要覆盖重复、漏项和边界返回

单测不应只断言 HTTP 200。至少准备四组数据：同一秒创建的多条订单、只有一页的数据、恰好 100 条的数据，以及中途插入新订单的数据。

• 请求第一页后，next_cursor 非空且 has_more=true 时才能继续请求。
• 连续请求两页，按订单 ID 合并后不重复、不漏掉原始快照中的记录。
• 最后一页返回空的 next_cursor 和 has_more=false。
• limit=0、limit=101、未知 status 都返回对应的 400 错误码。
• 伪造或过期游标不会变成第一页静默返回，而是得到 cursor_expired。

如果底层查询使用 (created_at, id) ，一定要让排序方向和比较符号成对出现。只改其中一个，测试数据量少时可能看不出错，到了同秒记录或翻页边界就会出现重复。

相关问题

游标分页一定比页码分页快吗？

不一定。数据量小、页码很浅时差异不明显；当调用方经常翻到很深的页，游标更容易保持稳定的查询范围。最终仍要看排序索引和实际查询计划。

游标可以直接暴露数据库自增 ID 吗？

不建议。ID 可能泄露增长速度，也无法单独表达时间排序。至少封装成不透明字符串，并在服务端校验签名和筛选条件。

数据变化后，旧游标还能继续用吗？

新插入的数据通常不会影响已经走过的位置，但删除、排序字段修正或游标过期策略可能改变结果。客户端应接受游标失效并重新加载第一页。

把接口契约收敛成一张迁移清单

上线前只要能回答下面这些问题，分页接口就具备了可维护的边界：排序是否稳定、游标是否不透明、limit 是否限幅、错误码是否可操作、旧客户端是否有退出时间，以及重复和漏项是否有回归测试。先在一个列表接口灰度，确认监控中的 400 比例、游标失效率和平均查询耗时，再推广到其他资源。