texttemplate生成配置文件

Go 的 text/template 可以用固定模板和数据生成配置文件：先 Parse，再 Execute 到内存缓冲，成功后才写入文件。它不会自动按 JSON、YAML 或其他配置格式转义，因此字符串字段要使用目标格式的编码函数；模板执行成功也不等于配置语义一定正确。

官方文档：https://pkg.go.dev/text/template

迁移范围：从手工拼接改成受信模板

假设部署脚本原先用多段字符串拼接服务名和端口，后来名称里出现引号，配置就无法读取。这里将生成逻辑改成模板，讨论的是项目实现方式迁移，不是某个 Go 版本发生了破坏性变更。

本文选择小型 JSON 配置作为例子，让静态布局留在模板里、字段值来自程序。若整个文件只是普通结构化数据，直接使用 encoding/json 通常更省事；模板更适合确实需要维护固定文本骨架的场景，不必为了“模板化”而增加额外层。

变更表：将模板、数据和输出分开

旧代码风险：文本输出不自带格式约束

直接把服务名放在双引号之间，会漏掉引号、反斜杠和换行等情况。换成 text/template 后若仍写成引号包围字段动作，同样没有解决转义问题。不能把 Go 字符串字面量、JSON字符串和 YAML 字符串视为完全相同的规则。

另一个问题是 Execute 遇错时可能已经向 Writer 写出部分内容。若 Writer 就是正式配置文件，最后留下的可能是半份配置。内存缓冲能隔离模板失败，但不能让后面的文件写入自动具备事务性，这是两个不同故障阶段。

新写法：先完成渲染，再创建配置文件

下面的独立程序只依赖标准库。端口由 int 提供并检查范围，服务名通过 json.Marshal 编成JSON字符串，模板不会再为它额外添加引号。辅助函数在 Parse 之前注册。

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "os"
    "text/template"
)

// 模板来自程序自身；字符串字段必须使用目标格式的转义函数。
const configTemplate = `{
  "service": {{jsonString .service}},
  "port": {{.port}}
}
`

func jsonString(s string) (string, error) {
    b, err := json.Marshal(s)
    return string(b), err
}

func render(service string, port int) ([]byte, error) {
    if service == "" || port  65535 {
        return nil, fmt.Errorf("服务名不能为空，端口必须在 1 到 65535 之间")
    }
    // 函数必须在 Parse 前注册；缺失 map 键直接返回错误。
    t, err := template.New("config").
        Funcs(template.FuncMap{"jsonString": jsonString}).
        Option("missingkey=error").
        Parse(configTemplate)
    if err != nil {
        return nil, fmt.Errorf("解析模板：%w", err)
    }
    data := map[string]interface{}{"service": service, "port": port}
    var out bytes.Buffer
    // 先渲染内存，避免模板执行失败时破坏目标配置。
    if err := t.Execute(&out, data); err != nil {
        return nil, fmt.Errorf("渲染配置：%w", err)
    }
    return out.Bytes(), nil
}

func run() error {
    content, err := render("report-worker", 9123)
    if err != nil {
        return err
    }
    // 仅创建新文件，已有同名文件时拒绝覆盖。
    f, err := os.OpenFile("generated-config.json",
        os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
    if err != nil {
        return fmt.Errorf("创建配置：%w", err)
    }
    _, writeErr := f.Write(content)
    closeErr := f.Close() // 无论写入是否成功都释放文件句柄。
    if writeErr != nil {
        return fmt.Errorf("写入配置：%w", writeErr)
    }
    if closeErr != nil {
        return fmt.Errorf("关闭配置：%w", closeErr)
    }
    fmt.Println("已生成 generated-config.json")
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

将程序保存为 main.go，在一个用于演示的目录执行 go run main.go。按代码语义，首次成功会创建 generated-config.json，其中 service 为 report-worker，port 为9123；这里是预期行为说明，并非运行日志。再次运行因文件已存在而报错，是O_EXCL的预期保护行为。

模板中的点表示当前数据对象，.service和.port分别索引对应键。missingkey=error针对缺失map键，不负责判断空字符串、端口范围或任意业务规则，所以输入检查仍放在render函数开头。

回归场景：分别观察格式、字段和文件错误

迁移时可以为读者自己的项目准备这些输入：服务名包含双引号、反斜杠和换行；模板字段被拼错；端口为0或超过65535；输出文件已存在；目标目录不可写。它们分别覆盖字符串编码、模板执行、业务范围和文件系统操作，不能只用一份正常配置判断迁移完成。

本文程序保留了每个阶段的错误：Parse错误不开始渲染，Execute错误不创建文件，OpenFile错误不继续写入。写入或关闭失败时，可能已经产生一个不完整的新文件，示例不会把它宣称为成功；重试前要按部署流程处理该文件。

如果目标是更新线上正在使用的配置，应另外设计临时文件、关闭、替换及回退策略，并确认平台的替换语义与持久化需求。当前示例只生成新文件，不承诺原子更新或断电后数据持久性。0600是创建权限参数，在常见Unix权限模型中限制新文件访问，但仍要结合实际平台和部署账户。

迁移清单与常见问题

固定模板必须来自可信来源。不要让外部输入变成模板源码，也不要向不可信模板注册可访问文件、网络或秘密的函数。普通字段即使包含模板分隔符，在一次Execute中也只是数据，不会自动再次解析；不要为了支持“嵌套占位符”把输出重新Parse。

迁移时先确定文件格式和字段类型，再把对应转义收进辅助函数，随后区分模板错误与文件错误。配置中若包含密钥，诊断日志应只输出阶段与字段名，不把完整生成内容写入日志。

text/template能自动转义JSON吗？不能。本例使用专门的jsonString函数；若不需要文本骨架，优先考虑直接序列化完整结构体。

可以用html/template替代吗？它面向HTML输出，不能把HTML上下文转义当作配置文件编码规则。

missingkey=error能防止空值吗？不能。存在但为空的键与缺失键不同，业务必填项仍需显式判断。

参考：text/template标准库文档；json.Marshal文档；os.OpenFile文档。