This resume is also available in English.

七、實戰踩坑第 3 / 5 篇 · 全部目錄

專欄 › 七、實戰踩坑 › 第 28 篇

支付防重複與事故應變:從按鈕到金流商,出事時怎麼止血

Preventing Duplicate Payments and Handling Payment Incidents: From the Button to the Provider, and How to Stop the Bleeding

重複交易單會從按鈕、用戶端、閘道、訂單、支付、金流商與回呼任何一層冒出來,這篇逐層說明怎麼擋。接著整理支付事故的預防、告警與應變步驟,並用 Go 實作先查再重試與卡單掃描器。

  • 支付
  • 冪等
  • 事故
  • Go
這篇的步驟
  1. 這篇要解決什麼
  2. 第一部分:重複從哪裡來
  3. 第 1 層:付款按鈕
  4. 第 2 層:用戶端(網頁與 App)
  5. 第 3 層:Gateway、負載平衡器與服務之間的重試
  6. 第 4 層:訂單服務,一次結帳只成立一張訂單
  7. 第 5 層:支付服務,一張訂單一次只有一個付款嘗試
  8. 第 6 層:金流商
  9. 第 7 層:回呼與訊息重送
  10. 第 8 層:使用者看得到的那一面
  11. 用 Go 把第 4、5 層串起來
  12. 第二部分:支付事故
  13. 支付事故長什麼樣子
  14. 事前預防:讓事故變小
  15. 付款狀態:誰能讓 unknown 結束
  16. 事故應變手冊
  17. 卡單掃描器
  18. 重點整理
  19. 下一篇

上一篇〈支付常見問題:重複扣款、回呼與對帳〉把十個金流問題各自拆開來修:冪等鍵、狀態機、逾時進入 unknown、回呼驗簽、對帳與帳本。那些是零件;這篇把零件組起來,回答兩個更實際的問題。第一,一筆付款從使用者按下按鈕,到金流商真的扣款,中間經過七、八層,重複的交易單到底從哪一層冒出來,每一層各自要擋什麼。第二,就算每一層都做對了,金流商還是會當機、回呼還是會停、新版程式還是可能算錯金額,真的出事時要怎麼發現、怎麼止血、先做什麼後做什麼。

這篇要解決什麼

上一篇的第 1 個問題已經說過「冪等鍵要端到端」,但只用一段話帶過。實務上最常見的重複扣款,不是某一層完全沒做,而是每一層都「差不多有做」:按鈕有停用但沒產生冪等鍵、用戶端有帶鍵但逾時後換了一把新的、支付服務有去重但逾時後直接換一個商店訂單編號重扣。所以第一部分會一層一層往下走,每一層都回答三件事:重複從哪裡來、這一層的防線是什麼、這一層不能依賴什麼。

第二部分處理事故。支付事故和一般的服務故障不同:一般服務掛了,修好就恢復;支付出事時,故障期間已經發生的扣款、取消與退款都是真實世界的金錢流動,修好程式之後還要把每一筆錢的狀態找回來。這部分會整理常見的事故類型、事前的預防與告警、事故當下的應變手冊,最後用 Go 實作一個把卡住的付款找回結果的掃描器。

延續這個系列的例子:網路商店 example.com/shop,使用者經過 api-gateway 呼叫 order 服務建立訂單,payment 服務向金流商發起扣款,成功後透過 Outbox 發事件讓訂單變成 paid,inventory 服務在訂單取消時釋放庫存;資料存在 PostgreSQL,金額一律是最小貨幣單位的 int64。付款狀態沿用上一篇的狀態機:created、pending、unknown、succeeded、failed,以及退款相關的狀態。

第一部分:重複從哪裡來

先看全貌。一次結帳從畫面到金流商,會經過下面這些層,每一層都有自己產生重複的方式:

層 重複從哪裡來 這一層的防線 付款按鈕 連點、按上一頁重送 停用按鈕 載入時產生 checkout_token 用戶端 逾時自動重試 App 回到前景重送 所有重試沿用同一把冪等鍵 Gateway/LB 沒回應就換一台再送 只重試冪等請求、只在一層 訂單服務 同一次結帳建立兩張訂單 唯一約束 (user_id, checkout_token) 支付服務 逾時後換新編號重扣 一個嘗試一個編號 先查再重試 金流商 不同編號就是新交易 拒絕重複編號或冪等鍵 回呼與佇列 至少一次投遞 以交易編號、事件 ID 去重 使用者畫面 「付款失敗」誘導重付 結果不明顯示「確認中」 上層:減少次數、改善體驗 下層:保證只扣一次

圖:由上到下是一次付款經過的八層,左邊是這一層產生重複的原因,右邊是這一層的防線;越下面的防線越可靠,上面的只是減少發生次數。

這張圖有一個重要的方向性:越上面的防線越不可信,越下面的越可靠。按鈕停用可以被繞過(重新整理、開兩個分頁、直接打 API),用戶端的冪等鍵要靠用戶端正確實作,但資料庫的唯一約束不會被繞過。所以上層的防線是為了減少重複的次數與改善體驗,真正保證「只扣一次」的必須是資料庫約束與狀態機。反過來說,只有下層沒有上層也不行:下層擋住了重複,但使用者看到的是一堆錯誤訊息,客服電話會先把你淹沒。

第 1 層:付款按鈕

重複從哪裡來:網路慢的時候,使用者以為沒按到,再按一次;手機上的觸控也常常一次觸發兩下。付款完按上一頁、重新整理,瀏覽器可能再送一次表單。

防線:送出後立刻停用按鈕並顯示「處理中」,直到收到結果;同時在結帳頁載入時產生一個 checkout_token(隨機的 UUID),表單與 API 請求都帶著它。注意是載入時產生一次,而不是每次按下按鈕才產生:連點十下的十個請求,帶的是同一個 token。使用者真的想再買一次,會重新進入結帳頁,拿到新的 token。

不能依賴什麼:按鈕停用。它只存在於這一個分頁的記憶體裡,重新整理、開第二個分頁、網路斷線後重連,都會讓它失效;呼叫 API 的人也完全可以不經過按鈕。按鈕停用是為了體驗,不是防線。

第 2 層:用戶端(網頁與 App)

重複從哪裡來:HTTP 用戶端在逾時或連線中斷後自動重試;App 進入背景後被系統暫停,回到前景時把請求再送一次;離線佇列在恢復連線後補送。

防線:所有重試沿用同一個 checkout_token 作為冪等鍵(例如放在 Idempotency-Key 標頭),不管重試幾次、隔多久。最常見的錯誤是把冪等鍵的產生放在「送出請求」的函式裡,結果每次重試都產生一把新的鍵,冪等完全失效。冪等鍵應該跟「這一次付款意圖」綁在一起,存在結帳頁的狀態裡(App 要存在可以撐過程式被系統終止的地方),而不是跟「這一次 HTTP 請求」綁在一起。

用戶端還要能正確處理「處理中」的回應:伺服器回 202 或 409(同一把鍵的請求還在處理中,見〈冪等與分散式鎖〉),用戶端要做的是改成輪詢付款狀態,而不是再送一次付款請求。

不能依賴什麼:用戶端一定會正確實作。舊版 App、第三方整合、被修改過的請求都可能不帶鍵或亂帶鍵,伺服器端的防線不能假設冪等鍵一定存在且一定正確;沒有鍵的付款請求應該直接拒絕。

第 3 層:Gateway、負載平衡器與服務之間的重試

重複從哪裡來:api-gateway、負載平衡器、服務網格的 sidecar、gRPC 用戶端,都可能被設定成「上游沒回應就換一台再送一次」。使用者只按了一次,payment 服務卻收到兩個請求,而且可能落在兩個不同的實例上,同時處理。

防線:照〈逾時、重試與熔斷〉的原則:只對冪等的請求重試,而且只在一層重試。具體到支付:

  • GET 查詢付款狀態可以重試。
  • POST 建立付款與扣款,只有在請求帶著冪等鍵、而且下游確定會用這把鍵去重時,才允許重試;否則中間層一律不重試,把錯誤往上傳。
  • 可以安全重試的錯誤是「請求確定沒被處理」的那一類:連線被拒、503 且對方明確表示沒有處理。逾時、502、504、連線在送出後中斷,都代表「不知道對方做了沒有」,只有冪等的請求才能重試。
  • 4xx 不重試(429 照 Retry-After 等待除外),業務結果(卡片被拒)也不重試。

很多 Gateway 與負載平衡器預設會對某些錯誤自動重試,而且不區分 HTTP 方法;上線前要檢查實際使用的元件預設值,對付款路徑明確關掉或限制。

不能依賴什麼:中間層知道哪些請求是冪等的。它看到的只是 HTTP 方法與路徑,最安全的做法是讓付款路徑的中間層完全不重試,重試只發生在最了解語意的地方:帶著冪等鍵的用戶端,以及會先查詢再決定的支付服務本身。

第 4 層:訂單服務,一次結帳只成立一張訂單

重複從哪裡來:上面三層漏下來的重複請求,最後都會變成「建立訂單」被呼叫兩次。如果訂單服務每次都 INSERT 一張新訂單,同一次結帳就會有兩張訂單,各自去付款,而上一篇「每張訂單最多一筆有效付款」的約束完全擋不住,因為它們是兩張不同的訂單。

防線:用資料庫的唯一約束保證「一次結帳意圖只對應一張訂單」。延續〈database/sql、交易與連線池〉的 orders 表,加上 checkout_token:

ALTER TABLE orders ADD COLUMN checkout_token text;
CREATE UNIQUE INDEX orders_one_per_checkout ON orders (user_id, checkout_token);

-- 建立訂單:同一個使用者、同一個 token 第二次進來不會新增
INSERT INTO orders (user_id, total, checkout_token)
VALUES ($1, $2, $3)
ON CONFLICT (user_id, checkout_token) DO NOTHING
RETURNING id;
-- 沒有回傳列:讀出既有訂單,金額相同就回傳它;不同就是同一個 token 被拿去做別的事,回 422

唯一鍵用 (user_id, checkout_token) 而不是只用 token,是為了讓「別人的 token」永遠撞不到你的訂單,也讓查詢時順便確認了擁有者。訂單建立之後,狀態照上一篇的規則只能 pending → paid 或 pending → cancelled,用帶目前狀態的條件式 UPDATE 寫入。

不能依賴什麼:「先 SELECT 看有沒有,沒有再 INSERT」。兩個並發請求會同時看到「沒有」,然後各自新增一張,這正是〈併發常見問題:從資料競爭到超賣〉說的讀改寫競爭。去重一定要落在唯一約束上。

第 5 層:支付服務,一張訂單一次只有一個付款嘗試

這一層是整條鏈上最關鍵的一層,因為它是唯一會直接對金流商發出扣款的地方。上面每一層漏掉的重複,到這裡都還有機會擋下;這裡漏掉,錢就真的扣兩次了。

重複從哪裡來:有三個來源。第一,並發:同一張訂單的兩個付款請求同時進來,落在兩個實例上。第二,逾時之後的重試:第一次扣款逾時,程式把它當成失敗,產生新的付款紀錄與新的商店訂單編號再扣一次。第三,重新付款:第一次真的失敗了(卡片被拒),使用者換一張卡再付,這是合理的第二次嘗試,但必須確定第一次真的失敗了。

第二個來源是最常見、也最容易被忽略的,值得畫出來:

錯誤:逾時就換新編號重扣 支付服務 金流商 1. 扣款 A01 扣款成功,回應遺失 ✕ 2. 逾時,當成失敗 3. 扣款 A02(新編號) 4. 成功 結果:扣了兩次 正確:先用同一編號查詢 支付服務 金流商 1. 扣款 A01 扣款成功,回應遺失 ✕ 2. 逾時 → unknown 3. 查詢 A01 4. 已成功 結果:只扣一次,標記成功

圖:左邊逾時後換一個新的商店訂單編號重扣,對金流商來說是兩筆不同的交易,兩筆都成功;右邊先用同一個編號查詢,發現第一次已經成功,就不再扣款。

防線有四條,合起來就是「每張訂單同一時間只有一個付款嘗試,而且換下一個嘗試之前一定先確認上一個的結果」:

  1. 每個嘗試有唯一的商店訂單編號(很多金流商稱為 merchant trade number 或 merchant order ID,通常要求在同一個商店內不能重複)。編號由「訂單編號+第幾次嘗試」組成:同一次嘗試的重送一律沿用同一個編號,確定失敗後的新嘗試才換號。這樣金流商端只要會拒絕重複編號,就多了一道防線。
  2. 同一張訂單同時最多一個進行中的嘗試:沿用上一篇 payments 表的部分唯一索引 payments_one_active_per_order。
  3. 先查再重試(query before retry):嘗試的結果是 unknown 時,絕不直接發起下一次扣款,而是用同一個商店訂單編號向金流商查詢。查到成功就標記成功;查到明確失敗才允許新的嘗試;查不到這筆交易(對方根本沒收到),用同一個編號重送;查詢本身失敗或對方說還在處理,什麼都不做,回「確認中」。
  4. 所有狀態轉換都是條件式的:從 pending 改成 succeeded 要帶著 WHERE status = 'pending',搶輸的一方重新讀取狀態再決定,不會兩邊都去扣款。

在資料表上,就是在上一篇的 payments 表多記兩個欄位,冪等鍵直接用商店訂單編號:

ALTER TABLE payments ADD COLUMN attempt_no int NOT NULL DEFAULT 1;
ALTER TABLE payments ADD COLUMN trade_no text UNIQUE;  -- 送給金流商的商店訂單編號
ALTER TABLE payments ADD CONSTRAINT payments_one_row_per_attempt UNIQUE (order_id, attempt_no);

-- 建立第 n 次嘗試:第一次,或上一次已經確定失敗,才會新增
INSERT INTO payments (order_id, attempt_no, trade_no, idempotency_key, amount, currency, status)
SELECT $1, $2, $3, $3, $4, $5, 'pending'
WHERE $2 = 1
   OR EXISTS (SELECT 1 FROM payments WHERE order_id = $1 AND attempt_no = $2 - 1 AND status = 'failed')
ON CONFLICT DO NOTHING
RETURNING id;

ON CONFLICT DO NOTHING 不指定欄位,任何一個唯一約束衝突(同一個嘗試、同一個編號、同一張訂單已經有進行中的付款)都會讓這次新增變成「沒有回傳列」,呼叫端就知道自己不是負責扣款的那一個。

第 6 層:金流商

重複從哪裡來:我們這邊每一層都做對了,金流商仍然只是照收到的請求辦事:收到兩個不同編號的扣款請求,就是兩筆合法的交易。

防線:善用金流商提供的去重機制,當作最後一道保險,而不是唯一的保險。常見的有兩種:一種是商店訂單編號在同一個商店內必須唯一,重複的編號會被拒絕或回傳原本那筆交易;另一種是 API 支援冪等鍵標頭,在一段保留期間內,同一把鍵的請求會回傳第一次的結果。實際採用哪一種、重複時回什麼錯誤碼、冪等鍵保留多久,每家金流商都不同,要以它的官方文件為準,並且寫測試確認「重複編號」這個錯誤碼會被我們解讀成「去查詢原本那一筆」,而不是「失敗」。

不能依賴什麼:金流商一定會擋。有些付款方式沒有去重、有些冪等鍵只保留一段時間、有些在請求內容不同時行為不一樣;而且一旦我們自己換了編號,金流商就沒有任何理由認為那是重複。

第 7 層:回呼與訊息重送

重複從哪裡來:金流商的回呼是至少一次投遞,沒收到 2xx 就重送;我們自己發出的「付款成功」事件經過訊息佇列,消費者也可能收到兩次(〈訊息佇列與事件驅動〉)。這一層的重複不會造成第二次扣款,但會造成第二次出貨、第二封通知信、第二筆入帳分錄。

防線:回呼以金流商的交易編號或事件 ID 去重,並依狀態機冪等地套用(上一篇第 4 個問題);payment 服務更新狀態與寫入 Outbox 事件在同一個資料庫交易裡完成,消費端以事件 ID 寫入 Inbox 去重(〈分散式交易:Saga 與 Outbox〉)。每一個「收到事件就做一件事」的消費者,都要問自己:同一個事件來兩次,會不會做兩次?

第 8 層:使用者看得到的那一面

最後一層不在程式裡,在使用者的眼睛裡。很多重複付款其實是介面誘導出來的:逾時之後顯示「付款失敗,請重試」,使用者當然會再付一次。

防線:

  • 結果不明時顯示「付款確認中,請勿重複付款,確認後會通知您」,並提供查詢訂單狀態的入口,不要顯示「失敗」。
  • 訂單詳情頁顯示付款的真實狀態(確認中、成功、失敗),而不是只看前端記得的結果。
  • 同一張訂單已有進行中的付款時,「再付一次」的按鈕不要出現;只有付款確定失敗後才出現,而且按下去走的是第 5 層的「新嘗試」流程。
  • 客服的話術與後台也一致:客戶來電說「好像付了兩次」,客服看到的應該是每一筆嘗試的狀態與金流商交易編號,而不是一個籠統的「已付款」。

用 Go 把第 4、5 層串起來

下面用一個可以獨立編譯的 internal/payment 套件,把「一次結帳一張訂單」與「先查再重試」寫出來。為了讓範例可以直接跑,資料存在記憶體裡,但每一個需要互斥的地方都標註了它在資料庫裡對應的唯一約束或條件式 UPDATE。

// internal/payment/checkout.go
package payment

import (
	"context"
	"errors"
	"fmt"
	"sync"
)

type Status string

const (
	Pending   Status = "pending"   // 已送出或正要送出扣款,結果未定
	Unknown   Status = "unknown"   // 逾時、斷線、5xx:不知道對方做了沒有
	Succeeded Status = "succeeded" // 金流商明確回覆成功
	Failed    Status = "failed"    // 金流商明確回覆失敗(例如卡片被拒)
)

var (
	ErrDeclined   = errors.New("provider: declined")                     // 明確失敗
	ErrNotFound   = errors.New("provider: trade not found")              // 查無此商店訂單編號
	ErrProcessing = errors.New("payment is being confirmed")             // 對使用者顯示「確認中」,HTTP 202
	ErrKeyReused  = errors.New("checkout token reused, content differs") // HTTP 422
)

// Provider 是金流商的轉接層。Charge 回傳的錯誤只有 ErrDeclined 代表「確定沒扣」,
// 其他錯誤(逾時、斷線、5xx)一律視為結果不明。
type Provider interface {
	Charge(ctx context.Context, tradeNo string, amount int64, currency string) (txnID string, err error)
	Query(ctx context.Context, tradeNo string) (status Status, txnID string, err error)
}

type Order struct {
	ID       int64
	UserID   int64
	Token    string // checkout_token:結帳頁載入時產生一次
	Amount   int64  // 最小貨幣單位
	Currency string
}

type Attempt struct {
	OrderID int64
	No      int    // 這張訂單的第幾次付款嘗試
	TradeNo string // 送給金流商的商店訂單編號
	Status  Status
	TxnID   string // 金流商的交易編號
}

// TradeNo 由訂單編號與嘗試次數組成:同一次嘗試的重送沿用同一個編號,
// 確定失敗後的新嘗試才換號。長度與允許的字元以金流商文件為準。
func TradeNo(orderID int64, attempt int) string {
	return fmt.Sprintf("S%010dA%02d", orderID, attempt)
}

// Service 用記憶體模擬資料庫:每個需要鎖的地方,在資料庫裡都是唯一約束或條件式 UPDATE。
type Service struct {
	p        Provider
	mu       sync.Mutex
	nextID   int64
	orders   map[string]*Order // 唯一約束 (user_id, checkout_token)
	byID     map[int64]*Order
	attempts map[int64]*Attempt // 每張訂單目前的那一次嘗試
}

func NewService(p Provider) *Service {
	return &Service{p: p, orders: map[string]*Order{}, byID: map[int64]*Order{}, attempts: map[int64]*Attempt{}}
}

// Checkout:同一個使用者、同一個 checkout token 只會成立一張訂單。
func (s *Service) Checkout(userID int64, token string, amount int64, currency string) (Order, error) {
	if token == "" || amount <= 0 || len(currency) != 3 {
		return Order{}, errors.New("invalid checkout")
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	key := fmt.Sprintf("%d/%s", userID, token)
	if o, ok := s.orders[key]; ok {
		if o.Amount != amount || o.Currency != currency {
			return Order{}, ErrKeyReused
		}
		return *o, nil // 重送:回傳同一張訂單
	}
	s.nextID++
	o := &Order{ID: s.nextID, UserID: userID, Token: token, Amount: amount, Currency: currency}
	s.orders[key], s.byID[o.ID] = o, o
	return *o, nil
}

// Pay 可以被重複呼叫任意次,同一張訂單最多只會成功扣款一次。
func (s *Service) Pay(ctx context.Context, orderID int64) (Attempt, error) {
	a, o, err := s.claim(ctx, orderID)
	if err != nil || a.Status == Succeeded {
		return a, err
	}
	txnID, err := s.p.Charge(ctx, a.TradeNo, o.Amount, o.Currency)
	switch {
	case err == nil:
		got, _ := s.cas(a, Pending, Succeeded, txnID)
		return got, nil
	case errors.Is(err, ErrDeclined):
		got, _ := s.cas(a, Pending, Failed, "")
		return got, err
	default: // 逾時或其他錯誤:不猜,留給下一次呼叫或掃描器去查
		got, _ := s.cas(a, Pending, Unknown, "")
		return got, ErrProcessing
	}
}

// claim 決定這次要不要扣款、用哪個編號。回傳 Pending 的嘗試代表「由這個呼叫負責扣款」。
func (s *Service) claim(ctx context.Context, orderID int64) (Attempt, Order, error) {
	for {
		if err := ctx.Err(); err != nil {
			return Attempt{}, Order{}, err
		}
		o, a, err := s.load(orderID)
		if err != nil {
			return Attempt{}, Order{}, err
		}
		switch {
		case a == nil:
			if got, ok := s.create(orderID, 1); ok {
				return got, o, nil
			}
		case a.Status == Succeeded:
			return *a, o, nil // 已經付過:原樣回傳
		case a.Status == Pending:
			return *a, o, ErrProcessing // 另一個請求正在扣款:不能再扣一次
		case a.Status == Failed:
			if got, ok := s.create(orderID, a.No+1); ok { // 確定失敗,才換新編號
				return got, o, nil
			}
		case a.Status == Unknown:
			st, txnID, err := s.p.Query(ctx, a.TradeNo) // 先查再重試
			switch {
			case errors.Is(err, ErrNotFound): // 對方沒收到:用同一個編號重送
				if got, ok := s.cas(*a, Unknown, Pending, ""); ok {
					return got, o, nil
				}
			case err != nil || (st != Succeeded && st != Failed):
				return *a, o, ErrProcessing // 查詢失敗或對方仍在處理:什麼都不做
			default:
				s.cas(*a, Unknown, st, txnID) // 套用查到的結果,下一圈依新狀態處理
			}
		}
		// 沒搶到(別的請求先改了狀態):重新讀一次
	}
}

func (s *Service) load(orderID int64) (Order, *Attempt, error) {
	s.mu.Lock()
	defer s.mu.Unlock()
	o, ok := s.byID[orderID]
	if !ok {
		return Order{}, nil, fmt.Errorf("order %d not found", orderID)
	}
	if a, ok := s.attempts[orderID]; ok {
		cp := *a
		return *o, &cp, nil
	}
	return *o, nil, nil
}

// create 對應 INSERT ... ON CONFLICT (order_id, attempt_no) DO NOTHING。
func (s *Service) create(orderID int64, no int) (Attempt, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	cur := s.attempts[orderID]
	if (cur == nil && no != 1) || (cur != nil && (cur.No != no-1 || cur.Status != Failed)) {
		return Attempt{}, false
	}
	a := &Attempt{OrderID: orderID, No: no, TradeNo: TradeNo(orderID, no), Status: Pending}
	s.attempts[orderID] = a
	return *a, true
}

// cas 對應 UPDATE ... SET status = to WHERE order_id = ? AND attempt_no = ? AND status = from。
func (s *Service) cas(a Attempt, from, to Status, txnID string) (Attempt, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	cur := s.attempts[a.OrderID]
	if cur == nil || cur.No != a.No || cur.Status != from {
		return a, false
	}
	cur.Status = to
	if txnID != "" {
		cur.TxnID = txnID
	}
	return *cur, true
}

幾個重點:

  • Pay 可以被任意重複呼叫:使用者連點、用戶端重試、Gateway 重送、使用者幾分鐘後回來再按一次,都走同一個入口,由 claim 決定這一次要不要扣款。
  • 只有搶到 Pending 的那一個呼叫會真的呼叫 Charge;其他並發的呼叫看到 Pending,回 ErrProcessing(對使用者顯示「確認中」),不會等待也不會扣款。
  • Charge 回傳的錯誤只有明確的拒絕會讓狀態變成 Failed;逾時、斷線與其他錯誤一律變成 Unknown。
  • 狀態是 Unknown 時,下一次呼叫先 Query,用的是同一個 TradeNo。查到成功就不再扣款;查無此單才用同一個編號重送;查詢失敗什麼都不做。
  • 新的編號只在上一次確定 Failed 之後才會產生。

測試的重點是一個「扣款成功了、回應卻逾時」的假金流商。它每一次 Charge 都會真的成立一筆扣款,而且不替我們去重,所以「只扣一次」完全要靠我們自己的程式:

// internal/payment/checkout_test.go
package payment

import (
	"context"
	"errors"
	"fmt"
	"sync"
	"testing"
	"time"
)

// fakeProvider 每次 Charge 都會真的成立一筆扣款(不替我們去重),
// 所以「只扣一次」完全要靠我們自己的程式。
type fakeProvider struct {
	mu        sync.Mutex
	charges   []string          // 每一筆成立的扣款所用的商店訂單編號
	status    map[string]Status // 商店訂單編號 → 結果
	timeout   bool              // 扣款成功了,回應卻逾時
	declineN  int               // 前 N 次扣款被拒
	chargeDur time.Duration
}

func (f *fakeProvider) Charge(ctx context.Context, tradeNo string, amount int64, currency string) (string, error) {
	time.Sleep(f.chargeDur)
	f.mu.Lock()
	defer f.mu.Unlock()
	if f.status == nil {
		f.status = map[string]Status{}
	}
	if f.declineN > 0 {
		f.declineN--
		f.status[tradeNo] = Failed
		return "", ErrDeclined
	}
	f.charges = append(f.charges, tradeNo)
	f.status[tradeNo] = Succeeded
	if f.timeout {
		f.timeout = false // 只有第一次逾時
		return "", context.DeadlineExceeded
	}
	return fmt.Sprintf("txn-%d", len(f.charges)), nil
}

func (f *fakeProvider) Query(ctx context.Context, tradeNo string) (Status, string, error) {
	f.mu.Lock()
	defer f.mu.Unlock()
	st, ok := f.status[tradeNo]
	if !ok {
		return "", "", ErrNotFound
	}
	return st, "txn-of-" + tradeNo, nil
}

func (f *fakeProvider) count() int {
	f.mu.Lock()
	defer f.mu.Unlock()
	return len(f.charges)
}

func TestTimeoutThenRetryChargesOnce(t *testing.T) {
	p := &fakeProvider{timeout: true}
	s := NewService(p)
	ctx := context.Background()
	o, _ := s.Checkout(7, "tok-1", 1999, "USD")

	a, err := s.Pay(ctx, o.ID)
	if !errors.Is(err, ErrProcessing) || a.Status != Unknown {
		t.Fatalf("first try: %v %v, want unknown + ErrProcessing", a.Status, err)
	}
	// 使用者或用戶端重試:先查詢,發現已經成功,不再扣款
	a, err = s.Pay(ctx, o.ID)
	if err != nil || a.Status != Succeeded {
		t.Fatalf("retry: %v %v", a.Status, err)
	}
	if n := p.count(); n != 1 {
		t.Fatalf("charged %d times, want 1", n)
	}
}

// 錯誤的做法:逾時就當失敗,換一個新編號再扣一次。
func TestNaiveRetryChargesTwice(t *testing.T) {
	p := &fakeProvider{timeout: true}
	for i := 1; i <= 2; i++ {
		if _, err := p.Charge(context.Background(), fmt.Sprintf("naive-%d", i), 1999, "USD"); err == nil {
			break
		}
	}
	if n := p.count(); n != 2 {
		t.Fatalf("naive retry charged %d times; this test documents the bug", n)
	}
}

func TestDoubleClickConcurrent(t *testing.T) {
	p := &fakeProvider{chargeDur: 20 * time.Millisecond}
	s := NewService(p)
	var wg sync.WaitGroup
	for range 10 { // 同一個結帳頁連點十下
		wg.Go(func() {
			o, err := s.Checkout(7, "tok-2", 1999, "USD")
			if err != nil {
				t.Error(err)
				return
			}
			if _, err := s.Pay(context.Background(), o.ID); err != nil && !errors.Is(err, ErrProcessing) {
				t.Error(err)
			}
		})
	}
	wg.Wait()
	if n := p.count(); n != 1 {
		t.Fatalf("charged %d times, want 1", n)
	}
	if s.nextID != 1 {
		t.Fatalf("%d orders, want 1", s.nextID)
	}
}

func TestDeclinedThenNewAttempt(t *testing.T) {
	p := &fakeProvider{declineN: 1}
	s := NewService(p)
	o, _ := s.Checkout(7, "tok-3", 1999, "USD")
	if _, err := s.Pay(context.Background(), o.ID); !errors.Is(err, ErrDeclined) {
		t.Fatalf("want declined, got %v", err)
	}
	a, err := s.Pay(context.Background(), o.ID) // 換一張卡再付
	if err != nil || a.No != 2 || a.TradeNo == TradeNo(o.ID, 1) {
		t.Fatalf("second attempt: %+v %v", a, err)
	}
}

func TestTokenReusedWithOtherAmount(t *testing.T) {
	s := NewService(&fakeProvider{})
	s.Checkout(7, "tok-4", 1999, "USD")
	if _, err := s.Checkout(7, "tok-4", 2999, "USD"); !errors.Is(err, ErrKeyReused) {
		t.Fatalf("want ErrKeyReused, got %v", err)
	}
}

TestNaiveRetryChargesTwice 刻意示範錯誤的做法:逾時就換一個新編號再扣一次,結果扣了兩次。TestDoubleClickConcurrent 用十個 goroutine 模擬同一個結帳頁連點十下,配合 -race 執行,確認只成立一張訂單、只扣一次款,而且沒有資料競爭(sync.WaitGroup.Go 需要 Go 1.25 以上):

$ go test -race ./...
ok  	example.com/shop/internal/payment	1.2s
ok  	example.com/shop/internal/sweeper	1.3s

提示:真實的實作裡,Pending 有可能因為程式在呼叫 Charge 途中當掉而永遠卡住。這時候 claim 只會一直回 ErrProcessing,不會再扣款;把它找回結果是第二部分「卡單掃描器」的工作。寧可卡住等人處理,也不要冒險扣第二次。

第二部分:支付事故

第一部分的防線讓重複扣款變得很少,但支付系統依賴的外部因素太多,事故遲早會發生。重點不是保證永遠不出事,而是:事故要小、要早被發現、處理時不能把事情弄得更糟。

支付事故長什麼樣子

常見的支付事故大致有這幾類,每一類最早出現的訊號都不太一樣:

事故現象最早的訊號
金流商全面故障扣款請求全部失敗或逾時付款成功率驟降、熔斷器打開
金流商變慢回應時間從幾百毫秒變成十幾秒,逾時與重試暴增,連帶拖垮自己呼叫延遲上升、逾時率上升、unknown 數量增加
付款卡在處理中大量付款停在 pending 或 unknown,使用者不知道付了沒有卡住超過 15 分鐘的付款數
重複扣款已經發生同一張訂單在金流商有兩筆成功的扣款重複扣款偵測查詢、客訴
回呼停止金流商端成功了,我們這邊一直沒收到通知最後一則回呼距今的時間、unknown 累積
對帳差異暴增每日對帳的差異筆數或金額突然變多對帳報表
新版本算錯金額部署後的付款金額與訂單金額不符、幣別錯誤、小數位數錯金額合理性檢查擋下的筆數、付款金額分布突變
憑證或金鑰輪替失敗簽章驗證失敗,回呼全部被拒;或呼叫金流商時認證失敗回呼驗簽失敗率、金流商回 401/403

這張表有一個共同點:大部分支付事故不會讓服務當掉。HTTP 回應正常、CPU 正常、錯誤率可能也不高(回呼驗簽失敗回的是 401,看起來像是「有人亂打」),只有看業務指標才看得出來。這也是下面告警要以業務指標為主的原因。

事前預防:讓事故變小

每個金流商各自的逾時、熔斷與重試預算

依〈逾時、重試與熔斷〉的做法,每個金流商有自己的逾時、熔斷器與連線池,一家變慢不會拖垮所有付款,也不會拖垮與付款無關的功能。支付的特殊之處在於:熔斷器打開時,回給使用者的是「目前無法付款,請稍後再試」,而且這時候的請求確定沒有送出,所以可以安全地讓使用者稍後重試;而逾時的請求是「不知道」,要進入 unknown。

重試預算更重要。金流商變慢時,如果每個逾時的請求都重試,送到金流商的請求量會倍增,讓它更慢,形成惡性循環。支付服務對金流商的扣款本來就只在「先查再重試」的條件下才重送,查詢請求也要有自己的預算與限速。

開關:能停、能切換

事先準備好幾個可以在幾秒內生效、不需要部署的開關(feature flag):

  • 停止新的付款:結帳頁顯示「付款功能維護中」,已在進行的付款不受影響。這是最後手段,但它必須存在,而且要定期演練確認真的能用。
  • 切換金流商:有多家金流商時,把新的付款導到備援的那一家。注意只切換新的付款;已經在舊金流商進行中的付款,仍然要在舊金流商查詢與完成。
  • 暫停自動化工作:訂單逾時自動取消、自動退款、自動重試這類背景工作,在事故期間可能做出錯誤的決定(例如把其實已經付款成功、只是回呼沒到的訂單取消掉)。每一個都要能單獨暫停。

限流、金絲雀與金額合理性檢查

  • 限流:對單一使用者、單一卡片、單一 IP 的付款請求限流,擋住腳本攻擊與失控的用戶端重試;也遵守金流商對我們的限流,不要讓自己的突發流量觸發對方的封鎖。
  • 金絲雀部署:動到付款路徑的程式,先讓一小部分流量使用新版,以付款成功率、金額分布等業務指標判斷是否擴大(〈用 AI 工作流自動化部署與排查問題〉)。付款程式的錯誤常常不會讓服務當掉,只會讓金額或狀態錯,所以金絲雀的判斷條件一定要包含業務指標。
  • 金額合理性檢查:在 payment 服務送出扣款前,最後檢查一次:金額大於零、不超過這個商店或商品類型的上限、幣別在允許清單裡、付款金額等於訂單金額。檢查失敗就拒絕並告警,而不是送出去讓金流商決定。這道檢查能把「新版本算錯金額」從「已經扣錯幾千筆」變成「擋下幾千筆並告警」。

以業務指標告警

技術指標(錯誤率、延遲、CPU)仍然需要,但支付最重要的告警是業務指標。下面用白話描述幾條常見的告警規則,數字只是起點,要依自己的流量與歷史資料調整:

指標告警條件(白話)可能的事故
付款成功率過去 10 分鐘的成功率比上週同時段低 10 個百分點以上,且這段時間至少有 50 筆付款金流商故障、新版本錯誤、憑證問題
卡住的付款停在 pending 或 unknown 超過 15 分鐘的付款,連續 10 分鐘多於 0 筆金流商變慢、回呼停止、程式當掉
同一張訂單的成功扣款任何一張訂單在金流商有兩筆以上成功的扣款,立即通知重複扣款
同一張訂單的付款嘗試單張訂單的嘗試次數超過 3 次,或每張訂單平均嘗試次數突然上升用戶端重試失控、卡片被大量拒絕
回呼延遲有付款在進行中,但最後一則回呼已經是 15 分鐘前回呼停止、驗簽失敗、網址被擋
回呼驗簽失敗率驗簽失敗的比例超過 1%金鑰輪替失敗、有人偽造回呼
金額合理性檢查擋下的筆數過去 10 分鐘多於 0 筆新版本算錯金額
對帳差異每日差異筆數超過過去 30 天平均的 3 倍,或差異金額超過門檻任何一種靜默的錯誤

「重複扣款」與「金額合理性檢查擋下」這類告警的門檻應該是 0:正常情況下它們不會發生,發生一次就值得有人看。其他告警要避免太敏感,否則半夜響太多次,大家就會開始忽略它。

付款狀態:誰能讓 unknown 結束

事故期間最大量的工作,是把停在 pending 與 unknown 的付款找回結果。先把規則畫清楚:unknown 只能由「向金流商確認過」的結果結束,而能做確認的來源有好幾個,它們都走同一套條件式轉換,所以誰先到都不會互相覆蓋。

處理中 pending 成功 succeeded 結果不明 unknown 失敗 failed 向金流商查詢 使用者重試、回呼 掃描器、對帳、人工 明確成功 逾時、斷線 5xx 查到失敗 查到成功 查無此單: 同編號重送 明確拒絕(例如卡片被拒) failed 之後要再付,建立新的嘗試與新的商店訂單編號

圖:逾時、斷線與 5xx 讓付款進入 unknown;使用者重試、回呼、掃描器、對帳與人工處理都只能在向金流商確認後,把它轉成 succeeded 或 failed;查無此單時用同一個編號重送。

事故應變手冊

事故當下最容易犯的錯,是急著「修好」而跳過確認:看到一堆 unknown 就全部改成失敗、看到重複扣款就整批退款。下面的順序是刻意安排的,每一步都在為下一步取得正確的資訊。

1. 偵測 告警、客訴 金流商通知 2. 宣告事故 指定指揮者 開始記錄時間軸 3. 止血 開關、回滾 暫停自動化 4. 溝通 「確認中, 請勿重複付款」 5. 圈出範圍 用時間軸 與 SQL 查詢 6. 向金流商確認 查詢 API、對帳檔 存成 provider 表 7. 修復 掃描器、恢復訂單 冪等地退款 8. 對帳與檢討 重跑對帳 不究責的檢討 第 6 步之前:不改狀態、不退款、不取消

圖:從偵測、宣告、止血、溝通,到圈出範圍、向金流商確認狀態、修復,最後對帳與事後檢討;確認狀態之前不做任何退款或取消。

1. 偵測

來源是上面的告警、客服回報的客訴、金流商的狀態頁或通知。第一個收到的人先做最小的確認:是單一使用者的問題,還是很多筆都有同樣的現象?

2. 宣告事故

只要牽涉到金錢、影響不只一位使用者,就宣告事故,不要等確定原因。指定一位事故指揮者負責決策與協調,開一個專用的溝通頻道,從這一刻開始記錄時間軸:幾點發現、幾點做了什麼、看到什麼。事後檢討與圈出影響範圍,都靠這份時間軸裡的時間點。

3. 止血

目標是讓損害停止擴大,而不是找出根本原因:

  • 金流商故障或變慢:熔斷器應該已經打開;必要時用開關切換到備援金流商,或停止新的付款。
  • 新版本造成的錯誤:立刻回滾,不要在事故中修程式往前推。
  • 暫停可能做錯決定的自動化:訂單逾時自動取消、自動退款、自動重試。
  • 回呼停止或驗簽失敗:確認回呼網址、憑證與金鑰;回呼通常會重送,修好之後積壓的通知會陸續進來。

止血不包括修改資料。這個階段不要改任何付款或訂單的狀態。

4. 溝通

讓客服與使用者知道正確的訊息:「部分付款結果確認中,請勿重複付款,確認後會主動通知」。結帳頁與訂單頁顯示相同的訊息。對內定期更新狀態,即使沒有新進展也說「沒有新進展,下一次更新在 30 分鐘後」。

5. 圈出受影響的範圍

用時間軸裡的時間點與資料庫查詢,列出可能受影響的付款與訂單。幾個常用的查詢:

-- 卡住的付款:依狀態統計數量與最舊的時間
SELECT status,
       count(*)                                                        AS payments,
       count(*) FILTER (WHERE updated_at < now() - interval '15 minutes') AS older_than_15m,
       min(updated_at)                                                 AS oldest
FROM payments
WHERE status IN ('pending', 'unknown')
GROUP BY status;

-- 付款成功、訂單卻已取消(事故期間自動取消的受害者)
SELECT o.id AS order_id, p.id AS payment_id, p.amount, p.currency, p.provider_txn_id
FROM orders o
JOIN payments p ON p.order_id = o.id
WHERE o.status = 'cancelled'
  AND p.status = 'succeeded'
  AND p.updated_at >= $1;  -- 事故開始時間

-- 部署期間付款金額與訂單金額不符
SELECT p.id AS payment_id, p.order_id, o.total, p.amount
FROM payments p
JOIN orders o ON o.id = p.order_id
WHERE p.created_at BETWEEN $1 AND $2  -- 部署到回滾的時間
  AND p.amount <> o.total;

6. 向金流商確認真實狀態

這是整個流程裡最重要的一步:我們資料庫裡的狀態,在事故期間是不可信的。unknown 可能其實是成功、failed 可能是被錯誤程式寫錯的、回呼停止期間的成功完全沒有被記錄。所以在做任何修復之前,先用金流商的查詢 API(或對帳檔)取得每一筆相關交易的真實狀態,存進一張表裡:

-- 從金流商查詢、回呼與對帳檔同步回來的交易,以金流商的交易編號為準
CREATE TABLE provider_transactions (
  provider_txn_id text        PRIMARY KEY,
  trade_no        text        NOT NULL,     -- 我們送出的商店訂單編號
  status          text        NOT NULL,     -- 金流商回報的狀態
  amount          bigint      NOT NULL,     -- 最小貨幣單位
  currency        char(3)     NOT NULL,
  created_at      timestamptz NOT NULL,     -- 金流商那邊的交易時間
  synced_at       timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX provider_transactions_trade_no ON provider_transactions (trade_no);

有了這張表,重複扣款就可以用一個查詢找出來:同一張訂單在金流商有兩筆以上成功的交易。

-- 重複扣款偵測:同一張訂單在金流商有兩筆以上成功的扣款
SELECT p.order_id,
       count(*)                                                  AS succeeded_charges,
       sum(t.amount)                                             AS charged_total,
       array_agg(t.provider_txn_id ORDER BY t.created_at)        AS provider_txn_ids
FROM provider_transactions t
JOIN payments p ON p.trade_no = t.trade_no
WHERE t.status = 'succeeded'
  AND t.created_at >= now() - interval '7 days'
GROUP BY p.order_id
HAVING count(*) > 1;

-- 金流商有、我們完全沒有紀錄的成功交易:要人工追查
SELECT t.*
FROM provider_transactions t
LEFT JOIN payments p ON p.trade_no = t.trade_no
WHERE t.status = 'succeeded' AND p.id IS NULL;

這個偵測查詢同時也是平常的監控:每 15 分鐘跑一次,結果不是空的就觸發上面「同一張訂單的成功扣款」那條告警。

卡在 pending 與 unknown 的付款,則交給下一節的掃描器逐筆向金流商查詢。

7. 修復:先確認,再一筆一筆、冪等地修

修復的順序與原則:

  • 卡住的付款:由掃描器依查詢結果轉成 succeeded 或 failed,走同一套條件式轉換。
  • 付款成功但訂單已取消:依業務規則恢復訂單(庫存還在時)或全額退款,並通知使用者。
  • 重複扣款:保留訂單上記錄的那一筆,其餘的退款。退款要冪等而且有紀錄:每一筆要退的扣款產生一個固定的冪等鍵,寫進退款表,再由退款工作照上一篇第 7 個問題的流程向金流商發起。腳本重跑、兩個人同時執行,都不會退兩次。
CREATE TABLE refunds (
  id              bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  provider_txn_id text        NOT NULL,                  -- 要退的那一筆扣款
  idempotency_key text        NOT NULL UNIQUE,
  amount          bigint      NOT NULL CHECK (amount > 0),
  currency        char(3)     NOT NULL,
  reason          text        NOT NULL,
  status          text        NOT NULL DEFAULT 'pending',
  created_by      text        NOT NULL,                  -- 誰決定的,稽核用
  created_at      timestamptz NOT NULL DEFAULT now()
);

-- 只退「不是訂單上記錄的那一筆」的成功扣款;同一筆扣款永遠只會有一筆退款紀錄
INSERT INTO refunds (provider_txn_id, idempotency_key, amount, currency, reason, created_by)
SELECT t.provider_txn_id, 'dup-refund:' || t.provider_txn_id, t.amount, t.currency,
       'duplicate_charge', $1                            -- 例如事故編號加上執行者
FROM provider_transactions t
JOIN payments p    ON p.trade_no = t.trade_no
JOIN payments kept ON kept.order_id = p.order_id
                  AND kept.status IN ('succeeded', 'partially_refunded', 'refunded')
WHERE t.status = 'succeeded'
  AND t.provider_txn_id <> kept.provider_txn_id
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING provider_txn_id, amount;

為什麼不能先整批退款:如果在確認狀態之前,就依照我們資料庫的狀態退款,會發生兩種錯誤。一種是退了不該退的:把其實是唯一一筆成功扣款的 unknown 當成重複退掉,客戶拿到退款也拿到商品。另一種是漏退:回呼停止期間成功的扣款在我們這邊沒有紀錄,只看自己的資料庫根本找不到它。退款也是一筆真實的金錢流動,退錯了要再向客戶收回來,比多扣一次更難處理。所以順序永遠是:確認 → 記錄 → 冪等地執行 → 再確認。

8. 對帳與事後檢討

事故處理完,針對事故期間重新跑一次完整的對帳,確認所有差異都已經處理或有人負責。接著做不究責的事後檢討(blameless postmortem):依時間軸還原發生了什麼、為什麼現有的防線沒擋住、為什麼告警晚了(或為什麼沒有告警)、哪些步驟花了太久;產出的行動項目要有負責人與期限,例如「新增回呼延遲的告警」「訂單自動取消前先查詢付款狀態」「金鑰輪替加入預先驗證的步驟」。檢討的對象是系統與流程,不是按下部署按鈕的人:如果一個人的一次失誤就能造成事故,該修的是讓這個失誤可能發生的系統。

卡單掃描器

卡在 pending 與 unknown 的付款,平常就會有少量(回呼遺失、程式在扣款途中重啟),事故期間則可能一次累積幾千筆。掃描器是一個定期執行的背景工作,把它們逐筆向金流商查詢,有明確結果才改狀態。

開始一輪 before = now − MinAge 取一批:id > after ORDER BY id LIMIT n 沒有資料:結束 每一筆 等限速 ctx 取消就停 查詢金流商 同一個商店訂單編號 成功或失敗 條件式更新 沒改到=已處理 仍在處理 不改,下一輪再查 查詢失敗 不改,記錄錯誤 after = 這批最後一筆 id

圖:每一輪先固定時間界線,再依 id 一批一批往後取;每筆查詢前先等限速,查到成功或失敗才做條件式更新,沒改到代表已被回呼處理;中途可以隨時取消。

設計上有幾個重點:

  • 只碰夠舊的:比 MinAge(例如 15 分鐘)新的付款,還在正常流程或等回呼,不要去搶。時間界線在每一輪開始時固定,這一輪才不會追著新變成卡住的資料一直跑下去。
  • keyset 分頁:用 id > 上一批最後一筆 往後取,而不是 OFFSET。掃描的同時,前面的付款會因為被處理而離開「卡住」的集合,用 OFFSET 會讓整批資料往前移,跳過一些付款;keyset 不受影響,每一筆剛好掃到一次。
  • 限速:查詢金流商之間至少間隔一段時間。事故期間金流商本來就可能很吃緊,幾千筆查詢一次送出,會讓自己被對方限流,甚至讓對方更慢。
  • 條件式轉換:只有目前狀態仍然是掃描時看到的那個,才會被改;沒改到代表回呼或使用者的重試先處理了,這是正常情況,不是錯誤。
  • 查不到不改:查詢失敗、對方還在處理,都保持原狀,下一輪再查。掃描器永遠不會「猜」結果。
  • 可以中斷與重跑:每一步都看 ctx,部署或關閉時能立刻停下(〈設定與優雅關閉〉);因為所有寫入都是條件式的,重跑或兩個實例同時跑也不會出錯,只是浪費一些查詢。真的要避免重複查詢,可以用〈冪等與分散式鎖〉的租約讓同時只有一個實例在跑。

查詢與更新在 PostgreSQL 裡長這樣:

-- 只索引卡住的付款,掃描時不必讀整張表
CREATE INDEX payments_stuck ON payments (id) WHERE status IN ('pending', 'unknown');

-- Stuck:keyset 分頁
SELECT id, trade_no, status
FROM payments
WHERE status IN ('pending', 'unknown')
  AND id > $1               -- 上一批最後一筆的 id
  AND updated_at < $2       -- 這一輪開始時固定的時間界線
ORDER BY id
LIMIT $3;

-- Transition:只在狀態仍是掃描時看到的那個時才改
UPDATE payments
SET status = $3, provider_txn_id = coalesce(NULLIF($4, ''), provider_txn_id), updated_at = now()
WHERE id = $1 AND status = $2;
-- 影響 1 列:改到了;影響 0 列:別人先處理了

Go 的部分只依賴兩個介面,資料庫與金流商都可以替換成測試用的假物件:

// internal/sweeper/sweeper.go
package sweeper

import (
	"context"
	"time"
)

type Payment struct {
	ID      int64
	TradeNo string
	Status  string // pending 或 unknown
}

type Store interface {
	// Stuck 依 id 遞增,取 id > afterID、最後更新早於 before 的 pending/unknown 付款,最多 limit 筆。
	Stuck(ctx context.Context, afterID int64, before time.Time, limit int) ([]Payment, error)
	// Transition 只在目前狀態仍是 from 時才改;回傳是否真的改了。
	Transition(ctx context.Context, id int64, from, to, txnID string) (bool, error)
}

type Provider interface {
	Query(ctx context.Context, tradeNo string) (status, txnID string, err error)
}

type Sweeper struct {
	Store    Store
	Provider Provider
	MinAge   time.Duration // 比這個新的不碰,留給正常流程與回呼
	Batch    int
	Interval time.Duration // 兩次查詢之間的最短間隔,保護金流商也避免被限流
	Now      func() time.Time
}

type Result struct {
	Scanned, Resolved, AlreadyDone, StillPending, QueryErrors int
}

// Run 掃過一輪:每筆卡住的付款向金流商查一次,有明確結果才改狀態。
// 隨時可以中斷,也可以重跑;同一筆被改兩次的情況由條件式更新擋掉。
func (s *Sweeper) Run(ctx context.Context) (Result, error) {
	var r Result
	tick := time.NewTicker(s.Interval)
	defer tick.Stop()
	before := s.Now().Add(-s.MinAge) // 在開始時固定,這一輪才不會追著新資料跑
	var after int64
	for {
		batch, err := s.Store.Stuck(ctx, after, before, s.Batch)
		if err != nil || len(batch) == 0 {
			return r, err
		}
		for _, p := range batch {
			select {
			case <-ctx.Done():
				return r, ctx.Err()
			case <-tick.C: // 限速
			}
			r.Scanned++
			st, txnID, err := s.Provider.Query(ctx, p.TradeNo)
			switch {
			case err != nil:
				r.QueryErrors++ // 查不到就不改,下一輪再查
			case st == "succeeded" || st == "failed":
				ok, err := s.Store.Transition(ctx, p.ID, p.Status, st, txnID)
				if err != nil {
					return r, err
				}
				if ok {
					r.Resolved++
				} else {
					r.AlreadyDone++ // 回呼或使用者重試先處理了
				}
			default:
				r.StillPending++
			}
		}
		after = batch[len(batch)-1].ID // keyset:下一批從最後一筆之後開始
	}
}

Transition 改成功之後,訂單變成 paid 的事件、通知信、帳本分錄,都跟正常流程一樣透過 Outbox 發出;掃描器只負責「找回結果」,不另外做一套後續處理,避免兩條路徑的行為不一致。

測試確認三件事:每一筆夠舊的卡單剛好被查一次(keyset 分頁沒有漏也沒有重複)、掃描途中被回呼搶先處理的那一筆不會被覆蓋、查詢失敗的維持原狀;另外確認 ctx 取消時會立刻停下:

// internal/sweeper/sweeper_test.go
package sweeper

import (
	"context"
	"errors"
	"fmt"
	"sort"
	"sync"
	"testing"
	"time"
)

var t0 = time.Date(2026, 11, 15, 12, 0, 0, 0, time.UTC)

type row struct {
	Payment
	updated time.Time
}

type fakeStore struct {
	mu   sync.Mutex
	rows map[int64]*row
}

func (f *fakeStore) Stuck(ctx context.Context, afterID int64, before time.Time, limit int) ([]Payment, error) {
	f.mu.Lock()
	defer f.mu.Unlock()
	var out []Payment
	for _, r := range f.rows {
		if r.ID > afterID && r.updated.Before(before) && (r.Status == "pending" || r.Status == "unknown") {
			out = append(out, r.Payment)
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
	return out[:min(limit, len(out))], nil
}

func (f *fakeStore) Transition(ctx context.Context, id int64, from, to, txnID string) (bool, error) {
	f.mu.Lock()
	defer f.mu.Unlock()
	r := f.rows[id]
	if r.Status != from {
		return false, nil
	}
	r.Status = to
	return true, nil
}

type fakeProvider struct {
	mu      sync.Mutex
	queried map[string]int
	before  func(tradeNo string) // 查詢前的動作,用來模擬回呼搶先
}

func (f *fakeProvider) Query(ctx context.Context, tradeNo string) (string, string, error) {
	if f.before != nil {
		f.before(tradeNo)
	}
	f.mu.Lock()
	f.queried[tradeNo]++
	f.mu.Unlock()
	var n int
	fmt.Sscanf(tradeNo, "T%d", &n)
	switch {
	case n%7 == 0:
		return "", "", errors.New("provider 503")
	case n%5 == 0:
		return "pending", "", nil
	case n%2 == 0:
		return "failed", "", nil
	default:
		return "succeeded", fmt.Sprintf("txn-%d", n), nil
	}
}

func TestSweepEveryStuckPaymentOnce(t *testing.T) {
	st := &fakeStore{rows: map[int64]*row{}}
	for id := int64(1); id <= 25; id++ {
		updated := t0.Add(-time.Hour)
		if id > 22 {
			updated = t0.Add(-time.Minute) // 太新,這一輪不碰
		}
		st.rows[id] = &row{Payment{id, fmt.Sprintf("T%d", id), "unknown"}, updated}
	}
	p := &fakeProvider{queried: map[string]int{}}
	p.before = func(tradeNo string) {
		if tradeNo == "T3" { // 掃描器查詢的同時,回呼先把 3 號改成成功
			st.Transition(context.Background(), 3, "unknown", "succeeded", "txn-3")
		}
	}
	s := &Sweeper{Store: st, Provider: p, MinAge: 15 * time.Minute, Batch: 10,
		Interval: time.Millisecond, Now: func() time.Time { return t0 }}

	r, err := s.Run(context.Background())
	if err != nil {
		t.Fatal(err)
	}
	if r.Scanned != 22 || len(p.queried) != 22 {
		t.Fatalf("scanned %d, queried %d distinct, want 22", r.Scanned, len(p.queried))
	}
	for no, n := range p.queried {
		if n != 1 {
			t.Errorf("%s queried %d times", no, n)
		}
	}
	if r.AlreadyDone != 1 || r.Resolved+r.AlreadyDone+r.StillPending+r.QueryErrors != 22 {
		t.Fatalf("result %+v", r)
	}
	if got := st.rows[14].Status; got != "unknown" { // 查詢失敗的不改
		t.Fatalf("payment 14 is %s", got)
	}
	again, _ := s.Run(context.Background()) // 重跑只會碰到還沒結果的
	if again.Resolved != 0 || again.Scanned != r.StillPending+r.QueryErrors {
		t.Fatalf("second run %+v", again)
	}
}

func TestSweepStopsOnCancel(t *testing.T) {
	st := &fakeStore{rows: map[int64]*row{1: {Payment{1, "T1", "pending"}, t0.Add(-time.Hour)}}}
	s := &Sweeper{Store: st, Provider: &fakeProvider{queried: map[string]int{}}, MinAge: time.Minute,
		Batch: 10, Interval: time.Hour, Now: func() time.Time { return t0 }}
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
	defer cancel()
	r, err := s.Run(ctx)
	if !errors.Is(err, context.DeadlineExceeded) || r.Scanned != 0 {
		t.Fatalf("got %+v %v", r, err)
	}
}

假金流商依交易編號決定結果(7 的倍數查詢失敗、5 的倍數仍在處理、偶數失敗、其餘成功),22 筆夠舊的卡單全部被掃到一次;第二輪只會再碰到還沒有結果的那幾筆。實際上線時,再為掃描器加上指標:每一輪掃了幾筆、解決幾筆、查詢失敗幾筆、最舊的卡單有多久,這些數字就是前面「卡住的付款」告警的來源。

重點整理

  • 重複交易單可以從八層冒出來:按鈕、用戶端、Gateway 與服務重試、訂單服務、支付服務、金流商、回呼與訊息重送,以及誘導使用者重付的介面。上層的防線減少次數、改善體驗,真正保證只扣一次的是資料庫約束與狀態機。
  • 冪等鍵跟「這一次付款意圖」綁在一起,在結帳頁載入時產生一次,所有重試都帶同一把;訂單以 (user_id, checkout_token) 唯一。
  • 中間層只對冪等的請求重試,而且只在一層重試;付款路徑的中間層最好完全不重試。
  • 支付服務每個嘗試有唯一的商店訂單編號,同一次嘗試的重送沿用同一個編號;結果不明時先查再重試,確定失敗才換新編號。
  • 結果不明時對使用者顯示「確認中」,不是「失敗」。
  • 大部分支付事故不會讓服務當掉,要靠業務指標告警:成功率、卡單、重複扣款、回呼延遲、驗簽失敗、金額檢查與對帳差異。
  • 事前準備好開關(停止付款、切換金流商、暫停自動化)、每個金流商各自的逾時與熔斷、重試預算、限流、金絲雀與金額合理性檢查。
  • 事故處理的順序:偵測、宣告、止血、溝通、圈出範圍、向金流商確認狀態、冪等地修復、對帳與不究責的檢討。確認狀態之前不退款、不改狀態。
  • 卡單掃描器:固定時間界線、keyset 分頁、限速、條件式轉換、查不到不改、可隨時中斷與重跑。
檢查項目做到了嗎
結帳頁載入時產生一次 checkout_token☐
所有重試帶同一把冪等鍵,沒有鍵的付款請求拒絕☐
付款路徑的 Gateway、負載平衡器不自動重試☐
訂單有 (user_id, checkout_token) 唯一約束☐
每個嘗試有唯一的商店訂單編號,重送沿用☐
結果不明先查詢,確定失敗才建立新嘗試☐
回呼與事件消費者都以 ID 去重☐
結果不明時畫面顯示「確認中」☐
停止付款、切換金流商、暫停自動化的開關可用且演練過☐
送出扣款前的金額合理性檢查☐
業務指標告警與重複扣款偵測查詢☐
卡單掃描器與它的指標☐
事故手冊:確認狀態之前不退款☐

下一篇

這篇的事故處理,最後都收斂到同一件事:事故期間我們自己的資料不可信,要以金流商那邊的紀錄為準,逐筆比對才知道哪些付款卡住、哪些重複、哪些我們根本沒記到。掃描器處理的是「我們知道卡住」的那幾筆,而對帳要找的是「我們不知道錯了」的那些。下一篇〈對帳:金流對帳單怎麼對才可靠〉把對帳從頭做一遍:怎麼取得對帳單、怎麼依交易編號配對、怎麼處理日界與手續費,以及差異怎麼追到結案。