Go html/template 表单校验错误怎么回填：POST 分支、字段状态与焦点提示

注册表单提交失败时，用户最在意的不是服务器返回了哪句错误，而是刚才填过的邮箱还在不在、哪个字段需要修改、按回车后焦点是否落在正确位置。Go 的 html/template 可以把这三件事交给同一次 POST 渲染完成：保留合法输入，单独传递字段错误，并让模板标记出第一个失败字段。

把表单值和字段错误放进同一个页面模型，POST 校验失败就重新执行模板；不要用重定向丢掉输入，也不要让模板自己猜错误属于哪个字段。

先把“校验失败还原页面”拆成三个状态

这个问题常见于服务端渲染的注册、登录或地址簿页面。一个请求至少有三种结果：GET 初次打开时表单为空，POST 校验失败时表单带着用户刚输入的内容，POST 保存成功时跳转到完成页。把三种结果都塞进一个字符串错误变量，后面很快就会出现输入丢失和错误位置不清的问题。

页面模型可以只保留渲染需要的字段：

type FormData struct {
    Email       string
    DisplayName string
    FieldErrors map[string]string
    FirstError  string
}

func validateRegistration(form FormData) map[string]string {
    errors := make(map[string]string)
    if !strings.Contains(form.Email, "@") {
        errors["Email"] = "请输入有效邮箱"
    }
    if strings.TrimSpace(form.DisplayName) == "" {
        errors["DisplayName"] = "请输入显示名称"
    }
    return errors
}

FieldErrors 的键使用模型字段名，模板里再映射到输入框的 name。这样校验函数不需要拼 HTML，页面也不会把用户输入当作模板代码执行；html/template 会按 HTML 上下文进行转义。

POST 分支要先保留输入，再决定返回还是跳转

提交注册表单后，处理器先调用 ParseForm，再构造 FormData。校验失败直接执行模板，成功保存后使用重定向，避免刷新页面重复提交。

func registrationHandler(tmpl *template.Template, store Store) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        if r.Method == http.MethodGet {
            renderForm(w, tmpl, FormData{})
            return
        }
        if err := r.ParseForm(); err != nil {
            http.Error(w, "无法读取表单", http.StatusBadRequest)
            return
        }

        form := FormData{
            Email:       r.PostFormValue("email"),
            DisplayName: r.PostFormValue("display_name"),
        }
        form.FieldErrors = validateRegistration(form)
        if len(form.FieldErrors) > 0 {
            form.FirstError = firstError(form)
            renderForm(w, tmpl, form)
            return
        }
        if err := store.Create(r.Context(), form.Email, form.DisplayName); err != nil {
            http.Error(w, "保存失败，请稍后重试", http.StatusInternalServerError)
            return
        }
        http.Redirect(w, r, "/registration/complete", http.StatusSeeOther)
    }
}

这里的关键不是把所有错误都返回 400，而是保留失败分支的页面上下文。业务保存失败属于服务器异常，和用户输入不合法不是同一个状态；前者不应把数据库错误伪装成字段提示。

renderForm 内部最终调用 ExecuteTemplate，因此这条调用链的最后一步仍由模板执行结果决定，而不是由校验函数直接拼接页面。

模板只负责显示值和状态，不负责重新校验

模板要做的是把 FormData 的值放回输入框，并把对应字段错误紧跟在控件旁边。错误文本的存在还应同步到 aria-invalid，让屏幕阅读器和键盘用户知道哪些控件需要处理。

  邮箱
  
  {{with index .FieldErrors "Email"}}
{{.}}
{{end}}

  显示名称
  
  {{with index .FieldErrors "DisplayName"}}
{{.}}
{{end}}

  创建账号

不要在模板里根据空字符串推断“这个字段错了”。空字符串可能是用户确实没填，也可能是合法输入，真正的状态来自 FieldErrors。错误提示放在控件后面，视觉阅读顺序和辅助技术的阅读顺序也更稳定。

从数据角度看，FormData 进入 template.Execute 后，FieldErrors 只流向对应字段的提示节点；输入值和错误状态始终是同一个页面模型的一部分。

第一个错误字段要有稳定的焦点策略

仅给输入框加红色边框不够。服务端返回页面后，可以让 FirstError 作为页面上的一个稳定标识，再由很小的脚本将焦点放到对应控件；没有脚本时，错误摘要也要能被键盘找到。

  {{if .FirstError}}请先修正标记为错误的字段{{end}}

实际项目中，FirstError 应由固定字段顺序计算，而不是遍历 map 的顺序。map 迭代顺序不保证稳定，测试里偶尔先聚焦邮箱、偶尔先聚焦名称，会让问题难以复现。

避免回填逻辑带来的三个隐蔽问题

不要用重定向承载校验失败

校验失败重定向到 GET 会丢掉 POST 数据，除非额外引入一次性 session 或短期缓存；对一个普通表单来说，直接重新执行模板更清楚。

不要把未经处理的 HTML 当成安全提示

用户输入只作为字符串交给 html/template。不要把它转换成 template.HTML 来“修复”显示效果，那会绕过该上下文的自动转义边界。

不要让字段名和 HTML name 各自漂移

如果 Go 模型使用 DisplayName，表单使用 display_name，就在处理器边界显式映射一次；不要让校验器到处猜大小写或下划线规则。

用请求测试验收可见结果

至少覆盖三条回归路径：GET 返回空表单；非法邮箱和空名称时，响应仍包含原始显示名称、两个字段提示以及 aria-invalid="true"；合法提交后响应是 303 See Other，并指向 /registration/complete。验收关注页面状态，而不是只看处理器没有返回错误。

相关问题

html/template 和 text/template 该选哪个？

输出 HTML 时选 html/template。它与 text/template 接口相近，但会根据 HTML、属性、JavaScript 等上下文处理转义。

表单校验失败应该返回什么状态码？

如果页面正常渲染并展示用户可修正的输入，项目可以统一约定响应状态；关键是保持错误字段、输入值和可见提示的一致，不要用状态码替代页面状态。

什么时候应该改用 PRG？

保存成功后适合使用 Post/Redirect/Get，避免刷新重复提交；输入校验失败需要回显时，直接在 POST 请求中重新渲染更容易保留完整上下文。

小结

Go 表单回填的稳定做法是：处理器读取 POST，校验函数只返回字段错误，页面模型同时携带合法输入和错误状态，html/template 负责安全渲染；失败回页面，成功走重定向。焦点、aria-invalid 和固定字段顺序补上之后，用户看到的就不只是“提交失败”，而是一条能继续完成任务的路径。