Go 每日一庫之 fasttemplate
簡介
fasttemplate是一個比較簡單、易用的小型模板庫。fasttemplate的作者valyala另外還開源了不少優(yōu)秀的庫，如大名鼎鼎的fasthttp，前面介紹的bytebufferpool，還有一個重量級的模板庫quicktemplate。quicktemplate比標(biāo)準(zhǔn)庫中的text/template和html/template要靈活和易用很多，后面會專門介紹它。今天要介紹的fasttemlate只專注于一塊很小的領(lǐng)域——字符串替換。它的目標(biāo)是為了替代strings.Replace、fmt.Sprintf等方法，提供一個簡單，易用，高性能的字符串替換方法。
本文首先介紹fasttemplate的用法，然后去看看源碼實現(xiàn)的一些細(xì)節(jié)。
快速使用
本文代碼使用 Go Modules。
創(chuàng)建目錄并初始化：
$ mkdir fasttemplate && cd fasttemplate
$ go mod init github.com/darjun/go-daily-lib/fasttemplate
安裝fasttemplate庫：
$ go get -u github.com/valyala/fasttemplate
編寫代碼：
package main
import (
"fmt"
"github.com/valyala/fasttemplate"
)
func main() {
template := `name: {{name}}
age: {{age}}`
t := fasttemplate.New(template, "{{", "}}")
s1 := t.ExecuteString(map[string]interface{}{
"name": "dj",
"age": "18",
})
s2 := t.ExecuteString(map[string]interface{}{
"name": "hjw",
"age": "20",
})
fmt.Println(s1)
fmt.Println(s2)
}
定義模板字符串，使用 {{和}}表示占位符，占位符可以在創(chuàng)建模板的時候指定；調(diào)用 fasttemplate.New()創(chuàng)建一個模板對象t，傳入開始和結(jié)束占位符；調(diào)用模板對象的 t.ExecuteString()方法，傳入?yún)?shù)。參數(shù)中有各個占位符對應(yīng)的值。生成最終的字符串。
運(yùn)行結(jié)果：
name: dj
age: 18
我們可以自定義占位符，上面分別使用{{和}}作為開始和結(jié)束占位符。我們可以換成[[和]]，只需要簡單修改一下代碼即可：
template := `name: [[name]]
age: [[age]]`
t := fasttemplate.New(template, "[[", "]]")
另外，需要注意的是，傳入?yún)?shù)的類型為map[string]interface{}，但是fasttemplate只接受類型為[]byte、string和TagFunc類型的值。這也是為什么上面的18要用雙引號括起來的原因。
另一個需要注意的點，fasttemplate.New()返回一個模板對象，如果模板解析失敗了，就會直接panic。如果想要自己處理錯誤，可以調(diào)用fasttemplate.NewTemplate()方法，該方法返回一個模板對象和一個錯誤。實際上，fasttemplate.New()內(nèi)部就是調(diào)用fasttemplate.NewTemplate()，如果返回了錯誤，就panic：
// src/github.com/valyala/fasttemplate/template.go
func New(template, startTag, endTag string) *Template {
t, err := NewTemplate(template, startTag, endTag)
if err != nil {
panic(err)
}
return t
}
func NewTemplate(template, startTag, endTag string) (*Template, error) {
var t Template
err := t.Reset(template, startTag, endTag)
if err != nil {
return nil, err
}
return &t, nil
}
這其實也是一種慣用法，對于不想處理錯誤的示例程序，直接panic有時也是一種選擇。例如html.template標(biāo)準(zhǔn)庫也提供了Must()方法，一般這樣用，遇到解析失敗就panic：
t := template.Must(template.New("name").Parse("html"))
占位符中間內(nèi)部不要加空格?。?！
占位符中間內(nèi)部不要加空格！??！
占位符中間內(nèi)部不要加空格！！！
快捷方式
使用fasttemplate.New()定義模板對象的方式，我們可以多次使用不同的參數(shù)去做替換。但是，有時候我們要做大量一次性的替換，每次都定義模板對象顯得比較繁瑣。fasttemplate也提供了一次性替換的方法：
func main() {
template := `name: [name]
age: [age]`
s := fasttemplate.ExecuteString(template, "[", "]", map[string]interface{}{
"name": "dj",
"age": "18",
})
fmt.Println(s)
}
使用這種方式，我們需要同時傳入模板字符串、開始占位符、結(jié)束占位符和替換參數(shù)。
TagFunc
fasttemplate提供了一個TagFunc，可以給替換增加一些邏輯。TagFunc是一個函數(shù)：
type TagFunc func(w io.Writer, tag string) (int, error)
在執(zhí)行替換的時候，fasttemplate針對每個占位符都會調(diào)用一次TagFunc函數(shù)，tag即占位符的名稱?？聪旅娉绦颍?/p>
func main() {
template := `name: {{name}}
age: {{age}}`
t := fasttemplate.New(template, "{{", "}}")
s := t.ExecuteFuncString(func(w io.Writer, tag string) (int, error) {
switch tag {
case "name":
return w.Write([]byte("dj"))
case "age":
return w.Write([]byte("18"))
default:
return 0, nil
}
})
fmt.Println(s)
}
這其實就是get-started示例程序的TagFunc版本，根據(jù)傳入的tag寫入不同的值。如果我們?nèi)ゲ榭丛创a就會發(fā)現(xiàn)，實際上ExecuteString()最終還是會調(diào)用ExecuteFuncString()。fasttemplate提供了一個標(biāo)準(zhǔn)的TagFunc：
func (t *Template) ExecuteString(m map[string]interface{}) string {
return t.ExecuteFuncString(func(w io.Writer, tag string) (int, error) { return stdTagFunc(w, tag, m) })
}
func stdTagFunc(w io.Writer, tag string, m map[string]interface{}) (int, error) {
v := m[tag]
if v == nil {
return 0, nil
}
switch value := v.(type) {
case []byte:
return w.Write(value)
case string:
return w.Write([]byte(value))
case TagFunc:
return value(w, tag)
default:
panic(fmt.Sprintf("tag=%q contains unexpected value type=%#v. Expected []byte, string or TagFunc", tag, v))
}
}
標(biāo)準(zhǔn)的TagFunc實現(xiàn)也非常簡單，就是從參數(shù)map[string]interface{}中取出對應(yīng)的值做相應(yīng)處理，如果是[]byte和string類型，直接調(diào)用io.Writer的寫入方法。如果是TagFunc類型則直接調(diào)用該方法，將io.Writer和tag傳入。其他類型直接panic拋出錯誤。
如果模板中的tag在參數(shù)map[string]interface{}中不存在，有兩種處理方式：
直接忽略，相當(dāng)于替換成了空字符串 ""。標(biāo)準(zhǔn)的stdTagFunc就是這樣處理的；保留原始 tag。keepUnknownTagFunc就是做這個事情的。
keepUnknownTagFunc代碼如下：
func keepUnknownTagFunc(w io.Writer, startTag, endTag, tag string, m map[string]interface{}) (int, error) {
v, ok := m[tag]
if !ok {
if _, err := w.Write(unsafeString2Bytes(startTag)); err != nil {
return 0, err
}
if _, err := w.Write(unsafeString2Bytes(tag)); err != nil {
return 0, err
}
if _, err := w.Write(unsafeString2Bytes(endTag)); err != nil {
return 0, err
}
return len(startTag) + len(tag) + len(endTag), nil
}
if v == nil {
return 0, nil
}
switch value := v.(type) {
case []byte:
return w.Write(value)
case string:
return w.Write([]byte(value))
case TagFunc:
return value(w, tag)
default:
panic(fmt.Sprintf("tag=%q contains unexpected value type=%#v. Expected []byte, string or TagFunc", tag, v))
}
}
后半段處理與stdTagFunc一樣，函數(shù)前半部分如果tag未找到。直接寫入startTag + tag + endTag作為替換的值。
我們前面調(diào)用的ExecuteString()方法使用stdTagFunc，即直接將未識別的tag替換成空字符串。如果想保留未識別的tag，改為調(diào)用ExecuteStringStd()方法即可。該方法遇到未識別的tag會保留：
func main() {
template := `name: {{name}}
age: {{age}}`
t := fasttemplate.New(template, "{{", "}}")
m := map[string]interface{}{"name": "dj"}
s1 := t.ExecuteString(m)
fmt.Println(s1)
s2 := t.ExecuteStringStd(m)
fmt.Println(s2)
}
參數(shù)中缺少age，運(yùn)行結(jié)果：
name: dj
age:
name: dj
age: {{age}}
帶io.Writer參數(shù)的方法
前面介紹的方法最后都是返回一個字符串。方法名中都有String：ExecuteString()/ExecuteFuncString()。
我們可以直接傳入一個io.Writer參數(shù)，將結(jié)果字符串調(diào)用這個參數(shù)的Write()方法直接寫入。這類方法名中沒有String：Execute()/ExecuteFunc()：
func main() {
template := `name: {{name}}
age: {{age}}`
t := fasttemplate.New(template, "{{", "}}")
t.Execute(os.Stdout, map[string]interface{}{
"name": "dj",
"age": "18",
})
fmt.Println()
t.ExecuteFunc(os.Stdout, func(w io.Writer, tag string) (int, error) {
switch tag {
case "name":
return w.Write([]byte("hjw"))
case "age":
return w.Write([]byte("20"))
}
return 0, nil
})
}
由于os.Stdout實現(xiàn)了io.Writer接口，可以直接傳入。結(jié)果直接寫到os.Stdout中。運(yùn)行：
name: dj
age: 18
name: hjw
age: 20
源碼分析
首先看模板對象的結(jié)構(gòu)和創(chuàng)建：
// src/github.com/valyala/fasttemplate/template.go
type Template struct {
template string
startTag string
endTag string
texts [][]byte
tags []string
byteBufferPool bytebufferpool.Pool
}
func NewTemplate(template, startTag, endTag string) (*Template, error) {
var t Template
err := t.Reset(template, startTag, endTag)
if err != nil {
return nil, err
}
return &t, nil
}
模板創(chuàng)建之后會調(diào)用Reset()方法初始化：
func (t *Template) Reset(template, startTag, endTag string) error {
t.template = template
t.startTag = startTag
t.endTag = endTag
t.texts = t.texts[:0]
t.tags = t.tags[:0]
if len(startTag) == 0 {
panic("startTag cannot be empty")
}
if len(endTag) == 0 {
panic("endTag cannot be empty")
}
s := unsafeString2Bytes(template)
a := unsafeString2Bytes(startTag)
b := unsafeString2Bytes(endTag)
tagsCount := bytes.Count(s, a)
if tagsCount == 0 {
return nil
}
if tagsCount+1 > cap(t.texts) {
t.texts = make([][]byte, 0, tagsCount+1)
}
if tagsCount > cap(t.tags) {
t.tags = make([]string, 0, tagsCount)
}
for {
n := bytes.Index(s, a)
if n < 0 {
t.texts = append(t.texts, s)
break
}
t.texts = append(t.texts, s[:n])
s = s[n+len(a):]
n = bytes.Index(s, b)
if n < 0 {
return fmt.Errorf("Cannot find end tag=%q in the template=%q starting from %q", endTag, template, s)
}
t.tags = append(t.tags, unsafeBytes2String(s[:n]))
s = s[n+len(b):]
}
return nil
}
初始化做了下面這些事情：
記錄開始和結(jié)束占位符； 解析模板，將文本和 tag切分開，分別存放在texts和tags切片中。后半段的for循環(huán)就是做的這個事情。
代碼細(xì)節(jié)點：
先統(tǒng)計占位符一共多少個，一次構(gòu)造對應(yīng)大小的文本和 tag切片，注意構(gòu)造正確的模板字符串文本切片一定比tag切片大 1。像這樣| text | tag | text | ... | tag | text |；為了避免內(nèi)存拷貝，使用 unsafeString2Bytes讓返回的字節(jié)切片直接指向string內(nèi)部地址。
看上面的介紹，貌似有很多方法。實際上核心的方法就一個ExecuteFunc()。其他的方法都是直接或間接地調(diào)用它：
// src/github.com/valyala/fasttemplate/template.go
func (t *Template) Execute(w io.Writer, m map[string]interface{}) (int64, error) {
return t.ExecuteFunc(w, func(w io.Writer, tag string) (int, error) { return stdTagFunc(w, tag, m) })
}
func (t *Template) ExecuteStd(w io.Writer, m map[string]interface{}) (int64, error) {
return t.ExecuteFunc(w, func(w io.Writer, tag string) (int, error) { return keepUnknownTagFunc(w, t.startTag, t.endTag, tag, m) })
}
func (t *Template) ExecuteFuncString(f TagFunc) string {
s, err := t.ExecuteFuncStringWithErr(f)
if err != nil {
panic(fmt.Sprintf("unexpected error: %s", err))
}
return s
}
func (t *Template) ExecuteFuncStringWithErr(f TagFunc) (string, error) {
bb := t.byteBufferPool.Get()
if _, err := t.ExecuteFunc(bb, f); err != nil {
bb.Reset()
t.byteBufferPool.Put(bb)
return "", err
}
s := string(bb.Bytes())
bb.Reset()
t.byteBufferPool.Put(bb)
return s, nil
}
func (t *Template) ExecuteString(m map[string]interface{}) string {
return t.ExecuteFuncString(func(w io.Writer, tag string) (int, error) { return stdTagFunc(w, tag, m) })
}
func (t *Template) ExecuteStringStd(m map[string]interface{}) string {
return t.ExecuteFuncString(func(w io.Writer, tag string) (int, error) { return keepUnknownTagFunc(w, t.startTag, t.endTag, tag, m) })
}
Execute()方法構(gòu)造一個TagFunc調(diào)用ExecuteFunc()，內(nèi)部使用stdTagFunc：
func(w io.Writer, tag string) (int, error) {
return stdTagFunc(w, tag, m)
}
ExecuteStd()方法構(gòu)造一個TagFunc調(diào)用ExecuteFunc()，內(nèi)部使用keepUnknownTagFunc：
func(w io.Writer, tag string) (int, error) {
return keepUnknownTagFunc(w, t.startTag, t.endTag, tag, m)
}
ExecuteString()和ExecuteStringStd()方法調(diào)用ExecuteFuncString()方法，而ExecuteFuncString()方法又調(diào)用了ExecuteFuncStringWithErr()方法，ExecuteFuncStringWithErr()方法內(nèi)部使用bytebufferpool.Get()獲得一個bytebufferpoo.Buffer對象去調(diào)用ExecuteFunc()方法。所以核心就是ExecuteFunc()方法：
func (t *Template) ExecuteFunc(w io.Writer, f TagFunc) (int64, error) {
var nn int64
n := len(t.texts) - 1
if n == -1 {
ni, err := w.Write(unsafeString2Bytes(t.template))
return int64(ni), err
}
for i := 0; i < n; i++ {
ni, err := w.Write(t.texts[i])
nn += int64(ni)
if err != nil {
return nn, err
}
ni, err = f(w, t.tags[i])
nn += int64(ni)
if err != nil {
return nn, err
}
}
ni, err := w.Write(t.texts[n])
nn += int64(ni)
return nn, err
}
整個邏輯也很清晰，for循環(huán)就是Write一個texts元素，以當(dāng)前的tag執(zhí)行TagFunc，索引 +1。最后寫入最后一個texts元素，完成。大概是這樣：
| text | tag | text | tag | text | ... | tag | text |
注：ExecuteFuncStringWithErr()方法使用到了前面文章介紹的bytebufferpool，感興趣可以回去翻看。
總結(jié)
可以使用fasttemplate完成strings.Replace和fmt.Sprintf的任務(wù)，而且fasttemplate靈活性更高。代碼清晰易懂，值得一看。
吐槽：關(guān)于命名，Execute()方法里面使用stdTagFunc，ExecuteStd()方法里面使用keepUnknownTagFunc方法。我想是不是把stdTagFunc改名為defaultTagFunc好一點？
大家如果發(fā)現(xiàn)好玩、好用的 Go 語言庫，歡迎到 Go 每日一庫 GitHub 上提交 issue??
參考
fasttemplate GitHub：github.com/valyala/fasttemplate Go 每日一庫 GitHub：https://github.com/darjun/go-daily-lib
推薦閱讀