Go LDAP 怎样用分页查询读取大型目录结果

Go 通过 LDAP 查询大型目录时，别把所有条目一次性塞进内存。更稳妥的做法是使用 github.com/go-ldap/ldap/v3 的 ControlPaging：每次取固定数量，读取服务端返回的 opaque cookie，再在同一条连接上请求下一页。最后拿到空 cookie，才说明这次搜索已经结束。

官方地址：https://pkg.go.dev/github.com/go-ldap/ldap/v3

分页不是把客户端数组切片，而是让 LDAP 服务端用分页控制维护搜索游标。客户端只负责重复发送相同搜索条件，并把上一页返回的 cookie 带到下一页。

先固定搜索请求，再加入分页控制

分页循环最容易写错的地方，是每一轮重新拼装了不同的过滤器，或者把 cookie 当成页码自己递增。RFC 2696 的分页控制由页大小和服务端 cookie 组成，cookie 不需要解码，也不能跨连接复用。

package main

import (
    "fmt"

    "github.com/go-ldap/ldap/v3"
)

func readDirectory(conn *ldap.Conn) error {
    // 只取业务需要的属性，避免每页携带过大的对象数据。
    attrs := []string{"uid", "cn", "mail"}
    req := ldap.NewSearchRequest(
        "ou=people,dc=example,dc=org",
        ldap.ScopeWholeSubtree,
        ldap.NeverDerefAliases,
        0, 0, false,
        "(&(objectClass=person)(mail=*))",
        attrs,
        nil,
    )

    // pageSize 是单次响应的条目上限，不是最终总数。
    pageSize := uint32(200)
    paging := ldap.NewControlPaging(pageSize)

    for {
        // 每轮只更新 cookie，搜索条件和分页大小保持不变。
        req.Controls = []ldap.Control{paging}
        result, err := conn.Search(req)
        if err != nil {
            return fmt.Errorf("search ldap page: %w", err)
        }

        for _, entry := range result.Entries {
            // 这里可以写入队列或逐条处理，不必累计全部结果。
            fmt.Println(entry.GetAttributeValue("uid"))
        }

        control := ldap.FindControl(result.Controls, ldap.ControlTypePaging)
        next, ok := control.(*ldap.ControlPaging)
        if !ok || next == nil {
            return fmt.Errorf("LDAP 响应缺少分页控制")
        }
        paging.Cookie = next.Cookie
        if len(paging.Cookie) == 0 {
            return nil // 空 cookie 表示服务端没有下一页。
        }
    }
}

示例中的 fmt.Println 只是占位处理点，生产代码可以在这里做去重、写入数据库或投递消息。关键是不要修改 BaseDN、过滤器、属性列表和连接对象；分页游标依赖这组上下文。

循环读取每一页并判断是否结束

服务端返回的分页控制会带回下一次搜索需要的 cookie。把它原样交给下一轮即可，不要把 cookie 转成字符串后截断，也不要用本地页码替代它。若响应没有分页控制，应立即报错，避免把“只返回了第一批”误判为“目录已读完”。

连接生命周期也要包住整个循环：先建立连接、完成 Bind，再开始第一页搜索，最后统一关闭。切换到连接池中的另一条连接，会让原 cookie 失去对应的会话上下文。

生产环境的连接、权限与参数边界

如果目录服务支持 TLS，先按服务端要求使用 LDAPS 或 STARTTLS，再执行 Bind。账号只申请读取目标 OU 所需的权限；分页不会绕过服务端 ACL，也不能突破服务端对单次查询、时间或响应大小的限制。

分页控制不代表结果具有稳定排序。如果目录在读取期间发生新增或删除，跨页结果的业务一致性仍要由目录服务、过滤器和后续去重策略共同保证；需要稳定顺序时，应确认服务端是否支持排序控制，并单独评估它和分页的组合。

常见问题

为什么每页都返回相同数据？

通常是没有把响应 cookie 写回下一次请求，或者每轮重新创建了没有 cookie 的分页控制。保留同一个 ControlPaging，只更新它的 Cookie。

为什么结果少于目录实际条目数？

先检查过滤器、服务端分页支持和 ACL，再确认循环确实等到空 cookie。某些服务端会在 cookie 过期或查询上下文改变后拒绝续页，此时应重新发起一次完整搜索，而不是盲目复用旧 cookie。