Go Testify 怎样用 MatchedBy 只匹配结构体中的关键字段

在一次给订单服务补单元测试时，我遇到过一个很典型的 mock 失稳问题：业务真正关心的是用户和动作，但请求结构体里还带着每次都会变化的追踪号、创建时间。用完整结构体写 Mock.On，测试很快就被这些无关字段拖着变化。

如果 mock 方法接收的是复杂结构体，先把业务契约字段筛出来，再用 mock.MatchedBy 返回布尔结果。这样既能检查关键字段，也不会把运行时元数据硬编码进期望值。

官方文档：https://pkg.go.dev/github.com/stretchr/testify/mock

这篇只讨论 Testify 的 MatchedBy：如何匹配结构体字段、如何处理值类型和指针类型，以及哪些字段不应该放进 matcher。Testify 官方文档说明，MatchedBy 接收一个单参数函数，函数返回 true 才算匹配；函数签名不符合要求时会 panic。

先把完整结构体拆成业务约束

假设服务调用一个保存请求：

type SaveRequest struct {
    UserID         int
    Action         string
    IdempotencyKey string
    TraceID        string
    CreatedAt      time.Time
}

type Store interface {
    Save(req SaveRequest) error
}

type MockStore struct {
    mock.Mock
}

func (m *MockStore) Save(req SaveRequest) error {
    // 让接口方法把真实参数交给 Testify 的期望匹配器。
    return m.Called(req).Error(0)
}

订单保存的业务契约可能只有 UserID 和 Action。TraceID 用于链路追踪，CreatedAt 由运行时生成；它们仍然有价值，但不一定属于这个测试的断言范围。

直接把整个值写进期望，会把测试绑定到所有字段：

expected := SaveRequest{
    UserID:  42,
    Action:  "paid",
    TraceID: "trace-001", // 测试还要维护一个非核心字段
}

store.On("Save", expected).Return(nil).Once()

这种写法不是错误，只适合“每个字段都属于本用例契约”的场景。若时间和追踪号由被测代码生成，就应该把它们排除在本次匹配之外。

用 MatchedBy 只匹配关键字段

把期望参数换成 matcher，函数参数类型必须和 Save 的实际参数一致。这里方法接收的是值类型 SaveRequest，所以 matcher 也接收 SaveRequest：

func TestSaveUsesBusinessFields(t *testing.T) {
    store := new(MockStore)

    store.On("Save", mock.MatchedBy(func(req SaveRequest) bool {
        // 只断言业务契约，忽略每次调用都会变化的追踪号和时间。
        return req.UserID == 42 && req.Action == "paid"
    })).Return(nil).Once()

    err := store.Save(SaveRequest{
        UserID:         42,
        Action:         "paid",
        IdempotencyKey: "order-42",
        TraceID:        "trace-generated-by-runtime",
        CreatedAt:      time.Now(),
    })

    require.NoError(t, err)
    store.AssertExpectations(t)
}

matcher 的职责很窄：它只回答“这个参数是否满足本次期望”。不要在函数里修改请求、发起网络调用或依赖全局可变状态，否则测试会从一个清晰的参数判断变成隐藏的业务流程。

如果关键字段较多，可以把判断提取成有名字的函数，让失败信息和复用边界更容易理解：

func isPaidRequest(req SaveRequest) bool {
    // 订单保存只要求用户和动作匹配，运行元数据由其他测试负责。
    return req.UserID == 42 && req.Action == "paid"
}

store.On("Save", mock.MatchedBy(isPaidRequest)).Return(nil).Once()

值类型、指针和 nil 要分开处理

我第一次改这类测试时最容易忽略的是参数形态。MatchedBy 不是“自动帮你转成目标类型”的通配符；传给它的函数必须是单参数、返回 bool，并且参数类型要对应 mock 实际收到的参数。

如果接口改成接收指针，matcher 也要跟着改：

type PointerStore interface {
    Save(req *SaveRequest) error
}

pointerStore.On("Save", mock.MatchedBy(func(req *SaveRequest) bool {
    // 指针参数可能为空；先挡住 nil，再读取业务字段。
    return req != nil && req.UserID == 42 && req.Action == "paid"
})).Return(nil).Once()

反过来，把 func(*SaveRequest) bool 用在值参数上，或把返回类型写成非 bool，都不是“匹配不到”这么简单，而是 matcher 签名不符合约定。这个错误应在写测试期望时直接修正。

方案取舍：哪些字段该匹配

可以把字段分成三类，再决定 matcher 的范围：

• 业务决策字段：例如用户编号、动作、金额或资源标识。它们决定 mock 是否应该响应，通常应纳入 matcher。
• 传输或运行元数据：例如 TraceID、请求时间、重试次数。除非本用例专门验证它们，否则不必和业务字段绑定。
• 必须完整一致的字段：例如签名、幂等键或安全策略字段。它们虽然也是字符串，但如果错误会改变业务结果，就应该明确匹配。

因此，MatchedBy 不是让断言变得越宽松越好。matcher 过宽会让错误参数也通过，过窄又会让测试反复跟随实现细节变化。更稳妥的做法是：每个 matcher 只覆盖一个明确的业务契约，并用 Once、Times 等调用次数约束补上交互边界。

store.On("Save", mock.MatchedBy(func(req SaveRequest) bool {
    // 幂等键会影响重复提交判断，因此本用例把它列为契约字段。
    return req.UserID == 42 &&
        req.Action == "paid" &&
        req.IdempotencyKey != ""
})).Return(nil).Once()

如果字段判断已经复杂到需要多分支、查数据库或解析外部数据，通常说明被测对象的职责或测试夹具需要重新拆分，而不是继续把逻辑塞进 MatchedBy。

落地清单：让 matcher 稳定又可读

1. 先确认 mock 方法到底接收值还是指针，按真实签名写 matcher。
2. 只选择本用例真正要保护的业务字段，不要顺手比较所有结构体字段。
3. 指针参数先处理 nil；如果 nil 合法，把它写成单独的期望更清楚。
4. 保持 matcher 纯粹，只读取参数并返回布尔值。
5. 匹配条件较长时提取命名函数，并用 Once 或 Times 限制调用次数。

最终判断标准很简单：当追踪号或时间变化时，测试不应无故失败；当用户、动作或幂等策略等真实业务字段错误时，测试必须失败。做到这两点，MatchedBy 就把“实现细节的波动”和“业务契约的变化”分开了。

相关问题

MatchedBy 和 mock.Anything 有什么区别？

mock.Anything 会忽略参数内容，而 MatchedBy 仍然会按你写的函数检查字段。需要保护业务条件时优先使用 MatchedBy。

为什么 MatchedBy 的函数签名不对会 panic？

Testify 需要把调用参数传入这个函数并读取布尔返回值，因此函数必须是单参数且返回 bool。参数类型不对应时，应先检查接口方法和 matcher 的值/指针形态。

可以在 matcher 里修改结构体吗？

不建议。matcher 应该是纯判断；修改参数会让断言带来隐藏副作用，也会让后续调用和失败定位变得困难。