2. Go 语言基础回顾：支付场景下的核心语言特性

在进入支付中间件设计之前，有必要回顾 Go 语言中与支付业务强相关的四个核心特性：接口（interface）、结构体（struct）、错误处理（error） 和 并发模型（goroutine/channel）。支付系统对可扩展性、数据完整性、容错性和高吞吐有极高要求，Go 的这些特性恰好能一一对应。

2.1 结构体（struct）：支付领域模型的基石

支付业务中的每一个实体——订单、账户、交易流水、对账单——都可以用结构体精确建模。结构体通过字段组合，天然适合表达“值对象”和“聚合根”。

设计原则：支付结构体应避免“万能对象”，每个结构体只承载一个明确的业务职责。例如，PaymentOrder 只负责订单状态与金额，Account 只负责余额与冻结。 
// 支付订单结构体
type PaymentOrder struct {
    OrderID     string    `json:"order_id"`
    MerchantID  string    `json:"merchant_id"`
    Amount      int64     `json:"amount"`       // 单位：分
    Currency    string    `json:"currency"`
    Status      OrderStatus `json:"status"`
    CreatedAt   time.Time `json:"created_at"`
}

// 账户结构体
type Account struct {
    AccountID   string    `json:"account_id"`
    Balance     int64     `json:"balance"`      // 可用余额
    Frozen      int64     `json:"frozen"`       // 冻结金额
    Version     int64     `json:"version"`      // 乐观锁版本号
}
结构体字段 支付场景含义 常见陷阱
Amount int64 金额以“分”为单位，避免浮点精度丢失 使用 float64 导致对账不平
Version int64 乐观锁版本号，用于并发扣款 遗漏版本字段导致超卖
Status 自定义类型 强类型枚举，防止状态乱赋值 使用 string 导致状态值不可控
json:"order_id" 序列化标签，对接外部渠道 标签缺失导致字段名不匹配

2.2 接口（interface）：支付渠道的抽象契约

支付中间件需要对接、支付宝、银联等数十种渠道。接口将“支付行为”与“具体渠道实现”解耦，使得新增渠道只需实现接口，无需修改核心流程。

// 支付渠道接口
type PaymentChannel interface {
    Pay(ctx context.Context, order *PaymentOrder) (*PayResponse, error)
    Refund(ctx context.Context, order *PaymentOrder, amount int64) (*RefundResponse, error)
    Query(ctx context.Context, orderID string) (*OrderStatus, error)
    ChannelName() string
}

// 支付实现
type WechatPay struct {
    AppID  string
    MchID  string
    APIKey string
}

func (w *WechatPay) Pay(ctx context.Context, order *PaymentOrder) (*PayResponse, error) {
    // 调用支付 SDK
    return &PayResponse{TradeNo: "wx" + order.OrderID}, nil
}

func (w *WechatPay) ChannelName() string {
    return "wechat"
}

// 支付宝实现
type Alipay struct {
    AppID      string
    PrivateKey string
}

func (a *Alipay) Pay(ctx context.Context, order *PaymentOrder) (*PayResponse, error) {
    // 调用支付宝 SDK
    return &PayResponse{TradeNo: "ali" + order.OrderID}, nil
}
接口设计要点：支付接口的方法签名应包含 context.Context 作为第一个参数，用于传递超时、链路追踪和取消信号。返回值中的 error 必须区分“业务失败”和“系统异常”，不能混为一谈。
支付渠道接口抽象架构 PaymentChannel 接口 Pay(ctx, order) Refund(ctx, order) Query(ctx, id) WechatPay 实现 Alipay 实现 UnionPay 实现 新增渠道只需实现 PaymentChannel 接口 核心支付流程无需任何修改（开闭原则）

2.3 错误处理（error）：支付失败的精确表达

支付系统中，错误不仅仅是“出错了”，它需要携带明确的业务语义：是余额不足、渠道超时、重复支付还是风控拦截？Go 的 error 接口结合自定义错误类型，可以精确表达这些场景。

// 自定义支付错误类型
type PayError struct {
    Code    string // 错误码，如 "BALANCE_INSUFFICIENT"
    Message string // 人类可读描述
    Err     error  // 原始错误（可选）
}

func (e *PayError) Error() string {
    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}

func (e *PayError) Unwrap() error {
    return e.Err
}

// 预定义错误常量
var (
    ErrBalanceInsufficient = &PayError{Code: "BALANCE_INSUFFICIENT", Message: "余额不足"}
    ErrOrderExpired        = &PayError{Code: "ORDER_EXPIRED", Message: "订单已过期"}
    ErrDuplicatePayment    = &PayError{Code: "DUPLICATE_PAYMENT", Message: "重复支付"}
    ErrChannelTimeout      = &PayError{Code: "CHANNEL_TIMEOUT", Message: "渠道超时"}
)

// 使用 errors.Is 判断错误类型
func handlePayResult(err error) {
    if errors.Is(err, ErrBalanceInsufficient) {
        // 提示用户充值
    } else if errors.Is(err, ErrChannelTimeout) {
        // 触发重试机制
    }
}
错误码 业务含义 处理策略
BALANCE_INSUFFICIENT 账户余额不足 返回前端提示，不重试
CHANNEL_TIMEOUT 第三方渠道超时 幂等重试（最多3次）
DUPLICATE_PAYMENT 同一订单重复支付 返回已有支付结果，拒绝新支付
CHANNEL_UNAVAILABLE 渠道服务不可用 切换备用渠道
错误处理红线：支付系统中，error 绝不能吞掉不处理。每个错误都必须被记录、分类并触发相应的补偿动作。使用 _ = someFunc() 忽略错误是支付代码中的严重违规。

2.4 并发模型（goroutine/channel）：高并发支付的引擎

支付系统每秒需要处理数千笔交易，同时还要保证数据一致性。Go 的 goroutine 提供轻量级并发，channel 则用于 goroutine 之间的安全通信和同步。

2.4.1 goroutine：异步任务处理

支付中的异步场景包括：发送支付结果通知、生成对账单、触发风控检查。这些任务不应阻塞主流程。

// 异步发送支付通知
func (s *PaymentService) ProcessPayment(ctx context.Context, order *PaymentOrder) error {
    // 同步执行核心支付逻辑
    resp, err := s.channel.Pay(ctx, order)
    if err != nil {
        return err
    }

    // 异步发送通知（不阻塞主流程）
    go s.sendPaymentNotification(order, resp)

    // 异步记录审计日志
    go s.recordAuditLog(order, resp)

    return nil
}

func (s *PaymentService) sendPaymentNotification(order *PaymentOrder, resp *PayResponse) {
    // 重试3次，每次间隔1秒
    for i := 0; i < 3; i++ {
        err := s.notifier.Notify(order, resp)
        if err == nil {
            return
        }
        time.Sleep(time.Second)
    }
    log.Errorf("发送支付通知失败: order=%s", order.OrderID)
}

2.4.2 channel：流水线处理与限流

支付对账场景中，需要将原始流水经过“解析 → 校验 → 匹配 → 差异处理”多个阶段。channel 可以构建高效的流水线模型。

// 支付对账流水线
func ReconciliationPipeline(rawRecords <-chan RawRecord) {
    // 阶段1：解析
    parsed := make(chan ParsedRecord, 100)
    go func() {
        for record := range rawRecords {
            parsed <- parseRecord(record)
        }
        close(parsed)
    }()

    // 阶段2：校验
    validated := make(chan ValidatedRecord, 100)
    go func() {
        for record := range parsed {
            if validateRecord(record) {
                validated <- ValidatedRecord{Record: record}
            }
        }
        close(validated)
    }()

    // 阶段3：匹配
    for record := range validated {
        matchResult := matchWithLocal(record)
        handleMatchResult(matchResult)
    }
}
支付对账流水线并发模型 阶段1：解析 goroutine 1 chan 阶段2：校验 goroutine 2 chan 阶段3：匹配 goroutine 3 每个阶段独立 goroutine，通过 channel 传递数据 任意阶段可独立扩缩容，互不阻塞 轻量级 goroutine channel 安全通信 天然支持背压

2.5 综合案例：支付网关的核心骨架

将上述四个特性组合，可以构建一个支付网关的核心骨架。这个骨架体现了接口抽象、结构体建模、错误处理和并发协作的完整闭环。

// 支付网关核心
type PaymentGateway struct {
    channels map[string]PaymentChannel // 渠道注册表
    mu       sync.RWMutex
}

// 统一支付入口
func (g *PaymentGateway) Pay(ctx context.Context, channelName string, order *PaymentOrder) (*PayResponse, error) {
    // 1. 获取渠道（接口）
    channel, err := g.getChannel(channelName)
    if err != nil {
        return nil, fmt.Errorf("获取渠道失败: %w", err)
    }

    // 2. 幂等校验（结构体）
    if order.Status != OrderStatusPending {
        return nil, ErrDuplicatePayment
    }

    // 3. 并发调用渠道（goroutine + channel）
    type result struct {
        resp *PayResponse
        err  error
    }
    resultCh := make(chan result, 1)

    go func() {
        resp, err := channel.Pay(ctx, order)
        resultCh <- result{resp: resp, err: err}
    }()

    // 4. 超时控制
    select {
    case res := <-resultCh:
        if res.err != nil {
            // 错误处理：区分业务错误和系统错误
            var payErr *PayError
            if errors.As(res.err, &payErr) {
                log.Warnf("支付业务错误: %v", payErr)
            } else {
                log.Errorf("支付系统错误: %v", res.err)
            }
            return nil, res.err
        }
        return res.resp, nil
    case <-ctx.Done():
        return nil, ErrChannelTimeout
    }
}

func (g *PaymentGateway) getChannel(name string) (PaymentChannel, error) {
    g.mu.RLock()
    defer g.mu.RUnlock()
    ch, ok := g.channels[name]
    if !ok {
        return nil, fmt.Errorf("不支持的渠道: %s", name)
    }
    return ch, nil
}
← 上一章 📖 返回目录 下一章 →