Go template.Execute 输出部分内容后如何处理错误

Go 的 text/template 执行失败时，目标 io.Writer 里不一定是空的。Template.Execute 会边执行边写出文本；如果某个动作取值失败，或者 Writer 自己返回写入错误，执行会停止，但错误发生前已经写出的内容可能保留下来。

如果模板输出要进入 HTTP 响应、正式文件或消息正文，不要直接把它交给最终 Writer。先写入 bytes.Buffer，只有 Execute 返回 nil 时再提交；如果提交阶段本身失败，仍要处理 io.Copy 或 Write 的错误。

官方文档：https://pkg.go.dev/text/template#Template.Execute

为什么 Execute 返回错误后仍可能有内容

Execute 的工作可以理解为“解析后的模板向 Writer 逐段写出”。普通文本、已经成功求值的动作可能先被写入，后面的动作才触发错误。因此，err != nil 只能说明这次执行没有完整成功，不能推出 Writer 仍然为空。

官方对 Execute 和 ExecuteTemplate 的描述都明确提到：执行错误或写出错误会停止执行，但部分结果可能已经写入输出 Writer。这个语义对 bytes.Buffer、文件、HTTP 响应和自定义 Writer 都成立，区别只在于调用方是否还能撤销已经发生的写入。

用 missingkey=error 看见“部分输出 + 错误”

下面的例子故意让模板访问不存在的 Status 键。标题和作者位于错误动作之前，渲染失败时它们可能已经写入缓冲区；这正是不能只看错误值就假设输出为空的原因。

package main

import (
	"bytes"
	"fmt"
	"text/template"
)

func main() {
	// 把会失败的字段放在已有文本之后，观察错误前可能留下的输出。
	source := "标题：{{.Title}}\n作者：{{.Author}}\n状态：{{.Status}}\n"
	tmpl, err := template.New("article").
		Option("missingkey=error").
		Parse(source)
	if err != nil {
		panic(err)
	}

	var buf bytes.Buffer
	// Status 不存在时 Execute 返回错误，但前面的文本可能已写入 buf。
	err = tmpl.Execute(&buf, map[string]string{
		"Title":  "模板渲染排障",
		"Author": "Go 读者",
	})
	fmt.Printf("错误：%v\n已写入：%q\n", err, buf.String())
}

这里的 buf.String() 仅用于展示 Writer 当前状态。实际业务中，如果这个缓冲区代表最终 HTTP body，就不能因为“已经有一部分内容”而继续返回成功页面；应根据业务约定将本次结果视为失败，或者把错误转换成独立的错误响应。

正式输出前先隔离模板渲染

最稳妥的通用做法是把模板执行和正式提交拆成两个阶段：第一阶段只写入临时缓冲；第二阶段确认没有模板错误后，再将缓冲内容复制到正式 Writer。这样模板执行中途失败不会污染正式输出。

package render

import (
	"bytes"
	"io"
	"text/template"
)

func Render(w io.Writer, tmpl *template.Template, data any) error {
	var staged bytes.Buffer

	// 先隔离模板阶段，避免 Execute 的部分结果直接进入正式 Writer。
	if err := tmpl.Execute(&staged, data); err != nil {
		return err
	}

	// 只有模板完整成功后才提交；提交阶段的 I/O 错误仍必须返回。
	_, err := io.Copy(w, &staged)
	return err
}

这个函数把“模板执行错误”和“正式 Writer 写入错误”分开了。前者发生时，w 没有收到本次模板内容；后者发生时，io.Copy 可能已经向 w 写入一部分数据，所以调用方还需要记录失败并决定是否重试、关闭连接或删除临时文件。

不要把已经写入的 Writer 当成可回滚事务

bytes.Buffer 适合做提交前暂存，但普通 io.Writer 没有回滚协议。文件 Writer 可能已经扩展文件，网络 Writer 可能已经发送字节，HTTP 响应在写入或调用 WriteHeader 后也可能无法再替换状态码和完整正文。

因此，下面两种写法的风险不同：

模板执行成功后，写出仍然可能失败

使用缓冲区并不意味着整个过程自动具备事务性。模板可能执行成功，但 io.Copy 向正式 Writer 写出时仍可能遇到磁盘空间不足、连接断开或自定义 Writer 拒绝写入。

工程上至少要区分两个错误来源：

• Execute 错误：模板数据、函数调用或模板内部动作没有得到完整结果，临时缓冲应视为不可提交。
• 提交错误：模板结果已经准备好，但目标 Writer 没有完整接收；不能把它记录成一次完整成功。

如果输出目标支持“临时资源写完后原子替换”，可以先把缓冲写入临时文件，关闭并确认写入成功，再执行改名。对于网络响应，则应尽量在写出首字节前完成模板渲染，并保留提交阶段的错误处理。

ExecuteTemplate、并发和 html/template 的边界

ExecuteTemplate 与 Execute 共享“失败时可能已有部分结果”的处理原则，只是前者选择关联模板集合中的指定模板。若代码使用命名模板，不要因为换成 ExecuteTemplate 就省略缓冲区隔离。

模板本身在构造完成后可以并行执行，但官方文档提醒：多个并行执行如果共享同一个 Writer，输出可能交错。并发场景应让每次执行拥有独立缓冲区，再由明确的协调逻辑决定提交顺序。

如果输出是 HTML，还要区分输出安全问题：text/template 不会自动进行 HTML 转义，官方建议生成 HTML 时使用 html/template。这解决的是内容转义边界，不会改变“Execute 可能留下部分输出”的 Writer 语义。

最后记住这几个判断

1. 看到 Execute 返回错误时，先假设 Writer 可能已有部分内容。
2. 正式 HTTP body、完整文件和消息正文，优先采用临时缓冲或临时文件提交。
3. 模板执行成功不代表最终写出成功，io.Copy、Write 的错误仍要向上返回。
4. 共享 Writer 的并行模板执行可能交错；独立缓冲区只能隔离每次执行，不能替代提交顺序设计。

相关问题

Execute 返回错误时一定会返回空字符串吗？

不会。官方契约明确允许错误发生前已经写入部分结果，具体内容取决于模板顺序、数据和 Writer 行为。

把目标换成 bytes.Buffer 就不会有问题了吗？

它能避免直接污染正式输出，但缓冲区本身仍可能是残片。只有在 Execute 返回 nil 后，才应把它当作完整结果提交。

ExecuteTemplate 需要单独处理吗？

需要沿用同一原则：指定模板名不会改变部分输出语义，也不会自动提供回滚能力。

参考文档：https://pkg.go.dev/text/template#Template.Execute、https://pkg.go.dev/text/template#Template.ExecuteTemplate、https://pkg.go.dev/io#Writer