Go html/template 表单校验失败怎么回填：字段错误、焦点定位与无障碍提示

登录页提交失败时，用户最不想看到的就是刚填完的内容全被清空的表单，外加一句干巴巴的“参数错误”。在 Go 的 net/http + html/template 组合里，最稳妥的做法是把输入值、字段错误和页面状态统一放进同一个视图模型里，校验失败时直接带着这份状态重新渲染页面；同时给错误字段加上 aria-invalid，自动把焦点定位到第一个需要修正的问题上。

先把一次失败提交拆成三种状态

很多表单处理函数会把所有逻辑揉在一块，但凡出问题就统一返回“提交失败”。这样写出来的代码，模板根本不知道该回填什么内容，也不清楚哪个控件需要补充错误说明。先把状态拆分开，后续写出来的HTML逻辑会清晰很多。

用 ViewModel 保留安全的旧输入

这里不直接把 r.Form 传给模板，而是单独定义一个只服务于页面渲染的结构体。它把业务对象和展示状态完全隔开，也让“哪些字段允许回填”变成代码里的明确约束。

type ProfileForm struct {
    DisplayName string
    Email       string
    Errors      map[string]string
    Notice      string
}

func newProfileForm(r *http.Request) ProfileForm {
    return ProfileForm{
        DisplayName: strings.TrimSpace(r.FormValue("display_name")),
        Email:       strings.TrimSpace(r.FormValue("email")),
        Errors:      map[string]string{},
    }
}

密码、验证码和一次性口令绝对不要放进这个结构体。哪怕后续日志、调试页面或者模板变量被误用，敏感字段也不会因为“方便回填”而意外泄露。邮箱是否统一转小写，要看业务是否把大小写当作身份标识的一部分，不要在渲染层悄悄修改用户输入的原始内容。

字段校验和 html/template 错误提示要成对出现

校验函数只负责填充错误信息，绝不手动拼接 HTML 片段。模板根据字段名自动决定 class、aria-invalid 和描述节点，这样错误文本仍由 html/template 负责安全输出。

func validateProfile(form *ProfileForm) bool {
    if form.DisplayName == "" {
        form.Errors["display_name"] = "请输入昵称"
    } else if utf8.RuneCountInString(form.DisplayName) > 30 {
        form.Errors["display_name"] = "昵称不能超过 30 个字"
    }
    if !strings.Contains(form.Email, "@") {
        form.Errors["email"] = "请输入可用的邮箱地址"
    }
    return len(form.Errors) == 0
}

模板里可以写一个很轻量的辅助函数，直接判断对应字段是否出错：

func hasError(errors map[string]string, name string) bool {
    _, ok := errors[name]
    return ok
}

昵称

{{with index .Errors "display_name"}}
  
{{.}}
{{end}}

错误说明的 id 和控件的 aria-describedby 必须一一对应。不要只把输入框标红：颜色是纯视觉提示，使用读屏器的用户仍需要能直接定位到具体错误原因。

让第一个错误字段先得到焦点

错误很多时，页面重新加载后焦点通常会回到地址栏或者表单最顶部。可以在服务端提前算出第一个错误字段，作为页面状态输出；模板只对这个字段添加 autofocus。示例里按固定顺序检查，完全避免 map 随机遍历顺序带来的页面跳动。

func firstError(form ProfileForm) string {
    for _, name := range []string{"display_name", "email"} {
        if _, ok := form.Errors[name]; ok {
            return name
        }
    }
    return ""
}

如果项目不希望依赖自动聚焦，也可以在页面顶部放一个简短状态区，并让它使用 role="status"。重点是让用户第一时间知道发生了什么，再把操作路径引导到可修改的控件上。

处理器只保留一条清楚的提交路径

把请求处理写成“解析表单—构造状态—校验—失败回填—成功保存”的线性顺序，排查问题时能直接对应到页面表现。下面的保存函数用接口占位，实际项目里替换成事务或者仓储调用即可。

func profileHandler(t *template.Template, save func(ProfileForm) error) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        form := newProfileForm(r)
        if r.Method == http.MethodPost {
            if !validateProfile(&form) {
                form.Notice = "请先修正标记的字段"
                _ = renderTemplate(t, w, "profile.html", form)
                return
            }
            if err := save(form); err != nil {
                http.Error(w, "暂时无法保存，请稍后再试", http.StatusInternalServerError)
                return
            }
            http.Redirect(w, r, "/profile?saved=1", http.StatusSeeOther)
            return
        }
        if r.URL.Query().Get("saved") == "1" {
            form.Notice = "资料已保存"
        }
        _ = renderTemplate(t, w, "profile.html", form)
    })
}

这里的重定向不是可选的附加功能，它把成功保存逻辑从 POST 请求中隔离出来。失败时保留当前页面状态，成功时进入新的 GET 页面；两条路径都更容易编写测试用例。

用浏览器和服务端各做一次检查

required、type="email" 和长度提示可以减少无效提交，但它们绝对不是安全边界。测试时至少覆盖下面几种场景：

• 昵称为空：只标记昵称错误，邮箱旧值仍正常保留。
• 邮箱格式错误：焦点落到邮箱输入框，错误说明能被控件正常关联到。
• 两个字段都错：焦点固定落在昵称输入框，不会因为 map 遍历顺序改变。
• 保存失败：不把数据库错误原文展示给用户，日志里记录完整内部细节。
• 保存成功后刷新：浏览器刷新 GET 请求，不会再次写入重复资料。

单元测试可以直接检查 ProfileForm.Errors 和渲染结果中的 aria-invalid。浏览器端再用键盘完整走一遍 Tab、修改、再次提交的流程，确认焦点没有被脚本带到不可见元素上。

常见问题

为什么不能把整个请求表单直接传给模板？

请求表单包含业务暂时不需要、甚至不应该回显的字段。ViewModel 能明确规定允许回填的内容，减少敏感数据和错误字段混在一起的概率。

错误文本应该放在页面顶部还是输入框旁边？

字段错误放在输入框旁边，页面顶部再补充一句总提示。这样习惯视觉操作的用户能快速定位，使用辅助技术的用户也能通过描述关联关系读到具体原因。

没有 JavaScript，焦点定位还有效吗？

服务端模板可以给第一个错误字段输出 autofocus，不依赖脚本也能正常工作。如果浏览器策略或组件不接受自动聚焦，至少保证错误顺序、关联说明和键盘操作路径稳定可用。

校验失败后要不要重定向？

一般不要。重定向会丢掉旧输入和字段错误；把重定向留给成功保存后的 GET 请求，能同时保留失败上下文并避免成功后的重复提交。

收尾：把“失败”变成下一步动作

好的表单错误处理不是多写一句提示，而是让用户知道哪一项需要改、改完后从哪里继续操作。Go 侧用 ViewModel 保存安全旧值和字段错误，模板侧把错误文本、aria-invalid、aria-describedby 与焦点顺序连起来，再用成功重定向收住提交边界，这套组合足够覆盖大多数服务端渲染表单场景。