Go template Execute 失败后为什么已经输出半段内容

Go template.Execute 失败后仍有半段内容，是因为它把生成结果写入传入的 Writer，返回错误只会停止后续执行，不会撤销已经发生的写入。需要“渲染失败就不提交页面”，应先在请求独立缓冲里执行，成功后再把完整结果交给最终目标。

这解决的是模板渲染阶段的部分输出，不保证网络发送具有事务性。即便渲染完成后只调用一次 Write，连接仍可能在发送过程中失败。官方地址：https://go.dev/。下文示例使用标准库，代码和预期用于解释接口，不冒充本机运行结果。

把目标定为渲染失败不提交页面

生产页面常见的现象是：日志报模板错误，浏览器却已经拿到导航或页面开头，有时状态码仍为 200。应先确认模板究竟写到了哪里，而不是只检查有没有 if err。目标如果是 ResponseWriter，前面生成的文字可能已经进入响应；目标如果是文件，也可能留下不完整文件。

将目标收窄为“模板错误发生时，未完成页面不进入最终 Writer”，才能选择合适的缓冲策略。它不是让 Execute 自动回滚，也不是把所有错误都变成解析错误。对于本来就需要流式输出的大页面，则必须接受部分提交语义，另行设计错误反馈。

先分清模板解析、执行与目标写入

Parse 成功说明模板已被解析，并不保证每组数据都能执行成功。执行中取值、调用模板函数或写入目标都可能遇到错误。text/template 与 html/template 的 Execute 接口都明确允许失败前已写入部分结果；生成 HTML 时应使用 html/template，缓冲并不能代替它的上下文转义。

// missingkey=error使本例在访问缺失字段时返回执行错误。
t, err := template.New("page").Option("missingkey=error").
    Parse("前缀 {{.Name}} 尾部")
if err != nil {
    return err // 解析失败与执行失败分开处理。
}
var dst bytes.Buffer
err = t.Execute(&dst, map[string]string{})
// err不为nil时，dst仍可能已有前缀；不能把dst内容当作完整结果。

这段片段放在可返回 error 的函数内，需导入 bytes 与 html/template。故意缺少 Name 字段，是为了说明合法模板仍会在数据访问时失败。不能把“缺字段总会报错”当成默认规则，因此示例显式配置 missingkey=error。这里的 dst 是演示输出目标，并不是成功结果容器。

用请求独立缓冲隔离未完成内容

为中小页面引入 bytes.Buffer，使未完成内容留在本请求内部。只有 ExecuteTemplate 返回 nil，才允许提交缓冲。若失败，直接放弃这份内容，再生成独立错误响应。下面处理器展示完整职责，调用者需提供已解析且存在 page 模板的对象，以及非 nil logger。

package page

import (
    "bytes"
    "html/template"
    "log"
    "net/http"
)

// NewHandler 要求模板在启动时准备好，使用期间不再修改。
func NewHandler(t *template.Template, logger *log.Logger) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // 每个请求独立持有缓冲；模板失败时绝不提交这段内容。
        var buf bytes.Buffer
        data := struct{ Name string }{Name: "示例用户"}
        if err := t.ExecuteTemplate(&buf, "page", data); err != nil {
            logger.Printf("render_failed template=page err=%v", err)
            http.Error(w, "页面暂时不可用", http.StatusInternalServerError)
            return
        }

        // 到这里才提交成功状态；前置中间件也不得提前写响应。
        w.Header().Set("Content-Type", "text/html; charset=utf-8")
        w.WriteHeader(http.StatusOK)
        n, err := w.Write(buf.Bytes())
        if err != nil {
            // 已开始发送，不能再追加错误页或企图改写为500。
            logger.Printf("send_failed template=page written=%d err=%v", n, err)
        }
    }
}

示例数据只有 Name，应配套使用引用该字段的 page 模板。模板可在服务启动时解析并处理错误；处理器不在每次请求中改动模板定义。多个请求各有自己的缓冲，不能把一个全局 bytes.Buffer 当成并发输出目标，否则会发生共享写入和内容串扰。

检查点不是“Buffer.Len 大于零”，而是 ExecuteTemplate 返回 nil。失败时缓冲中有多少内容都不提交。缓冲归请求所有，函数返回后没有其他 goroutine 继续使用它，也不把它存到跨请求状态里。

确认谁有权提交 HTTP 响应

HTTP 响应必须有明确的提交所有者。示例要求进入处理器前没有中间件写正文或提交最终状态。渲染失败分支这时才能发出独立 500 响应；成功分支才设置 HTML 类型并提交 200。如果前面的中间件已经写过欢迎语，局部加 Buffer 也无法撤回那部分响应。

ResponseWriter 的首次 Write 在没有显式状态时会隐式提交 200。因而直接 Execute(w, data) 后再调用 http.Error，可能只是把错误文字附加到已有页面，而不是得到一份干净的 500。即使服务端内部尚有缓冲，也不能依赖其实现细节把已经提交的状态当作可撤销状态。

同样的所有权约束适用于文件输出：先写临时目标，成功后再按文件系统规则处理替换，但不能把它直接等同于 HTTP 缓冲，也不能无条件宣称跨文件系统替换原子。本文示例只实现 HTTP 页面，不混入通用文件发布器。

分别记录渲染失败和发送失败

日志至少区分 render_failed 与 send_failed。前者发生在本例提交正文之前，可以切换为错误响应；后者发生在开始写出之后，应记录错误并结束，不能再尝试拼接另一份错误页。记录模板稳定名称和请求关联标识即可，不必记录整页正文、Cookie 或完整业务数据。

模板函数最好只做展示转换，不在渲染中发送通知或修改数据库。缓冲隔离的是输出字节，不是函数调用的外部副作用。如果业务动作需要事务，应在模板渲染之外定义自己的提交边界。

上线前明确缓冲策略的适用范围

缓冲会占用内存，并使首字节发送等待渲染完成。对大小可控的页面，这个代价通常容易评估；对大型报表或无界列表，不能只加 bytes.Buffer 就结束设计。应先限制输出规模和请求并发，必要时采用可返回明确超限错误的暂存方案。截断输出并当成功提交，会制造另一种半页面。

ExecuteTemplate 也需要缓冲吗？

需要相同考虑。它只是按名字选择模板，并没有新增输出回滚能力。

只写一次响应能保证完整送达吗？

不能。一次 Write 不是网络事务，返回 nil 也不等于用户浏览器已完整展示。缓冲承诺的是渲染错误不泄露未完成页面，而非端到端送达保证。

是否应给所有页面加 missingkey=error？

这取决于数据契约和已有模板行为。它能使某些缺失 map 键成为错误，但不是通用数据校验器，也不能防止底层 Writer 失败。迁移时应单独评估，不把这个选项当成缓冲的替代品。

上线前把三项约定写清：最终响应只由一个组件提交，渲染错误丢弃内部缓冲，发送错误不再追加第二份页面。这样日志中的失败阶段、客户端可能看到的内容和代码处理方式才能对应起来。

参考：html/template Execute 文档、text/template 执行契约、HTTP 响应写入接口。