Go模板中安全输出原始JSON数据：template.JS的实践指南-Golang-PHP中文网

Go模板中安全输出原始JSON数据：template.JS的实践指南

霞舞

发布： 2025-11-21 14:56:31

原创

773人浏览过

Go模板中安全输出原始JSON数据：template.JS的实践指南

本教程详细阐述了在go html/template中将json数据输出到客户端javascript时遇到的转义问题。文章深入分析了转义发生的原因——go模板引擎的安全机制，并提供了基于template.js类型的解决方案，确保json数据以原始、非转义的形式呈现，从而简化前端数据处理，避免不必要的客户端解析。

在现代Web开发中，后端Go服务经常需要将结构化数据传递给前端JavaScript进行处理。一种常见的方法是将Go对象序列化为JSON字符串，然后将其嵌入到HTML模板中。然而，在使用Go标准库的html/template包时，开发者可能会遇到一个普遍的问题：序列化后的JSON字符串在模板中输出时会被自动转义，导致在JavaScript中无法直接作为JSON对象或数组使用。

理解Go模板中的JSON转义现象

当开发者尝试将一个Go对象通过json.Marshal转换为JSON字符串，并在html/template中直接输出时，例如：

// 假设这是模板函数注册的一部分
"marshal": func(v interface {}) string {
  a, _ := json.Marshal(v)
  return string(a) // 返回一个普通的字符串
},

登录后复制

并在模板中使用：

<script>
  var arr = {{ marshal .Arr }};
</script>

登录后复制

预期的结果可能是var arr=["o1","o2"]，以便JavaScript可以直接将其识别为数组。但实际输出往往是var arr="[\"o1\",\"o2\"]"，这是一个被转义的字符串。

为什么会发生转义？

html/template包在设计时就考虑了安全性，特别是防止跨站脚本攻击（XSS）。它默认会对所有从Go代码输出到HTML模板的字符串进行HTML实体转义。这意味着，像双引号（"）、尖括号（<、>）等特殊字符都会被转换为它们的HTML实体形式（例如，" 变为 " 或 \"）。当JSON字符串被视为普通字符串处理时，其中的双引号会被转义，导致整个JSON字符串被包裹在额外的双引号中，并且内部的双引号也一并被转义。

这种行为虽然增强了安全性，但对于需要在JavaScript上下文中直接使用的原始JSON数据来说，却带来了不便。

解决方案：利用template.JS类型

Go标准库的html/template包提供了一系列“安全”类型，用于告知模板引擎某个字符串内容已经过处理，是安全的，不应再进行默认的转义。其中，template.JS类型正是为JavaScript上下文设计的。

当一个函数返回template.JS类型的值时，html/template会认为该内容是安全的JavaScript代码或数据，并会将其不加转义地直接输出到模板中。

因此，解决JSON转义问题的关键在于修改自定义的marshal函数，使其返回template.JS类型：

import (
    "encoding/json"
    "html/template" // 引入 template 包
    "log"
)

// 新的 marshal 函数，返回 template.JS 类型
"marshal": func(v interface {}) template.JS {
  a, err := json.Marshal(v)
  if err != nil {
      log.Printf("Error marshaling to JSON: %v", err)
      return template.JS("{}") // 发生错误时返回一个空的JS对象或合适的错误提示
  }
  return template.JS(a) // 将 JSON 字节切片转换为 template.JS 类型
},

登录后复制

在模板中的使用方式保持不变：

落笔AI

AI写作，AI写网文、AI写长篇小说、短篇小说

查看详情

<script>
  var arr = {{ marshal .Arr }};
</script>

登录后复制

通过这种修改，{{ marshal .Arr }}将直接输出["o1","o2"]，而不是转义后的字符串，JavaScript引擎可以正确地将其解析为数组。

完整示例

以下是一个完整的Go Web应用示例，演示如何在Go模板中安全地输出原始JSON数据：

package main

import (
    "encoding/json"
    "html/template"
    "log"
    "net/http"
)

// PageData 定义了要传递给模板的数据结构
type PageData struct {
    Title string
    Items []string
}

func main() {
    // 创建一个新的模板实例，并注册自定义函数
    // 注意：这里使用 template.New("index.html") 是为了给模板命名，
    // 如果后续从文件解析，通常会用 template.ParseFiles 或 template.ParseGlob
    tmpl := template.New("example_template").Funcs(template.FuncMap{
        "marshal": func(v interface{}) template.JS {
            a, err := json.Marshal(v)
            if err != nil {
                log.Printf("Error marshaling to JSON: %v", err)
                // 在生产环境中，可以返回更友好的错误信息或空JSON对象
                return template.JS("[]") // 返回一个空的JS数组作为 fallback
            }
            return template.JS(a) // 关键：返回 template.JS 类型
        },
    })

    // 解析模板字符串
    // 实际应用中，模板通常存储在文件中，例如 tmpl.ParseFiles("templates/index.html")
    tmpl, err := tmpl.Parse(`<!DOCTYPE html>
<html>
<head>
    <title>{{.Title}}</title>
    <script>
        // 使用 marshal 函数输出原始JSON数组
        var dataItems = {{ marshal .Items }};
        console.log("dataItems:", dataItems);
        console.log("Type of dataItems:", typeof dataItems);
        console.log("Is dataItems an array?", Array.isArray(dataItems));
        console.log("First item:", dataItems[0]);

        // 假设有一个错误的marshalWrong函数（这里不实际实现，仅为说明对比）
        // 如果不使用 template.JS，输出会是转义字符串
        // var escapedItems = "{{ .EscapedJSON }}"; // 假设 .EscapedJSON 是一个普通的转义字符串
        // console.log("escapedItems:", escapedItems);
        // console.log("Type of escapedItems:", typeof escapedItems);
        // console.log("Requires JSON.parse to be useful:", JSON.parse(escapedItems));
    </script>
</head>
<body>
    <h1>{{.Title}}</h1>
    <p>请打开浏览器开发者工具的控制台查看JavaScript数据的输出。</p>
</body>
</html>`)
    if err != nil {
        log.Fatalf("Error parsing template: %v", err)
    }

    // 定义HTTP处理器
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        data := PageData{
            Title: "Go Template JSON 输出示例",
            Items: []string{"Apple", "Banana", "Cherry", "Date"},
        }
        // 执行模板并将数据写入响应
        err := tmpl.Execute(w, data)
        if err != nil {
            http.Error(w, "Error executing template", http.StatusInternalServerError)
            log.Printf("Error executing template: %v", err)
        }
    })

    log.Println("服务器正在监听 :8080 端口...")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

登录后复制

运行上述Go程序，并在浏览器中访问http://localhost:8080，打开开发者工具的控制台，您会看到dataItems被正确地识别为一个JavaScript数组，而不是一个字符串。

注意事项与最佳实践

安全性至关重要： template.JS类型会绕过Go模板引擎的自动转义机制。这意味着，如果传递给template.JS的内容本身包含恶意脚本，这些脚本将直接输出到HTML页面并可能被执行，造成XSS攻击。因此，只有当您完全信任JSON数据的来源，并确信它不包含任何可执行的恶意代码时，才应使用template.JS。 对于用户输入或来自不可信源的数据，务必进行严格的净化和验证，或者考虑在客户端使用JSON.parse()。
错误处理： 在实际应用中，json.Marshal可能会因为各种原因失败（例如，传入了无法序列化的循环引用）。在自定义的marshal函数中，务必对json.Marshal返回的错误进行处理。在示例中，我们简单地记录了错误并返回了一个空的JSON数组（[]）作为备用方案，这在某些场景下可能比直接导致模板渲染失败更友好。
替代方案：客户端JSON.parse()： 尽管template.JS提供了一种直接输出原始JSON的方法，但客户端的JSON.parse()方法仍然是一个完全有效且常用的替代方案。如果JSON数据量非常大，或者需要在客户端进行更复杂的预处理，先将JSON作为转义字符串输出，然后在客户端使用JSON.parse()进行解析，也是一种可行的策略。例如：
```
<script>
    var rawJsonString = "{{ marshalWrong .Items }}"; // marshalWrong 返回普通字符串
    var dataItems = JSON.parse(rawJsonString);
</script>
```
登录后复制
这种方法将解析的负担转移到客户端，并且即使marshalWrong返回的是一个普通字符串，Go模板的自动转义也会确保该字符串本身是安全的HTML内容，之后再由JavaScript进行解析。
上下文匹配： html/template提供了多种“安全”类型，如template.HTML、template.CSS、template.URL等，它们分别对应不同的输出上下文。选择正确的类型至关重要。template.JS专用于JavaScript上下文，不应错误地用于HTML属性或CSS样式等其他位置。

总结

在Go html/template中输出原始JSON数据以供JavaScript直接使用时，template.JS类型是解决自动转义问题的标准且推荐的方法。通过将自定义的JSON序列化函数修改为返回template.JS类型，我们可以确保JSON数据以非转义的形式嵌入到HTML模板中，从而简化前端的数据处理流程。然而，开发者必须时刻牢记template.JS会绕过模板引擎的安全机制，因此在使用时务必确保数据的来源是可信的，以避免潜在的安全风险。

以上就是Go模板中安全输出原始JSON数据：template.JS的实践指南的详细内容，更多请关注php中文网其它相关文章！