Go x/text/currency Symbol 怎样按地区格式化货币符号

做多语言账单时，我最先踩到的坑不是金额计算，而是把 USD、$ 和“美国用户看到的显示方式”混成了一个概念。Go 的 golang.org/x/text/currency 可以把货币单位和金额绑定，再通过 currency.Symbol 交给本地化打印器按语言标签选择符号；它做的是格式化展示，不是汇率换算。

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

这篇只解决一个具体任务：已有一个货币金额时，怎样根据 zh-CN、en-US、ja-JP 等地区标签输出更自然的货币符号。当前包文档还特别提示，格式化能力仍在演进，因此生产代码要把显示策略和业务金额计算分开。

先把四个对象分开

currency.Unit 是 ISO 4217 货币单位，例如 currency.CNY 或 currency.USD；Unit.Amount 把一个数值和单位组成 currency.Amount；currency.Symbol 是使用常见符号的格式化器；语言标签则由 message.Printer 提供本地化上下文。它们不是同一个层次。

先创建可靠的货币单位

已知代码时可以直接使用包里的常量；代码来自接口或配置文件时，优先使用 ParseISO，把错误交给调用方处理。只有确定输入是内置配置、错误可以在启动阶段暴露时，才适合用会触发 panic 的 MustParseISO。

package main

import (
    "fmt"

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

func main() {
    // 外部代码可能来自配置或接口，因此保留解析错误，不把坏数据带到展示层。
    unit, err := currency.ParseISO("CNY")
    if err != nil {
        fmt.Println("货币代码无效:", err)
        return
    }

    // Amount 只绑定数值与单位，不负责汇率转换或账户记账。
    amount := unit.Amount(128.5)
    fmt.Println("货币单位:", amount.Currency())
}

如果货币单位已经由业务分支确定，也可以直接写 currency.CNY.Amount(128.5)。这样做的好处是金额对象携带了单位，后面的格式化器不需要猜测这个数字究竟是什么货币。

用 Symbol 配合 Printer 输出地区格式

关键写法是让 message.Printer 持有语言标签，再把 currency.Symbol(amount) 作为格式化参数传入。相同的金额和单位，在不同标签下可能出现不同的符号位置、数字分组或小数表现；具体显示应以当前依赖版本的本地化数据为准。

package main

import (
    "fmt"

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

func main() {
    amount := currency.CNY.Amount(128.5)
    tags := []language.Tag{
        language.MustParse("zh-CN"),
        language.MustParse("en-US"),
        language.MustParse("ja-JP"),
    }

    for _, tag := range tags {
        // Printer 提供地区上下文，Symbol 负责选择货币符号而不是 ISO 代码。
        printer := message.NewPrinter(tag)
        fmt.Println(tag, printer.Sprintf("%v", currency.Symbol(amount)))
    }
}

这里的 fmt.Println 只打印标签和结果，真正负责本地化格式的是 printer.Sprintf。不要先把金额拼成字符串再替换“元”或“$”，那会丢掉语言环境、数字分组和符号位置的信息。

地区推断要分清 FromTag 和 FromRegion

如果业务输入只有语言标签，可以用 currency.FromTag 取得最可能的货币单位；如果业务已经有明确的地区代码，可以使用 currency.FromRegion。两者都可能遇到无法推断的情况，所以不要把推断结果当作用户真实结算币种。

package main

import (
    "fmt"

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

func unitFromTag(tag language.Tag) currency.Unit {
    // FromTag 会结合标签中的地区或 u 扩展推断最可能的货币。
    unit, confidence := currency.FromTag(tag)
    if confidence == language.No {
        // 推断没有依据时返回 XXX，调用方可以改用 ISO 展示或要求用户选择。
        return currency.XXX
    }
    return unit
}

func main() {
    tag := language.MustParse("en-GB")
    inferred := unitFromTag(tag)
    fmt.Println("标签推断:", inferred)

    // 地区没有法定货币时，ok 为 false，不能继续假设一个默认单位。
    if unit, ok := currency.FromRegion(language.MustParse("AQ").Region()); ok {
        fmt.Println("地区货币:", unit)
    } else {
        fmt.Println("地区没有可用法定货币")
    }
}

需要注意，FromTag 返回的是“最可能”的货币以及置信度，并不等价于账户的结算配置。面向付款、退款、发票和对账时，货币单位应来自订单或账户数据；语言标签只能影响显示。

Symbol、ISO 和舍入策略怎么选

面向普通价格卡片、购物车和阅读型账单时，currency.Symbol 通常更适合，因为读者先看到的是熟悉的符号。跨地区对账、导出 CSV 或接口返回时，currency.ISO 更不容易产生歧义。金额精度则要结合 currency.Standard、currency.Cash 或 currency.Accounting 这类 Kind，不要用浮点格式化替代财务规则。

// 同一个金额可以按展示目的切换格式化器。
display := currency.Symbol(amount) // 面向用户的常见符号
audit := currency.ISO(amount)      // 面向接口或对账的 ISO 代码
_ = display
_ = audit

包文档把格式化能力标记为仍在开发中，因此建议锁定 golang.org/x/text 版本，并把展示结果作为 UI 层输出。金额比较、汇率换算、税费计算和最终入账仍然应该使用明确的业务模型。

我在项目里会保留的三条边界

1. 货币单位从订单、账户或配置读取，语言标签只决定展示上下文。
2. 格式化前保留 Amount，不要提前变成字符串。
3. 无法确定地区或货币时，优先回退到 ISO 或要求用户明确选择，不默默显示一个猜测的符号。

这样，Go x/text/currency 的 Symbol 就只承担它擅长的工作：把带单位的金额交给本地化上下文，生成更符合读者习惯的货币显示。它不会替你做汇率、记账或结算决策，这个边界保留下来，后续升级依赖时也更容易检查。

常见疑问

Symbol 会自动把 USD 换算成 CNY 吗？

不会。它只负责货币单位的格式化展示，不提供汇率换算。

为什么不用字符串替换直接加货币符号？

符号位置、数字分组和语言环境可能不同，直接替换会把本地化规则压扁成脆弱的字符串逻辑。

FromTag 能当作用户结算币种吗？

不能。它给出最可能的单位和置信度，结算币种应来自业务数据。