Go Bubble Tea 怎么把耗时查询结果送回 Update

在 Bubble Tea 里，耗时查询不应该直接写进 Update。更稳妥的做法是把查询封装成 tea.Cmd：命令函数在后台完成 I/O，然后返回一个自定义 tea.Msg；运行时把这个消息送回 Update，由 Update 统一修改模型。

核心关系只有一句话：Cmd 负责做耗时工作，Msg 携带工作结果，Update 负责把结果写进状态。

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

先把 Cmd、Msg、Update 的职责分开

Bubble Tea 的模型循环会在收到消息后调用 Update，而 Update 可以返回下一条命令。耗时查询属于 I/O，不应让键盘事件处理和界面状态更新等待它完成。命令函数只拿到必要的输入，完成查询后返回结果消息即可。

下面的示例使用当前官方仓库展示的 v2 导入路径。如果项目仍使用 v1，替换导入路径即可，Cmd、Msg 和 Update 的协作思路不变。

定义带结果和错误的消息

自定义消息最好同时携带请求序号、结果和错误。这样 Update 不需要从共享变量读取查询状态，也能判断这次返回属于哪一次请求。

type queryResultMsg struct {
	requestID uint64 // 标识本次查询，防止旧结果覆盖新结果
	items     []string
	err       error // 成功时为 nil，失败时交给 Update 展示
}

type model struct {
	requestID uint64
	loading   bool
	items     []string
	err       error
}

func queryCmd(id uint64) tea.Cmd {
	return func() tea.Msg {
		items, err := loadItems() // 这里执行数据库、HTTP 或文件等耗时 I/O
		return queryResultMsg{requestID: id, items: items, err: err}
	}
}

queryCmd 没有接触 model，所以查询函数和界面状态不会互相绑死。错误也作为消息的一部分返回，避免在 goroutine 中直接打印或修改界面字段。

在 Init 或按键事件中启动查询

第一次进入界面时，可以从 Init 返回命令；用户按键触发时，则在对应的 Update 分支中返回命令。下面保留一个最小的按键入口，重点是请求序号在启动命令前递增。

func (m model) Init() tea.Cmd {
	return m.startQuery() // 首次进入界面时启动一次查询
}

func (m model) startQuery() tea.Cmd {
	m.requestID++
	m.loading = true
	m.err = nil
	return queryCmd(m.requestID)
}

func (m model) View() tea.View {
	if m.loading {
		return tea.NewView("正在查询，请稍候...\n") // 查询期间保留明确反馈
	}
	if m.err != nil {
		return tea.NewView("查询失败：" + m.err.Error() + "\n")
	}
	return tea.NewView(strings.Join(m.items, "\n") + "\n")
}

这里的 startQuery 返回了命令，但值接收者不会把 loading 的修改带回运行中的模型。实际使用时，应在 Update 里先更新副本，再返回命令；下面的完整分支会把这一点写清楚。

在 Update 中接收并应用查询结果

Update 收到自定义消息后，先比较请求序号，再处理错误或成功数据。只有当前请求的结果才允许写入模型。

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyPressMsg:
		if msg.String() == "r" {
			m.requestID++
			m.loading = true
			m.err = nil
			return m, queryCmd(m.requestID) // 返回 Cmd，让运行时异步执行查询
		}
		if msg.String() == "q" {
			return m, tea.Quit // 退出命令不携带查询结果
		}

	case queryResultMsg:
		if msg.requestID != m.requestID {
			return m, nil // 丢弃已经过期的查询结果
		}
		m.loading = false
		m.err = msg.err
		if msg.err == nil {
			m.items = msg.items // 只有 Update 修改展示数据
		}
	}
	return m, nil
}

成功消息和失败消息都会经过同一条路径。失败时保留旧列表并显示错误；成功时替换列表并结束加载状态。命令完成后通常返回 nil，表示没有下一条自动命令。

重复触发时为什么必须判断过期结果

假设用户连续按两次 r：请求 1 先开始，但请求 2 可能先完成。如果不带请求序号，随后到达的请求 1 会把较新的列表覆盖掉。序号并不会取消旧 I/O，它解决的是“旧结果能不能写状态”的问题。

如果旧查询本身需要停止，应进一步给查询函数传入可取消的 context.Context，并在数据源支持取消时调用取消函数。不要把“丢弃旧消息”和“取消后台工作”混成同一个动作：前者是状态一致性，后者是资源节省。

一个可直接套用的完整骨架

下面把消息、命令和更新分支放在一起。loadItems 代表实际的数据源，示例只展示回传链路。

type queryResultMsg struct {
	requestID uint64
	items     []string
	err       error
}

func queryCmd(id uint64) tea.Cmd {
	return func() tea.Msg {
		items, err := loadItems() // 耗时操作在 Cmd 中完成，不阻塞 Update
		return queryResultMsg{requestID: id, items: items, err: err}
	}
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyPressMsg:
		switch msg.String() {
		case "r":
			m.requestID++
			m.loading = true
			m.err = nil
			return m, queryCmd(m.requestID)
		case "q", "ctrl+c":
			return m, tea.Quit
		}
	case queryResultMsg:
		if msg.requestID != m.requestID {
			return m, nil // 旧请求完成也不能覆盖当前请求
		}
		m.loading = false
		m.err = msg.err
		if msg.err == nil {
			m.items = msg.items
		}
	}
	return m, nil
}

常见问题

能不能在 queryCmd 里直接修改 model？

不建议。命令和 Update 可能在不同执行时机运行，直接修改共享模型会让状态边界不清晰，也容易引入数据竞争。把数据放入 Msg，再由 Update 写入模型。

查询失败时要返回 nil Msg 吗？

不要。返回带 error 的自定义消息，Update 才能结束 loading 状态并展示可理解的错误。

请求序号能取消旧查询吗？

不能。它只保证旧结果不会覆盖新结果；需要节省连接或计算资源时，再使用支持取消的 context。

为什么查询结束后界面没有刷新？

检查命令函数是否真的返回了自定义消息、Update 是否包含对应的类型分支，以及 Update 返回的是否是更新后的模型副本。不要只在命令里修改字段。