如何在 Go 模板生成代码时自动格式化输出（而非模板本身）

在日常使用 go:generate 配合 Go 模板生成代码时，很多人会踩到一个不大不小的坑：试图用 gofmt 直接格式化那个带着 {{...}} 花括号的模板文件。结果是，灰溜溜地收到一堆报错。

其实，这并非一个疏漏，而是一个设计上的必然。Go 模板（无论是 .tmpl 文件还是内联模板）本质上是一种混合文本——Go 语法和模板指令（比如 {{.Field}}、{{range .Items}}）缠在一起，压根就不是合法的 Go 源文件。gofmt 解析失败，是预期行为，不是 bug。官方工具链没有提供“模板级的 gofmt 支持”，原因就在于此：格式化目标，应该是最终生成的 Go 代码，而不是中间环节的模板本身。

那么，正确的做法是什么？很简单：在代码生成逻辑中，嵌入一个格式化步骤。下面是一个典型的、健壮的生成器示例，值得收藏：

package main

import (
    "bytes"
    "fmt"
    "go/format"
    "os"
    "text/template"
)

func generateModel(w io.Writer, data interface{}) error {
    t := template.Must(template.New("model").Parse(`// Code generated by go:generate; DO NOT EDIT.
package model

type {{.Name}} struct {
{{- range .Fields}}
    {{.Name}} {{.Type}} ` + "`json:\"{{.JSONTag}}\"`" + `
{{- end}}
}`))

    var buf bytes.Buffer
    if err := t.Execute(&buf, data); err != nil {
        return fmt.Errorf("executing template: %w", err)
    }

    // 这一步是关键：对生成的纯 Go 代码字节流进行 gofmt 格式化
    formatted, err := format.Source(buf.Bytes())
    if err != nil {
        return fmt.Errorf("formatting generated code: %w", err)
    }

    _, err = w.Write(formatted)
    return err
}

这个方案有几个关键点，值得展开说说：

• 首先，用 bytes.Buffer 捕获模板执行结果，这时的内容就是纯正的 Go 源码了。
• 然后，调用 go/format.Source() 处理这个 []byte。这个函数的核心逻辑，和你在命令行里敲 gofmt -w 是等价的。
• 错误处理不能敷衍。格式化失败，通常意味着生成逻辑产出了非法的 Go 语法（比如括号不匹配、字符串未闭合），这时候应该立即回头检查模板或数据，而不是把问题藏着掖着。
• 还有一个好消息：go/format 是标准库的一部分，不需要额外引入任何第三方依赖。Go 命令本身也是基于这个包来工作的。

当然，还有一些细节需要注意。首先，千万别在模板里动什么“手动缩进 {{if}} 块”之类的心思，试图去迎合 gofmt 的可读性。这种做法只会让模板变得难以维护，而且极易出错。其次，如果生成的内容涉及多个文件，建议为每个文件单独执行 format.Source，避免跨文件格式造成污染。最后，在 CI 流程里，可以加一个校验步骤：生成代码后，跑一遍 go fmt ./... 并对比是否有变更，确保格式化逻辑始终在生效。

总结一下，优雅的代码生成，其实就两件事：正确的模板设计，加上执行后即时格式化。把 gofmt 留给真正的 Go 源码，既符合工具链的设计哲学，也保证了最终产出的质量与可维护性。