Go x/text/number Percent 为什么把输入放大为百分比

先给结论：number.Percent 接收的是“比例”，不是已经乘过 100 的百分数。官方约定是 1.0 表示 100%，因此 0.12 显示为 12%。如果业务字段里保存的是 12，再直接交给 Percent，结果就会变成 1200%；这不是库把输入算错了，而是输入语义重复放大。

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

把百分比拆成两层：数据层保存 0 到 1 之间的比例，展示层用 number.Percent 把比例呈现为百分数。先确认字段契约，再决定是否调用这个格式化器。

• 正确输入：0.12 表示完成率为百分之十二。
• 正确显示：number.Percent(0.12) 的语义是 12%。
• 高风险输入：12.0 已经是百分数数值，再按比例解释就会得到 1200%。

先看结论：Percent 不是普通的乘法函数

排查“输入被放大”时，先不要改格式选项。Percent 的核心契约是把一个比例按百分比规则格式化；官方文档直接给出 number.Percent(0.12) 显示为 12% 的例子。也就是说，它的输入坐标系以 1 为完整值，而不是以 100 为完整值。

触发条件：数据库字段和接口字段用了不同单位

这类问题通常出现在数据流的交界处：数据库保存 0.12，接口为了方便前端改成了 12，渲染层却继续调用 number.Percent。另一个常见情况是同一个字段在导入时已经乘过 100，后来又被统一格式化。

先为字段写清楚单位，再决定是否格式化。内部统计、排序和阈值判断最好使用比例；面向人的文本才转换成百分比。不要因为页面上看见百分号，就把存储字段改成带百分号的字符串。

package main

import (
    "fmt"

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

func main() {
    // ratio 使用 0 到 1 的比例单位，便于统计、比较和存储。
    ratio := 0.12

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

    // 机器字段继续保留原始比例，避免展示文本反向污染接口数据。
    fmt.Printf("ratio=%.4f\n", ratio)
}

这个分层很重要：日志、JSON 字段、缓存键和数据库列应继续使用稳定的数值单位；页面文案、报表单元格和通知文本才使用格式化后的百分数。

修复动作：让输入契约只在一个边界转换

如果接口明确规定字段是百分数，例如返回 12 表示百分之十二，那么进入 Go 领域模型时应先统一成 0.12，之后所有统计与展示都围绕比例工作。反过来，如果领域模型已经是比例，就不要在格式化前再做一次除法或乘法。

// percentFromAPI 把外部的百分数数值转换成内部比例；只在入站边界做一次。
func percentFromAPI(value float64) float64 {
    return value / 100
}

// displayPercent 只负责展示，不再改变比例的数量级。
func displayPercent(printer *message.Printer, ratio float64) string {
    return printer.Sprintf("%v", number.Percent(ratio))
}

如果外部协议可能同时出现两种单位，不要靠数值大小猜测：0.12 和 12 都是合法浮点数。应在 DTO、字段名或协议文档中明确 ratio 与 percent，并在转换边界保留一次清晰的责任。

语言环境与选项：改变显示，不改变比例语义

number.Percent 返回的是格式化器，可以交给 message.Printer 输出。语言标签影响数字的本地化呈现；它不会把“完整值是 1.0”改成“完整值是 100”。因此，换语言环境不是修复重复放大的办法。

需要控制显示位数时，可以传入 number.MaxFractionDigits、number.MinFractionDigits 或 number.Scale 等选项。它们解决的是小数位和显示精度问题，不负责判断输入到底是比例还是百分数。

// ratio 仍然是比例；Scale 只把显示精度固定为两位小数。
ratio := 0.125
printer := message.NewPrinter(language.English)
printer.Printf("完成率：%v\n", number.Percent(ratio, number.Scale(2)))

// MaxFractionDigits 只限制最多显示几位小数，不能把 12 修正成 0.12。
printer.Printf("简写：%v\n", number.Percent(ratio, number.MaxFractionDigits(1)))

图中的 English、German 等分支表示呈现规则可能随语言变化；同一个比例仍然是同一个比例。协议签名、机器比较和聚合计算不要依赖本地化后的字符串。

根因复盘：为什么会出现 1200%

把问题缩小成一次输入检查就很清楚：number.Percent(12.0) 的调用者告诉格式化器“这里有一个等于 12 倍完整值的比例”，所以显示为 1200%。它没有上下文可以知道这个 12 原本来自“百分之十二”。

1. 追踪字段从数据库、接口到模板的单位变化，记录每个边界是 ratio 还是 percent。
2. 检查是否在 DTO 转换、业务计算和渲染函数中重复执行了 * 100 或 / 100。
3. 在变量名中保留单位，例如 completionRatio 与 completionPercent，不要都叫 value。
4. 只在最后一个面向人的输出边界调用 number.Percent，机器字段不要复用这段字符串。

如果数据来自多个系统，最稳妥的修复是把单位写进接口契约和测试样例：约定 0.12 的输入必须展示 12%，而 12 只有在先转换成 0.12 后才能进入展示层。

常见问题

为什么 number.Percent(0.12) 会显示 12%？

因为官方定义中 1.0 表示 100%，输入是比例单位，百分数只是展示单位。

我已经有 12 这个值，怎样显示成 12%？

先确认 12 的确表示“百分之十二”，再在入站边界转换成 0.12。不要直接把 12 传给 number.Percent。

Scale 会把 12.0 修正为 12% 吗？

不会。Scale 只控制小数位，输入单位仍由调用者负责。单位错了，应修复数据转换，而不是继续添加格式选项。

能不能把格式化后的 12% 存回数据库？

不建议。保留比例数值更适合计算、比较和跨语言使用；百分号字符串应留在展示边界。