Go huh 用户取消表单后怎么区分取消与校验失败

在 Go huh 表单里，用户按退出键离开，调用方拿到的是 huh.ErrUserAborted；用户输入不合规时，Validate 只会把错误留在当前字段并阻止继续提交，form.Run() 不会因此返回“取消”。所以判断顺序应该是：先处理 Run 的返回值，再把提交、取消和其它错误分开。

官方地址：https://github.com/charmbracelet/huh

校验失败表示表单还在运行，取消表示表单已经被用户主动退出。不要用“有没有错误”这一件事推断用户意图，使用 errors.Is(err, huh.ErrUserAborted) 识别取消，用表单状态或字段错误处理校验。

先看清 huh 表单的三个出口

把 huh.Form 想成一个带门禁的交互边界，会比较容易定位问题：

• 提交：所有当前字段通过校验，表单进入完成状态，Run() 返回 nil。
• 取消：用户主动离开且没有提交，Run() 返回 huh.ErrUserAborted。
• 校验未通过：字段保留错误，当前表单继续显示，调用方暂时拿不到 Run() 的返回值。

最后一条是最容易被忽略的地方。校验函数返回的错误属于字段层，表单会因为当前分组存在错误而拒绝前进；它不是一次已经结束的表单运行错误。因此，下面这种写法会把正常的取消和真正的运行故障混在一起：

if err := form.Run(); err != nil {
	// 中文说明：所有非 nil 都显示成“取消”，会掩盖超时或运行时故障。
	fmt.Println("用户取消")
}

用 Validate 把校验失败留在表单内

Validate 应该只负责判断字段值是否可提交，并返回面向读者的提示。它不负责表达“用户取消”，也不应该在校验函数里修改订单、写文件或发送请求。

package main

import (
	"errors"
	"fmt"

	"charm.land/huh/v2"
)

func buildForm(project *string) *huh.Form {
	return huh.NewForm(
		huh.NewGroup(
			huh.NewInput().
				Title("项目名").
				Value(project).
				Validate(func(value string) error {
					// 中文说明：校验只返回字段错误，不把它包装成取消。
					if value == "" {
						return errors.New("项目名不能为空")
					}
					return nil
				}),
		),
	)
}

func main() {
	var project string
	form := buildForm(&project)

	// 中文说明：校验失败时 Run 仍停留在表单；只有提交或退出才离开这里。
	if err := form.Run(); err != nil {
		fmt.Println("表单退出：", err)
	}
}

用户把项目名留空并按提交键时，当前字段会显示校验消息，仍可以修改后再次提交。此时不能在外层立即执行“取消后的清理”逻辑，因为外层代码还没有收到 Run() 的返回。

用 errors.Is 识别真正的用户取消

当表单离开交互循环后，再处理返回值。判断 huh 定义的哨兵错误要用 errors.Is，这样即使上层再包一层错误，也不会因为字符串变化而失效。

func collectProject() (string, error) {
	var project string
	form := buildForm(&project)
	// 中文说明：把表单值和错误一起返回，提交分支才能安全读取结果。
	return project, form.Run()
}

func main() {
	project, err := collectProject()
	switch {
	case err == nil:
		// 中文说明：nil 只表示表单完成，可以把已经收集的值交给业务层。
		fmt.Println("提交项目：", project)
	case errors.Is(err, huh.ErrUserAborted):
		// 中文说明：用户主动退出，不保存草稿，也不要当成系统故障告警。
		fmt.Println("用户取消表单")
	case errors.Is(err, huh.ErrTimeout):
		// 中文说明：超时是运行策略结果，和用户按退出键是两种通知路径。
		fmt.Println("表单超时，请重新打开")
	default:
		// 中文说明：其它错误交给日志或上层重试策略，保留原始错误。
		fmt.Println("表单运行失败：", err)
	}
}

上面的示例把表单值和错误放在同一个函数边界返回，提交分支可以安全读取结果；取消或其它错误则不会误用半成品数据。若业务结果不止一个字段，可以继续把返回值换成结构体。

type formResult struct {
	Project string
}

func collectProject() (formResult, error) {
	var result formResult
	form := buildForm(&result.Project)
	if err := form.Run(); err != nil {
		// 中文说明：保留 huh 的错误身份，调用方才能用 errors.Is 分类。
		return formResult{}, err
	}
	return result, nil
}

不要把字段 Error 当成取消原因

字段错误的生命周期和取消错误不同：字段在当前表单里仍然存在，用户修正输入后可以再次尝试；取消错误则说明这一轮交互已经结束。排查时可按下面的表格定位：

尤其不要通过比较 err.Error() == "user aborted" 来判断取消。官方定义的是哨兵错误，errors.Is 才是稳定的分类方式。

嵌入 Bubble Tea 时再看 Form.State

如果 huh 表单作为 Bubble Tea 模型的一部分运行，除了错误身份，还可以看 Form.State。官方状态包括 huh.StateNormal、huh.StateCompleted 和 huh.StateAborted：

• StateNormal：还在填写，字段校验失败也会停留在这里。
• StateCompleted：表单已经满足提交条件。
• StateAborted：用户已经退出表单。

func formMessage(form *huh.Form) string {
	switch form.State {
	case huh.StateCompleted:
		// 中文说明：只有完成状态才把表单值交给后续命令。
		return "提交"
	case huh.StateAborted:
		// 中文说明：退出状态只结束交互，不触发保存命令。
		return "取消"
	default:
		// 中文说明：正常状态包含用户正在修正校验错误的阶段。
		return "继续填写"
	}
}

这里的判断解决的是模型状态，不替代 Run() 的错误分类。独立调用表单时优先用 errors.Is；嵌入 Bubble Tea 时，把状态转成消息或命令即可。两种场景都不要把“当前有字段错误”翻译成“用户取消”。

把提交、取消和失败通知接到不同回路

按照“触发场景—表单阶段—门禁—失败处理—通知复盘”的工作流来收口，调用方会更稳定：

1. 触发场景：打开表单只准备默认值，不在打开时写入最终数据。
2. 表单阶段：字段的 Validate 负责门禁，校验失败时留在当前阶段。
3. 完成出口：收到 nil 或 StateCompleted 后，再调用保存或提交命令。
4. 取消出口：匹配 huh.ErrUserAborted 或 StateAborted，只清理本轮临时状态。
5. 失败通知：超时和其它错误进入日志、重试或提示回路，不能伪装成用户取消。

这套分支的价值不在于多写一个 switch，而在于让权限、保存和通知都只响应正确的出口。例如取消时可以撤销临时文件，提交时才发出领域事件，校验错误则只更新界面提示。

常见追问

校验函数返回 error 后，Run 会立即返回吗？

不会。正常交互模式下，字段错误会阻止前进并继续显示表单，用户可以修正后再次提交。只有表单完成、用户退出或运行器遇到其它错误时，外层才会收到 Run() 的结果。

为什么不用比较错误文本？

错误文本适合展示，不适合做控制流契约。使用 errors.Is 匹配 huh.ErrUserAborted，同时保留其它错误用于日志和重试。

Bubble Tea 中只看 State 可以吗？

嵌入式模型可以用 State 判断完成、取消和继续填写；如果还要区分超时或底层运行异常，仍然要保留错误值并用 errors.Is 分类。

小结

Go huh 的关键边界是“校验失败不离开表单，用户取消才离开表单”。把 Validate 留在字段层，用 errors.Is(err, huh.ErrUserAborted) 处理取消，用 Form.State 表达嵌入式表单状态，最后只在提交出口执行保存，就能避免把用户取消、输入错误和系统故障混为一谈。

参考资料

• https://github.com/charmbracelet/huh
• https://pkg.go.dev/github.com/charmbracelet/huh
• https://raw.githubusercontent.com/charmbracelet/huh/main/form.go
• https://raw.githubusercontent.com/charmbracelet/huh/main/field_input.go