Go 模板模板 Execute 返回错误但响应已写出怎么办

我排查这类问题时，最容易误判的一点是：Execute 返回错误，并不代表响应体一定是空的。Go 的模板包会把结果写入传入的 io.Writer；如果执行到中途才发现数据方法、模板函数或写出过程出错，前面已经写进去的字节不会自动撤销。这个 Writer 如果就是 http.ResponseWriter，客户端就可能收到一段不完整的 HTML。

处理原则很简单：不要让模板直接写最终响应。先把模板执行到 bytes.Buffer，确认没有错误后，再设置响应头并一次性提交完整正文。

为什么 Execute 返回错误时响应还可能有内容

text/template 和 html/template 的 Execute 都接收一个 io.Writer。模板中的普通文本、字段访问和函数调用并不是一次性组装成字符串后才写出，而是随着执行不断向 Writer 写入。官方文档明确说明：执行或写出发生错误时，执行会停止，但部分结果可能已经写到输出 Writer。

因此下面两件事并不矛盾：函数返回了非空错误；响应体已经包含了标题、导航或一部分数据。常见触发点包括模板调用了返回错误的函数、数据方法在执行中失败，以及底层 Writer 自身写出失败。

先分清模板错误和响应写出错误

排日志时不要只看“Execute 失败”这一句。模板执行错误通常会包装成模板执行错误，能继续用 errors.As 检查底层原因；如果是 Writer 写出失败，返回的通常是 Writer 自己的错误，而不是模板执行错误类型。两者的修复方向不同：前者检查数据和模板逻辑，后者检查客户端断开、代理链路或响应写出过程。

更关键的是，ResponseWriter 不是事务对象。第一次写正文通常会隐式提交成功状态；显式调用 WriteHeader 后也不能再把状态码改成另一个值。所以在已经写出部分正文之后，再调用错误处理函数，往往只能追加一段错误内容，不能把前面的半页 HTML 换掉。

package main

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

// pageData 故意保留一个可能返回错误的方法，用来说明执行中断边界。
type pageData struct {
    Title string
}

// LoadItems 代表执行模板期间可能失败的数据访问。
func (pageData) LoadItems() ([]string, error) {
    return nil, fmt.Errorf("items unavailable")
}

func badHandler(t *template.Template) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // 这里直接把最终 ResponseWriter 交给模板，失败后可能已经写出半段正文。
        if err := t.Execute(w, pageData{Title: "订单"}); err != nil {
            // 此时再写错误页，不能撤回已经发送的状态码和正文。
            log.Printf("template execution failed: %v", err)
            http.Error(w, "render failed", http.StatusInternalServerError)
        }
    }
}

这里特意把错误方法写得明显，是为了说明“模板执行到一半才失败”的边界。实际项目中，错误也可能来自字段链、函数映射或底层 Writer。这个处理器的问题不在于检查了错误，而在于检查错误之前已经把最终响应交给了模板。

先渲染成功，再提交 HTTP 响应

更稳妥的结构是把 bytes.Buffer 当成临时渲染区。模板无论写入多少内容，都只会影响内存中的缓冲区；只有 Execute 返回 nil 后，处理器才把状态码、内容类型和完整缓冲区写入 ResponseWriter。

package main

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

func goodHandler(t *template.Template) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        var body bytes.Buffer

        // 先写入临时缓冲区，把模板错误与最终 HTTP 响应隔离开。
        err := t.Execute(&body, pageData{Title: "订单"})
        if err != nil {
            // 模板失败时尚未提交响应，可以安全返回统一错误页。
            log.Printf("template execution failed: %v", err)
            http.Error(w, "render failed", http.StatusInternalServerError)
            return
        }

        // 模板完整成功后再设置响应头，避免把半成品交给客户端。
        w.Header().Set("Content-Type", "text/html; charset=utf-8")
        w.WriteHeader(http.StatusOK)
        if _, err := w.Write(body.Bytes()); err != nil {
            // 这里属于响应写出错误，不能再次尝试写错误页。
            log.Printf("response write failed: %v", err)
        }
    }
}

这段代码的价值不只是“多加一个 Buffer”。它把系统拆成两个清晰的边界：模板阶段可以失败且不污染 HTTP 响应；提交阶段只处理已经完成的正文。这样错误页不会和半截成功页拼接在一起，日志也能准确区分模板问题与网络写出问题。

生产代码还要留意这几个边界

如果响应正文很大，缓冲会增加一次内存占用，这是真实的取舍。对普通 HTML 页面，完整性通常比节省一次小规模内存分配更重要；对流式下载、长连接或刻意采用边生成边发送的场景，则不能假设可以随时回滚，应该把协议设计成客户端能处理分段失败。

常见问题

Execute 返回错误后还能把状态码改成 500 吗？

只有在响应尚未提交时才可靠。若已经调用 WriteHeader 或第一次 Write，状态码可能已经发送，后续再改写通常不会产生预期效果。

为什么不直接把模板执行结果保存成字符串？

字符串也可以作为缓冲，但 bytes.Buffer 能直接实现 io.Writer，和模板 API 的边界更自然。重点不是具体容器，而是不要让模板直接触碰最终响应。

响应写出失败时还要调用 http.Error 吗？

通常不要。写出失败说明响应链路已经部分提交或客户端已断开，再写错误页既无法撤回已发内容，还可能制造第二个错误。记录上下文并交给请求日志或指标系统更合适。