Go语言写JSON格式化工具教程

本文深入讲解了如何用 Go 语言编写健壮、跨平台且生产就绪的 JSON 格式化命令行工具，强调以 json.MarshalIndent 为核心实现轻量可控的格式化，同时系统性规避常见陷阱：避免 fmt.Println 引入多余换行破坏管道兼容性，推荐 os.Stdout.Write 直接输出原始字节；通过 io.LimitReader 限制输入长度防 OOM，弃用 bufio.Scanner 改用 io.ReadAll 避免单行长 JSON 截断；精细区分 json.SyntaxError、io.ErrUnexpectedEOF 等错误类型并提供精准定位提示；并针对 Windows 下 stdin 文本模式导致的换行异常和卡顿问题，给出 syscall 层面的二进制模式修复方案——真正难点不在格式化逻辑本身，而在于边界处理、错误反馈与跨平台一致性，这些细节恰恰决定了工具能否在真实生产环境中稳定可靠运行。

用 json.MarshalIndent 做基础格式化，但别直接 print 到 stdout

命令行管道场景下，json.MarshalIndent 是最轻量、最可控的格式化方式。它不依赖外部工具，也不引入额外依赖，适合嵌入到小型 CLI 工具中。

常见错误是把格式化后字节直接 fmt.Println —— 这会在末尾多加一个换行，破坏管道兼容性（比如接 jq 或 grep 时出错）。

• 始终用 os.Stdout.Write() 或 fmt.Fprint(os.Stdout, ...) 输出原始字节
• 缩进字符推荐用两个空格：" "，避免 tab 导致某些老工具解析异常
• 如果输入可能含非 UTF-8 字节（如误传二进制），json.Unmarshal 会报 invalid character '' looking for beginning of value，需提前检查或忽略 BOM

处理 stdin 输入时必须设超时或限制长度，否则管道挂起

Go 默认读 os.Stdin 是阻塞的。当上游没关流（比如 curl -s URL | yourtool 中 curl 出错未退出），你的程序会永远等下去。

真实场景里，用户不会手动 Ctrl+D，得靠代码主动收口。

• 用 io.LimitReader(os.Stdin, 10*1024*1024) 限制最大读 10MB，防 OOM
• 别用 bufio.Scanner 默认行为——它按行切分，而 JSON 可能单行超长；改用 io.ReadAll + 长度检查
• 如果想支持“边读边格式化”（如大数组流式 prettify），得用 json.Decoder.Token() 手动遍历，但绝大多数 CLI 场景没必要

错误处理要区分 json.SyntaxError 和其他 panic 风险

用户扔过来的很可能不是合法 JSON：少逗号、多逗号、单引号、注释、YAML 混入……这些都会让 json.Unmarshal 失败，但错误类型不同，处理策略也不同。

• json.SyntaxError 含 Offset 字段，可定位到出错位置，建议输出类似 error at byte 123: invalid character ',' after object key
• io.ErrUnexpectedEOF 表示流提前结束，常见于网络传输中断，应提示 “incomplete JSON input” 而非泛泛的 “invalid JSON”
• 别 recover panic —— Go 的 json 包不会 panic，强行包一层反而掩盖真实错误
• 如果想兼容带注释的 JSON（如 VS Code 配置），得先用正则删注释（不推荐）或换用 github.com/tidwall/gjson 等库，但那就超出纯标准库范围了

Windows 下换行符和重定向需额外注意 os.Stdin 模式

在 PowerShell 或 cmd 中运行 echo {"a":1} | yourtool.exe，有时会卡住或读到奇怪字符。这不是 Go 的 bug，而是 Windows 控制台默认以文本模式打开 stdin，会把 \r\n 自动转成 \n，还可能缓存不刷新。

• 加一句 os.Stdin = os.NewFile(uintptr(syscall.Stdin), "/dev/stdin")（仅 Windows）强制二进制模式，但需 import "syscall"
• 更稳妥做法：用 golang.org/x/sys/windows 调用 SetConsoleMode 关闭 ENABLE_LINE_INPUT
• 测试时优先用 type file.json | yourtool.exe 而非 echo，避免 shell 层面的转义干扰

管道处理真正麻烦的从来不是格式化本身，而是输入边界模糊、错误反馈太笼统、跨平台行为不一致——这些点不提前压住，上线后第一反应往往是“怎么在客户机器上就不行”。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于Golang的相关知识，也可关注golang学习网公众号。