text/template 自定义函数并处理空值的模板方案

在结构化日志里，模板通常会被反复执行：服务名有值，某些可选字段却可能为空或根本不存在。比较稳妥的方案是把“展示层兜底”集中到一个自定义函数里，模板只负责组合字段；同时给可选 map 字段使用 missingkey=zero，让缺失键先变成元素零值，再交给函数处理。模板本身只解析一次，后续请求重复调用 Execute。

先用 Funcs 注册 defaultText，再 Parse；可选字符串字段使用 missingkey=zero，必填字段则在数据进入模板前校验，必要时切换到 missingkey=error。

高频日志渲染时，先把责任拆开

一个容易失控的写法，是在每个模板动作里重复判断空值，或者让业务层到处拼接“未知”“-”等展示文本。这样一来，字段规则散落在数据组装、模板和调用方之间，新增字段时很难知道应该改哪里。

这里把边界收窄为两层：业务数据保持原始含义，defaultText 只负责把 nil、空白文本和缺失值转换成最终展示值；text/template 负责布局，不负责业务校验。对于高频场景，模板构造也不要放进请求循环，解析阶段和执行阶段应分离。

用 defaultText 统一处理空字符串和缺失值

下面的函数故意接收 any，这样模板可以传入结构体字段或 map 字段。它先判断 nil，再把值转成文本并去掉首尾空白；空文本统一使用备用值。示例中的 Fields 是 map[string]string，因此 missingkey=zero 对不存在的键返回空字符串。

package main

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

type LogData struct {
    Service string
    Method  string
    Fields  map[string]string
}

// defaultText 只处理展示层空值，不把缺失字段伪装成业务成功。
func defaultText(fallback string, value any) string {
    if value == nil {
        return fallback
    }
    text := strings.TrimSpace(fmt.Sprint(value))
    if text == "" || text == "" {
        return fallback
    }
    return text
}

func render(data LogData) (string, error) {
    const source = `service={{defaultText "unknown" .Service}} method={{defaultText "-" .Method}} trace={{defaultText "-" .Fields.trace_id}}`

    // Funcs 必须先于 Parse，让解析器认识模板中的函数名。
    tpl, err := template.New("log").
        Funcs(template.FuncMap{"defaultText": defaultText}).
        Option("missingkey=zero").
        Parse(source)
    if err != nil {
        return "", err
    }

    var out bytes.Buffer
    // 模板已经解析完成；每次调用只传入本次日志数据并检查错误。
    if err := tpl.Execute(&out, data); err != nil {
        return "", err
    }
    return out.String(), nil
}

这个方案的关键不在于把所有值都转成字符串，而是明确“哪些空值只是展示缺省，哪些缺失代表输入不完整”。例如 trace_id 可以显示为 -，但订单号、租户号等必填字段不应靠占位符掩盖。

missingkey 的选择决定了模板边界

官方文档把缺失 map 键的行为分成三档。default（或 invalid）继续执行，打印时可能得到 ；zero 返回 map 元素类型的零值；error 则在执行阶段停止。对于可选日志字段，zero 与 defaultText 的组合更容易得到稳定输出；对于契约字段，直接使用 error 更容易暴露数据问题。

上线前检查复用和错误处理

模板构造完成后可以安全地并发执行，但不要在多个 goroutine 中同时修改模板定义或继续注册函数。生产代码还应为输出缓冲区、写入器错误和模板执行错误留出处理路径；否则即使日志字段本身没有问题，写入失败也可能被悄悄吞掉。

复查时可以按这条清单走：函数是否在 Parse 前注册；可选字段是否明确使用了零值策略；必填字段是否在数据层校验；模板是否只初始化一次；每次 Execute 是否检查错误。这样既能保持日志格式稳定，也不会让展示层兜底越过业务数据边界。

常见问题

Funcs 放在 Parse 后还能生效吗？

不建议。模板解析阶段就要识别函数名，应先调用 Funcs 再 Parse；解析完成后主要复用模板执行。

missingkey=zero 会处理已有的空字符串吗？

不会。它只影响不存在的 map 键；已经存在但值为 "" 的字段仍需由 defaultText 或数据层规则处理。

所有字段都应该使用 missingkey=error 吗？

不应该一刀切。可选日志维度适合温和兜底，契约字段才适合严格失败；先按字段责任分类，再选择执行策略。