Go 常量文档工具怎样输出不丢精度的复数值

在做 Go AST、类型检查或常量文档生成时，复数常量经常需要同时展示“人能看懂的值”和“不会丢信息的值”。go/constant 的 Value 接口已经把这两个用途分开：String() 适合短小的阅读输出，ExactString() 才适合需要保留精度的文档、缓存或快照。复数值会分别格式化实部和虚部。

官方文档：https://pkg.go.dev/go/constant

如果输出结果要被后续程序再次解析、比较或写入文档，优先调用 ExactString()；只有面向人看的临时日志，才使用 String()。

先看清 String 和 ExactString 的职责

constant.Value 的数值种类包含整数、浮点数和复数。官方接口说明明确指出，String() 对数值允许返回近似结果；ExactString() 则返回精确的人类可读形式。因此，复数并没有一个额外的“复数专用精度开关”，关键在于它的实部、虚部各自采用哪种格式化方法。

尤其要注意：精确字符串不一定长得像十进制小数。浮点内部表示可能以十六进制浮点形式表达，这是为了准确描述当前值，而不是为了模拟源码里的十进制写法。

用实部和虚部组装一个复数值

构造复数时，建议先把输入保留为 constant.Value，再用 MakeImag 和 BinaryOp 组合。下面的示例故意使用较长的小数，让输出策略的差异更容易观察。

package main

import (
	"fmt"
	"go/constant"
	"go/token"
)

func main() {
	// 用源码字面量创建精确的有理数，避免一开始就落到 float64。
	realPart := constant.MakeFromLiteral("123456789.123456789", token.FLOAT, 0)
	imagPart := constant.MakeFromLiteral("0.000000000000000123456789", token.FLOAT, 0)

	// MakeImag 把虚部变成复数，再用加法合成 a + bi。
	value := constant.BinaryOp(realPart, token.ADD, constant.MakeImag(imagPart))

	fmt.Println("kind:", value.Kind())
	fmt.Println("short:", value.String())
	fmt.Println("exact:", value.ExactString())
}

这个示例的重点不是某一行固定输出，而是输出契约：short 允许为了可读性做近似，exact 保留当前 Value 的精确组成。真实文档工具应把 exact 作为稳定内容，把 short 当作辅助展示。

MakeFromLiteral 的最后一个参数必须是零；字面量非法时会得到 Unknown。这也是为什么文档生成器不要只拼接字符串，而要在生成阶段记录 Kind()。

为什么复数的精度要沿着两个分量一起看

复数的格式化本质上是“实部格式化 + 虚部格式化”。只要其中一个分量已经是浮点近似，整个复数的精确性就不能再按原始十进制字面量理解。反过来，如果两个分量仍保持精确表示，调用 ExactString() 就能把这份精度带到最终文本。

package main

import (
	"fmt"
	"go/constant"
)

func printParts(v constant.Value) {
	// 先拆分分量，便于单独记录精度和错误边界。
	re := constant.Real(v)
	im := constant.Imag(v)

	// Float64Val 返回数值和 exact 标志，false 不能被忽略。
	real64, realExact := constant.Float64Val(re)
	imag64, imagExact := constant.Float64Val(im)
	fmt.Printf("real=%v exact=%t\\n", real64, realExact)
	fmt.Printf("imag=%v exact=%t\\n", imag64, imagExact)

	// 文档文本仍然使用原 Value 的精确字符串，而不是拼 float64。
	fmt.Println("document:", v.ExactString())
}

func main() {
	// MakeFloat64 会把 Go 的 float64 值交给常量包，转换精度由输入值决定。
	v := constant.MakeImag(constant.MakeFloat64(0.1))
	printParts(v)
}

这里的 Float64Val 只是为了把值交给运行时数值计算；它的第二个返回值表示是否能精确表示。若目标是生成文档，直接保存 ExactString()，不要先转成 complex128 再格式化。

文档工具落地时的选择清单

• 需要稳定快照、跨版本比较或缓存键时，保存 Kind() 与 ExactString()。
• 只给开发者临时查看时，可以输出 String()，但不要把它当作可逆序列化格式。
• 要参与数值运算时，分别取 Real() 和 Imag()，检查 Float64Val 返回的精度标志。
• 遇到 Unknown 时，保留未知状态，不要把默认的零值写成有效复数。

最容易踩的坑是把“打印出来看起来一样”误当成“内部精度一样”。String() 的目标是人类可读，ExactString() 的目标才是准确表达；这两个目标不应由同一个字段承担。

常见问题

为什么我的复数输出出现十六进制形式？

这通常说明分量已经处于浮点表示，ExactString() 正在忠实描述它，而不是发生了新的丢精度。若必须保留十进制源码字面量，应在进入浮点转换前保存原始 AST 文本。

可以直接用 fmt.Sprintf 拼复数吗？

可以用于临时日志，但不适合作为常量文档的唯一来源。文档工具应优先记录 Value 的种类和 ExactString()，再按展示场景生成短格式。

总结

Go 常量文档工具要输出不丢精度的复数值，核心做法是保留 constant.Value，让实部和虚部都尽量停留在精确表示，并用 ExactString() 生成最终文本。String() 适合阅读，Float64Val 适合明确知道可能有损的运行时转换；把三者的职责分开，文档结果就不会被一次无意的浮点转换带偏。