Go 怎样把 JSON 缩进写入已有缓冲区

我在整理接口日志时经常遇到一个小问题：JSON 已经是 []byte，但输出区域不是一个新的返回值，而是一个正在拼接的 bytes.Buffer。这时不需要先反序列化成结构体，再重新编码。Go 标准库的 json.Indent 可以直接把 JSON 的缩进形式追加到已有缓冲区。

最小写法是 json.Indent(&dst, src, "", " ")。其中 dst 是目标缓冲区，src 是原始 JSON 字节，第三个参数控制每层前缀，第四个参数控制每层缩进。下面按“目标和边界—流程—复用—嵌入—误区”的顺序整理一遍。

一、先明确 json.Indent 的目标：格式化，而不是重新建模

json.Indent 的签名是 func Indent(dst *bytes.Buffer, src []byte, prefix, indent string) error。它接收已经存在的 JSON 字节，把对象或数组的层级换成更易读的换行和缩进，然后追加到 dst。它不会把 JSON 转成 Go 结构体，也不会替你清空目标缓冲区。

这个边界决定了它适合三类工作：给已有 JSON 增加可读格式、把格式化结果拼接到日志或报告中、在循环中复用一个缓冲区。若手里是 Go 值而不是 JSON 字节，应优先考虑 json.MarshalIndent；若只是想把原始 JSON 放进一个更大的文本容器，json.Indent 更直接。

二、完整工作流：输入、缓冲区、参数和检查点

我通常把这件事拆成四个检查点。第一，确认输入是完整 JSON，而不是只截取了一段日志；第二，决定目标缓冲区是全新使用还是复用；第三，区分 prefix 与 indent；第四，始终处理返回的错误。

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
)

// formatJSONInto 清空并复用目标缓冲区，把原始 JSON 格式化后写入其中。
func formatJSONInto(dst *bytes.Buffer, src []byte) error {
	// Reset 保留底层容量，避免上一次内容残留在本次结果中。
	dst.Reset()

	// 空前缀表示不额外添加标记，两个空格表示每层缩进宽度。
	if err := json.Indent(dst, src, "", "  "); err != nil {
		// 用上下文包装错误，调用方仍可通过 errors.Is/As 继续判断。
		return fmt.Errorf("格式化 JSON: %w", err)
	}
	return nil
}

func main() {
	src := []byte(`{"service":"api","retry":{"max":3}}`)
	var dst bytes.Buffer

	if err := formatJSONInto(&dst, src); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(dst.String())
}

这个流程的关键不是代码量，而是边界清晰：Reset 只负责清掉旧内容，json.Indent 只负责把合法 JSON 以缩进形式追加进去。缓冲区的容量可以继续复用，但上一次的字节不会混进新的结果。

三、把格式化 JSON 接到已有文本后面

如果目标缓冲区里已经有标题、日志前缀或外层文本，就不要先把它转成字符串再拼回去。直接写入已有文本，再调用 json.Indent 即可。需要注意的是，格式化结果的第一行会紧接在当前位置；prefix 主要影响后续换行后的层级。

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
)

func main() {
	src := []byte(`{"name":"Go","features":["buffer","json"]}`)
	var report bytes.Buffer

	// 先写入报告标题，JSON 将从当前游标位置继续追加。
	report.WriteString("payload:\n")

	// prefix 给换行后的 JSON 行增加统一标记，indent 控制嵌套层级。
	if err := json.Indent(&report, src, "  ", "  "); err != nil {
		fmt.Printf("无法格式化 payload: %v\\n", err)
		return
	}

	fmt.Print(report.String())
}

嵌入已有文本时，我会先确定读者看到的是“独立 JSON”还是“报告中的 JSON 片段”。如果它必须保持独立 JSON，就不要随意添加标题；如果它只是日志或 Markdown 片段，前缀可以用来标出层级，但要在正文中说明这已经不是单独可解析的 JSON 文档。

四、推荐的复用流程：一次创建，多次格式化

在批量处理多条 JSON 时，可以在循环外创建一个 bytes.Buffer，每轮开始调用 Reset。这样写的收益是减少短生命周期缓冲区的创建；代价是调用者必须保证每轮都清理旧内容，并且不能在下一轮开始后继续依赖上一次返回的字符串视图。

func formatMany(items [][]byte) ([]string, error) {
	var dst bytes.Buffer
	results := make([]string, 0, len(items))

	for index, src := range items {
		// 每一轮复用同一个 Buffer，但先清除上一条 JSON。
		dst.Reset()
		if err := json.Indent(&dst, src, "", "  "); err != nil {
			// 错误中带上序号，方便定位批处理中的坏输入。
			return nil, fmt.Errorf("第 %d 条 JSON 无效: %w", index, err)
		}
		// String 会复制出字符串结果，避免下一轮 Reset 影响已保存内容。
		results = append(results, dst.String())
	}
	return results, nil
}

这里有一个容易忽略的取舍：如果结果要长期保存，转成字符串或复制字节是稳妥的；如果结果只是马上写入网络、文件或下一个输出缓冲区，可以继续围绕同一个 bytes.Buffer 传递，减少中间对象。

五、常见误区与排查顺序

1. 把 json.Indent 当成清空操作。它是追加 API。目标 Buffer 需要新结果时先 Reset；需要保留已有文本时才让它从当前游标继续写。
2. 把 prefix 当成首行前缀。首行直接接在目标当前位置，prefix 主要用于换行后的行。若要让首行也有标签，应先手动写入标签。
3. 忽略错误。输入截断、引号未闭合或多余字符都可能使格式化失败。不要把失败后的 Buffer 当成完整 JSON 继续发送。
4. 为了缩进先 Unmarshal 再 Marshal。如果输入已经是 JSON 字节，这会增加结构体映射和重新编码成本，也可能改变数字或字段表示。只改变空白时，直接使用 json.Indent 更合适。
5. 把带报告前缀的内容当成 JSON。写入了 payload: 或日志标记后，整体文本就不再是一个独立 JSON 文档；这适合展示，不适合直接交给 JSON 解析器。

六、最后的速查表

相关问题

json.Indent 会修改原始 src 吗？

它把格式化结果写入目标 Buffer，调用方式不会要求你把缩进结果写回原始切片。需要长期保存结果时，保存目标 Buffer 的字符串或字节副本。

什么时候应该使用 json.MarshalIndent？

当输入是 Go 值，需要先进行 JSON 编码时使用它；当输入已经是 JSON 字节，只调整空白格式时，使用 json.Indent 更省步骤。

为什么复用 Buffer 后会出现上一条内容？

因为 json.Indent 会追加而不是清空。把 dst.Reset() 放到每一轮开始处，并确认没有在 Reset 后继续使用旧的缓冲区视图。