lifecycle 应用生命周期管理包
基于 context 的应用生命周期封装:以 Start(start -> run -> stop) 三段式模型管理程序从启动到退出的完整流程,支持优雅停止、系统信号处理与 panic 隔离。
特性
- 三段式生命周期:启动前置 → 运行主体 → 停止收尾,职责清晰
- ctx 驱动的优雅退出:运行函数通过
ctx 感知取消信号,Stop()/Ctrl+C 后可完成清理再退出
- 信号处理:首个 SIGINT/SIGTERM 触发优雅停止,第二个信号强制终止(收尾卡死时的逃生通道)
- panic 隔离:运行函数 panic 不会击穿整个进程,会被 recover 转为错误并照常执行收尾
- 可重启:生命周期结束后(含启动失败回滚)
App 实例可再次 Start
- 并发安全:所有方法可安全并发调用,不存在死锁路径(用户回调一律在锁外执行)
快速开始
package main
import (
"context"
"fmt"
"gitee.com/usmos/basic-go/lifecycle"
)
func main() {
app := lifecycle.NewApp()
app.SetupSignalHandler() // Ctrl+C / kill 触发优雅停止
err := app.Start(
// 启动前置: 初始化资源, 失败则中断启动并回滚状态
func() error {
fmt.Println("init resources")
return nil
},
// 运行主体: 必须监听 ctx 取消信号
func(ctx context.Context) error {
fmt.Println("service running")
<-ctx.Done() // 收到停止信号
fmt.Println("draining...")
return ctx.Err() // context.Canceled 会被视为正常退出
},
// 停止收尾: 运行函数退出后执行, 释放资源
func() error {
fmt.Println("release resources")
return nil
},
)
fmt.Println("exit:", err)
}
生命周期模型
Start() 调用
│
├─ startFunc() 同步执行; 失败 → 回滚状态并返回错误
├─ go runFunc(ctx) 独立协程; 退出/panic 后自动触发停止流程
│
│ ┌─ 外部 Stop() / 系统信号 ──→ cancel() ──→ ctx.Done()
│ └─ runFunc 自然返回
│
├─ <-ctx.Done() Start 解除阻塞
├─ wg.Wait() 等待运行协程完全退出(含 runErr 落盘)
├─ stopFunc() 锁外同步执行收尾
└─ return errors.Join(runErr, stopErr)
三个回调的执行时序与线程:
| 回调 |
执行线程 |
时机 |
失败影响 |
StartFunc |
Start 调用方协程,同步 |
运行函数之前 |
中断启动,状态回滚,可再次 Start |
RunFunc |
独立协程 |
收到 ctx 后应尽快返回 |
错误/panic 经 Start 返回值上报 |
StopFunc |
Start 调用方协程,同步 |
运行函数退出之后 |
错误与运行错误合并返回 |
接口总览
| 方法 |
说明 |
NewApp() |
创建生命周期实例 |
Start(startFunc, runFunc, stopFunc) |
启动并阻塞,直至运行结束;runFunc 不可为 nil |
Stop() |
主动停止:取消上下文;未运行时报错,重复调用安全 |
Running() |
是否处于运行态 |
Context() |
当前生命周期上下文;未启动过返回 context.Background |
SetupSignalHandler() |
注册 SIGINT/SIGTERM,应在 Start 之前调用 |
回调签名(见 app.go):
type StartFunc func() error // 启动前置
type RunFunc func(ctx context.Context) error // 运行主体(必须监听 ctx)
type StopFunc func() error // 停止收尾
关键语义
RunFunc 必须监听 ctx:这是本包的核心约定。Stop() 只负责取消上下文,若运行函数不监听 ctx 并返回,Start 将一直阻塞等待其自然退出
context.Canceled 视为正常退出:外部主动停止时运行函数通常返回 ctx.Err()(即 context.Canceled),不作为错误上报;返回值为 errors.Join(runErr, stopErr)
- panic 隔离:运行函数 panic 被 recover 并转为
run func panic: ... 错误,ctx 取消与 stopFunc 收尾照常执行
- 状态回滚:
startFunc 失败后 Running() 立即为 false,同一实例可直接再次 Start
- 信号双保险:首个信号优雅停止并注销监听;第二个信号交还系统默认处理(直接终止进程),用于收尾逻辑卡死时强制退出
并发安全设计
内部仅一把互斥锁,且遵循三条原则保证无死锁(详见 app.go 包注释):
- 用户回调(
startFunc/stopFunc)一律在锁外执行
cancel() 为非阻塞操作(仅关闭 done 通道),持锁调用安全
- 运行协程在
wg.Done() 之前完成 runErr 赋值,保证 Start 读到完整结果
注意事项
SetupSignalHandler 在 Start 之前调用时,先于 Start 到达的信号会被丢弃(此时应用尚未运行,Stop 返回错误)
StopFunc 执行期间 Running() 仍为 true(状态在收尾完成后才重置),且在 stopFunc 内调用 Stop() 是安全的(幂等)
Start 返回即代表整个生命周期完全结束(运行协程已退出、收尾已执行),无需额外等待