Bubble Tea 最小程序需实现 tea.Model 接口并传入 tea.NewProgram() 启动；Init() 必须返回 tea.Cmd（可为 nil），Update() 未匹配消息须 fallback 返回 (m, nil)，View() 返回 string 由框架处理渲染。
用 Bubble Tea 开发 TUI，核心不是“怎么搭界面”，而是“怎么组织模型状态与命令流”——它本质是 Elm 架构的 Go 实现，状态不可变、更新靠 Msg 驱动，写错模式会导致 UI 卡死或响应丢失。
如何定义一个可运行的最小 Bubble Tea 程序
Bubble Tea 的入口不是 main() 里直接渲染，而是实现 tea.Model 接口，并传给 tea.NewProgram() 启动。漏掉 Init() 或返回 nil 命令，程序会静默退出；忘记在 Update() 中处理消息，按键就完全无反应。
-
Init()必须返回一个tea.Cmd（哪怕只是nil），否则程序启动后立即终止 -
Update(msg tea.Msg, m Model) (Model, tea.Cmd)中，未匹配的msg类型必须 fallback 到原样返回(m, nil)，否则 panic -
View()返回的是string，不是fmt.Print，所有换行/清屏逻辑由 Bubble Tea 自动处理
func main() {
p := tea.NewProgram(initialModel())
if _, err := p.Run(); err != nil {
log.Fatal(err)
}
}
type model struct{ count int }
func initialModel() model { return model{count: 0} }
func (m model) Init() tea.Cmd { return nil }
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
if msg.Type == tea.KeyCtrlC || msg.Type == tea.KeyEsc {
return m, tea.Quit
}
if msg.Type == tea.KeySpace {
m.count++
}
}
return m, nil
}
func (m model) View() string {
return fmt.Sprintf("Count: %d\n(press SPACE to increment, ESC to quit)", m.count)
}
如何正确处理键盘输入和退出逻辑
Bubble Tea 不自动拦截 Ctrl+C —— 它把所有按键都作为 tea.KeyMsg 发给 Update()，是否退出完全由你决定。常见错误是只监听 tea.KeyCtrlC 却忽略 tea.KeyEsc 或窗口关闭信号，导致用户无法退出。
- 退出必须显式返回
tea.Quit命令，不能只改状态变量 -
tea.KeyMsg的Type字段才是按键类型标识，String()是可读描述，不可用于判断 - 需要响应组合键（如 Ctrl+L）时，检查
msg.Type == tea.KeyCtrlL，不是拼字符串 - 终端被缩放或收到 SIGWINCH 时，会触发
tea.WindowSizeMsg，不处理不会崩溃，但可能影响布局计算
如何安全地在 TUI 中执行阻塞操作（比如 HTTP 请求）
不能在 Update() 里直接调用 http.Get 或 time.Sleep，这会让整个 UI 冻结。Bubble Tea 要求所有异步操作通过 tea.Cmd 启动，并用自定义 Msg 回传结果。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 用
tea.Tick或time.AfterFunc包装定时任务，避免time.Sleep - HTTP 请求需封装为函数，返回
tea.Cmd，并在 goroutine 中完成，完成后发送自定义Msg（如loadFinishedMsg{data: ..., err: ...}） - 请求中状态变更（如 loading = true）必须在
Update()处理对应Msg前就完成，否则 UI 不会及时反映 - 多个并发请求要小心
Msg乱序，建议带 request ID 或用 channel 配对
为什么你的组件不重绘？检查这三个地方
TUI 不刷新，90% 是因为没理解 “模型变更必须返回新实例” 这一约束。Go 没有强制不可变，但 Bubble Tea 的运行时只靠你返回的 Model 值判断是否需要重绘 —— 如果你修改了结构体字段却返回原指针，View() 就不会被再次调用。
- 不要用
*model作为Model类型，除非你每次Update都return &newModel - 切片、map、channel 等引用类型字段，只要内容变了，就必须在
Update()中构造新值并返回新模型（例如用append([]int{}, oldSlice...)） - 调试时可在
View()开头加fmt.Fprintln(os.Stderr, "redraw")，确认是否被调用；如果没输出，说明Update()返回的模型跟上次完全一致
最易被忽略的点：Bubble Tea 默认禁用鼠标事件，tea.WithMouseCellMotion 这类选项必须显式传入 tea.NewProgram() 才生效；还有，View() 返回的字符串里别混用 ANSI 转义序列（比如自己写 \033[2J），它有自己的清屏和光标控制逻辑，冲突会导致显示错乱。
