如何避免Go text/template将panic渲染到输出，转而返回执行错误？

问题场景 #

使用Go的text/template渲染模板时，若自定义类型的String()方法触发panic，panic信息会被直接渲染到输出结果中，而非让模板执行终止并返回错误。示例代码及输出如下：

package main

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

type MyDate struct {
    Time *time.Time
}

func (d *MyDate) String() string {
    // 此处会触发panic
    return d.Time.Format("15:04 02.01.2006")
}

type templateDto struct {
    Date *MyDate
}

func main() {
    s := `start
auto {{ .Date }}
finish`

    t := template.Must(template.New("test").Parse(s))
    buf := bytes.NewBuffer([]byte{})

    err := t.Execute(buf, &templateDto{
        Date: &MyDate{},
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("%s\n", buf.String())
}

输出结果：

start
auto %!v(PANIC=String method: runtime error: invalid memory address or nil pointer dereference)
finish

解决方案 #

1. 修复String()方法避免panic #

直接修改自定义类型的String()方法，提前做nil校验，从根源上避免panic：

func (d *MyDate) String() string {
    if d.Time == nil {
        return "invalid date" // 或返回空字符串等默认值
    }
    return d.Time.Format("15:04 02.01.2006")
}

这种方式最简单，模板渲染时不会触发panic，自然不会出现错误信息被渲染的情况。

2. 自定义模板函数处理panic并返回错误 #

若无法修改String()方法，可定义专门的模板函数，内部捕获panic并转为错误返回：

func formatDate(date *MyDate) (string, error) {
    var err error
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("date format failed: %v", r)
        }
    }()
    return date.String(), err
}

注册该函数到模板：

t := template.Must(template.New("test").Funcs(template.FuncMap{
    "formatDate": formatDate,
}).Parse(s))

修改模板调用该函数：

start
auto {{ formatDate .Date }}
finish

此时若函数内部捕获到panic，会返回错误，Execute()方法会终止执行并将错误返回给调用者，不会继续渲染模板内容。

3. 利用模板错误处理机制（进阶） #

Go模板支持错误处理，可结合{{ if err ... }}结构或自定义函数触发模板执行终止。例如在自定义函数中，若遇到错误可调用template.Exit(1)，不过这种方式需要配合模板的错误配置使用，适合复杂场景。

原理说明 #

text/template的默认行为是：当渲染过程中调用的方法触发panic时，引擎会捕获panic并将其格式化为特殊字符串输出，以尽量完成渲染流程。通过上述方法，要么从根源避免panic，要么将panic转为可被模板识别的错误，从而终止渲染并返回错误。

内容的提问来源于stack exchange，提问作者Exel