《互联网产品的服务端架构·交易、增长与平台化》3.2 回调、幂等与掉单

UPDATE orders SET status = 'paid' WHERE id = ?;
INSERT INTO shipments ...;

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

package payment

import (
	"errors"
	"fmt"
)

var (
	// ErrEmptyTradeNo 表示渠道流水号为空。没有渠道流水号就无法做幂等，
	// 也无法和渠道账单对上，必须在入口拒绝。
	ErrEmptyTradeNo = errors.New("payment: empty trade no")
	// ErrAmountMismatch 表示回调金额和订单金额不一致。
	ErrAmountMismatch = errors.New("payment: callback amount mismatch")
	// ErrInvalidStatus 表示回调状态不是 success 或 failed。
	ErrInvalidStatus = errors.New("payment: callback status must be success or failed")
	// ErrNilApplied 表示幂等表没有初始化，无法安全写入。
	ErrNilApplied = errors.New("payment: nil applied map")
)

// Callback 是渠道异步通知里与本业务相关的最小字段集合。生产环境还要
// 保存签名、通知时间、渠道原始报文，这里为了聚焦幂等只保留关键字段。
type Callback struct {
	Channel     Channel
	OrderID     string
	TradeNo     string
	AmountCents int64
	Status      string
}

// Verify 校验回调是否可信且与本地订单一致。它假定调用方已经完成验签，
// 只检查业务字段：渠道流水号、金额和状态。
func Verify(cb Callback, amountCents int64) error {
	if cb.TradeNo == "" {
		return ErrEmptyTradeNo
	}
	if cb.AmountCents != amountCents {
		return fmt.Errorf("%w: callback %d, order %d", ErrAmountMismatch, cb.AmountCents, amountCents)
	}
	if cb.Status != "success" && cb.Status != "failed" {
		return fmt.Errorf("%w: %q", ErrInvalidStatus, cb.Status)
	}
	return nil
}

// Apply 把回调登记到幂等表，返回本次是否第一次处理。同一个 TradeNo
// 第二次调用返回 (false, nil)，调用方据此跳过发货、加积分等副作用。
//
// applied 是调用方持有的幂等表，键是渠道流水号。函数只写这一个 map，
// 不修改 cb 的任何字段；cb 按值传入，也保证了回调内容不会被就地改写。
// 空 TradeNo 或 nil map 返回错误，避免把不同订单混成一条。
func Apply(applied map[string]bool, cb Callback) (bool, error) {
	if cb.TradeNo == "" {
		return false, ErrEmptyTradeNo
	}
	if applied == nil {
		return false, ErrNilApplied
	}
	if applied[cb.TradeNo] {
		return false, nil
	}
	applied[cb.TradeNo] = true
	return true, nil
}

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

package payment

import (
	"errors"
	"strings"
	"testing"
)

func baseCallback() Callback {
	return Callback{
		Channel:     Alipay,
		OrderID:     "o1",
		TradeNo:     "t1",
		AmountCents: 9900,
		Status:      "success",
	}
}

func TestVerifyAcceptsSuccessAndFailed(t *testing.T) {
	for _, status := range []string{"success", "failed"} {
		cb := baseCallback()
		cb.Status = status
		if err := Verify(cb, 9900); err != nil {
			t.Fatalf("status %q err = %v; want nil", status, err)
		}
	}
}

func TestVerifyRejectsEmptyTradeNo(t *testing.T) {
	cb := baseCallback()
	cb.TradeNo = ""
	if err := Verify(cb, 9900); !errors.Is(err, ErrEmptyTradeNo) {
		t.Fatalf("err = %v; want ErrEmptyTradeNo", err)
	}
}

func TestVerifyRejectsAmountMismatchAndReportsBoth(t *testing.T) {
	cb := baseCallback()
	err := Verify(cb, 9800)
	if !errors.Is(err, ErrAmountMismatch) {
		t.Fatalf("err = %v; want ErrAmountMismatch", err)
	}
	msg := err.Error()
	if !strings.Contains(msg, "9900") || !strings.Contains(msg, "9800") {
		t.Fatalf("message %q should contain both amounts", msg)
	}
}

func TestVerifyRejectsInvalidStatus(t *testing.T) {
	for _, status := range []string{"", "pending", "SUCCESS", "refund"} {
		cb := baseCallback()
		cb.Status = status
		if err := Verify(cb, 9900); !errors.Is(err, ErrInvalidStatus) {
			t.Fatalf("status %q err = %v; want ErrInvalidStatus", status, err)
		}
	}
}

func TestApplyIsIdempotentPerTradeNo(t *testing.T) {
	applied := map[string]bool{}
	cb := baseCallback()
	first, err := Apply(applied, cb)
	if err != nil || !first {
		t.Fatalf("first Apply = %v, %v; want true, nil", first, err)
	}
	second, err := Apply(applied, cb)
	if err != nil {
		t.Fatalf("second Apply err = %v; want nil", err)
	}
	if second {
		t.Fatal("second Apply = true; want false")
	}
	if len(applied) != 1 {
		t.Fatalf("applied size = %d; want 1", len(applied))
	}
}

func TestApplyDoesNotDoubleFireSideEffect(t *testing.T) {
	applied := map[string]bool{}
	shipped := 0
	for i := 0; i < 3; i++ {
		fresh, err := Apply(applied, baseCallback())
		if err != nil {
			t.Fatalf("Apply #%d err = %v", i+1, err)
		}
		if fresh {
			shipped++
		}
	}
	if shipped != 1 {
		t.Fatalf("side effect fired %d times; want 1", shipped)
	}
}

func TestApplyDifferentTradeNosBothApply(t *testing.T) {
	applied := map[string]bool{}
	a := baseCallback()
	b := baseCallback()
	b.TradeNo = "t2"
	if fresh, err := Apply(applied, a); err != nil || !fresh {
		t.Fatalf("Apply(t1) = %v, %v; want true, nil", fresh, err)
	}
	if fresh, err := Apply(applied, b); err != nil || !fresh {
		t.Fatalf("Apply(t2) = %v, %v; want true, nil", fresh, err)
	}
	if len(applied) != 2 {
		t.Fatalf("applied size = %d; want 2", len(applied))
	}
}

func TestApplyRejectsEmptyTradeNoAndNilMap(t *testing.T) {
	cb := baseCallback()
	cb.TradeNo = ""
	if _, err := Apply(map[string]bool{}, cb); !errors.Is(err, ErrEmptyTradeNo) {
		t.Fatalf("empty trade no err = %v; want ErrEmptyTradeNo", err)
	}
	if _, err := Apply(nil, baseCallback()); !errors.Is(err, ErrNilApplied) {
		t.Fatalf("nil map err = %v; want ErrNilApplied", err)
	}
}

func TestApplyDoesNotMutateCallback(t *testing.T) {
	applied := map[string]bool{}
	cb := baseCallback()
	before := cb
	if _, err := Apply(applied, cb); err != nil {
		t.Fatalf("Apply err = %v", err)
	}
	if cb != before {
		t.Fatalf("callback mutated: before %+v, after %+v", before, cb)
	}
}

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

=== RUN   TestVerifyAcceptsSuccessAndFailed
--- PASS: TestVerifyAcceptsSuccessAndFailed (0.00s)
=== RUN   TestVerifyRejectsEmptyTradeNo
--- PASS: TestVerifyRejectsEmptyTradeNo (0.00s)
=== RUN   TestVerifyRejectsAmountMismatchAndReportsBoth
--- PASS: TestVerifyRejectsAmountMismatchAndReportsBoth (0.00s)
=== RUN   TestVerifyRejectsInvalidStatus
--- PASS: TestVerifyRejectsInvalidStatus (0.00s)
=== RUN   TestApplyIsIdempotentPerTradeNo
--- PASS: TestApplyIsIdempotentPerTradeNo (0.00s)
=== RUN   TestApplyDoesNotDoubleFireSideEffect
--- PASS: TestApplyDoesNotDoubleFireSideEffect (0.00s)
=== RUN   TestApplyDifferentTradeNosBothApply
--- PASS: TestApplyDifferentTradeNosBothApply (0.00s)
=== RUN   TestApplyRejectsEmptyTradeNoAndNilMap
--- PASS: TestApplyRejectsEmptyTradeNoAndNilMap (0.00s)
=== RUN   TestApplyDoesNotMutateCallback
--- PASS: TestApplyDoesNotMutateCallback (0.00s)
PASS
ok  	webapp/internal/payment	0.234s