Go 服务如何用端口适配器隔离支付渠道：接口稳定、供应商可替换

订单服务接入第二个支付渠道时，最先乱掉的往往不是支付接口本身，而是业务层各处冒出来的供应商专属字段：一个渠道叫 trade_no，另一个叫 payment_id；一个用 SUCCESS 表示成功，另一个返回数字类型的状态码。改不了几次，订单状态流转、重试逻辑、回调处理全被第三方SDK捆得死死的。

先看失控点：支付 SDK 为什么会钻进订单服务

很多项目初期只对接一个支付渠道，订单服务里直接写SDK调用完全正常。问题出在第二次接入：为了赶迭代进度，开发者复制一份调用代码，再把 trade_no、签名串和渠道状态判断逻辑散落到handler、service甚至定时任务里。

这时业务代码表面上是在“创建支付”，实际上已经完全知晓供应商的请求结构、错误码和回调协议。后续要更换渠道就不再是替换一个客户端那么简单，得把全项目跨模块搜一遍相关代码。更麻烦的是，两个渠道对“已受理”“处理中”“已支付”的定义可能不完全对齐，直接把渠道返回的字符串带进订单状态机，很容易藏下很难发现的分支漏洞。

把业务依赖收窄成一个支付端口

端口不是把所有供应商能力拼成一个巨型接口，而是从订单实际用到的流程反推，提取出最小必要能力集。订单创建只需要拿到支付跳转信息，查询只需要确认支付最终状态，回调则需要把外部通知转换成内部统一事件。

package payment

import "context"

type CreateInput struct {
    OrderID string
    Amount  int64
    Subject string
}

type CreateResult struct {
    ChannelRef string
    PayURL     string
    State      State
}

type State string

const (
    StatePending State = "pending"
    StatePaid    State = "paid"
    StateFailed  State = "failed"
)

type Port interface {
    Create(ctx context.Context, in CreateInput) (CreateResult, error)
    Query(ctx context.Context, channelRef string) (State, error)
}

这里的 Port 只保留订单流程真正要用的动作。它里面不会出现某家渠道的专属签名参数，也不会直接把供应商的响应对象作为返回值。ChannelRef 是业务侧认可的外部引用号，这个字段在渠道侧具体叫什么名，全由适配器层自行决定。

适配器只做转换，不替业务决定订单状态

以一个虚构的 BluePay 渠道为例，适配器可以持有SDK客户端和渠道配置，但对外只实现统一的支付端口。字段转换、金额单位换算、渠道错误码解析这类逻辑，全部留在这一层处理。

type BluePay struct {
    client *Client
}

func (p *BluePay) Create(ctx context.Context, in payment.CreateInput) (payment.CreateResult, error) {
    out, err := p.client.CreateOrder(ctx, blueRequest{
        MerchantOrder: in.OrderID,
        TotalFen:      in.Amount,
        Description:   in.Subject,
    })
    if err != nil {
        return payment.CreateResult{}, mapBlueError(err)
    }
    return payment.CreateResult{
        ChannelRef: out.PaymentID,
        PayURL:     out.RedirectURL,
        State:      mapBlueState(out.Status),
    }, nil
}

业务层不需要再次判断 out.Status。如果某个渠道有“风控审核”或“等待补充资料”这类特殊状态，先判断它能不能安全映射到业务统一状态；不能安全映射的话，就返回明确的渠道错误，或者把请求送入人工处理队列，不要偷偷把这类状态当成支付成功处理。

下单端口和回调端口要分开

下单是服务端主动发起的请求，回调是接收第三方的被动通知，两者的信任边界完全不一样。把回调解析逻辑直接塞进 Port.Create，会让支付接口同时承担签名验证、原始报文保存和订单状态推进多个职责，后面很难做单测。

type CallbackPort interface {
    VerifyAndDecode(body []byte, headers map[string]string) (Notice, error)
}

type Notice struct {
    OrderID    string
    ChannelRef string
    State      payment.State
    NoticeID   string
}

func HandleCallback(body []byte, headers map[string]string, cb CallbackPort, orders OrderStore) error {
    notice, err := cb.VerifyAndDecode(body, headers)
    if err != nil {
        return err
    }
    if orders.SeenNotice(notice.NoticeID) {
        return nil
    }
    return orders.ApplyPayment(notice.OrderID, notice.ChannelRef, notice.State, notice.NoticeID)
}

回调入口先走验签逻辑，再做通知幂等判断，最后由订单仓储根据当前状态判断是否允许推进流程。这样即使同一通知被重复投递，也不会因为回调接口被调用两次就触发重复发货的问题。

渠道替换时，真正要验证的是后果

把构造函数里的 BluePay 换成 GreenPay 只是最后一步操作。更重要的是提前验证统一端口的所有行为：金额是否仍以分为单位、创建成功后是否一定返回可追踪的外部引用号、查询超时是否会被误判成支付失败，以及回调晚于主动查询时谁拥有最终状态决定权。

测试阶段可以先用一个内存适配器把订单全链路用例覆盖完，再为每个真实渠道补充字段映射和签名相关的测试用例。端口测试站在业务视角验证最终结果，适配器测试单独验证供应商报文的转换逻辑。两层测试分开之后，后续替换渠道也不需要跟着修改订单相关的原有测试用例。

哪些场景不适合硬套端口适配器

如果项目长期只对接一个渠道，没有后续替换计划，而且供应商提供的能力和业务模型几乎完全对应，直接封装一个轻量小客户端反而更省事。端口适配器的额外成本来自接口设计、映射测试和后续故障排查，为了抽象而抽象，最后大概率只是多了一层没用的转发逻辑。

另一个反例是强行把所有渠道差异都压缩成三个通用状态。退款、分账、预授权和撤销这类操作往往有完全不同的生命周期，强行复用“创建支付”的通用接口，反而会让接口模型失去实际含义。正确的做法是按业务能力拆分端口，必要时让退款和支付各自拥有独立的状态模型。

上线前留一张可回退的判断清单

• 订单 service 和 handler 是否还残留导入供应商 SDK 的代码？
• 统一结果是否能覆盖成功、处理中、失败和未知四类结果？
• 回调原文、验签结果和通知 ID 是否全链路可追溯？
• 切换渠道后，主动查询与异步回调的竞态场景是否有对应测试？
• 新渠道出现异常时，是否能按租户或流量比例切回旧适配器？

相关问题

支付端口要不要暴露供应商原始响应？

通常不建议。可以在适配器日志里保存脱敏后的原始信息，对外的业务接口只返回完成订单决策所需的必要字段就行。

渠道超时应该直接把订单标成失败吗？

不应该直接标失败。超时只说明本次查询没拿到明确结果，订单应保持处理中状态，后续通过回调、补偿查询或人工核对得到最终状态。

什么时候应该增加第三个支付适配器？

当渠道差异已经开始侵入业务核心代码、流量灰度切换成为刚需，或者同一支付能力需要被多个业务用例复用时，再新增适配器通常投入产出比更高。

把变化留在边界里

端口适配器的价值不是让代码看起来更精巧，而是把供应商专属字段、错误码和回调协议全部关在边界层里。订单服务只面对稳定的业务动作，后续渠道替换时先做统一契约验证，再处理具体渠道的映射逻辑，排查问题的范围会小很多。边界划分清楚之后，新增渠道不再等于给核心流程追加一串长长的条件分支。