Go format.Source 怎么格式化内存中的 Go 源码

内存中的 Go 源码可以直接交给 format.Source：它接收 []byte，语法正确时返回标准 gofmt 风格的新字节，语法错误时返回错误。最小调用就是 formatted, err := format.Source(src)，不需要先把内容写成临时文件。

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

项目目标：给内存代码生成器加格式化出口

假设我们正在做一个很小的代码生成器：程序拼出一段 Go 文件，格式可能松散，导入顺序也不稳定。目标不是制作完整模板系统，而是在“生成完成”和“写文件”之间加入一个可靠的格式化函数，并保留语法错误的上下文。

项目只需要标准库。创建一个目录并初始化模块：

# 创建示例项目并进入目录。
mkdir sourcefmt-demo
cd sourcefmt-demo

# 初始化独立 Go 模块，不需要安装第三方依赖。
go mod init example.com/sourcefmt-demo

核心数据始终停留在内存中：生成器产出 []byte，格式化器返回 []byte，调用方确认成功后再决定写文件、发送 HTTP 响应或继续做 AST 分析。

先把 Source 的输入输出边界说清楚

format.Source 会先解析输入，因此它不是简单的缩进美化器。括号缺失、字符串未闭合、关键字位置错误等语法问题会直接返回错误。官方接口允许三种常见输入形态：

• 带 package 声明的完整 Go 源文件；
• 一组 Go 声明，例如连续的 const、type、func；
• 一组 Go 语句，例如赋值、条件判断和函数调用。

因此，调用方要把格式化失败当成生成阶段失败，而不是继续保存半成品。一个实用封装应补充错误上下文，但不吞掉原始解析错误：

package sourcefmt

import (
    "fmt"
    "go/format"
)

// Format 接收内存中的 Go 源码，成功时返回 gofmt 风格的字节。
func Format(src []byte) ([]byte, error) {
    formatted, err := format.Source(src)
    if err != nil {
        // 包装错误以标明失败阶段，同时保留底层语法错误供 errors.Is/As 使用。
        return nil, fmt.Errorf("format generated Go source: %w", err)
    }
    return formatted, nil
}

返回错误时使用 nil，能迫使调用方区分成功结果和原始输入。若业务希望失败后展示原文，应单独持有 src，不要把原文伪装成“已格式化结果”。

实现一个完整的内存生成示例

下面的 main.go 故意把空格和导入顺序写得不整齐，然后调用刚才的封装。示例最终打印结果，但在真实生成器里可以把 formatted 交给 os.WriteFile、对象存储或网络响应。

package main

import (
    "fmt"
    "log"

    "example.com/sourcefmt-demo/sourcefmt"
)

func main() {
    // 这段源码在内存中生成，语法合法但缩进、空格和 imports 顺序不规范。
    src := []byte(`package greeting
import "strings"
import "fmt"
func Hello(name string)string{
return fmt.Sprintf("hello, %s",strings.TrimSpace(name))
}
`)

    formatted, err := sourcefmt.Format(src)
    if err != nil {
        // 生成结果不合法时立即停止，避免把坏代码覆盖到目标文件。
        log.Fatal(err)
    }

    // 这里仅展示返回字节；生产代码可在成功后再执行持久化。
    fmt.Print(string(formatted))
}

对完整文件，format.Source 会使用标准格式输出声明，并对 imports 做排序整理。它不会替你删除业务上“未使用的导入”；未使用导入属于类型检查或编译阶段的问题，不是纯语法格式化职责。

完整文件和局部源码的行为不同

这是集成时最容易漏掉的边界。完整文件能明确识别 package 和 import 区域，所以会排序导入。局部声明或语句为了适应嵌入场景，会保留原输入的首尾空白，并根据第一行实际代码的缩进调整结果；它不会重排局部 imports。

例如，下面的输入没有 package 声明，是两条局部语句。前导四个空格会继续影响格式化结果：

package main

import (
    "fmt"
    "go/format"
    "log"
)

func main() {
    // 局部语句故意带四个空格，Source 会把这层缩进应用到格式化结果。
    src := []byte("    total:=price*count\n    fmt.Println(total)\n")

    formatted, err := format.Source(src)
    if err != nil {
        // 片段同样必须语法正确，不能把解析失败当成普通文本处理。
        log.Fatal(err)
    }
    fmt.Print(string(formatted))
}

如果需求是格式化已经解析好的 ast.Node，可以改用 format.Node。它需要 io.Writer 和 token.FileSet，适合 AST 变换后的输出；直接处理原始内存字节时，Source 更简洁。

给小项目补上三个验收测试

格式化函数本身很短，真正值得测试的是调用契约：合法完整文件能格式化、局部语句能保留嵌入缩进、语法错误绝不能产生可保存结果。

package sourcefmt

import (
    "strings"
    "testing"
)

func TestFormatCompleteFile(t *testing.T) {
    // 完整文件应规范函数声明中的空格。
    src := []byte("package demo\nfunc Add(a,b int)int{return a+b}\n")
    got, err := Format(src)
    if err != nil {
        t.Fatalf("Format() error = %v", err)
    }
    if !strings.Contains(string(got), "func Add(a, b int) int") {
        t.Fatalf("unexpected formatted source:\n%s", got)
    }
}

func TestFormatPartialStatements(t *testing.T) {
    // 第一条语句前有四个空格，格式化后应保留嵌入层级。
    src := []byte("    value:=1+2\n    println(value)\n")
    got, err := Format(src)
    if err != nil {
        t.Fatalf("Format() error = %v", err)
    }
    if !strings.HasPrefix(string(got), "    value :=") {
        t.Fatalf("indent was not preserved: %q", got)
    }
}

func TestFormatRejectsInvalidSource(t *testing.T) {
    // 缺少右花括号，期望得到错误且不能得到可写入的结果。
    got, err := Format([]byte("package demo\nfunc Broken() {\n"))
    if err == nil {
        t.Fatal("Format() error = nil, want syntax error")
    }
    if got != nil {
        t.Fatalf("Format() result = %q, want nil", got)
    }
}

运行测试时，命令本身也保持简单：

# 运行当前模块全部测试，确认成功和失败分支都符合约定。
go test ./...

不要把测试写成完整字符串快照后永远不更新。Go 官方明确说明，源码格式会随版本变化；如果测试只关心关键行为，可以断言必要片段、解析成功或幂等性。若团队确实要求每个字节长期固定，就需要固定工具链版本。

接入生成流程时避免覆盖事故

格式化通常位于持久化之前。一个安全的生成顺序是：先在内存中完成拼接，调用 Format，确认无误后再一次性写入目标。对于已有文件，最好先写同目录临时文件并原子替换，避免进程中断留下半个文件。

formatted, err := sourcefmt.Format(generated)
if err != nil {
    // 保留 generated 供日志或调试使用，但不要覆盖现有目标文件。
    return fmt.Errorf("prepare generated file: %w", err)
}

// 只有格式化成功后才进入写入阶段；实际项目可再配合同目录临时文件和原子重命名。
if err := os.WriteFile(target, formatted, 0o644); err != nil {
    return fmt.Errorf("write generated file: %w", err)
}

如果输入来自不受信任的网络请求，还应在调用前限制字节长度、设置请求超时，并避免把解析错误原样暴露给外部用户。format.Source 负责格式化，不替代资源控制、鉴权或业务校验。

什么时候不用 format.Source

• 需要稳定的预提交比较：官方建议执行固定版本的 gofmt 二进制，避免开发者使用不同 Go 版本时得到不同检查结果。
• 已经拥有 AST：使用 format.Node，避免把 AST 先打印成字节再解析一次。
• 需要自动添加或删除导入：go/format 只负责标准格式与完整文件的导入排序，不负责依赖语义修复。
• 输入不是 Go 语法：模板残片、带占位符的半成品或其他语言文本，要在占位完成后再调用。

相关问题

format.Source 会修改传入的字节切片吗

接口返回新的格式化结果。调用方应始终使用返回值，不要假设原切片已原地变更。

为什么格式化局部代码后 imports 没排序

官方契约明确说明，局部源码不排序 imports。需要整理导入时，应提供包含 package 声明的完整文件。

语法错误时能拿到部分格式化结果吗

不要依赖部分结果。把错误视为整个生成阶段失败，保留原输入用于定位，修复后重新格式化。

format.Source 与 gofmt 的结果永远一样吗

它们遵循同类标准格式化逻辑，但格式规则会随 Go 版本演进。需要跨环境字节级稳定时，固定并执行具体版本的 gofmt。