lifecycle

package
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 6 Imported by: 0

README

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 包注释):

  1. 用户回调(startFunc/stopFunc)一律在锁外执行
  2. cancel() 为非阻塞操作(仅关闭 done 通道),持锁调用安全
  3. 运行协程在 wg.Done() 之前完成 runErr 赋值,保证 Start 读到完整结果

注意事项

  • SetupSignalHandler 在 Start 之前调用时,先于 Start 到达的信号会被丢弃(此时应用尚未运行,Stop 返回错误)
  • StopFunc 执行期间 Running() 仍为 true(状态在收尾完成后才重置),且在 stopFunc 内调用 Stop() 是安全的(幂等)
  • Start 返回即代表整个生命周期完全结束(运行协程已退出、收尾已执行),无需额外等待

Documentation

Overview

Package lifecycle 提供基于 context 的应用生命周期管理封装。

生命周期模型: Start(startFunc -> runFunc -> stopFunc) 阻塞执行直至运行函数返回, 或外部调用 Stop / 触发系统信号; 运行函数通过 ctx 感知取消信号, 实现优雅退出。

并发安全: 内部仅持有一把互斥锁, 且锁内绝不调用用户回调(startFunc/stopFunc 均在锁外 执行), cancel() 为非阻塞操作, 因此不存在死锁路径。

使用示例:

app := lifecycle.NewApp()
app.SetupSignalHandler() // Ctrl+C / kill 触发优雅停止
_ = app.Start(nil, func(ctx context.Context) error {
	<-ctx.Done() // 监听取消信号, 退出前完成清理
	return nil
}, nil)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App 管理应用生命周期与上下文。 cancel 非 nil 即代表应用处于运行态, 所有方法并发安全。

func NewApp

func NewApp() *App

NewApp 创建一个新的 App 实例。

func (*App) Context

func (app *App) Context() context.Context

Context 返回 App 当前管理的上下文, 供外部按需获取。 未启动过时返回 context.Background。

func (*App) Running

func (app *App) Running() bool

Running 返回应用是否正在运行。 运行函数退出到 Start 返回之间的短暂窗口内仍视为运行中。

func (*App) SetupSignalHandler

func (app *App) SetupSignalHandler()

SetupSignalHandler 注册系统信号, 实现 Ctrl+C / kill 的优雅停止。 应在 Start 之前调用; 首个信号触发 App.Stop, 且信号监听随之注销, 第二个信号将按系统默认行为直接终止进程, 可作为收尾卡死时的强制退出手段。

func (*App) Start

func (app *App) Start(startFunc StartFunc, runFunc RunFunc, stopFunc StopFunc) error

Start 启动应用并阻塞, 直到运行函数返回或外部调用 Stop/触发停止信号。

执行顺序: startFunc(同步) -> runFunc(独立协程) -> stopFunc(同步收尾)。 返回值: 运行错误与收尾错误的合并(errors.Join); 运行函数因主动停止返回 context.Canceled 时视为正常退出, 不作为错误。

func (*App) Stop

func (app *App) Stop() error

Stop 主动停止当前运行的任务: 取消上下文, 运行函数应监听 ctx 并尽快退出。 可重复调用(幂等); 应用未运行时返回错误。

type RunFunc

type RunFunc func(ctx context.Context) error

RunFunc 运行函数: 在独立协程中执行, 必须监听 ctx 取消信号并尽快返回; 若不监听 ctx, Stop 之后 Start 仍会阻塞等待本函数自然退出。

type StartFunc

type StartFunc func() error

StartFunc 启动前置函数: 在运行函数之前同步执行(不持有锁), 返回错误会中断启动流程并回滚应用状态, 保证 App 可被再次 Start。

type StopFunc

type StopFunc func() error

StopFunc 停止收尾函数: 在运行函数退出后、Start 返回前同步执行(不持有锁), 适合执行资源释放等清理动作, 返回错误会与运行错误合并后由 Start 返回。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL