Go go-cmp 比较含未导出字段的结构体为什么 panic

用 cmp.Equal 比较一个含小写字段的结构体，测试突然出现 cannot handle unexported field，原因通常不是断言写错，而是 go-cmp 有意不替你猜测包内字段是否属于对外可观察状态。未导出字段默认不能被直接比较，因此会 panic。

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

先看这个字段是不是测试真正关心的业务结果：不关心就定向忽略；关心的是公开语义就写 Comparer；只有确实掌握内部表示且类型由自己维护时，才考虑 AllowUnexported。

先从 panic 路径判断到底比较到了什么

假设被测类型由当前包维护，并且 traceID 只是内部实现细节：

package user_test

import (
    "testing"

    "github.com/google/go-cmp/cmp"
)

type response struct {
    Code    int
    Message string
    traceID string // 只服务于内部追踪，不属于接口结果
}

func TestResponse(t *testing.T) {
    want := response{Code: 200, Message: "ok", traceID: "a"}
    got := response{Code: 200, Message: "ok", traceID: "b"}

    // 这里会因比较路径进入未导出字段而 panic。
    if diff := cmp.Diff(want, got); diff != "" {
        t.Fatalf("response differs (-want +got):\n%s", diff)
    }
}

排查时重点看 panic 中的路径和类型名，而不是先把所有字段都忽略。go-cmp 的默认行为是递归比较结构体字段；当字段不可通过公开接口安全访问时，它会停止并给出处理建议。这个设计避免测试无意中绑定到另一个包的内部布局。

先决定：这个字段应该被忽略还是被解释

修复前先把字段分成两类。像追踪 ID、缓存指针、懒加载状态这类值，如果不影响接口语义，可以忽略；如果字段本身不可见，但它承载了对用户有意义的状态，则应该通过比较器把内部表示转换成业务语义。直接放行内部字段只是第三种选择。

自有结构体：只忽略直接未导出字段

当 traceID 只是响应对象的内部状态，可以明确告诉 go-cmp 忽略 response 的未导出字段：

import (
    "testing"

    "github.com/google/go-cmp/cmp"
    "github.com/google/go-cmp/cmp/cmpopts"
)

func TestResponseIgnoringInternalState(t *testing.T) {
    want := response{Code: 200, Message: "ok", traceID: "a"}
    got := response{Code: 200, Message: "ok", traceID: "b"}

    // 只忽略 response 的直接未导出字段，公开结果仍会继续比较。
    if diff := cmp.Diff(want, got, cmpopts.IgnoreUnexported(response{})); diff != "" {
        t.Fatalf("response differs (-want +got):\n%s", diff)
    }
}

这里的“直接”很重要。如果 response 还有一个导出字段 meta，而 meta 的类型内部又有未导出字段，仍可能继续 panic。此时不要把整个对象树盲目放行；要么把确实需要忽略的嵌套自有类型一并列出，要么为 meta 写比较器。

第三方类型和嵌套字段怎么处理

第三方类型的未导出字段属于维护者的实现选择，直接使用 IgnoreUnexported 会让测试依赖它当前的内部布局。更稳妥的做法是提取测试真正关心的结果，并用 cmp.Comparer 定义比较规则。例如只比较自有包装类型的公开方法返回值，而不是比较第三方对象内部指针。

type token struct {
    raw string // 内部编码，测试不应依赖具体格式
}

// tokenEqual 只比较业务上稳定的规范值。
func tokenEqual(x, y token) bool {
    return normalizeToken(x.raw) == normalizeToken(y.raw)
}

func normalizeToken(raw string) string {
    // 示例中只保留稳定语义；真实项目应替换成明确的规范化规则。
    return raw
}

func sameToken(want, got token) bool {
    // Comparer 让比较意图停在业务语义，不继续深入 raw。
    return cmp.Equal(want, got, cmp.Comparer(tokenEqual))
}

只有当类型由你维护、内部字段就是待测不变量，而且你愿意让实现变更推动测试重新审视时，才使用 cmp.AllowUnexported(response{})。对错误值、协议对象等已有稳定语义的类型，也应优先使用项目提供的比较辅助函数，而不是自行开放全部内部字段。

修复后用这份清单复查

• panic 路径是否已经定位到具体类型和字段，而不是通过全局忽略掩盖。
• 忽略选项是否只绑定到自有类型；嵌套结构体是否有独立的处理意图。
• Comparer 是否比较稳定语义，并且没有在比较函数里修改输入或隐藏错误。
• AllowUnexported 是否只用于你控制实现的类型，内部字段变化是否应该让测试失败。

如果只是接口响应断言，通常选择 IgnoreUnexported 或自定义 Comparer；如果测试的是内部不变量，才让 AllowUnexported 明确承担这份耦合。这样 panic 就从“莫名其妙的测试崩溃”变成了比较意图没有声明的信号。

相关问题

为什么不用 reflect.DeepEqual 直接替换？

它的访问和比较语义不同，替换后可能把原本不想绑定的内部状态纳入结果；应先确认测试要表达的业务契约。

IgnoreUnexported 能递归忽略所有私有字段吗？

不能。它针对传入结构体类型的直接未导出字段，嵌套结构体需要单独声明或改用语义比较器。