Go 接口设计：接口参数不够用时，该不该加个 struct

接入第三方支付渠道时撞上一个很具体的问题：项目里已经有一个通用的支付接口

1
2
3

type IPay interface {
    QueryOrder(tradeNo, total string) (map[string]interface{}, error)
}

新接入的渠道查单接口要求同时传两个字段：商户这边的订单号，和支付渠道那边自己生成的订单号。可接口签名只有两个 string 参数，位置和语义早被前面的渠道锁死了。

这类问题在 Go 项目里反复出现不是偶然——Go 没有函数重载，也没有默认参数，一个方法签名从定义那一刻起就是唯一的、固定的。Java 或 Python 遇到同样的情况，可以再重载一个签名、或者给新参数一个默认值，两边都不用动老代码；Go 没有这条退路，签名要么原地不动，要么牵一发动全身。

借道传参：能用，但看运气

改接口签名意味着要动所有已经接入的渠道实现，压力不小。当时更快的做法是不动签名，在调用方对这个新渠道单独处理，把 total 参数挪过来传渠道订单号：

// payment.go 调用方
if payChannel == "new_channel" {
    _, err = e.QueryOrder(params.OutTradeNo, params.ChannelTradeNo) // total 借用为渠道订单号
} else {
    _, err = e.QueryOrder(queryTradeNo, params.Money)
}

// new_channel.go 实现方
func (ep *NewChannelPay) QueryOrder(tradeNo, total string) (...) {
    params := map[string]interface{}{
        "order_sn":  tradeNo,
        "trade_num": total, // 按约定解读，实为渠道订单号
        ...
    }
}

能跑，问题也确实解决了，但埋下两个雷：参数的真实语义完全靠注释和口头约定维护，total 在这个分支里其实是渠道订单号，下一个接手的人如果不看注释，大概率会把它当金额传；下次再接一个需要额外字段的渠道，又得在调用方加一个 if 分支，同样的补丁打第二次。接口本该描述”这个方法需要什么数据”，现在变成了”这个方法第二个参数在不同分支里代表不同东西”，签名对读代码的人撒了谎。

这一招还有个更根本的前提：这次查询本身用不上金额，才腾得出 total 这个位置去装渠道订单号。如果新渠道的查单接口同时要商户订单号、渠道订单号、金额三个必填值——两个参数位只够装两个东西，借道传参直接失效，没有第三个位置可以牺牲了。真到了这一步，如果还想硬撑着不改签名，能想到的办法有两条，但都不算好。

死磕不改签名的另外两条路

办法一：把多个值拼进一个字符串

// total 参数塞进一个用分隔符拼接的字符串
total := params.Money + "|" + params.ChannelTradeNo

// 实现方里再拆开
parts := strings.Split(total, "|")
money, channelTradeNo := parts[0], parts[1]

问题很明显：分隔符本身可能出现在业务数据里（金额格式变化、订单号规则调整），一旦冲突解析就直接错位；这套”打包再解包”的逻辑还分散在调用方和实现方两处，全靠字符串操作，编译器帮不上任何忙，类型系统形同虚设。

办法二：定义一个可选的能力接口，不动 IPay 本身

type IPay interface {
    QueryOrder(tradeNo, total string) (map[string]interface{}, error)
}

// 需要渠道订单号的实现，额外实现这个"能力接口"
type ChannelTradeNoQuerier interface {
    QueryOrderWithChannelTradeNo(tradeNo, channelTradeNo, total string) (map[string]interface{}, error)
}

// 调用方用类型断言探测这个能力：有就走扩展方法，没有就走老接口
if q, ok := e.(ChannelTradeNoQuerier); ok {
    resp, err = q.QueryOrderWithChannelTradeNo(params.OutTradeNo, params.ChannelTradeNo, params.Money)
} else {
    resp, err = e.QueryOrder(params.OutTradeNo, params.Money)
}

这是 Go 标准库里常见的手法——http.Flusher、io.ReaderFrom 都是同一个思路：主接口保持不变，需要额外能力的实现单独多实现一个接口，调用方用类型断言探测。它确实没有碰 IPay 的签名，类型也是安全的，比字符串拼接靠谱得多。但代价是调用方永远要多写一次类型断言分支，渠道差异越多，这种”能力接口”就定义得越多——真到了每接一个新渠道都要单独定义一个能力接口的地步，维护成本并不比 struct 化更低，只是把复杂度从”改签名”挪到了”接口数量”上。

真正的解法：把参数包进一个 struct

前面两条办法本质上都是在绕开”改签名”这三个字，绕来绕去反而更麻烦。真正该做的是正面解决——把 QueryOrder 的参数从两个裸 string 改成一个结构体：

type QueryOrderReq struct {
    OrderSN        string // 商户订单号
    ChannelTradeNo string // 渠道订单号
    Money          string // 金额
}

type IPay interface {
    QueryOrder(req QueryOrderReq) (map[string]interface{}, error)
}

调用方统一构造一次 req，每个渠道的实现只取自己需要的字段：

resp, err := e.QueryOrder(QueryOrderReq{
    OrderSN:        params.OutTradeNo,
    ChannelTradeNo: params.ChannelTradeNo,
    Money:          params.Money,
})

NewChannelPay 只关心 OrderSN 和 ChannelTradeNo，老渠道的实现只关心 OrderSN 和 Money——各取所需，不用再靠位置和注释猜语义。这个重构能落地的关键，在于 Go 的一个具体规则：struct 里没有显式赋值的字段，会被自动填成对应类型的零值（string 是 ""，int 是 0，指针是 nil）。这意味着以后再接入第三个渠道，需要一个新字段（比如 SubMerchantID），只需要在 QueryOrderReq 里加一行，已有的调用方和渠道实现完全不用跟着改——它们构造 QueryOrderReq{} 时没有填 SubMerchantID，这个字段自动是空字符串，对现有逻辑没有任何影响。接口签名 QueryOrder(req QueryOrderReq) 本身也没变，struct 把”新增字段”和”新增参数”两件事彻底解耦了。

调用点的变化也很直接：e.QueryOrder(tradeNo, total) 光看调用点完全猜不出 total 在这个分支里到底传的是什么，必须跳到实现代码里看注释；req.ChannelTradeNo 这种写法字段名本身就是文档。借道传参每加一个特殊渠道就要在调用方加一个 if 分支，扩展成本随渠道数量递增；struct 方案不管接入多少个渠道，加字段永远是同一个动作——加一行定义。

零值兜底是把双刃剑

前面说”没填的字段自动填零值”是非破坏性变更的关键，但这句话反过来看是个陷阱：**Go 没法区分”调用方没填这个字段”和”调用方明确想传空字符串/传 0”**。QueryOrderReq{OrderSN: "123"} 里的 Money 是空字符串，可能是因为调用方压根没打算传金额，也可能是这次查询金额恰好就是 "0"——从 struct 本身完全看不出是哪种情况。

这不是我瞎担心，Stripe 官方的 Go SDK（stripe-go）就真的在这个问题上纠结过，而且专门开了一个 issue 讨论：stripe-go#560。Stripe 工程师 brandur 在 issue 里把问题归纳为”零值本身经常就是有意义的业务值”——Description 就是想设成空字符串、Closed 就是想设成 false、Quantity 就是想设成 0，这些合法的业务值恰好和”没设置”共用同一个零值，SDK 没法区分，哪怕调用方明确设置了也不会被编码进请求。Stripe 给出的方案是把 ChargeParams 里所有可选字段从值类型改成指针：

// 改造前：值类型，零值和"没设置"分不清
type ChargeParams struct {
    Customer string
}

// 改造后：指针类型，nil 就是"没设置"，非 nil 就是"设置了，哪怕值是零值"
type ChargeParams struct {
    Customer *string
}

nil 明确表示”这个字段没被设置”，非 nil 的指针——哪怕指向的是空字符串或者 0——都表示”调用方确实设置了这个值”。代价是调用方不能再直接写 Customer: "abc"，得用一个辅助函数把值包成指针，比如 stripe.String("abc")；而且指针字段解引用前要判空，用错了就是一次真实的空指针 panic，这也是 issue 里 brandur 自己提到的顾虑。

这次例子里为什么不需要指针

回到 QueryOrderReq：OrderSN、ChannelTradeNo、Money 这几个字段，业务上空字符串本身就不是一个合法值——商户订单号、渠道订单号、金额都不可能真的是空字符串，只要是空字符串，就一定代表”这个渠道不需要这个字段”，不存在”我就是想传空字符串”的合法场景。零值和”没设置”在这个场景里恰好重合成同一个意思，所以直接用值类型没有歧义，用不上 Stripe 那套指针方案。

但这不是可以无脑套用的结论——只要你的 struct 里有任何一个字段的零值本身也是一个合法业务值（金额允许是 0、开关默认就是 false、描述允许是空字符串），零值兜底的”非破坏性”就会变成”没法分辨调用方到底想不想传”的歧义。这时候要么照 Stripe 的做法把这个字段改成指针，要么干脆接受这个歧义（前提是想清楚了这个字段的零值确实等价于”不传”）。

和 Option 模式、Context 的边界

参数膨胀是个很常见的问题，Go 里针对不同场景有几种不同的标准解法，struct 化只是其中处理”必填数据字段变多”这一种情况的方案，而且顺带说一句：函数式选项模式完全不会遇到零值歧义的问题——因为”调用方没调用某个 WithXxx“本身就是一个显式信号，不需要靠字段的零值去猜。如果膨胀的是可选参数（构造函数大部分调用只需要默认值，少数场景要覆盖某几项），Option 模式比 struct 更合适。

如果要传递的是跨调用链的请求域数据（trace ID、认证信息这类”跟这次请求绑定、但不是这个函数业务逻辑本身需要的参数”），应该用 Context 的 WithValue，而不是把它们也塞进业务 struct 里跟真正的业务参数混在一起。QueryOrderReq 里的商户订单号、渠道订单号都是业务必填字段，这次重构选 struct 是对的，换成传 trace ID 或者做成一堆 WithXxx 反而是把简单问题复杂化。

下次设计接口时多问一句

参数超过 2-3 个同类型的值，或者能预见到以后还会继续加字段，这两个信号出现任意一个，接口设计的第一天就该直接上 struct，不用等到打了第一个补丁才回头重构。但 struct 化不是设计工作的终点——多问一句”这个字段的零值，在业务上算不算一个合法值”，答案是”算”，就提前想清楚要不要照 Stripe 的思路把它改成指针，而不是等到线上出现”调用方明明传了 0，结果被当成没传”这种诡异 bug 才回头查。