Go x/text/currency ParseISO 怎样识别三字母货币代码

我在整理多币种订单时，最先遇到的不是金额计算，而是接口里的 currency 字段经常只有一个三字母字符串。Go 的 golang.org/x/text/currency 已经提供了 ParseISO，它会把 ISO 4217 货币代码解析成 currency.Unit，同时把格式不对或不认识的代码交给调用方处理。

外部输入优先使用 currency.ParseISO(code)，同时检查返回的 error；它解析的是三字母 ISO 4217 代码，不是任意三字符标签。解析成功后再把 Unit 传给金额或格式化链路。

官方地址：https://pkg.go.dev/golang.org/x/text/currency

先看懂 ParseISO 返回的两个对象

ParseISO 的签名是 func ParseISO(s string) (Unit, error)。文档明确说明：输入必须是三字母 ISO 4217 货币代码；字符串格式不正确，或者代码不在已识别的货币集合中，都会返回错误。成功时得到的 Unit 可以用 String() 重新拿到 ISO 代码。

这意味着解析层不要把“长度为 3”当成成功条件，也不要只检查返回的 Unit。长度、字母形式和是否被库识别，应该统一交给 ParseISO，再由业务决定是拒绝请求、使用默认币种还是记录脏数据。

外部字段怎样解析才不会吞掉错误

下面这个小函数适合放在请求 DTO 到领域对象之间。它不猜测缺省币种，也不把错误改成一个看似有效的 Unit，这样调用方才能区分“客户端没传”和“传了一个未知代码”。

package money

import "golang.org/x/text/currency"

// ParseCurrency 只负责把外部代码转换成 Unit；业务层决定如何展示错误。
func ParseCurrency(code string) (currency.Unit, error) {
	// ParseISO 同时处理格式和识别结果，不能只按字符串长度做判断。
	unit, err := currency.ParseISO(code)
	if err != nil {
		// 保留原始错误，便于请求层记录字段和值的排查信息。
		return currency.XXX, err
	}
	return unit, nil
}

示例中用 currency.XXX 表示失败时的占位值，但真正的判定依据仍然是 err。业务代码应在错误分支结束当前处理，例如返回参数错误；不要继续调用 Amount 或格式化器，避免把解析失败延迟成更难定位的展示问题。

解析成功后，Unit 会连接哪些对象

Unit 是 ISO 4217 货币标识。成功解析后可以调用 String() 得到代码，也可以调用 Amount(value) 把数值和币种绑定成金额对象。文档还提供 currency.ISO 等格式化器，但“解析代码”和“按地区显示”是两件事：前者确认身份，后者才决定符号、语言和呈现方式。

我倾向于把这两个阶段拆开：入口只保存已经解析的 Unit，输出层根据用户语言选择 Formatter。这样同一个 CNY 不会因为接口入口的默认语言而被提前格式化成固定文本。

package main

import (
	"fmt"

	"golang.org/x/text/currency"
)

func main() {
	unit, err := currency.ParseISO("CNY")
	if err != nil {
		// 外部代码解析失败时立即停止，不把错误 Unit 继续传递。
		fmt.Println("货币代码无效:", err)
		return
	}

	amount := unit.Amount(128.50)
	// String 用于稳定的 ISO 代码；金额格式化应放到展示层处理。
	fmt.Println(unit.String(), amount.Currency().String())
}

ParseISO 与 MustParseISO 怎么选

MustParseISO 是同一类解析的强制版本：无法解析时会 panic。它适合程序启动时就固定写入、失败便应该让初始化暴露的常量；HTTP 请求、消息队列、CSV 或数据库字段都不属于这个场景，仍应使用 ParseISO 并返回可处理的错误。

最后再提醒一个容易混淆的点：ParseISO 只负责“这是什么币种”，不负责汇率换算、金额精度策略或地区化文案。金额计算、舍入与展示仍应按业务规则单独设计。

几个容易踩到的边界

• 不要只验证字符串长度为 3；长度正确的未知代码仍可能解析失败。
• 不要忽略 error 后继续使用返回值。
• 不要把 Unit.String() 当作本地化货币名称；它返回的是 ISO 代码。
• 不要因为需要显示货币符号，就在入口处提前固定语言和格式化方式。

相关问题

ParseISO 能直接解析人民币符号 ¥ 吗？

不能把符号当作它的输入契约。应先取得三字母 ISO 4217 代码，例如 CNY，再调用 ParseISO。

解析失败时应该返回哪个 Unit？

调用方应以 error 为准。示例中的 currency.XXX 只是失败分支的占位，不代表解析成功。

为什么不全部使用 MustParseISO？

因为外部数据错误是业务可处理的输入问题，panic 会扩大故障范围；只有硬编码且无法接受启动继续时，MustParseISO 才更合适。

把 ParseISO 放在输入边界，把 Unit 留给领域层，把格式化留给展示层，通常就能让多币种代码既容易排错，也不绑死后续的本地化策略。