Go template.FuncMap 注册函数时如何避免共享状态：模板并发执行与初始化边界

把函数放进 Go 的 template.FuncMap，并不等于这个函数天然适合并发。真正安全的边界是：先完成 Funcs 注册和 Parse，之后让多个 goroutine 并行调用 Execute；如果注册进去的闭包还在读写普通 map、计数器或复用可变缓冲区，竞态仍然会发生。

推荐把 FuncMap 当成初始化配置：注册阶段完成依赖装配，执行阶段只调用无共享写入的函数；确实需要状态时，为每次执行创建状态，或用明确的锁保护它。

先分清 FuncMap 的三个时间点

排查这类问题时，先把代码按时间拆开：Funcs 把名字映射到函数，Parse 把模板文本解析成可执行结构，Execute 才会在请求或任务中反复调用这些函数。前两步属于构造阶段，最后一步属于运行阶段。

func upper(s string) string { return strings.ToUpper(s) }

tmpl, err := template.New("welcome").
    Funcs(template.FuncMap{"upper": upper}).
    Parse("Hello, {{upper .Name}}")
if err != nil {
    log.Fatal(err)
}

var buf bytes.Buffer
if err := tmpl.Execute(&buf, map[string]string{"Name": "gopher"}); err != nil {
    log.Fatal(err)
}

官方文档允许解析完成后的模板并行执行，但模板构造不能和执行混在一起。这里的 upper 没有外部写入，适合复用；buf 却是本次输出专用，不能被多个执行共享。

第一个检查点：闭包有没有偷偷保存可变数据

最容易漏掉的是闭包。下面的 nextID 看起来只是给模板提供编号，实际却把状态放在 FuncMap 外层；两个 Execute 同时调用它时，counter++ 就是未同步写入。

counter := 0
funcMap := template.FuncMap{
    "nextID": func() int {
        counter++
        return counter
    },
}

tmpl := template.Must(template.New("item").
    Funcs(funcMap).
    Parse(`{{.Name}}`))

这个问题和模板是否安全无关：不安全的是函数闭包本身。把 counter 换成普通 map、切片追加或可复用 bytes.Buffer，结论一样。这里先别急着给模板加锁，先判断状态是否真的需要跨请求存在。

第二个检查点：状态应该隔离，还是集中加锁

如果编号只服务于一次渲染，优先把它放进输入数据，而不是藏在 FuncMap 里。需要跨执行共享时，才保留状态并用 sync.Mutex 明确保护。

type sequence struct {
    mu      sync.Mutex
    counter int
}

seq := &sequence{}
funcMap := template.FuncMap{
    "nextID": func() int {
        seq.mu.Lock()
        defer seq.mu.Unlock()
        seq.counter++
        return seq.counter
    },
}

tmpl := template.Must(template.New("item").
    Funcs(funcMap).
    Parse(`{{.Name}}`))

sync.Mutex 只保护计数器，不会自动保护输出目标，也不会让其他共享对象变安全。每个 goroutine 仍应创建自己的 bytes.Buffer，执行后再把完整字符串交给下游。

用最小并发测试把边界跑出来

只看单线程输出很容易误判。测试里让每个 goroutine 使用独立的 bytes.Buffer，再用 go test -race 检查 FuncMap 函数是否存在未同步访问。

func render(t *template.Template, name string) (string, error) {
    var buf bytes.Buffer
    err := t.Execute(&buf, map[string]string{"Name": name})
    return buf.String(), err
}

func TestRenderParallel(t *testing.T) {
    var wg sync.WaitGroup
    for i := 0; i 

验证顺序建议固定为：先运行普通测试确认模板输出，再运行 go test -race ./...。如果报告指向 nextID 或它调用的缓存函数，修复共享状态；如果只是多个 goroutine 共用一个 Writer，则改成每次执行独立 Writer。

常见误区与上线前清单

相关问题：模板并发执行还要注意什么

Funcs 注册后还能不能替换同名函数？

可以，但应把替换视为模板构造或明确的测试阶段动作，不要在并发 Execute 正在进行时修改共享模板的函数配置。

多个 Execute 共用一个 Writer 会怎样？

输出可能交错，即使模板解析本身没有竞态。为每次执行分配独立 Writer，或者在写入边界上做串行化。

FuncMap 里的函数返回 error 可以吗？

可以使用单个返回值，或使用第二个返回值为 error 的双返回值函数；error 非 nil 时，模板执行会停止并返回该错误。

把初始化和执行边界留在代码里

稳定的做法不是给所有模板调用套一把大锁，而是让 Funcs、Parse 在初始化阶段完成，让 Execute 使用独立输入和输出。只有确实要共享的状态，才在最小范围内使用 sync.Mutex；最后用 go test -race ./... 把判断变成证据。