Go format.Source 怎样格式化一段源码并处理错误

把源码字节交给 format.Source，先检查返回的 error，只有成功时才使用格式化结果。失败时保留原始输入并把错误交给调用方，尤其不要把失败返回值直接写回原文件。该接口格式化Go语法，不负责证明代码可以编译或运行。

官方文档：https://pkg.go.dev/go/format#Source。它属于标准库，导入路径为 go/format。

最小配方：只在成功时接收输出

代码生成器或源码预览功能常常先拼出一段文本，再统一整理空格、换行和缩进。不要用字符串替换空格来模仿Go排版；让Source根据语法结构处理更合适。嵌入已有函数时，核心写法如下：

// src是已有的源码字节；成功后才替换预览内容。
out, err := format.Source(src)
if err != nil {
    return fmt.Errorf("格式化源码: %w", err)
}
preview = out

这里的 src 是输入，out 是结果，err 是成功与失败的分界。preview 为调用方的预览内容。由于这段使用return返回错误，所在函数需要具有error返回值。

可以把结构看成三个分组：“输入”包含src；“格式化接口”包含format.Source、out、err；“调用方”包含preview和原始内容。Source关联src及两个返回值，preview只接收成功结果；原始内容供失败时保留。图示表达接口关系，不是实际运行输出。

完整文件与源码片段怎样选择

Source接收语法正确的Go文件，也接受声明列表或语句列表。因此，一个临时计算片段不一定要硬加package和函数外壳。先确认自己提供的是完整文件还是允许的片段，避免把“缺少package”误判为所有错误的原因。

官方契约说明，片段会考虑原有首尾空白和首个代码行的缩进，且不会排序片段中的导入。若预览必须保留周围布局，不要不加区分地先TrimSpace，再假定Source能恢复已被删掉的空白。

格式化失败时保留输入并返回错误

预览工具与文件生成器可以采用不同策略：预览仍显示原文，同时提示格式化错误；生成器则通常应该中止本次生成，不更新正式文件。两者共同点是：回退内容不能被当成格式化成功的结果。

下面完整示例的 makePreview 采用“字节内容加错误”的约定。失败时用 输入副本 保留显示内容，并返回 包装错误；成功时返回 格式化结果。预览调用方 收到这些值后，根据错误决定显示方式；正式文件 不由这个函数操作。

返回副本是这个包装函数的所有权约定，避免预览持有调用方可能继续修改的输入数组；它不是Source强制要求。包装使用 %w 保留底层错误，外层可以继续做错误分类，而不是只比较一段固定的报错文本。

完整示例：格式化预览而不写文件

将下列代码保存为 main.go。它包括完整文件、语句片段和错误输入三类素材，未附本机执行记录；最终排版及错误文字以实际使用的Go工具链为准。

package main

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

// makePreview失败时返回输入副本和错误；副本只供显示，不代表成功。
func makePreview(src []byte) ([]byte, error) {
    out, err := format.Source(src)
    if err != nil {
        original := append([]byte(nil), src...)
        return original, fmt.Errorf("生成格式化预览: %w", err)
    }
    return out, nil
}

func run() error {
    samples := []struct {
        name string
        src string
    }{
        {
            name: "complete",
            src: "package demo\n// Double返回两倍值。\nfunc Double(n int)int{return n*2}\n",
        },
        {
            name: "statements",
            src: "// 计算临时宽度。\nw:=7\nw+=2\n",
        },
        {
            name: "broken",
            src: "package demo\nfunc Broken( {\n",
        },
    }
    for _, sample := range samples {
        view, err := makePreview([]byte(sample.src))
        if err != nil {
            // 错误与回退预览分开显示，调用方仍能识别失败。
            if _, writeErr := fmt.Fprintf(os.Stderr,
                "%s: %v\n原文预览：\n%s\n", sample.name, err, view); writeErr != nil {
                return fmt.Errorf("输出错误信息: %w", writeErr)
            }
            continue
        }
        // 这里只输出到终端，不覆盖任何源文件。
        if _, err := fmt.Fprintf(os.Stdout, "%s格式化预览：\n%s\n",
            sample.name, view); err != nil {
            return fmt.Errorf("输出预览: %w", err)
        }
    }
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

示例的broken分支用于演示局部失败后继续展示其他预览，所以格式化错误没有导致整个run失败。若把它改成构建工具，应在该分支直接返回错误，而不是照搬continue后仍宣布生成成功。

Source内部会解析并打印语法结构，但不是类型检查器。缺少名称定义、类型不匹配等问题可能仍能排版。也不要期待它自动寻找并补齐依赖，或删除全部无用导入。源码实现可参考：https://go.dev/src/go/format/format.go。

如果多人环境要求逐字节稳定的排版，统一工具链或固定版本的gofmt更合适。官方文档特别提醒格式规则会随时间变化；不能把一次生成的排版永久视为所有Go版本的唯一结果。

常见问题

成功返回是否说明源码能编译？

不说明。格式化处理语法与排版；编译、类型及依赖正确性属于另外的工作。

失败后直接把原文返回并设error为nil可以吗？

会把“未格式化”伪装成成功。需要保留预览时，同时保留错误或独立状态，让调用方作出选择。

为什么只格式化片段时导入顺序没变？

片段不执行导入排序。要处理整个文件的导入布局，应传入完整文件；这仍不等于自动管理缺失或无用依赖。