Go 的 html/template 可以渲染页面，embed 可以把模板打进二进制。小型后台、内部工具、邮件预览页都很适合这种组合。问题是模板一多，如何组织 base layout、partial 和具体页面？如果随便 ParseGlob，很快会乱。
本文用一个后台页面示例，讲一种简单组织方式。
目录结构
internal/web/templates/
base.html
partials/nav.html
pages/dashboard.html
pages/users.html
base.html 放整体 HTML 骨架，partials 放导航、页脚等片段，pages 放具体页面。
embed 文件
//go:embed templates/*.html templates/partials/*.html templates/pages/*.html
var templateFiles embed.FS
解析：
func ParseTemplates() (*template.Template, error) {
return template.ParseFS(templateFiles,
"templates/*.html",
"templates/partials/*.html",
"templates/pages/*.html",
)
}
路径是相对包含 //go:embed 的源码文件。移动目录后要同步调整。
base 模板
base.html：
{{define "base"}}
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>{{block "title" .}}后台{{end}}</title>
</head>
<body>
{{template "nav" .}}
<main>
{{block "content" .}}{{end}}
</main>
</body>
</html>
{{end}}
partials/nav.html：
{{define "nav"}}
<nav>
<a href="/dashboard">概览</a>
<a href="/users">用户</a>
</nav>
{{end}}
页面模板：
{{define "title"}}概览{{end}}
{{define "content"}}
<h1>概览</h1>
<p>当前用户数：{{.UserCount}}</p>
{{end}}
渲染时执行 base：
func RenderDashboard(w http.ResponseWriter, tmpl *template.Template, data DashboardData) error {
return tmpl.ExecuteTemplate(w, "base", data)
}
多页面 block 冲突
如果一次解析所有页面模板，并且它们都定义了同名 title、content，后解析的可能覆盖前面的。更稳的方式是为每个页面创建独立模板集合：base + partials + 当前 page。
func ParsePage(page string) (*template.Template, error) {
files := []string{
"templates/base.html",
"templates/partials/nav.html",
"templates/pages/" + page + ".html",
}
return template.ParseFS(templateFiles, files...)
}
这样 dashboard 和 users 各自有自己的 content block，不会互相覆盖。
启动时解析
模板语法错误应该启动时暴露：
dashboardTmpl, err := ParsePage("dashboard")
if err != nil {
log.Fatal(err)
}
不要等用户访问页面才发现模板坏了。内部工具也应该启动失败，而不是运行到一半才报错。
测试模板
func TestParseDashboard(t *testing.T) {
tmpl, err := ParsePage("dashboard")
if err != nil {
t.Fatal(err)
}
var buf bytes.Buffer
err = tmpl.ExecuteTemplate(&buf, "base", DashboardData{UserCount: 3})
if err != nil {
t.Fatal(err)
}
if !strings.Contains(buf.String(), "当前用户数") {
t.Fatalf("html = %s", buf.String())
}
}
测试能防止模板路径、define 名称和数据字段错掉。模板也是代码，应该被验证。
开发模式
embed 需要重新编译才能看到模板变化。开发时可以从磁盘读取：
func ParsePageFromDisk(root string, page string) (*template.Template, error) {
return template.ParseFiles(
filepath.Join(root, "base.html"),
filepath.Join(root, "partials/nav.html"),
filepath.Join(root, "pages", page+".html"),
)
}
生产用 embed，开发用磁盘，二者保持同样模板结构。不要让开发模式和生产模式使用完全不同路径，否则上线后容易出错。
模板函数放在哪里
模板函数要在解析模板前注册。常见函数包括格式化时间、截断文本、生成静态资源路径。不要在模板里放复杂业务逻辑，模板函数应该短小、确定、没有副作用。
func newTemplates() (*template.Template, error) {
funcs := template.FuncMap{
"date": func(t time.Time) string {
return t.Format("2006-01-02")
},
}
return template.New("").Funcs(funcs).ParseFS(templates, "templates/*.html")
}
如果函数需要访问数据库或远程服务，通常说明逻辑放错地方了。先在 handler 或 service 中准备好数据，再交给模板渲染。这样模板失败大多是展示问题，而不是业务链路问题。
数据模型要面向页面
模板数据不一定等于数据库模型。页面需要什么，就准备什么。比如用户详情页可能要用户名、注册时间、订单数量和是否展示管理按钮，这些可以组合成一个 view model。
type UserPage struct {
Title string
Name string
JoinedAt time.Time
OrderCount int
CanManage bool
}
func userPage(u User, orders int, viewer Role) UserPage {
return UserPage{
Title: u.Name + " 的资料",
Name: u.Name,
JoinedAt: u.CreatedAt,
OrderCount: orders,
CanManage: viewer == RoleAdmin,
}
}
这样模板只负责判断和展示，不需要知道数据库字段名，也不需要临时计算复杂状态。以后换页面样式时，不会牵动仓库层。
处理模板执行错误
ExecuteTemplate 也可能失败，比如模板里访问不存在字段、函数返回错误、写响应时客户端断开。由于 HTTP 响应可能已经写出一部分，错误处理要尽量在开发阶段暴露。
func render(w http.ResponseWriter, tmpl *template.Template, name string, data any) {
var buf bytes.Buffer
if err := tmpl.ExecuteTemplate(&buf, name, data); err != nil {
http.Error(w, "render page", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_, _ = w.Write(buf.Bytes())
}
先渲染到 buffer，再写给客户端，可以避免页面写了一半才发现模板错误。对大页面来说会多占一点内存，但普通后台页面、设置页、文档页完全可以接受。若是超大流式页面，再考虑直接写响应。
小结
Go 的 embed.FS 和 html/template 很适合小型页面。组织模板时，可以用 base layout、partials 和 page 模板。为了避免 block 冲突，每个页面最好解析独立模板集合。
模板路径、define 名称和数据字段都要测试。生产用 embed 提升部署稳定性，开发可以从磁盘读取提高迭代效率。边界清楚后，标准库模板足够支撑很多内部工具。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。