2016年10月09日

by smallnest

Go 模板嵌套最佳实践

Go 官方库提供了两个模板库： text/template 和 html/template。这两个库类似，只不过 html/template对html格式做了特别的处理，当需要输出html格式的代码时需要使用html/template。

使用模版，可以帮助我们写一些通用的代码，或者提供清晰的文件布局，或者提供一个代码生成器。

官方文档提供了很好的模版的使用方法, 其中 text/template提供了基础的模版的使用方法，比如 Action、 Argument、Pipeline、Variable、Function、模版嵌套的介绍， html/template对 Context 进行了介绍。本文假定你已经了解了这些基础知识。如果你还不清楚，或者还没有用过模版，可以参考文末的参考文档进行学习。

虽然text/template官方文档对模版嵌套简单了介绍，但是对于如何使用嵌套模版进行实际开发，以及注意事项并没有详细的介绍，所以本文着重介绍嵌套模版的使用。

虽然本文名称为嵌套模版的最佳实践，但是准确的讲，这只是最佳实践之一。如果读者有其它的实践方案，或者更好的处理模版嵌套的方案，欢迎讨论。

在我们开发web应用程序的时候，不可避免的要使用到模版。

一般一个网站包含很多的页面，比如新闻页面、注册页面、文章列表等。不同的新闻可能使用同一个新闻布局模版，不同的文章详细页也可能使用同一个文章布局页面，同时新闻布局模版和文章布局页面也可能有一些公用的东西，比如header、footer、导航栏等。如何将这些公用的东西抽取成统一的模版呢？

本文将逐步介绍这些技术，首先介绍嵌套文件的使用。

Parse vs ParseFiles vs ParseBlob

首先我们看一下这三个文件有何不同。事实上是五个文件：

func ParseFiles(filenames ...string) (*Template, error)
func ParseGlob(pattern string) (*Template, error)
func (t *Template) Parse(text string) (*Template, error)
func (t *Template) ParseFiles(filenames ...string) (*Template, error)
func (t *Template) ParseGlob(pattern string) (*Template, error)

Parse用来解析一个字符串，字符串代表模版的内容，并且嵌套的模版也会和这个模版进行关联。

1
2
3

tmpl, err := template.New("name").Parse(...)
// Error checking elided
err = tmpl.Execute(out, data)

和

import "html/template"
...
t, err := template.New("foo").Parse(`\{\{define "T"\}\}Hello, \{\{.\}\}!\{\{end\}\}`)
err = t.ExecuteTemplate(out, "T", "<script>alert('you have been pwned')</script>")

ParseFiles用来解析一组命名的文件模版，当模版定义在不同的文件中的时候，使用这个方法可以产生一个可执行的模版，模版执行的时候不会出错。
ParseGlob与ParseFiles类似，它使用filepath.Glob模式匹配的方式遍历文件，将这些文件生成模版。

这两个函数还可以作为 *Template的方法使用。作为函数使用的时候，它返回模版的名字是第一个文件的名字，模版以第一个文件作为base模版。
同时后面的文件也会生成模版作为这个模版的关联模板,你可以通过Lookup方法查找到这个模版，因为每个模版都保存着它的关联模版：

1	set map[string]*Template

我们以一个例子演示一下嵌套模版的使用。

当前文件夹下有两个文件。
header.html

1 2	Title is \{\{.Title\}\} \{\{template "footer"\}\}

footer.html

1	\{\{define "footer"\}\}Body is \{\{.Body\}\}\{\{end\}\}

测试程序:

package main
import (
	"fmt"
	"html/template"
	"net/http"
)
func handler(w http.ResponseWriter, r *http.Request) {
	t, _ := template.ParseFiles("header.html", "footer.html")
	err := t.Execute(w, map[string]string{"Title": "My title", "Body": "Hi this is my body"})
	if err != nil {
		panic(err)
	}
}
func main() {
	http.HandleFunc("/", handler)
	http.ListenAndServe(":8080", nil)
}

浏览器访问 http://localhost:8080/会得到渲染的结果:

1 2	Title is My title Body is

可以看到结果基本符合预期。header.html嵌套了footer模版，渲染的时候以header.html为主模版显示，嵌套渲染了footer.html。

但是上面的结果显示有一点点问题，就是footer渲染的时候并没有显示body的结果，这是因为data传给了主模版，嵌套模版如果要使用这个数据，需要在嵌套的地方把data传递给它。我们可以修改header.html:

1 2	Title is \{\{.Title\}\} \{\{template "footer" <div class=""></div>\}\}

这样footer.html就可以使用传入的data渲染了:

1 2	Title is My title Body is Hi this is my body

在使用ParseFiles、ParseGlob 函数的时候，默认以文件的路径的最后一个部分作为模版名称，比如文件a/foo的模版名称为foo，但是如果参数中不同的文件夹下有相同的文件名时，最后那个同名的模版文件会"覆盖"前面的重名文件模版，官方库的实现中不能保存重名的模版文件。

Execute vs ExecuteTemplate

上面的例子显示了一个简单的嵌套模版的使用，但是如果我们把两个文件的顺序交换一下，如下所示：

func handler(w http.ResponseWriter, r *http.Request) {
	t, _ := template.ParseFiles("footer.html", "header.html")
	err := t.Execute(w, map[string]string{"Title": "My title", "Body": "Hi this is my body"})
	if err != nil {
		panic(err)
	}
}

运行后浏览器访问一下,会发现没报错，但是也没有渲染任何东西。
这是因为｀template.ParseFiles｀返回的模版以第一个为主模版。在这种情况下footer.html没有可渲染的东西。

在这种情况下，我们就需要显示的指定要渲染的模版：

func handler(w http.ResponseWriter, r *http.Request) {
	t, _ := template.ParseFiles("footer.html", "header.html")
	//err := t.Execute(w, map[string]string{"Title": "My title", "Body": "Hi this is my body"})
	err := t.ExecuteTemplate(w, "header.html", map[string]string{"Title": "My title", "Body": "Hi this is my body"})
	if err != nil {
		panic(err)
	}
}

使用ExecuteTemplate可以选择渲染t关联的模版作为渲染的主模版。上面的例子中我们选择header.html作为主模版，所以它可以正常渲染。

或者，通过下面的方法也能正常渲染,它和上面的代码基本是等价的(只有escape细微的差别)。

func handler(w http.ResponseWriter, r *http.Request) {
	t, _ := template.ParseFiles("footer.html", "header.html")
	t = t.Lookup("header.html")
	err := t.Execute(w, map[string]string{"Title": "My title", "Body": "Hi this is my body"})
	//err := t.ExecuteTemplate(w, "header.html", map[string]string{"Title": "My title", "Body": "Hi this is my body"})
	if err != nil {
		panic(err)
	}
}

所以可以看到Execute和ExecuteTemplate的功能的差别，当你想用指定的关联的模版渲染时，就使用ExecuteTemplate。

最佳实践

有了上面的基础，我们就可以解决文章开始提出的问题：如何规划一个网站的模版？

我们创建两个文件夹：layouts、widgets，将hello.html放入到layouts文件夹中，header.html、footer.html放入到widgets文件夹中，
我们就以这三个文件作为例子，看看嵌套模版在网站中的应用。

但是在进一步介绍之前，我需要介绍上面代码中的一个问题。可以看到，上面的每个请求都会读取模版文件再进行解析，这会严重影响程序的性能，解决方案就是预先读取这些文件并生成Template对象，这样请求来了就直接使用解析好的template对象即可。

var templates map[string]*template.Template
func init() {
	if templates == nil {
		templates = make(map[string]*template.Template)
	}
	//templatesDir := "./templates/"
  templatesDir := "./"
	layouts, err := filepath.Glob(templatesDir + "layouts/*.html")
	if err != nil {
		log.Fatal(err)
	}
	widgets, err := filepath.Glob(templatesDir + "widgets/*.html")
	if err != nil {
		log.Fatal(err)
	}
	for _, layout := range layouts {
		files := append(widgets, layout)
		templates[filepath.Base(layout)] = template.Must(template.ParseFiles(files...))
	}
}

通过一个map对象，我们保存了每一个布局对应的template对象。

然后提供一个模版渲染的方法：

func renderTemplate(w http.ResponseWriter, name string, data interface{}) error {
	tmpl, ok := templates[name]
	if !ok {
		return fmt.Errorf("The template %s does not exist.", name)
	}
	w.Header().Set("Content-Type", "text/html; charset=utf-8")
	return tmpl.ExecuteTemplate(w, name, data)
}

我在为rpcx开发web GUI的时候使用了这个方法：rpcx-ui。

当然通过一些变换也可以实现其它的模版设计，比如一个base.html模版，里面定义好了header，footer,还嵌套了body模版，通过不同的body模版实现不同模版布局，比如news.html定义了显示news的body， music.html定义了music的body，这也是一个不错的模版布局。

鸟窝

《深入理解Go并发编程》新书发售中。一书在手，并发无忧

Go 模板嵌套最佳实践

Parse vs ParseFiles vs ParseBlob

Execute vs ExecuteTemplate

最佳实践

参考文档