Go LDAP EscapeFilter 和 EscapeDN 为什么不能互换

在 Go 项目里，LDAP 查询值和用户 DN 都可能来自表单、配置或上游接口。它们都需要转义，但转义的对象不是同一种语法：ldap.EscapeFilter 服务于 LDAP filter，ldap.EscapeDN 服务于 Distinguished Name。把两者互换，轻则查询条件被改变，重则 DN 结构被拆成多个 RDN。

一句话结论：值要放进 (uid=...) 这类过滤器时用 EscapeFilter；值要放进 uid=...,ou=People,... 这类 DN 时用 EscapeDN。官方文档地址：https://pkg.go.dev/github.com/go-ldap/ldap/v3

本文用一个小型“按用户名搜索并准备用户 DN”的 Go 示例串起判断过程，重点只放在两个函数的适用边界。

先看输入要进入哪一种 LDAP 语法

LDAP filter 是搜索条件，例如 (&(objectClass=person)(uid=alice))；用户提供的内容只是某个断言值。filter 中的括号、星号、反斜杠和 NUL 具有特殊含义，不能原样拼接。

DN 则是目录条目的名字，例如 uid=alice,ou=People,dc=example,dc=com。这里的逗号分隔 RDN，加号可以分隔同一 RDN 中的多个属性，首字符井号和首尾空格也有专门规则。两个位置的“特殊字符集合”本来就不同，所以函数不能靠感觉替换。

组装搜索条件时只对 filter 值调用 EscapeFilter

EscapeFilter 的职责是把外部值变成可以安全放入 filter 断言的位置。它不会帮你补括号、属性名或 AND/OR 结构，因此结构仍由程序固定，外部输入只作为值进入。

package main

import (
    "fmt"

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

func buildUserFilter(login string) string {
    // 固定 filter 结构，只把外部登录名作为断言值插入。
    escaped := ldap.EscapeFilter(login)
    return fmt.Sprintf("(&(objectClass=person)(uid=%s))", escaped)
}

func main() {
    // 星号和括号是 filter 语法字符，不能直接当作普通用户名拼接。
    fmt.Println(buildUserFilter("a*(b)"))
}

这里的关键不是“把字符串变长”，而是把输入中的 filter 控制字符编码成值的一部分。比如用户输入包含星号时，EscapeFilter 会按 LDAP filter 规则处理；函数不会把它解释成通配查询。

排查查询结果为空时，先确认转义函数调用发生在构造完整 filter 之前，而且只包住用户值。若把整个 (&(objectClass=person)...) 交给 EscapeFilter，括号也会被编码，最终就不再是预期的 filter 结构。

组装用户 DN 时改用 EscapeDN

DN 的属性值可能包含逗号、加号或首尾空格。以 uid=a,b 为例，逗号如果不转义，会被 DN 解析器当成 RDN 分隔符，而不是 uid 值的一部分；这和 filter 中处理星号是完全不同的问题。

package main

import (
    "fmt"

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

func buildUserDN(login string) string {
    // 只转义 uid 的属性值，后面的 DN 层级由服务端配置固定。
    escaped := ldap.EscapeDN(login)
    return fmt.Sprintf("uid=%s,ou=People,dc=example,dc=com", escaped)
}

func main() {
    // 逗号应留在 uid 值里，而不是被当作下一个 RDN 的分隔符。
    fmt.Println(buildUserDN("a,b"))
}

EscapeDN 遵循 DN 的规则：官方文档列出的处理范围包括 " + , ; \、首尾空格、首字符 # 和 NUL。它并不负责生成完整 DN，也不会检查 uid 是否是合法属性名；这些仍是组装代码的职责。

把判断规则固定在代码边界上

可以把选择规则压缩成一个判断：看字符串下一步要被谁解析。要被 LDAP filter 解析，就用 EscapeFilter；要被 DN 解析，就用 EscapeDN。不要因为两个函数都返回字符串，就用一个统一的“通用转义”包装所有场景。

• 搜索条件：固定属性名和逻辑结构，单独转义断言值。
• 用户 DN：固定层级和属性名，单独转义 RDN 属性值。
• 二次处理：不要先用一个函数再用另一个函数，重复转义会把已经产生的反斜杠继续当成输入。

如果错误已经出现，可以按输入位置回看：查询表达式中括号或星号被编码，通常是把完整 filter 交给了错误的处理；DN 中逗号导致层级变化，通常是没有使用 EscapeDN，或把 DN 当成普通 filter 值处理。

常见问题

EscapeDN 能不能替代 EscapeFilter？

不能。两者分别面向 RFC4514 的 DN 和 RFC4515 的 filter 字符串，特殊字符集合与解析上下文不同。

应该转义完整的 DN 或完整的 filter 吗？

通常不应该。固定结构由代码构造，外部输入只在对应的属性值位置调用一次函数。这样既不会破坏结构，也更容易定位问题。

记住这条边界即可：EscapeFilter 保护 filter 值，EscapeDN 保护 DN 值；函数名相似，语法上下文不同。