《互联网产品的服务端架构·交易、增长与平台化》3.1 支付渠道接入

// file: internal/payment/channel.go
// tier: L1
// verify: go test ./internal/payment/

package payment

import (
	"errors"
	"fmt"
)

// Channel 是支付渠道的稳定标识。字符串值会写进订单备注、审计日志和
// 对账文件，不要用中文名或展示名做键。
type Channel string

const (
	Alipay   Channel = "alipay"
	Wechat   Channel = "wechat"
	ApplePay Channel = "applepay"
)

var (
	// ErrUnknownChannel 表示渠道不在已接入清单内。新增渠道必须先登记，
	// 否则后面的币种、签名和账单适配都无从选择。
	ErrUnknownChannel = errors.New("payment: unknown channel")
	// ErrInvalidAmount 表示金额不是正整数。金额单位是分，0 元和负数都
	// 不是合法支付请求。
	ErrInvalidAmount = errors.New("payment: amount must be positive")
	// ErrInvalidCurrency 表示币种不是三位大写字母。
	ErrInvalidCurrency = errors.New("payment: currency must be three uppercase letters")
	// ErrUnsupportedCurrency 表示渠道不接收该币种。
	ErrUnsupportedCurrency = errors.New("payment: currency not supported by channel")
)

// Request 是发起支付时提交给渠道的最小请求。AmountCents 以分为单位，
// 用整数避免浮点误差；Currency 使用 ISO 4217 的三位大写代码。
type Request struct {
	OrderID     string
	AmountCents int64
	Currency    string
}

// Supports 判断渠道是否支持某币种。本案例假设支付宝和微信只收人民币，
// Apple Pay 支持美元和人民币。真实接入应以渠道文档和商户签约币种为准，
// 不能把这里的假设直接带上线。
func Supports(c Channel, currency string) bool {
	switch c {
	case Alipay, Wechat:
		return currency == "CNY"
	case ApplePay:
		return currency == "USD" || currency == "CNY"
	default:
		return false
	}
}

// Validate 校验渠道与请求是否匹配。它只做本地参数校验，不发起任何渠道
// 调用，也不检查订单是否已经支付；那些属于回调和对账层。
func Validate(c Channel, r Request) error {
	switch c {
	case Alipay, Wechat, ApplePay:
	default:
		return fmt.Errorf("%w: %q", ErrUnknownChannel, c)
	}
	if r.AmountCents <= 0 {
		return fmt.Errorf("%w: %d", ErrInvalidAmount, r.AmountCents)
	}
	if !isUpperCurrency(r.Currency) {
		return fmt.Errorf("%w: %q", ErrInvalidCurrency, r.Currency)
	}
	if !Supports(c, r.Currency) {
		return fmt.Errorf("%w: %s %s", ErrUnsupportedCurrency, c, r.Currency)
	}
	return nil
}

// isUpperCurrency 只接受三个 A-Z 字符。长度正确但含数字或小写的代码
// 同样拒绝，避免 "cny" 和 "CNY" 在日志里被当成两种币种。
func isUpperCurrency(s string) bool {
	if len(s) != 3 {
		return false
	}
	for i := 0; i < len(s); i++ {
		if s[i] < 'A' || s[i] > 'Z' {
			return false
		}
	}
	return true
}

// file: internal/payment/channel_test.go
// tier: L1
// verify: go test ./internal/payment/

package payment

import (
	"errors"
	"testing"
)

func TestValidateAcceptsKnownChannelAndCurrency(t *testing.T) {
	cases := []struct {
		name string
		c    Channel
		req  Request
	}{
		{"alipay cny", Alipay, Request{OrderID: "o1", AmountCents: 1, Currency: "CNY"}},
		{"wechat cny", Wechat, Request{OrderID: "o2", AmountCents: 9900, Currency: "CNY"}},
		{"applepay usd", ApplePay, Request{OrderID: "o3", AmountCents: 499, Currency: "USD"}},
		{"applepay cny", ApplePay, Request{OrderID: "o4", AmountCents: 1200, Currency: "CNY"}},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			if err := Validate(tc.c, tc.req); err != nil {
				t.Fatalf("Validate(%s, %+v) = %v; want nil", tc.c, tc.req, err)
			}
		})
	}
}

func TestValidateRejectsUnknownChannel(t *testing.T) {
	err := Validate(Channel("paypal"), Request{OrderID: "o1", AmountCents: 100, Currency: "USD"})
	if !errors.Is(err, ErrUnknownChannel) {
		t.Fatalf("err = %v; want ErrUnknownChannel", err)
	}
}

func TestValidateRejectsNonPositiveAmount(t *testing.T) {
	for _, amount := range []int64{0, -1, -9900} {
		err := Validate(Alipay, Request{OrderID: "o1", AmountCents: amount, Currency: "CNY"})
		if !errors.Is(err, ErrInvalidAmount) {
			t.Fatalf("amount %d err = %v; want ErrInvalidAmount", amount, err)
		}
	}
}

func TestValidateRejectsBadCurrency(t *testing.T) {
	for _, currency := range []string{"", "CN", "CNYY", "cny", "C1Y", "人民币"} {
		err := Validate(Alipay, Request{OrderID: "o1", AmountCents: 100, Currency: currency})
		if !errors.Is(err, ErrInvalidCurrency) {
			t.Fatalf("currency %q err = %v; want ErrInvalidCurrency", currency, err)
		}
	}
}

func TestValidateRejectsUnsupportedCurrency(t *testing.T) {
	cases := []struct {
		c        Channel
		currency string
	}{
		{Alipay, "USD"},
		{Wechat, "USD"},
		{ApplePay, "EUR"},
	}
	for _, tc := range cases {
		err := Validate(tc.c, Request{OrderID: "o1", AmountCents: 100, Currency: tc.currency})
		if !errors.Is(err, ErrUnsupportedCurrency) {
			t.Fatalf("Validate(%s, %s) err = %v; want ErrUnsupportedCurrency", tc.c, tc.currency, err)
		}
	}
}

func TestSupportsMatrix(t *testing.T) {
	cases := []struct {
		c        Channel
		currency string
		want     bool
	}{
		{Alipay, "CNY", true},
		{Alipay, "USD", false},
		{Wechat, "CNY", true},
		{Wechat, "USD", false},
		{ApplePay, "USD", true},
		{ApplePay, "CNY", true},
		{ApplePay, "EUR", false},
		{Channel("paypal"), "USD", false},
	}
	for _, tc := range cases {
		if got := Supports(tc.c, tc.currency); got != tc.want {
			t.Fatalf("Supports(%s, %s) = %v; want %v", tc.c, tc.currency, got, tc.want)
		}
	}
}

cd .local/checks/webapp-lab && go test ./internal/payment/ -run 'TestValidate|TestSupports' -count=1 -v

=== RUN   TestValidateAcceptsKnownChannelAndCurrency
=== RUN   TestValidateAcceptsKnownChannelAndCurrency/alipay_cny
=== RUN   TestValidateAcceptsKnownChannelAndCurrency/wechat_cny
=== RUN   TestValidateAcceptsKnownChannelAndCurrency/applepay_usd
=== RUN   TestValidateAcceptsKnownChannelAndCurrency/applepay_cny
--- PASS: TestValidateAcceptsKnownChannelAndCurrency (0.00s)
    --- PASS: TestValidateAcceptsKnownChannelAndCurrency/alipay_cny (0.00s)
    --- PASS: TestValidateAcceptsKnownChannelAndCurrency/wechat_cny (0.00s)
    --- PASS: TestValidateAcceptsKnownChannelAndCurrency/applepay_usd (0.00s)
    --- PASS: TestValidateAcceptsKnownChannelAndCurrency/applepay_cny (0.00s)
=== RUN   TestValidateRejectsUnknownChannel
--- PASS: TestValidateRejectsUnknownChannel (0.00s)
=== RUN   TestValidateRejectsNonPositiveAmount
--- PASS: TestValidateRejectsNonPositiveAmount (0.00s)
=== RUN   TestValidateRejectsBadCurrency
--- PASS: TestValidateRejectsBadCurrency (0.00s)
=== RUN   TestValidateRejectsUnsupportedCurrency
--- PASS: TestValidateRejectsUnsupportedCurrency (0.00s)
=== RUN   TestSupportsMatrix
--- PASS: TestSupportsMatrix (0.00s)
PASS
ok  	webapp/internal/payment	0.324s