Go fmt.Appendf 怎样保留错误信息

如果你的目标是把错误原因追加到一段字节缓冲中，fmt.Appendf 可以保留错误的可读文本；如果你的目标是让上层继续用 errors.Is 或 errors.As 找到原始错误，就不能只依赖 Appendf。它的返回值是更新后的 []byte，没有 error 返回值，也不会像 fmt.Errorf 那样建立错误包装链。

记住一句话：Appendf 负责“把错误写进字节序列”，fmt.Errorf("...: %w", err) 负责“把错误保留在错误链里”。两者可以配合，但职责不能混淆。

先看 Appendf 的返回值：它只追加字节

fmt.Appendf 的签名是 func Appendf(b []byte, format string, a ...any) []byte。它先按照格式动词生成文本，再把文本追加到传入的切片，并返回更新后的切片。调用者必须接住返回值，因为追加可能触发扩容，也可能复用原有容量。

package main

import "fmt"

func main() {
	buf := []byte("request failed: ")
	errText := "timeout"

	// Appendf 返回的是追加后的切片，赋回 buf 才能拿到可能扩容后的结果。
	buf = fmt.Appendf(buf, "cause=%s", errText)
	fmt.Println(string(buf))
}

这段代码得到的是一串字节，例如 request failed: cause=timeout。它没有失败分支：格式化过程本身不会把一个业务错误重新作为返回值交给调用者。这里的“保留”指错误文本被写进了缓冲区，而不是保留了错误对象的身份。

需要展示错误文本时用 %v 或 %s

当缓冲区用于日志行、协议响应或诊断消息时，通常只需要给读者展示错误文本。此时把 error 作为格式参数传给 %v，或者显式传入 err.Error() 配合 %s，都能得到可读信息。

package main

import (
	"errors"
	"fmt"
)

func main() {
	baseErr := errors.New("数据库连接超时")
	buf := []byte("operation failed: ")

	// %v 调用 error 的文本表示，适合把原因写入日志或响应缓冲。
	buf = fmt.Appendf(buf, "%v", baseErr)
	fmt.Println(string(buf))
}

如果错误实现了自定义的 Format 方法，格式化结果还可能遵循它的格式化规则。因此，面向展示的缓冲区应把它当成最终文本处理，不要再假设里面仍然能取回原来的错误对象。

需要保留错误链时改用 fmt.Errorf

如果上层要判断“是不是超时”、提取某个自定义错误类型，或者继续把根因交给调用者，就要保留错误链。正确做法是先用 fmt.Errorf 和 %w 包装原始错误，再把包装错误的文本按需追加到缓冲区。

package main

import (
	"errors"
	"fmt"
)

var ErrTimeout = errors.New("数据库连接超时")

func load() error {
	// %w 建立错误链，让调用方仍能用 errors.Is 识别根因。
	return fmt.Errorf("读取用户资料失败: %w", ErrTimeout)
}

func main() {
	err := load()
	buf := fmt.Appendf(nil, "message=%v", err)
	fmt.Println(string(buf))

	// 展示文本和错误链是两条独立信息，判断时仍使用原始 err。
	fmt.Println(errors.Is(err, ErrTimeout))
}

不要把 fmt.Appendf(nil, "...: %w", err) 当成错误包装。Appendf 的结果是 []byte，即便输出中出现了类似格式文本，也不会返回一个带 Unwrap 方法的错误值。需要错误链时，先构造 err，最后才把它格式化成展示文本。

区分格式化成功与业务操作成功

Appendf 返回一个切片，所以它适合在“准备一条消息”的阶段使用。它不代表网络发送成功、文件写入成功，也不代表业务动作已经成功。真正的 I/O 错误应由对应的 io.Writer、文件或网络 API 返回。

package main

import (
	"fmt"
	"io"
)

func writeMessage(w io.Writer, err error) error {
	buf := fmt.Appendf(nil, "operation failed: %v", err)

	// Appendf 只完成内存中的格式化，写入失败仍要检查 Writer 的返回值。
	_, writeErr := w.Write(buf)
	if writeErr != nil {
		return fmt.Errorf("写入错误消息失败: %w", writeErr)
	}
	return nil
}

这里有两层错误：业务原因是参数 err，写消息时出现的 I/O 问题是 writeErr。如果只保存 string(buf)，就会丢掉后者；如果把两者都需要追踪，应分别保留错误变量，或在返回时用 fmt.Errorf 组合出明确的错误链。

常见误区与选择清单

还有一个容易忽略的细节：调用 Appendf 后要使用它返回的新切片。即使当前容量足够、底层数组没有变化，忽略返回值也会让后续代码继续使用旧的长度，表现为“错误信息没有追加”。

相关问题

fmt.Appendf 和 fmt.Sprintf 应该怎么选？

已有 []byte 缓冲并希望直接追加时用 Appendf；需要一个独立字符串时用 Sprintf。两者都只产生格式化结果，不会替你建立错误链。

为什么不用 err.Error() 直接拼接？

可以这样做，但 %v 更容易统一处理实现了格式化接口的错误，也能让格式模板保持集中。若你明确只需要基础错误字符串，err.Error() 配合 %s 也可以。

错误文本已经写入缓冲后还能用 errors.Is 吗？

不能从字节缓冲反推出原始错误。请在格式化前保留 error 变量，并在业务判断处使用 errors.Is 或 errors.As。