Go x/text/number Percent 怎样格式化比例数值

我在做报表和接口展示时，遇到过一种很容易混淆的比例数据：数据库里保存的是 0.125，页面却需要显示成带百分号、符合语言习惯的文本。直接把数值乘以 100 再拼接 %，看起来能用，但小数位、舍入和不同语言的格式很快会散落在各个调用点。

Go 的 golang.org/x/text/number 提供了更清晰的边界：number.Percent(0.125) 表示 12.5%，1.0 表示 100%，再交给 message.Printer 结合语言标签输出。官方文档地址：https://pkg.go.dev/golang.org/x/text/number。

比例值先保持业务语义中的小数，再用 number.Percent 负责百分比尺度，用 Scale 或其他选项负责展示精度；不要在业务层提前乘 100。

先确认 Percent 的输入尺度

排查这类显示问题时，我通常先回到输入值，而不是先调字符串模板。Percent 接收的是比例值：0.125 会被解释成 12.5%，0.5 是 50%，1.0 是 100%。如果调用方已经把 0.125 乘成 12.5，再传给 Percent，结果就会被再次按百分比尺度放大。

最小调用可以这样写：

package main

import (
    "fmt"

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

func main() {
    ratio := 0.125

    // Percent 使用比例尺度：1.0 表示 100%，而不是 1%。
    formatted := number.Percent(ratio)
    fmt.Printf("%v\n", formatted)
}

这里的 Formatter 还没有指定某种语言的展示器，因此更适合把它看成“百分比格式对象”。真正面向用户输出时，再让 message.Printer 处理语言标签和本地化规则。

用 message.Printer 输出本地化百分比

number 的官方示例把格式对象交给 message.Printer：英文环境下，number.Percent(0.12) 可以输出 12%。这种组合的好处是，数值换算和文字呈现分开了：业务仍然保存比例小数，展示层决定语言和标点。

package main

import (
    "golang.org/x/text/language"
    "golang.org/x/text/message"
    "golang.org/x/text/number"
)

func main() {
    ratio := 0.125

    // Printer 负责语言环境，Percent 负责把比例解释为百分比。
    printer := message.NewPrinter(language.English)
    printer.Printf("完成度：%v\n", number.Percent(ratio))
}

如果产品需要中文或其他语言，只替换 language.Tag 的来源，不要为每种语言复制一套乘法和拼接逻辑。语言标签来自请求、用户设置还是服务端默认值，应由应用层明确决定。

用 Scale 和 Precision 控制显示精度

实际报表里，12.5% 和 12.50% 可能代表同一个数值，却有不同的版式要求。number.Scale(n) 同时设置最小和最大小数位，适合“固定显示 n 位”的场景。例如比例为 0.125 时，用 Scale(2) 可以保留两位小数。

package main

import (
    "golang.org/x/text/language"
    "golang.org/x/text/message"
    "golang.org/x/text/number"
)

func main() {
    printer := message.NewPrinter(language.English)

    // Scale(2) 表示百分比文本固定保留两位小数。
    printer.Println(number.Percent(0.125, number.Scale(2)))
}

如果需求是限制有效数字，而不是固定小数位，可以考虑 number.Precision(p)。若只想限制小数部分的最长长度，则使用 number.MaxFractionDigits(max)。这些选项描述的是“怎么显示”，不改变业务数值本身。

我在选择选项时会先问一句：产品要的是固定列宽、固定小数位，还是有效数字？固定列宽可以结合 FormatWidth 和 Pad；固定小数位优先用 Scale；有效数字才使用 Precision。不要把多个选项随意叠加后再凭感觉判断结果。

排查舍入和输入边界

百分比显示“不对”通常有三类原因。第一类是输入尺度错了：把 12.5 当成 0.125 的同义值传入。第二类是格式化舍入：显示两位小数时，末位可能因为舍入从 12.345 变为 12.35。第三类是浮点数来源本身带有误差，格式化器只能决定展示，不会替业务重新定义精确值。

输入范围也应该属于业务边界，而不是交给格式化器猜测。完成率通常限定在 0 到 1，增长率可能允许负数，份额则可能因为数据异常超过 1。是否拒绝、截断或展示异常值，需要由领域规则决定。

package main

import (
    "fmt"

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

func formatRatio(ratio float64) (number.Formatter, error) {
    // 这里只演示完成率的业务边界；增长率不要直接复用这条规则。
    if ratio  1 {
        return number.Formatter{}, fmt.Errorf("完成率超出范围: %v", ratio)
    }

    // Scale 只控制展示精度，不负责校验比例是否合理。
    return number.Percent(ratio, number.Scale(1)), nil
}

上面的返回值可以继续交给 message.Printer。如果项目对非法值采用降级显示，建议在这一层记录原始比例和业务字段，而不是把异常值静默改成 0% 或 100%。

封装稳定的比例格式化函数

当同一种百分比在列表、导出和通知中重复出现时，我会把输入校验、格式选项和语言标签集中到一个小函数里。这样调用方不会一会儿传 0.12，一会儿传 12，也不会出现列表保留两位而导出保留一位的隐性差异。

package report

import (
    "fmt"

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

func PercentText(ratio float64, tag language.Tag) (string, error) {
    // 该函数约定输入是 0 到 1 的完成率，并拒绝越界数据。
    if ratio  1 {
        return "", fmt.Errorf("ratio must be between 0 and 1: %v", ratio)
    }

    // 固定一位小数，避免不同调用点出现不同的展示精度。
    printer := message.NewPrinter(tag)
    return printer.Sprintf("%v", number.Percent(ratio, number.Scale(1))), nil
}

调用处只需要传入比例和语言标签，错误则由上层决定是返回接口错误、标记数据异常，还是使用专门的占位符。这个封装也方便补充表格测试：输入 0、0.125、1，以及一个越界值，分别检查输出和错误。

最后复查这几个容易混淆的点

常见问题

number.Percent(12.5) 会输出 12.5% 吗？

不会按“已经是百分数”理解。它把输入解释为比例，所以 12.5 会对应 1250% 的尺度。业务层应传入 0.125。

Scale(2) 会把原始比例改成两位小数吗？

不会。它只影响 Formatter 交给展示层的文本，数据库或内存中的原始比例仍保持不变。

Percent 能替我判断完成率是否合法吗？

不能。0 到 1 是否是合法范围取决于业务字段，应该在调用格式化器之前由业务代码决定。

什么时候用 Precision 而不是 Scale？

需要控制有效数字数量时用 Precision；需要固定小数位时用 Scale。两者服务的版式目标不同。

把比例值保持为业务小数、把百分号尺度交给 number.Percent、把语言交给 message.Printer，再根据版式选择 Scale 或 Precision，这条分工基本能覆盖报表和接口展示中的大多数场景。