Go 處理金額:整數分、decimal、幣別、四捨五入與分攤
Handling Money in Go: Minor Units, Decimals, Currencies, Rounding and Allocation
為什麼金額不能用 float64,怎麼用最小貨幣單位的 int64 加上幣別建立 Money 型別,處理不同小數位數、JSON、稅率與匯率的捨入、不掉一分錢的分攤,以及資料庫欄位與測試。
這篇的步驟
上一篇〈支付常見問題:重複扣款、回呼與對帳〉處理的是「錢有沒有被扣兩次」「回呼可不可信」「帳對不對得起來」。在那篇裡我們順手提了一句:金額一律用最小貨幣單位的整數存,絕對不要用浮點數。那句話背後其實有一整套學問:幣別的小數位數不一樣怎麼辦?稅率 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)判斷,同時錯誤訊息裡帶著實際的幣別,方便除錯。
圖:使用者輸入、JSON 與資料庫欄位進來時都先變成 Money;加減乘、比率與分攤都在型別內完成,出錯一律回傳 error,輸出時再格式化成字串。
提示:
Sub先擋掉math.MinInt64是因為它沒有對應的正數,-math.MinInt64在二補數裡還是自己。這種邊界值是金額程式碼最常漏測的地方,第 9 步的測試會特別涵蓋。
第 3 步:幣別的小數位數與 ISO 4217
「最小貨幣單位是 1/100」只對部分幣別成立。國際標準 ISO 4217 為每個幣別定義了代碼(例如 USD、JPY)與小數位數(exponent,也常稱 minor unit),常見的如下:
| 幣別 | 代碼 | ISO 4217 小數位數 | 1 個主單位=幾個最小單位 | 說明 |
|---|---|---|---|---|
| 美元 | USD | 2 | 100 | 最常見的情況 |
| 歐元 | EUR | 2 | 100 | |
| 人民幣 | CNY | 2 | 100 | |
| 新台幣 | TWD | 2 | 100 | 標準是 2,但實務上多以整數元計價,見下文 |
| 日圓 | JPY | 0 | 1 | 沒有小數 |
| 韓圜 | KRW | 0 | 1 | 沒有小數 |
| 科威特第納爾 | KWD | 3 | 1000 | 三位小數 |
| 巴林第納爾 | BHD | 3 | 1000 | 三位小數 |
Money 本身只存整數與幣別,「這個整數代表幾位小數」由 Exponent 查表決定。所以 Money{1999, "USD"} 是 19.99 美元,Money{1999, "JPY"} 是 1,999 日圓,Money{1999, "KWD"} 是 1.999 第納爾。這也是為什麼訂單裡一定要有幣別欄位:沒有幣別,整數就無法解讀。
新台幣需要特別說明。ISO 4217 給 TWD 的小數位數是 2,也就是標準上存在「角、分」;但日常交易與現金幾乎只用整數元,很多支付服務商的 API 也規定新台幣金額必須是整數元、不能有小數。同樣的狀況在其他幣別也存在:標準的小數位數,與某個支付服務商、某個國家的實務規定,不一定一致。
處理這種落差有兩種常見做法:
- 內部照 ISO 4217,在對接層換算。 系統內部 TWD 一律以 2 位小數(也就是「分」)存,
Order.Total是 80000 代表 800.00 元;送給規定整數元的金流商之前,在 payment 服務的對接層除以 100,並檢查能否整除,不能整除就拒絕,不偷偷捨入。這是本篇程式碼採用的做法,整個系列說的「Total是以分為單位的int64」也就一致了。 - 內部直接採用業務規定的小數位數。 如果整個系統只賣新台幣、而且確定永遠以整數元計價,也可以把 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。這些比率本身是小數,乘出來的結果常常不是整數個最小單位,一定得捨入。這裡要做對兩件事:
- 比率本身要精確。 不要寫
float64(amount) * 0.05,那又回到第 1 步的問題。用math/big.Rat從字串"0.05"建立精確的分數 5/100,或用整數表示比率(例如以「萬分之一」為單位的基點,500 代表 5%)。 - 捨入方式要明確選擇。 不同場合有不同規則,不能讓程式語言或函式庫幫你決定。
常見的捨入方式:
| 捨入方式 | 程式中的名稱 | 2.5 → | 3.5 → | -2.5 → | 常見用途 |
|---|---|---|---|---|---|
| 四捨五入(一半遠離零) | HalfUp | 3 | 4 | -3 | 一般收據與稅額計算,許多法規採用 |
| 銀行家捨入(一半取偶數) | HalfEven | 2 | 4 | -2 | 大量累計的利息、匯率換算、統計;正負誤差互相抵消 |
| 無條件捨去(往零截斷) | Down | 2 | 3 | -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):
- 每一份先拿「比例金額的整數部分」,也就是無條件捨去的結果。
- 算出還剩多少零頭(原金額減掉所有整數部分),零頭一定小於份數。
- 把零頭一個最小單位、一個最小單位地,依「被捨去的餘數」由大到小發出去;餘數一樣時,用固定的規則(例如排在前面的先拿)決定,讓結果可重現。
圖:先每人發 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 步的問題 |
MONEY | PostgreSQL 的貨幣型別 | 不建議:小數位數與格式受資料庫語系設定影響,也不帶幣別 |
不管哪一種,幣別都要有自己的欄位,而且要有約束。訂單資料表可以這樣設計:
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:可能是使用者付款時改了金額、對接層換算寫錯、或是一則偽造的回呼。正確的處理是保留原狀、寫日誌、發出告警,進入人工或自動的對帳流程。
圖:單位換算只發生在 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。 - 訂單總額由伺服器計算,回呼與對帳時比對金額與幣別;換匯記下匯率、來源、時間與捨入方式。
- 測試要涵蓋邊界值、每種捨入的「剛好一半」,並用性質測試檢查分攤總和。
下一篇
到這裡,系統已經能正確地算錢、收錢與對帳。下一篇〈微服務的安全性:認證、授權、密鑰與供應鏈〉要談的是怎麼保護它:服務之間如何互相認證與授權、密鑰怎麼管理,以及依賴與映像檔的供應鏈安全。