Go LDAP 查询返回 Referrals 为什么不等于已经读到所有条目

Go LDAP 查询返回的 Referrals 是引用地址，不是那些地址上的目录条目。go-ldap 的普通 Search 会把当前响应里的条目与引用分别放入 Entries 和 Referrals，并不会仅因收到了引用就自动连接其他服务器、认证和读取其全部结果。因此有 Entries、甚至本次 Search 没报错，也不等于已经完成跨目录查询。

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

如果应用只是列出一个端点返回的人员记录，可以明确限定这个范围；如果要同步跨目录数据，则必须先定义如何处理引用和不完整状态。不能用“能拿到几条记录”替代这个决定。

条目与引用是两种不同的结果

LDAP 目录可以分布在不同服务中。当前服务器在搜索时可能返回它实际提供的条目，也可能给出继续处理相关范围的引用。引用提供后续位置的信息，不包含已经读取那个位置的证明。客户端是否继续以及如何继续，是另一个处理过程。

go-ldap 的 Search 实现对条目响应追加 Entries，对搜索引用追加 Referrals，再处理搜索结束消息。这里没有隐含的递归拨号动作。应用只循环 Entries，就只消费了实际条目部分；引用内容不会自动被转成 Entry。

本次结束不代表引用范围已经完成

需要区分搜索过程中的 continuation reference 与最终结果码为 referral 的情况。前者可能与条目和本次成功结束一起出现；后者通过最终结果的错误处理路径报告。仅判断 Referrals 长度或者仅判断 error，都是只观察结果的一个侧面。

错误发生之前已经收到部分条目，也不意味着应该把它们当成完整名单。调用方可以保留这些数据用于诊断或明确的部分展示，但应同时保留“不完整”的事实。大小限制、时间限制、分页未结束和权限范围也会影响结果，引用并不是唯一因素。

按查询范围选择处理方式

对只连接一个可信端点的小型服务，第二种策略通常更容易解释；对分布式目录聚合，则应有专门的引用处理模块。这里比较的是应用策略，不是几个库的性能排名，也不能把“自动追踪”当作无条件更好的选择。

先写一个明确不追踪引用的查询函数

下面是可集成到应用的完整函数，接收已经建立的 LDAP 连接，保留条目和引用，并将未处理引用报告给上层。它不读取密码，不自动重新认证，也不关闭调用方的连接。

package directory

import (
    "fmt"

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

type LocalResult struct {
    Entries []*ldap.Entry
    Referrals []string
}

func SearchLocal(conn *ldap.Conn, baseDN string) (LocalResult, error) {
    if conn == nil {
        return LocalResult{}, fmt.Errorf("LDAP连接不能为空")
    }
    request := ldap.NewSearchRequest(
        baseDN,
        ldap.ScopeWholeSubtree,
        ldap.NeverDerefAliases,
        500, 10, false,
        "(objectClass=person)",
        []string{"cn"},
        nil,
    )
    // conn由调用方完成TLS、认证与超时配置，本函数不接管连接。
    result, err := conn.Search(request)
    out := LocalResult{}
    if result != nil {
        // 同时保留已返回的条目和引用，避免把部分结果丢掉。
        out.Entries = result.Entries
        out.Referrals = append([]string(nil), result.Referrals...)
    }
    if err != nil {
        return out, fmt.Errorf("LDAP搜索失败，已返回条目不能视为完整: %w", err)
    }
    if len(out.Referrals) != 0 {
        // 本策略不自动追踪，只报告仍有未处理的引用。
        return out, fmt.Errorf("存在%d条未处理引用，不能声称跨目录完整",
            len(out.Referrals))
    }
    return out, nil
}

示例中的500条和10秒是请求限制，不是“完整获取500条”的承诺。服务器还可能施加自己的约束；超过限制时，应处理错误。该函数未实现分页，也不声称解决所有完整性问题。代码是集成示例，本文没有连接目录或提供虚构运行记录。

调用方应同时查看返回值和错误：有错误时，不把 Entries 当全量成功结果。无引用且无错误，也只能说明这次请求在当前范围内完成，不能据此断言整个组织目录全部可见。

需要追踪时，为每个目标建立处理政策

引用地址应先按目标地址白名单和协议政策判断是否允许访问，再决定连接、TLS要求、认证身份以及查询参数。不能把当前连接的凭据不加区分地发送到返回的任意地址。LDAP URL 的查询范围等内容也应按协议和应用约定解释，而不是简单替换主机名后原样重试。

跨目录处理还需要记录已访问目标、限制跳转深度、合并重复条目并处理部分目标失败。失败时向上层报告哪些范围尚未完成，而不是把能够拿到的条目直接命名为全量结果。相关记录可以只保存目标标识和状态，避免无必要地输出整份目录属性。

分页与引用是不同维度。分页用于继续读取某次查询的后续页；引用则指向继续处理相关目录范围的位置。把 Search 改成 SearchWithPaging，不能自动取代引用策略，也不能因为处理了引用就忽略分页是否结束。

• 区分Entries中的数据与Referrals中的后续位置。
• 同时处理Search错误与引用列表。
• 为业务明确单端点范围或跨目录完整范围。
• 对跨目标访问设置身份、协议和循环限制。
• 将部分结果状态传递到展示或同步提交层。

Referrals有值是不是代表查询失败？不一定，它可能与本次实际返回的条目并存。是否符合业务要求，取决于应用是否需要覆盖引用范围。

设置DerefAliases能自动追踪Referrals吗？不能把别名解引用与引用追踪混为一谈，它们处理的对象不同。

没有Referrals就能宣布全局完整吗？不能，还要考虑请求范围、身份可见性、服务器限制和分页等条件。

参考：go-ldap 搜索返回结构与处理实现、RFC 4511 搜索继续引用。