This resume is also available in English.

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

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

Go 處理金額:整數分、decimal、幣別、四捨五入與分攤

Handling Money in Go: Minor Units, Decimals, Currencies, Rounding and Allocation

為什麼金額不能用 float64,怎麼用最小貨幣單位的 int64 加上幣別建立 Money 型別,處理不同小數位數、JSON、稅率與匯率的捨入、不掉一分錢的分攤,以及資料庫欄位與測試。

  • Go
  • Payments
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:先看清楚 float64 錯在哪裡
  3. 第 2 步:用最小貨幣單位的 int64 表示金額
  4. 第 3 步:幣別的小數位數與 ISO 4217
  5. 第 4 步:安全地解析與輸出——使用者輸入與 JSON
  6. 第 5 步:乘上稅率、折扣與匯率——用 math/big 精確計算並明確捨入
  7. 第 6 步:分攤——一分錢都不能多也不能少
  8. 第 7 步:什麼時候該用 decimal 函式庫
  9. 第 8 步:存進資料庫、算出訂單總額、與金流商比對
  10. 第 9 步:測試金額程式碼
  11. 常見陷阱
  12. 重點整理
  13. 下一篇

上一篇〈支付常見問題:重複扣款、回呼與對帳〉處理的是「錢有沒有被扣兩次」「回呼可不可信」「帳對不對得起來」。在那篇裡我們順手提了一句:金額一律用最小貨幣單位的整數存,絕對不要用浮點數。那句話背後其實有一整套學問:幣別的小數位數不一樣怎麼辦?稅率 5% 乘出來有零頭要怎麼捨入?一筆折扣要分攤到三個商品上,怎麼保證加回去剛好等於原本的折扣?這篇就把「在 Go 裡處理金額」從頭講到尾,最後把它接回訂單服務的 Order.Total。

這篇要解決什麼

金額是業務系統裡最不能出錯的資料,卻也是最容易「看起來沒問題」的資料。用 float64 存價格,測試時打幾筆 19.99、100 都正常;直到某天報表加總差了一分錢、某張訂單的稅額跟發票對不上、某次分期付款的三期加起來少一元,才開始追查。這類錯誤的麻煩在於:它不會讓程式當掉,只會默默地在帳上留下一個對不起來的差額,而且越晚發現越難追。

這篇會在 example.com/shop 裡建立一個 internal/money 套件,一步一步回答:

  • float64 為什麼不適合存金額,錯誤是從哪裡來的。
  • 怎麼用「最小貨幣單位的 int64+幣別」表示金額,並在相加、相減、乘以數量時擋下幣別混用與溢位。
  • 不同幣別的小數位數(ISO 4217 exponent)怎麼處理,新台幣這個特例又該怎麼看。
  • 使用者輸入與 JSON 裡的金額怎麼安全地解析與輸出。
  • 乘上稅率、折扣與匯率時,怎麼用 math/big 精確計算,並明確選擇捨入方式。
  • 怎麼分攤金額而不多一分、不少一分。
  • 什麼時候該改用 decimal 函式庫、資料庫欄位怎麼選、訂單服務怎麼算總額並與金流商比對、換匯怎麼留紀錄,以及金額程式碼該怎麼測。

第 1 步:先看清楚 float64 錯在哪裡

先跑一段程式,親眼看看浮點數算錢會發生什麼事:

package main

import "fmt"

func main() {
	// 1. 常數在編譯期用任意精度計算,所以這行是 true,容易讓人誤會
	fmt.Println(0.1+0.2 == 0.3)

	// 2. 一旦放進 float64 變數,就是執行期的二進位浮點數
	a, b := 0.1, 0.2
	fmt.Println(a+b == 0.3)
	fmt.Printf("%.17f\n", a+b)

	// 3. 一張訂單有一千筆 0.1 元的明細,加總起來
	var sum float64
	for i := 0; i < 1000; i++ {
		sum += 0.1
	}
	fmt.Println(sum == 100)
	fmt.Printf("%.15f\n", sum)

	// 4. 看起來沒問題的四捨五入
	price := 1.005
	fmt.Printf("%.2f\n", price)
	fmt.Printf("%.20f\n", price)

	// 5. 同樣的加總改用整數分
	var cents int64
	for i := 0; i < 1000; i++ {
		cents += 10 // 0.10 元 = 10 分
	}
	fmt.Println(cents == 10000, cents)
}

實際輸出:

true
false
0.30000000000000004
false
99.999999999998593
1.00
1.00499999999999989342
true 10000

第一行的 true 很容易誤導人。Go 的常數運算是在編譯期以任意精度完成的,0.1+0.2 == 0.3 兩邊都是「無型別常數」,比較的是精確的有理數,所以相等。但只要值進到 float64 變數,就變成執行期的二進位浮點數,第二行立刻變成 false,而 a+b 實際上是 0.30000000000000004。

原因用白話講是這樣:float64 用二進位來存小數,就像十進位沒辦法精確寫出三分之一(0.3333… 永遠寫不完),二進位也沒辦法精確寫出十分之一。0.1 在二進位是 0.0001100110011…,「0011」無限循環下去,float64 只有 52 個位元可以存有效數字,多出來的部分只好捨入。所以你以為存的是 0.1,其實存的是一個「最接近 0.1 的二進位分數」,差了大約 10 的負 17 次方。

單一筆差這麼一點點看不出來,但金額的特性就是會被加總:一千筆 0.1 元加起來不是 100,而是 99.999999999998593。如果之後有人用 sum == 100 判斷「是否付清」,或用 int(sum) 把它轉成整數,就會得到 99。第四個例子更陰險:1.005 實際存的是 1.00499999999999989342,所以「四捨五入到兩位」得到 1.00 而不是你預期的 1.01。這不是 fmt 的錯,而是那個數字本來就比 1.005 小一點點。

最後一段把同樣的加總改成以「分」為單位的整數,一千次加 10 分,結果剛好是 10000 分,沒有任何誤差。整數在 int64 的範圍內,加減乘都是精確的,這就是整套做法的基礎。

提示:浮點數本身沒有錯,它是為科學計算設計的:量測值本來就有誤差,重要的是相對精度與速度。金額則是「人為定義的離散值」,一分就是一分,需要的是精確,而不是近似。

第 2 步:用最小貨幣單位的 int64 表示金額

最小貨幣單位(minor unit)指的是一個幣別最小的計價單位:美元的最小單位是「分」(cent),1 美元等於 100 分;日圓沒有更小的單位,1 日圓就是最小單位。把金額存成「有幾個最小單位」的整數,19.99 美元就是 1999,1,000 日圓就是 1000。

但光有整數還不夠。1999 這個數字沒有告訴你它是美元、新台幣還是日圓,而把 1999 美分跟 1999 日圓相加,結果毫無意義。所以金額一定要跟幣別綁在一起,成為一個型別。這也是第 6 篇〈分層架構與依賴注入〉提過的原則:讓領域裡的概念有自己的型別,錯誤的用法在型別或建構函式這一層就被擋掉。

我們在 internal/money 定義 Money,並加上幾個最核心的操作:

// Package money 以「最小貨幣單位的整數」表示金額。
package money

import (
	"encoding/json"
	"errors"
	"fmt"
	"math"
	"math/bits"
	"strconv"
	"strings"
)

var (
	ErrCurrencyMismatch = errors.New("money: currency mismatch")
	ErrUnknownCurrency  = errors.New("money: unknown currency")
	ErrOverflow         = errors.New("money: overflow")
	ErrInvalidAmount    = errors.New("money: invalid amount")
)

// exponents 是 ISO 4217 的小數位數(minor unit)。
// TWD 在 ISO 4217 是 2,但多數金流只收整數元,轉換放在對接層處理。
var exponents = map[string]int{
	"TWD": 2, "USD": 2, "EUR": 2, "CNY": 2,
	"JPY": 0, "KRW": 0,
	"KWD": 3, "BHD": 3,
}

// Exponent 回傳幣別的小數位數。
func Exponent(currency string) (int, error) {
	e, ok := exponents[currency]
	if !ok {
		return 0, fmt.Errorf("%w: %q", ErrUnknownCurrency, currency)
	}
	return e, nil
}

// Money 是一筆金額:Amount 是最小貨幣單位(例如美元的「分」)。
type Money struct {
	Amount   int64
	Currency string
}

// New 建立金額並檢查幣別。
func New(amount int64, currency string) (Money, error) {
	if _, err := Exponent(currency); err != nil {
		return Money{}, err
	}
	return Money{Amount: amount, Currency: currency}, nil
}

// Add 相加;幣別不同或溢位都回傳錯誤。
func (m Money) Add(o Money) (Money, error) {
	if m.Currency != o.Currency {
		return Money{}, fmt.Errorf("%w: %s + %s", ErrCurrencyMismatch, m.Currency, o.Currency)
	}
	if (o.Amount > 0 && m.Amount > math.MaxInt64-o.Amount) ||
		(o.Amount < 0 && m.Amount < math.MinInt64-o.Amount) {
		return Money{}, ErrOverflow
	}
	return Money{Amount: m.Amount + o.Amount, Currency: m.Currency}, nil
}

// Sub 相減;規則同 Add。
func (m Money) Sub(o Money) (Money, error) {
	if o.Amount == math.MinInt64 {
		return Money{}, ErrOverflow
	}
	return m.Add(Money{Amount: -o.Amount, Currency: o.Currency})
}

// MulInt 乘上整數(例如數量),用 math/bits 偵測溢位。
func (m Money) MulInt(n int64) (Money, error) {
	if m.Amount == math.MinInt64 || n == math.MinInt64 {
		return Money{}, ErrOverflow
	}
	neg := (m.Amount < 0) != (n < 0)
	hi, lo := bits.Mul64(abs(m.Amount), abs(n))
	if hi != 0 || lo > math.MaxInt64 {
		return Money{}, ErrOverflow
	}
	v := int64(lo)
	if neg {
		v = -v
	}
	return Money{Amount: v, Currency: m.Currency}, nil
}

func abs(v int64) uint64 {
	if v < 0 {
		return uint64(-v)
	}
	return uint64(v)
}

// String 依幣別小數位數格式化,例如 USD 1999 → "19.99"。
func (m Money) String() string {
	e, err := Exponent(m.Currency)
	if err != nil {
		return strconv.FormatInt(m.Amount, 10) + " " + m.Currency
	}
	return formatAmount(m.Amount, e) + " " + m.Currency
}

func formatAmount(amount int64, exp int) string {
	s := strconv.FormatUint(abs(amount), 10)
	if exp > 0 {
		if len(s) <= exp {
			s = strings.Repeat("0", exp-len(s)+1) + s
		}
		s = s[:len(s)-exp] + "." + s[len(s)-exp:]
	}
	if amount < 0 {
		s = "-" + s
	}
	return s
}

// Parse 把使用者輸入的字串(例如 "19.99")轉成最小貨幣單位。
// 小數位數超過幣別允許的位數時直接拒絕,不偷偷四捨五入。
func Parse(s, currency string) (Money, error) {
	exp, err := Exponent(currency)
	if err != nil {
		return Money{}, err
	}
	bad := fmt.Errorf("%w: %q", ErrInvalidAmount, s)
	neg := strings.HasPrefix(s, "-")
	s = strings.TrimPrefix(s, "-")
	intPart, frac, hasDot := strings.Cut(s, ".")
	if intPart == "" || (hasDot && frac == "") || len(frac) > exp {
		return Money{}, bad
	}
	digits := intPart + frac + strings.Repeat("0", exp-len(frac))
	for _, c := range digits {
		if c < '0' || c > '9' {
			return Money{}, bad // 擋掉 "1e3"、"+5"、"1,000"、空白
		}
	}
	v, err := strconv.ParseInt(digits, 10, 64)
	if err != nil {
		return Money{}, ErrOverflow
	}
	if neg {
		v = -v
	}
	return Money{Amount: v, Currency: currency}, nil
}

type wire struct {
	Amount   string `json:"amount"`
	Currency string `json:"currency"`
}

// MarshalJSON 輸出 {"amount":"19.99","currency":"USD"},金額一律是字串。
func (m Money) MarshalJSON() ([]byte, error) {
	e, err := Exponent(m.Currency)
	if err != nil {
		return nil, err
	}
	return json.Marshal(wire{Amount: formatAmount(m.Amount, e), Currency: m.Currency})
}

// UnmarshalJSON 只接受字串金額;{"amount":19.99} 會因型別不符而失敗。
func (m *Money) UnmarshalJSON(b []byte) error {
	var w wire
	if err := json.Unmarshal(b, &w); err != nil {
		return err
	}
	v, err := Parse(w.Amount, w.Currency)
	if err != nil {
		return err
	}
	*m = v
	return nil
}

幾個設計重點:

  • 欄位是公開的,但運算都經過方法。 Money{Amount: 1999, Currency: "USD"} 在測試與資料庫掃描時很方便;真正會出錯的加減乘,則一律走 Add、Sub、MulInt,在那裡檢查幣別與溢位。
  • 幣別不同就回傳錯誤,而不是自動換匯。 換匯需要匯率、時間點與捨入方式,絕對不能在 Add 裡偷偷發生。要換匯就明確呼叫第 5 步的 Convert。
  • 溢位要檢查。 int64 的上限約是 9.22 × 10¹⁸,以「分」計算大約是九百兆美元,一般訂單碰不到;但金額常常被乘上數量、累加成報表、或被惡意輸入塞進極大值。Go 的整數溢位不會 panic,而是默默繞回負數,一張「負九百兆」的訂單比當掉還糟。Add 用明確的上下界判斷;MulInt 則用 math/bits.Mul64 算出 128 位元的乘積,高位不為零就代表超出範圍。
  • 錯誤用哨兵值包裝。 依照第 2 篇〈錯誤處理:包裝、哨兵、自訂型別〉的做法,呼叫端可以用 errors.Is(err, money.ErrCurrencyMismatch) 判斷,同時錯誤訊息裡帶著實際的幣別,方便除錯。
使用者輸入 "19.99" USD JSON 請求 金額是字串 資料庫 BIGINT+幣別 money.Money Amount int64 = 1999 Currency = "USD" Add/Sub:同幣別才行 MulInt:數量,查溢位 MulRat:比率+捨入 Format/JSON "19.99" Allocate 分攤不掉一分 錯誤:幣別不符、溢位、位數過多 一律回傳 error,不靜默修正 所有進出點 都先轉成 Money

圖:使用者輸入、JSON 與資料庫欄位進來時都先變成 Money;加減乘、比率與分攤都在型別內完成,出錯一律回傳 error,輸出時再格式化成字串。

提示:Sub 先擋掉 math.MinInt64 是因為它沒有對應的正數,-math.MinInt64 在二補數裡還是自己。這種邊界值是金額程式碼最常漏測的地方,第 9 步的測試會特別涵蓋。

第 3 步:幣別的小數位數與 ISO 4217

「最小貨幣單位是 1/100」只對部分幣別成立。國際標準 ISO 4217 為每個幣別定義了代碼(例如 USD、JPY)與小數位數(exponent,也常稱 minor unit),常見的如下:

幣別代碼ISO 4217 小數位數1 個主單位=幾個最小單位說明
美元USD2100最常見的情況
歐元EUR2100
人民幣CNY2100
新台幣TWD2100標準是 2,但實務上多以整數元計價,見下文
日圓JPY01沒有小數
韓圜KRW01沒有小數
科威特第納爾KWD31000三位小數
巴林第納爾BHD31000三位小數

Money 本身只存整數與幣別,「這個整數代表幾位小數」由 Exponent 查表決定。所以 Money{1999, "USD"} 是 19.99 美元,Money{1999, "JPY"} 是 1,999 日圓,Money{1999, "KWD"} 是 1.999 第納爾。這也是為什麼訂單裡一定要有幣別欄位:沒有幣別,整數就無法解讀。

新台幣需要特別說明。ISO 4217 給 TWD 的小數位數是 2,也就是標準上存在「角、分」;但日常交易與現金幾乎只用整數元,很多支付服務商的 API 也規定新台幣金額必須是整數元、不能有小數。同樣的狀況在其他幣別也存在:標準的小數位數,與某個支付服務商、某個國家的實務規定,不一定一致。

處理這種落差有兩種常見做法:

  1. 內部照 ISO 4217,在對接層換算。 系統內部 TWD 一律以 2 位小數(也就是「分」)存,Order.Total 是 80000 代表 800.00 元;送給規定整數元的金流商之前,在 payment 服務的對接層除以 100,並檢查能否整除,不能整除就拒絕,不偷偷捨入。這是本篇程式碼採用的做法,整個系列說的「Total 是以分為單位的 int64」也就一致了。
  2. 內部直接採用業務規定的小數位數。 如果整個系統只賣新台幣、而且確定永遠以整數元計價,也可以把 TWD 的小數位數設成 0。好處是少一次換算;代價是哪天要接受有小數的幣別,或要處理按比例計算後產生的零頭,就得回頭改資料。

不管選哪一種,關鍵是整個系統只能有一種解讀,而且對外的換算點只有一個。小數位數表最好集中在 internal/money,並在文件裡寫明採用的是哪一版、哪一種慣例。

提示:小數位數請以你串接的支付服務商規格為準。同一個幣別,不同支付服務商可能要求不同的格式(整數最小單位、帶小數點的字串、甚至只接受整數元),請逐一讀它們的 API 文件,並把換算寫成有測試的函式,不要散落在各處。

第 4 步:安全地解析與輸出——使用者輸入與 JSON

金額進入系統的地方通常是使用者輸入的表單、或 API 的 JSON。這兩處都不該經過 float64。前面的 Parse 直接把字串拆成整數部分與小數部分,補零到幣別的位數後用 strconv.ParseInt 轉成整數,全程沒有浮點數:

  • "19.9" 以 USD 解析,小數補成兩位 "90",得到 1990 分。
  • "19.999" 以 USD 解析,小數有三位,超過美元的兩位,直接拒絕。不要「幫使用者四捨五入」:多出來的位數可能代表使用者打錯、或前端算錯,靜默修正會讓錯誤延後到對帳時才出現。
  • "1e3"、"+5"、"1,000"、前後有空白,都會在逐字元檢查時被擋下。要支援千分位或全形數字,就在呼叫 Parse 之前由輸入層明確轉換,讓 Parse 保持嚴格。
  • 數字太大放不進 int64,ParseInt 會回傳錯誤,我們轉成 ErrOverflow。

JSON 的問題更隱晦。JSON 規格本身沒有限定數字精度,但絕大多數實作(包括瀏覽器的 JavaScript)會把 JSON 數字解析成雙精度浮點數。也就是說,就算你的 Go 程式用整數處理,只要 API 寫成 {"amount": 19.99},對方的程式很可能已經把它變成浮點數了。另外,JavaScript 的 Number 只能精確表示到 2⁵³,比 int64 的範圍小,太大的整數傳到前端也會失真。

所以 API 上的金額建議用字串,並且跟幣別一起傳:

{"amount": "19.99", "currency": "USD"}

我們在 Money 上實作 MarshalJSON 與 UnmarshalJSON:輸出時依小數位數格式化成字串;讀入時要求 amount 是字串,{"amount": 19.99} 會因為型別不符而直接失敗,再交給 Parse 做和表單同樣嚴格的檢查。

另一種常見的 API 設計是直接傳最小單位的整數字串,例如 {"amount_minor": "1999", "currency": "USD"},許多支付服務商就採用這種格式。兩種都可以,重點是同一個 API 內要一致,而且文件要寫清楚 amount 的單位。

提示:String() 只用於日誌與除錯。要顯示給使用者的金額格式(貨幣符號、千分位、小數點符號)會依語系而不同,例如「NT$1,234」或「1.234,56 €」,應該交給前端或專門的在地化套件處理,不要把顯示用的字串存進資料庫或拿來計算。

第 5 步:乘上稅率、折扣與匯率——用 math/big 精確計算並明確捨入

加減與乘以整數數量都是精確的;麻煩出現在乘上一個「比率」:5% 的營業稅、85 折、匯率 31.255。這些比率本身是小數,乘出來的結果常常不是整數個最小單位,一定得捨入。這裡要做對兩件事:

  1. 比率本身要精確。 不要寫 float64(amount) * 0.05,那又回到第 1 步的問題。用 math/big.Rat 從字串 "0.05" 建立精確的分數 5/100,或用整數表示比率(例如以「萬分之一」為單位的基點,500 代表 5%)。
  2. 捨入方式要明確選擇。 不同場合有不同規則,不能讓程式語言或函式庫幫你決定。

常見的捨入方式:

捨入方式程式中的名稱2.5 →3.5 →-2.5 →常見用途
四捨五入(一半遠離零)HalfUp34-3一般收據與稅額計算,許多法規採用
銀行家捨入(一半取偶數)HalfEven24-2大量累計的利息、匯率換算、統計;正負誤差互相抵消
無條件捨去(往零截斷)Down23-2「最多給這麼多」的情境,例如回饋點數、優惠上限
同一個「剛好一半」,三種捨入方式 -3 -2 -1 0 1 2 3 2.5 -2.5 模式 2.5 3.5 -2.5 常見用途 四捨五入 HalfUp 3 4 -3 收據、稅額(依法規) 銀行家 HalfEven 2 4 -2 大量累計、利息、統計 無條件捨去 Down 2 3 -2 優惠上限、不可多給 只有「剛好一半」時三者才分歧;2.6 一律變 3,2.4 一律變 2(Down 除外:2.6 變 2)

圖:只有遇到「剛好一半」時三種方式才會分歧;一般的 2.6、2.4 各方式結果相同(無條件捨去除外)。

為什麼需要銀行家捨入?四捨五入在遇到「剛好一半」時永遠往上進,如果你每天處理大量剛好落在一半的計算,整體結果就會系統性地偏高。銀行家捨入讓一半的情況一次往上、一次往下(取偶數),長期平均下來偏差趨近於零。但它不直覺,收據上的稅額若用銀行家捨入,可能跟顧客自己用計算機算的不一樣。所以原則是:跟著法規、合約或支付服務商的規格走,並把選擇寫進程式碼與文件,而不是「看哪個順手」。

下面的 MulRat 把金額乘上一個 big.Rat,先用整數除法得到往零截斷的商與餘數,再依捨入方式決定要不要進位;Convert 則在此之上處理換匯,並把匯率字串與捨入方式一起記錄下來(第 8 步會用到)。這份檔案也包含第 6 步的分攤:

package money

import (
	"errors"
	"fmt"
	"math"
	"math/big"
	"sort"
)

// Rounding 是捨入方式。
type Rounding int

const (
	HalfUp   Rounding = iota // 四捨五入:0.5 遠離零
	HalfEven                 // 銀行家捨入:0.5 取偶數
	Down                     // 無條件捨去:往零截斷
)

// MulRat 計算 m × r(r 是精確分數,例如 "0.05" 或 "1/3"),依 mode 捨入到最小單位。
func (m Money) MulRat(r *big.Rat, mode Rounding) (Money, error) {
	n := new(big.Int).Mul(big.NewInt(m.Amount), r.Num())
	q, rem := new(big.Int).QuoRem(n, r.Denom(), new(big.Int)) // q 往零截斷
	if rem.Sign() != 0 && mode != Down {
		twice := new(big.Int).Abs(rem)
		twice.Lsh(twice, 1) // 2|餘數| 與分母比,判斷是否過半
		c := twice.Cmp(r.Denom())
		if c > 0 || (c == 0 && (mode == HalfUp || q.Bit(0) == 1)) {
			q.Add(q, big.NewInt(int64(n.Sign()))) // 往遠離零的方向進一
		}
	}
	if !q.IsInt64() {
		return Money{}, ErrOverflow
	}
	return Money{Amount: q.Int64(), Currency: m.Currency}, nil
}

// Rate 把 "0.05"、"31.25" 這類字串轉成精確分數;不要從 float64 轉。
func Rate(s string) (*big.Rat, error) {
	r, ok := new(big.Rat).SetString(s)
	if !ok {
		return nil, fmt.Errorf("money: invalid rate %q", s)
	}
	return r, nil
}

// Allocate 依 weights 比例分攤 m,用最大餘數法:總和一定等於 m。
func (m Money) Allocate(weights []int64) ([]Money, error) {
	if m.Amount == math.MinInt64 {
		return nil, ErrOverflow
	}
	total := new(big.Int)
	for _, w := range weights {
		if w < 0 {
			return nil, errors.New("money: negative weight")
		}
		total.Add(total, big.NewInt(w))
	}
	if total.Sign() == 0 {
		return nil, errors.New("money: weights sum to zero")
	}
	sign := int64(1)
	amt := new(big.Int).SetInt64(m.Amount)
	if amt.Sign() < 0 { // 負數(例如退款)先取絕對值分,再補回負號
		sign = -1
		amt.Neg(amt)
	}
	out := make([]Money, len(weights))
	rems := make([]*big.Int, len(weights))
	left := new(big.Int).Set(amt)
	for i, w := range weights {
		q, r := new(big.Int).QuoRem(new(big.Int).Mul(amt, big.NewInt(w)), total, new(big.Int))
		out[i] = Money{Amount: q.Int64(), Currency: m.Currency}
		rems[i] = r
		left.Sub(left, q)
	}
	// 剩下的零頭(一定小於份數)一單位一單位發給餘數最大的;同分時前面的先拿
	order := make([]int, len(weights))
	for i := range order {
		order[i] = i
	}
	sort.SliceStable(order, func(a, b int) bool { return rems[order[a]].Cmp(rems[order[b]]) > 0 })
	for k := int64(0); k < left.Int64(); k++ {
		out[order[k]].Amount++
	}
	for i := range out {
		out[i].Amount *= sign
	}
	return out, nil
}

// Split 平均分成 n 份,例如 100 分成 3 份 → 34、33、33。
func (m Money) Split(n int) ([]Money, error) {
	if n <= 0 {
		return nil, errors.New("money: split into non-positive parts")
	}
	w := make([]int64, n)
	for i := range w {
		w[i] = 1
	}
	return m.Allocate(w)
}

// Conversion 記錄一次換匯用了哪個匯率、怎麼捨入,事後才對得起帳。
type Conversion struct {
	From     Money
	To       Money
	Rate     string // 原樣保存,例如 "31.2500":1 單位 From 幣別 = Rate 單位 To 幣別
	Rounding Rounding
}

// Convert 依「主單位」匯率換匯,並處理兩個幣別小數位數不同的情況。
func Convert(from Money, to, rate string, mode Rounding) (Conversion, error) {
	r, err := Rate(rate)
	if err != nil {
		return Conversion{}, err
	}
	ef, err := Exponent(from.Currency)
	if err != nil {
		return Conversion{}, err
	}
	et, err := Exponent(to)
	if err != nil {
		return Conversion{}, err
	}
	// from 的最小單位 × 匯率 × 10^(et-ef) = to 的最小單位
	scale := new(big.Rat).SetInt(new(big.Int).Exp(big.NewInt(10), big.NewInt(int64(abs(int64(et-ef)))), nil))
	if et < ef {
		scale.Inv(scale)
	}
	out, err := Money{Amount: from.Amount, Currency: to}.MulRat(new(big.Rat).Mul(r, scale), mode)
	if err != nil {
		return Conversion{}, err
	}
	return Conversion{From: from, To: out, Rate: rate, Rounding: mode}, nil
}

MulRat 的判斷邏輯值得仔細看:乘積除以分母後,餘數的兩倍若大於分母,就表示小數部分超過一半,一定要進位;若剛好等於分母,就是「剛好一半」,HalfUp 進位、HalfEven 只有在商是奇數時進位(進位後變偶數)。進位的方向跟著乘積的正負號,所以負數也對稱處理:-2.5 在 HalfUp 下變成 -3,而不是 -2。

用 big.Int 而不是 int64 做中間計算,是因為「金額 × 比率的分子」很容易超過 int64:一個很大的金額乘上分母是 10000 的比率,中間值就多了四個零。全部用 big.Int 算完,最後再用 IsInt64 確認結果放得回 int64。

Convert 處理換匯時還要注意小數位數不同:匯率通常以「主單位」報價(1 美元 = 31.255 新台幣),但我們存的是最小單位。從 USD(2 位)換到 JPY(0 位)時,要多乘上 10⁻²;從 JPY 換到 KWD(3 位)則要乘上 10³。把這個比例併進分數裡一次算完,只捨入一次,比「先換成主單位、捨入、再換回最小單位」少一次誤差。

提示:只要有捨入,就要決定在哪一層捨入、捨入幾次。例如稅額該「每一行各自算稅後捨入」還是「整張訂單小計算一次稅再捨入」,兩者的結果可能差一兩分。這是業務規則,要跟財務或法規確認,然後把它寫成一個函式,所有地方都呼叫它。

第 6 步:分攤——一分錢都不能多也不能少

分攤是金額處理裡最常被寫錯的地方。情境很多:100 元分三期付款、一張 100 元的折價券要分攤到三個不同價格的商品上(退貨時才知道每個商品實際折了多少)、運費要依重量分給幾個出貨單。

直覺的寫法是「每一份都算比例再四捨五入」:100 ÷ 3 = 33.33…,四捨五入成 33,三份加起來 99,少了一元。換個數字也可能多一元。只要每份各自捨入,總和就沒有保證。

正確的做法之一是最大餘數法(largest remainder method):

  1. 每一份先拿「比例金額的整數部分」,也就是無條件捨去的結果。
  2. 算出還剩多少零頭(原金額減掉所有整數部分),零頭一定小於份數。
  3. 把零頭一個最小單位、一個最小單位地,依「被捨去的餘數」由大到小發出去;餘數一樣時,用固定的規則(例如排在前面的先拿)決定,讓結果可重現。
100 元分給 3 人 每人理想值 33.33… 第一輪:每人先拿整數部分 33,共 99,剩 1 元零頭 甲:33 餘數 0.333… 乙:33 餘數 0.333… 丙:33 餘數 0.333… 第二輪:零頭依餘數由大到小一人一單位;同分時排前面的先拿 甲:34 拿到零頭 乙:33 丙:33 34 + 33 + 33 = 100:總和永遠等於原金額 直接各自四捨五入會得到 33+33+33=99,少了一元

圖:先每人發 33 元,剩下的 1 元給餘數最大的人;三人餘數相同時排在前面的先拿,總和永遠等於原金額。

上面 calc.go 裡的 Allocate 就是這個演算法:權重可以是任意非負整數(各行小計、重量、件數),中間值用 big.Int 避免溢位;負的金額(例如退款)先取絕對值分攤,再補回負號,讓正負對稱。Split(n) 則是「權重都是 1」的特例,Money{100, "TWD"}.Split(3) 得到 34、33、33。

折扣分攤的例子:一張訂單有三行,小計分別是 300、500、100 元(以分計為 30000、50000、10000),整張訂單折 100 元。用小計當權重分攤 10000 分:三行理想值是 3333.33…、5555.55…、1111.11… 分,先各取整數部分 3333、5555、1111,加起來 9999,剩 1 分給餘數最大的第二行(餘數 0.55…),得到 3333、5556、1111,總和剛好 10000。每一行折扣後的金額是 266.67、444.44、88.89 元,加起來剛好 800 元。

這個結果要存下來,而不是每次需要時重新計算。退貨時「這個商品實際付了多少」必須跟當初計算的一致;如果演算法或權重日後有調整,重新計算可能得到不同的數字。

提示:如果你的業務規定新台幣只能以整數元分攤,就以「元」為單位呼叫 Allocate(金額除以 100 後再分攤,結果再乘回 100),或在第 3 步採用內部 0 位小數的做法。演算法本身不變,變的只是「最小單位」是什麼。

第 7 步:什麼時候該用 decimal 函式庫

int64 最小單位加上 math/big 能涵蓋大部分電商與支付的需求,但有些情境用十進位小數(decimal)型別會更自然:

  • 需要比幣別更細的中間精度,例如單價是 0.0035 美元的 API 計費、以小數點後六位報價的匯率或手續費率,計算過程中不能先捨入到分。
  • 大量金融計算(利息、攤銷、投資組合),公式裡有很多乘除,用最小單位整數寫會很冗長。
  • 要與資料庫的 NUMERIC 欄位或其他語言的 decimal 型別互通。

Go 社群常見的選擇有 github.com/shopspring/decimal 與 github.com/cockroachdb/apd。前者 API 簡單;後者實作了通用十進位算術規範,可以透過 Context 設定精度與捨入方式,並回報不精確、溢位等狀況。下面是一段 shopspring/decimal 的寫法示意:

// 片段
import "github.com/shopspring/decimal"

// 單價 0.0035 美元的 API 呼叫 12,345 次,算完才捨入到分
unit := decimal.RequireFromString("0.0035") // 用字串建立,不用 NewFromFloat
calls := decimal.NewFromInt(12345)
raw := unit.Mul(calls) // 43.2075,中間值保留完整精度

halfUp := raw.Round(2)   // 43.21:一半遠離零
bank := raw.RoundBank(2) // 43.21:一半取偶數(這裡不是剛好一半,所以相同)
down := raw.Truncate(2)  // 43.2(即 43.20):往零截斷

// 轉回最小單位整數再存檔:43.21 → 4321 分
cents := halfUp.Shift(2).IntPart()
fmt.Println(raw, halfUp, bank, down, cents)

兩種做法的取捨:

面向int64 最小單位(+math/big)decimal 函式庫
精度固定為幣別的最小單位任意小數位數
效能與記憶體一般運算是原生整數,最快每個值都有內部大整數,較慢、會配置記憶體
依賴只用標準函式庫多一個第三方依賴
比較與雜湊可直接 ==、當 map 的鍵要呼叫 Equal;1.0 與 1.00 的內部表示可能不同
容易犯的錯忘記處理幣別小數位數忘記捨入到幣別位數就存檔;除法的預設精度
適合訂單、付款、退款、帳務餘額計費費率、利息、匯率等中間計算

常見的組合是:儲存與傳遞用最小單位整數,複雜的中間計算用 decimal,算完立刻依明確的捨入方式轉回最小單位。不管用哪一種,float64 都不該出現在金額的路徑上,包括「先轉成 float64 再建 decimal」這種寫法,例如 decimal.NewFromFloat(0.1),雖然函式庫會盡量還原,但輸入本身已經是近似值了,應該用字串或整數建立。

第 8 步:存進資料庫、算出訂單總額、與金流商比對

資料庫欄位。 在 PostgreSQL 裡,金額有兩種好選擇,以及幾個要避開的:

欄位型別存的是什麼建議
BIGINT最小單位的整數推薦:與 Go 的 int64 一對一,最簡單
NUMERIC(p, s)精確十進位,例如 NUMERIC(19,4)適合需要比最小單位更細的金額或費率
REAL/DOUBLE PRECISION/FLOAT二進位浮點數不要用,同第 1 步的問題
MONEYPostgreSQL 的貨幣型別不建議:小數位數與格式受資料庫語系設定影響,也不帶幣別

不管哪一種,幣別都要有自己的欄位,而且要有約束。訂單資料表可以這樣設計:

CREATE TABLE orders (
    id          TEXT PRIMARY KEY,
    user_id     TEXT        NOT NULL,
    currency    CHAR(3)     NOT NULL CHECK (currency ~ '^[A-Z]{3}$'),
    discount    BIGINT      NOT NULL DEFAULT 0 CHECK (discount >= 0),
    total       BIGINT      NOT NULL CHECK (total >= 0),  -- 最小貨幣單位
    status      TEXT        NOT NULL CHECK (status IN ('pending', 'paid', 'cancelled')),
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE order_items (
    order_id     TEXT   NOT NULL REFERENCES orders(id),
    line_no      INT    NOT NULL,
    sku          TEXT   NOT NULL,
    quantity     BIGINT NOT NULL CHECK (quantity > 0),
    unit_price   BIGINT NOT NULL CHECK (unit_price >= 0),
    line_total   BIGINT NOT NULL,  -- 分攤折扣後的金額,算好就存,不再重算
    PRIMARY KEY (order_id, line_no)
);

-- 換匯紀錄:換了多少、用哪個匯率、怎麼捨入
CREATE TABLE fx_conversions (
    id            BIGSERIAL PRIMARY KEY,
    order_id      TEXT        NOT NULL REFERENCES orders(id),
    from_amount   BIGINT      NOT NULL,
    from_currency CHAR(3)     NOT NULL,
    to_amount     BIGINT      NOT NULL,
    to_currency   CHAR(3)     NOT NULL,
    rate          NUMERIC(20,10) NOT NULL,
    rounding      TEXT        NOT NULL,
    rate_source   TEXT        NOT NULL,
    rated_at      TIMESTAMPTZ NOT NULL
);

如果用的是第 7 篇〈database/sql、交易與連線池〉的 database/sql,BIGINT 可以直接掃描進 int64;NUMERIC 則建議掃描成字串,再交給 money.Parse 或 decimal 函式庫,不要掃描進 float64。

訂單服務算總額。 訂單的總額一定由伺服器根據明細計算,不能相信用戶端送來的 total。下面把前面的工具組合起來:每一行先用 MulInt 算小計,折扣依小計比例用 Allocate 分攤,最後加總寫入 Order.Total。VerifyPaid 則是第 25 篇〈支付常見問題:重複扣款、回呼與對帳〉講的回呼與對帳時要做的檢查:

package order

import (
	"errors"
	"fmt"

	"example.com/check/internal/money"
)

type Item struct {
	SKU       string
	Quantity  int64
	UnitPrice int64 // 最小貨幣單位
}

type Order struct {
	ID       string
	UserID   string
	Items    []Item
	Currency string
	Discount int64 // 整張訂單的折扣,最小貨幣單位
	Total    int64 // 最小貨幣單位,整個系列沿用
	Status   string
}

// LineTotals 算出每一行折扣後的金額:折扣依各行小計比例分攤,總和保證等於小計減折扣。
func (o Order) LineTotals() ([]money.Money, error) {
	subtotals := make([]money.Money, len(o.Items))
	weights := make([]int64, len(o.Items))
	sum := money.Money{Currency: o.Currency}
	for i, it := range o.Items {
		if it.Quantity <= 0 || it.UnitPrice < 0 {
			return nil, fmt.Errorf("order: invalid item %q", it.SKU)
		}
		line, err := money.Money{Amount: it.UnitPrice, Currency: o.Currency}.MulInt(it.Quantity)
		if err != nil {
			return nil, err
		}
		subtotals[i], weights[i] = line, line.Amount
		if sum, err = sum.Add(line); err != nil {
			return nil, err
		}
	}
	if o.Discount < 0 || o.Discount > sum.Amount {
		return nil, errors.New("order: discount out of range")
	}
	if o.Discount == 0 {
		return subtotals, nil
	}
	shares, err := money.Money{Amount: o.Discount, Currency: o.Currency}.Allocate(weights)
	if err != nil {
		return nil, err
	}
	for i := range subtotals {
		if subtotals[i], err = subtotals[i].Sub(shares[i]); err != nil {
			return nil, err
		}
	}
	return subtotals, nil
}

// ComputeTotal 由明細算出 Total;寫入資料庫前呼叫,不相信用戶端送來的總額。
func (o *Order) ComputeTotal() error {
	lines, err := o.LineTotals()
	if err != nil {
		return err
	}
	total := money.Money{Currency: o.Currency}
	for _, l := range lines {
		if total, err = total.Add(l); err != nil {
			return err
		}
	}
	o.Total = total.Amount
	return nil
}

// VerifyPaid 比對金流回傳的金額與幣別;只要有一點不同就不能標成 paid。
func (o Order) VerifyPaid(paid money.Money) error {
	if paid.Currency != o.Currency || paid.Amount != o.Total {
		return fmt.Errorf("order %s: amount mismatch: want %d %s, got %d %s",
			o.ID, o.Total, o.Currency, paid.Amount, paid.Currency)
	}
	return nil
}

這段程式碼刻意讓所有金額都經過 money 套件:數量相乘查溢位、加總查幣別、折扣不能大於小計。LineTotals 的結果會存進 order_items.line_total,而 ComputeTotal 必須在建立訂單的同一個交易裡呼叫,讓 orders.total 與明細永遠一致。

與金流商比對。 回呼或對帳檔帶回的金額,要先在 payment 服務的對接層依規格換回系統內部的單位(例如把整數元乘以 100),再交給 VerifyPaid 比對金額與幣別。只要有任何不同,就不能把訂單標成 paid:可能是使用者付款時改了金額、對接層換算寫錯、或是一則偽造的回呼。正確的處理是保留原狀、寫日誌、發出告警,進入人工或自動的對帳流程。

order 服務 Total 80000 TWD payment 服務 依規格換單位 金流商 收 800(整數元) 回呼/對帳檔 回傳 800 比對金額 換回 80000 再比 相同 訂單標成 paid 不同 不改狀態,告警 換匯紀錄 匯率+捨入方式 單位換算只發生在 payment 的對接層;其他地方一律用同一套最小貨幣單位與幣別

圖:單位換算只發生在 payment 服務的對接層;回呼與對帳時換回同一單位比對,相同才標成 paid,換匯則另外記下匯率與捨入方式。

換匯要留紀錄。 當訂單幣別與付款幣別不同(例如商品以美元標價、顧客以新台幣付款),換算結果必須連同「用了哪個匯率、匯率從哪裡來、什麼時間的匯率、用哪種捨入方式」一起存下來,也就是上面 fx_conversions 表與 Conversion 結構的用途。匯率每分每秒都在變,事後只要少了任何一項,就無法重現當時的計算,對帳時差了幾分錢也說不清楚。匯率欄位以字串或 NUMERIC 原樣保存,不要轉成浮點數。

提示:退款要以「當初實際收到的金額與幣別」為準,而不是用今天的匯率重新換算。部分退款同樣用分攤後存下的 line_total 計算,才能保證全部退完時剛好等於原本收到的總額。

第 9 步:測試金額程式碼

金額的錯誤往往只在特定數值出現,所以測試要刻意去找邊界。依照第 8 篇〈測試:表格驅動、httptest、整合測試〉的表格驅動寫法,把正常值、邊界值與該被拒絕的輸入列在一起:

package money

import (
	"encoding/json"
	"errors"
	"math"
	"math/rand"
	"testing"
)

func TestParse(t *testing.T) {
	tests := []struct {
		in, cur string
		want    int64
		wantErr bool
	}{
		{"19.99", "USD", 1999, false},
		{"19.9", "USD", 1990, false},
		{"0.05", "USD", 5, false},
		{"-3.50", "USD", -350, false},
		{"1000", "JPY", 1000, false},
		{"1.234", "KWD", 1234, false},
		{"19.999", "USD", 0, true}, // 位數太多:拒絕,不偷偷捨入
		{"1.5", "JPY", 0, true},
		{"1e3", "USD", 0, true},
		{"1,000", "USD", 0, true},
		{" 5", "USD", 0, true},
		{"5.", "USD", 0, true},
		{"", "USD", 0, true},
		{"99999999999999999999", "USD", 0, true}, // 超過 int64
		{"1", "XXX", 0, true},
	}
	for _, tt := range tests {
		got, err := Parse(tt.in, tt.cur)
		if (err != nil) != tt.wantErr {
			t.Errorf("Parse(%q,%s) err = %v, wantErr %v", tt.in, tt.cur, err, tt.wantErr)
			continue
		}
		if err == nil && got.Amount != tt.want {
			t.Errorf("Parse(%q,%s) = %d, want %d", tt.in, tt.cur, got.Amount, tt.want)
		}
	}
}

func TestAddRejectsMixedCurrencyAndOverflow(t *testing.T) {
	usd, twd := Money{100, "USD"}, Money{100, "TWD"}
	if _, err := usd.Add(twd); !errors.Is(err, ErrCurrencyMismatch) {
		t.Errorf("want ErrCurrencyMismatch, got %v", err)
	}
	if _, err := (Money{math.MaxInt64, "USD"}).Add(Money{1, "USD"}); !errors.Is(err, ErrOverflow) {
		t.Errorf("want ErrOverflow, got %v", err)
	}
	if _, err := (Money{math.MaxInt64/2 + 1, "USD"}).MulInt(2); !errors.Is(err, ErrOverflow) {
		t.Errorf("want ErrOverflow, got %v", err)
	}
}

func TestMulRatRounding(t *testing.T) {
	half, _ := Rate("0.5")
	tests := []struct {
		amount int64
		mode   Rounding
		want   int64
	}{
		{5, HalfUp, 3}, {5, HalfEven, 2}, {5, Down, 2}, // 2.5
		{7, HalfUp, 4}, {7, HalfEven, 4}, {7, Down, 3}, // 3.5
		{-5, HalfUp, -3}, {-5, HalfEven, -2}, {-5, Down, -2}, // -2.5
	}
	for _, tt := range tests {
		got, err := Money{tt.amount, "USD"}.MulRat(half, tt.mode)
		if err != nil || got.Amount != tt.want {
			t.Errorf("%d×0.5 mode %d = %d (%v), want %d", tt.amount, tt.mode, got.Amount, err, tt.want)
		}
	}
}

func TestJSONUsesStrings(t *testing.T) {
	b, _ := json.Marshal(Money{1999, "USD"})
	if string(b) != `{"amount":"19.99","currency":"USD"}` {
		t.Errorf("got %s", b)
	}
	var m Money
	if err := json.Unmarshal([]byte(`{"amount":19.99,"currency":"USD"}`), &m); err == nil {
		t.Error("number amount should be rejected")
	}
	if err := json.Unmarshal([]byte(`{"amount":"-0.05","currency":"USD"}`), &m); err != nil || m.Amount != -5 {
		t.Errorf("got %v, %v", m, err)
	}
}

func TestConvertRecordsRate(t *testing.T) {
	// 10.00 USD,匯率 31.255,HalfUp → 312.55 TWD(TWD 依 ISO 為 2 位小數)
	c, err := Convert(Money{1000, "USD"}, "TWD", "31.255", HalfUp)
	if err != nil || c.To.Amount != 31255 || c.Rate != "31.255" {
		t.Errorf("got %+v, %v", c, err)
	}
	// 1,000 JPY → USD,匯率 0.0067 → 6.70 USD
	c, err = Convert(Money{1000, "JPY"}, "USD", "0.0067", HalfEven)
	if err != nil || c.To.Amount != 670 {
		t.Errorf("got %+v, %v", c, err)
	}
}

func TestSplit(t *testing.T) {
	parts, _ := Money{100, "TWD"}.Split(3)
	want := []int64{34, 33, 33}
	for i := range want {
		if parts[i].Amount != want[i] {
			t.Fatalf("Split(100,3) = %v, want %v", parts, want)
		}
	}
}

// 類似性質測試:隨機金額與權重,分攤結果總和一定等於原金額,且每份與理想值差距小於 1。
func TestAllocateSumsToTotal(t *testing.T) {
	rng := rand.New(rand.NewSource(1))
	for i := 0; i < 10000; i++ {
		amount := rng.Int63n(2_000_000) - 1_000_000
		weights := make([]int64, 1+rng.Intn(8))
		var wsum int64
		for j := range weights {
			weights[j] = rng.Int63n(1000)
			wsum += weights[j]
		}
		if wsum == 0 {
			continue
		}
		parts, err := Money{amount, "USD"}.Allocate(weights)
		if err != nil {
			t.Fatal(err)
		}
		var sum int64
		for j, p := range parts {
			sum += p.Amount
			ideal := float64(amount) * float64(weights[j]) / float64(wsum) // 測試裡只拿來比距離
			if d := float64(p.Amount) - ideal; d <= -1 || d >= 1 {
				t.Fatalf("part %d = %d, ideal %.3f", j, p.Amount, ideal)
			}
		}
		if sum != amount {
			t.Fatalf("Allocate(%d, %v) sums to %d", amount, weights, sum)
		}
	}
}

這組測試涵蓋了幾類重點:

  • 解析: 不同幣別的小數位數、負數、位數過多、科學記號、千分位、空白、超過 int64 的數字、未知幣別。每一個「應該失敗」的案例,都是一種線上真的會收到的輸入。
  • 運算: 幣別混用一定要錯;加法與乘法在 math.MaxInt64 附近要回報溢位,而不是繞回負數。
  • 捨入: 每種捨入方式都測「剛好一半」的正數、另一個奇偶不同的正數,以及負數。只測 2.6 這種不在一半的數字,三種方式都會通過,等於沒測。
  • JSON: 輸出是字串;數字型別的金額要被拒絕。
  • 換匯: 小數位數不同的兩個幣別互換,結果與匯率紀錄都要正確。
  • 分攤的性質: 最後一個測試不列舉固定答案,而是用固定種子產生一萬組隨機金額與權重,檢查兩個一定要成立的性質:各份總和等於原金額,以及每一份與理想比例的差距小於一個最小單位。這種「性質測試」能找到人想不到的組合,例如權重中有零、負金額、只有一份。固定種子讓失敗時可以重現;Go 內建的 fuzzing(go test -fuzz)也可以拿來做同樣的事。

在測試裡用 float64 計算「理想值」是可以的,因為它只用來判斷距離是否小於 1,不會流進產品程式碼。

提示:除了單元測試,對帳本身就是金額系統在正式環境的「測試」。每天把訂單總額、金流商入帳與退款加總比對,差額不是零就要有人看。

常見陷阱

  • 在任何一步用了 float64。 包括從 JSON 解析、strconv.ParseFloat 處理使用者輸入、資料庫欄位是 DOUBLE PRECISION、或 decimal.NewFromFloat。只要經過一次,精確度就回不來了。
  • 以為 0.1+0.2 == 0.3 是 true 就代表沒問題。 Go 的無型別常數在編譯期精確計算,放進變數後才是浮點數;拿常數做實驗會得到錯誤的結論。
  • 金額沒有帶幣別。 只有整數的金額在多幣別出現的那一天就會出事,而且資料無法補救。
  • 全系統對小數位數的解讀不一致。 例如訂單服務把 TWD 當 2 位、payment 服務當 0 位,金額就差了一百倍。換算點只能有一個,並且要有測試。
  • 整數溢位沒檢查。 Go 不會 panic,只會默默變成負數;尤其注意「金額 × 數量」與「金額 × 比率的分子」。
  • 捨入方式靠預設。 不同語言、函式庫、資料庫的預設捨入方式不一定相同;同一筆計算在前端、後端、報表算出不同結果,往往就是這個原因。
  • 每一份各自捨入再加總。 分期、分攤、拆單都要用最大餘數法或類似方法,保證總和不變。
  • 重新計算已經結帳的金額。 分攤結果、換匯結果、稅額都要在當下存下來;之後演算法或匯率變了,重算的結果就對不上。
  • 相信用戶端送來的總額。 總額永遠由伺服器依明細與當時的價格計算。
  • 回呼只看「成功」不看金額。 付款成功但金額或幣別不對,訂單不能標成已付款。

重點整理

  • float64 用二進位存小數,0.1 這類數字無法精確表示,加總、比較與捨入都會出錯;金額不要用浮點數。
  • 金額以最小貨幣單位的 int64 表示,並與幣別綁成 Money 型別;加減只允許同幣別,乘法與加總都要檢查溢位。
  • 幣別的小數位數依 ISO 4217:JPY、KRW 是 0,USD、EUR 是 2,KWD、BHD 是 3;TWD 標準是 2,但許多支付服務商只收整數元,換算集中在對接層,並以支付服務商的規格為準。
  • 使用者輸入與 JSON 的金額用字串,嚴格解析,位數過多直接拒絕;JSON 裡不放數字型別的金額。
  • 乘上稅率、折扣、匯率時,用 big.Rat 表示精確比率、big.Int 做中間計算,明確選擇四捨五入、銀行家捨入或無條件捨去。
  • 分攤用最大餘數法,總和永遠等於原金額,結果要存下來。
  • 需要更細的中間精度時用 decimal 函式庫,但儲存與傳遞仍建議回到最小單位整數。
  • 資料庫用 BIGINT 或 NUMERIC,加上幣別欄位與約束;不要用 FLOAT、REAL 或 MONEY。
  • 訂單總額由伺服器計算,回呼與對帳時比對金額與幣別;換匯記下匯率、來源、時間與捨入方式。
  • 測試要涵蓋邊界值、每種捨入的「剛好一半」,並用性質測試檢查分攤總和。

下一篇

到這裡,系統已經能正確地算錢、收錢與對帳。下一篇〈微服務的安全性:認證、授權、密鑰與供應鏈〉要談的是怎麼保護它:服務之間如何互相認證與授權、密鑰怎麼管理,以及依賴與映像檔的供應鏈安全。