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

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

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

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

权宜做法：借道传参

改接口签名意味着要动所有已经接入的渠道实现，压力不小。当时更快的做法是不动签名，在调用方对这个新渠道单独处理，把 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 里加一行：

type QueryOrderReq struct {
    OrderSN        string
    ChannelTradeNo string
    Money          string
    SubMerchantID  string // 新增字段
}

已有的调用方和渠道实现完全不用跟着改——它们构造 QueryOrderReq{} 时没有填 SubMerchantID，这个字段自动是空字符串，对现有逻辑没有任何影响。接口签名 QueryOrder(req QueryOrderReq) 本身也没变，不需要重新实现 IPay 接口的任何一方跟着改代码。对比一下如果参数还是摊平的裸参数列表，新增一个字段就必须在签名里加一个新参数，所有实现方和调用方都要同步改——struct 把”新增字段”和”新增参数”两件事彻底解耦了。

两个方案的差距在哪

改动面：借道传参每加一个特殊渠道就要在调用方加一个 if 分支，改动分散在业务逻辑里，容易漏改；struct 方案只需要在类型定义里加一行字段，调用方和实现方按需读取，不需要为了兼容新字段去改无关渠道的代码。

可读性：e.QueryOrder(tradeNo, total) 光看调用点完全猜不出 total 在这个分支里到底传的是什么，必须跳到实现代码里看注释；req.ChannelTradeNo 这种写法字段名本身就是文档，不需要额外解释。

扩展成本：借道传参的扩展成本是递增的——渠道越多，需要记住的”第几个参数在第几个渠道分支里代表什么”这张隐藏对照表就越复杂；struct 方案的扩展成本基本是常数——不管接入多少个渠道，加字段永远是同一个动作，加一行定义。

这不是唯一的行业选项

参数膨胀是个很常见的问题，Go 里针对不同场景有几种不同的标准解法，struct 化只是其中处理”必填数据字段变多”这一种情况的方案：

如果膨胀的是可选参数而不是必填字段（比如构造函数大部分调用只需要默认值，少数场景要覆盖某几项），更合适的是函数式选项模式——用一串 WithXxx(...) 函数而不是一个必须显式填满的 struct，调用方不用关心的选项完全不用出现在调用点上。

如果要传递的是跨调用链的请求域数据（trace ID、认证信息这类”跟这次请求绑定、但不是这个函数业务逻辑本身需要的参数”），应该用 Context 的 WithValue，而不是把它们也塞进业务 struct 里跟真正的业务参数混在一起。

三者的分界线很清楚：业务必填、调用点固定知道要传什么 用 struct；可选、不同调用方按需覆盖 用 Option；跟请求生命周期绑定、多层调用都可能要用但和当前函数的业务逻辑无关 用 Context。QueryOrderReq 里的商户订单号、渠道订单号都是业务必填字段，这次重构选 struct 是对的，换成传 trace ID 或者做成一堆 WithXxx 反而是把简单问题复杂化。

什么时候该动手 struct 化

不是所有接口都要一上来就传 struct——两个参数、以后大概率不会再加字段的场景，裸参数反而更直接。真正该考虑 struct 化的信号是：参数超过 2-3 个同类型的值（比如这个例子里全是 string，位置很容易传错也很容易看花眼），或者能预见到以后还会继续加字段（对接第三方系统尤其明显，几乎每接一个新的都会多几个专属字段）。这个场景符合两条信号中的任意一条，其实就该在设计接口的第一天直接用 struct，不用等到打了第一个补丁才回头重构。