Golang增强Go模板功能的实用插件库Sprout的使用

简介

Sprout是Masterminds/sprig库的现代化演进版本，专为现代Go版本重新设计。它引入了新功能并承诺持续维护，填补了Sprig停止更新后的空白。Sprig已有两年未更新且不支持Go 1.13以上版本，因此Sprout应运而生。

动机

Sprout诞生于对现代化、可维护且高性能模板函数库的需求。Sprig作为Sprout的前身，已有两年未更新且未针对较新Go版本优化。Sprout旨在填补这一空白，提供一个积极维护、兼容最新Go版本并优化性能的库。

从Sprig迁移

Sprout提供了sprigin包作为Sprig的临时替代方案，具有相同的函数名称和行为。要使用Sprout，只需将Sprig导入替换为sprigin：

import (
-  "github.com/Masterminds/sprig/v3"
+  "github.com/go-sprout/sprout/sprigin"
)

tpl := template.Must(
  template.New("base").
-   Funcs(sprig.FuncMap()).
+   Funcs(sprigin.FuncMap()).
    ParseGlob("*.tmpl")
)

重要提示：sprigin包是提供与Sprig向后兼容的临时解决方案。我们建议更新代码以直接使用Sprout包，以利用新功能和改进。

使用指南

创建处理器

Sprout中的处理器负责管理函数注册表和函数。DefaultHandler是Sprout提供的主要实现。

import "github.com/go-sprout/sprout"

handler := sprout.New()

自定义处理器

Sprout支持使用处理器选项进行各种自定义：

handler := sprout.New(
  // 添加日志记录器到处理器，使用标准slog包或任何实现slog.Logger接口的日志记录器
  // 默认情况下，Sprout使用slog.TextHandler
  sprout.WithLogger(slogLogger),
  // 为函数设置别名。默认情况下，Sprout为某些函数使用别名以保持与Sprig的兼容性
  sprout.WithAlias("hello", "hi"),
)

使用注册表

Sprout中的注册表是可以添加到处理器的函数组。它们有助于组织函数并优化模板性能。

import (
  "github.com/go-sprout/sprout/registry/conversion" // toString, toInt, toBool, ...
  "github.com/go-sprout/sprout/registry/std" // default, empty, any, all, ...
)

//...

handler.AddRegistries(
  conversion.NewRegistry(),
  std.NewRegistry(),
)

使用注册表组

在某些情况下，可以使用注册表组一次性添加多个注册表。

import (
  "github.com/go-sprout/sprout/group/all"
)

//...

handler.AddGroup(
  all.RegistryGroup(),
)

构建函数映射

要与html/template或text/template等模板引擎一起使用Sprout，需要构建函数映射：

funcs := handler.Build()
tpl := template.New("example").Funcs(funcs).Parse(`{{ hello }}`)

使用模板

函数映射准备好后，可以使用它来渲染模板：

tpl, err := template.New("example").Funcs(funcs).Parse(`{{ myFunc }}`)
if err != nil {
    log.Fatal(err)
}
tpl.Execute(os.Stdout, nil)

快速示例

以下是如何与text/template包一起使用Sprout的快速示例：

package main

import (
	"os"
	"text/template"

	"github.com/go-sprout/sprout"
	"github.com/go-sprout/sprout/registry/std"
)

func main() {
	handler := sprout.New()
	handler.AddRegistry(std.NewRegistry())

	tpl := template.Must(
    template.New("example").Funcs(handler.Build()).Parse(`{{ hello }}`),
  )
	tpl.Execute(os.Stdout, nil)
}

性能基准

Sprig v3.2.3 vs Sprout v0.5

goos: linux
goarch: amd64
pkg: sprout_benchmarks
cpu: Intel(R) Core(TM) i9-9900K CPU @ 3.60GHz
BenchmarkSprig-16              1        2991811373 ns/op        50522680 B/op      32649 allocs/op
BenchmarkSprout-16             1        1638797544 ns/op        42171152 B/op      18061 allocs/op
PASS
ok      sprout_benchmarks       4.921s

时间改进：45.3%
内存改进：16.5%

因此，Sprout v0.5比Sprig v3.2.3快约45.3%，内存使用减少16.5%。

开发理念

我们扩展和完善Sprout的方法遵循以下几个关键原则：

• 建立在简单性、灵活性和一致性的原则上
• 使开发人员能够创建强大的模板，而不牺牲性能或可用性
• 严格遵守Go的模板约定，确保熟悉Go原生工具的开发人员获得无缝体验
• 跨函数的命名约定标准化以实现可预测性和易用性
• 强调错误处理，倾向于安全默认值而非panic
• 提供清晰全面的文档以帮助用户理解库及其功能
• 保持高水平的代码质量，确保库经过良好测试、高性能且可靠
• 持续改进和优化库以满足社区需求
• 避免模板函数中的任何外部依赖，确保所有操作都是自包含且可靠的
• 性能是关键考虑因素，重点优化库的速度和效率