Documentation
¶
Overview ¶
Package bootstrap 定义组件化启动编排。
本文件保留组件接口与轻量组件；重量级组件（metrics/tracing/NNS） 位于嵌套 module：github.com/oekit/bootstrap/obs 与 github.com/oekit/bootstrap/nacos，以 BootstrapperOption 注入。
Package bootstrap 提供 oekit 微服务的启动编排——纯编排壳，零重依赖。
职责：App 生命周期（ctx/资源注册/后台任务）、组件化 Bootstrapper、 信号监听与优雅关闭、WorkerManager。
组件化接入 ¶
重量级能力以嵌套 module 形式提供，经 BootstrapperOption 函数注入：
import (
"github.com/oekit/bootstrap"
"github.com/oekit/bootstrap/nacos" // Nacos/NNS 注册（按需）
"github.com/oekit/bootstrap/obs" // Prometheus/OTel（按需）
)
b, _ := bootstrap.New(
bootstrap.WithServiceName("my-service"),
nacos.WithNNS(cfg.Nacos, cfg.Port, cfg.DepServices),
obs.WithMetrics(),
obs.WithTracing(tracing.Config{Endpoint: "otel:4317"}),
)
_ = b.Run(userFn)
第三方集成实现 Component 接口后经 WithComponent 注入即可。
多 Server 场景 ¶
启动多个 server，通过 AddResource 注册关闭函数（逆序执行）：
app.AddResource("hertz", func(ctx context.Context) error { return h.Shutdown(ctx) })
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run 启动服务，阻塞直到收到关闭信号或 userFn 返回。
这是兼容入口，内部委托至组件化 Bootstrapper。 推荐新代码直接使用 New(opts...).Run(userFn) 以获得更灵活的组件组合能力； Nacos/NNS 与可观测性组件分别来自：
github.com/oekit/bootstrap/nacos （nacos.WithNNS / WithRequiredNNS） github.com/oekit/bootstrap/obs （obs.WithMetrics / WithTracing）
执行顺序：
- 创建 App，调用 userFn(app) 启动用户服务
- 监听 SIGINT/SIGTERM 信号
- 优雅关闭
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App 是应用生命周期管理器，统一管理资源注册、后台任务和优雅关闭。
用法：
app := bootstrap.NewApp(shutdownMgr)
app.AddResource("db", db.Close)
app.GoBackground("poller", func(ctx context.Context) { ... })
// shutdown 时自动按注册逆序关闭所有资源和等待后台任务退出
func (*App) AddResource ¶
AddResource 注册需要在关闭时释放的资源。 name 用于日志标识，closer 是关闭函数。
func (*App) GoBackground ¶
GoBackground 启动一个带 panic recovery 的后台 goroutine。 关闭时通过 ctx 取消信号通知退出，并等待所有后台任务完成。
func (*App) RequestShutdown ¶
func (a *App) RequestShutdown()
RequestShutdown 请求应用进入关闭流程：取消根 context，解除 userFn 中 `<-app.Context().Done()` 的阻塞，使其返回并触发 shutdown.Manager 的优雅 关闭序列。幂等；在关闭序列中再次调用是安全的（cancel 本身幂等）。 典型用途见 lifecycle.App.RequestShutdown。
func (*App) SetWaitTimeout ¶
SetWaitTimeout 设置 GoBackground goroutine 的 drain 超时。 超时后 wg.Wait 被跳过，日志警告仍在运行的 goroutine 数量。 默认 30s；传 0 禁用超时（无限等待，仅在确信所有 goroutine 会自行退出时使用）。
type Bootstrapper ¶
type Bootstrapper struct {
// contains filtered or unexported fields
}
Bootstrapper 是组件化应用编排器。
通过函数选项配置启动组件；重量级集成（Nacos/NNS、Prometheus/OTel） 位于嵌套 module，以 Option 函数形式注入，根包保持零重依赖：
b, err := bootstrap.New(
bootstrap.WithServiceName("my-service"),
nacos.WithNNS(nacosCfg, 8080, deps), // github.com/oekit/bootstrap/nacos
obs.WithMetrics(), // github.com/oekit/bootstrap/obs
obs.WithTracing(tracing.Config{...}),
)
if err != nil { log.Fatal(err) }
b.Run(func(app *bootstrap.App) error {
h := server.New(server.WithHostPorts(":8080"))
app.AddResource("hertz", h.Shutdown)
return h.Run()
})
本地开发和测试场景可不添加任何外部依赖组件。
func (*Bootstrapper) AddComponent ¶ added in v0.3.0
func (b *Bootstrapper) AddComponent(c Component)
AddComponent 追加启动组件（动态注入）。 导出以支持嵌套 module 与第三方实现注入，与 WithComponent 等价。
type BootstrapperOption ¶
type BootstrapperOption func(*Bootstrapper)
BootstrapperOption 配置 Bootstrapper。
func WithComponent ¶
func WithComponent(c Component) BootstrapperOption
WithComponent 添加自定义组件——第三方集成注入的标准入口。
实现 Component 接口的任意类型都可通过本方法接入启动编排； 嵌套 module（bootstrap/nacos、bootstrap/obs）的 WithXxx 选项 内部即委托此方法。
func WithServiceName ¶
func WithServiceName(name string) BootstrapperOption
WithServiceName 设置服务名称（必填）。
func WithShutdownHook ¶
func WithShutdownHook(name string, hook func(ctx context.Context) error) BootstrapperOption
WithShutdownHook 添加自定义关闭钩子。
func WithShutdownTimeout ¶
func WithShutdownTimeout(d time.Duration) BootstrapperOption
WithShutdownTimeout 设置优雅关闭超时，默认 10 秒。
type Component ¶
type Component interface {
// Name 返回组件标识，用于日志。
Name() string
// Init 执行组件初始化，可通过 app 和 mgr 注册资源和关闭钩子。
Init(ctx context.Context, app *App, mgr *shutdown.Manager) error
}
Component 是可插拔的启动组件接口。 每个组件负责一项启动任务（如指标注册、追踪初始化、服务注册等）， 并可通过 mgr 注册关闭钩子。
type Config ¶
type Config struct {
// ServiceName 服务名称，用于 metrics 标签和组件回填。
ServiceName string
// ShutdownTimeout 优雅关闭总超时，默认 10 秒。
ShutdownTimeout time.Duration
}
Config 是启动编排的配置（兼容入口）。
重量级能力（Nacos/NNS 注册、Prometheus/OTel）已迁至嵌套 module， 请改用组件化 API：bootstrap.New + bootstrap/nacos、bootstrap/obs 的 WithXxx 选项注入。
type ServiceNameAware ¶ added in v0.3.0
type ServiceNameAware interface {
SetServiceName(name string)
}
ServiceNameAware 需要感知服务名的组件实现此接口； New() 在应用完全部选项后统一回填（与 WithServiceName 的调用顺序无关）。 嵌套 module 中的组件实现它即可参与回填，根包无需感知具体组件类型。
type ShutdownHookComponent ¶
ShutdownHookComponent 通用关闭钩子组件，用于注册自定义资源释放逻辑。
type WorkerManager ¶
type WorkerManager struct {
// contains filtered or unexported fields
}
WorkerManager 管理一组周期性后台任务。
用法：
wm := bootstrap.NewWorkerManager(ctx)
wm.AddTicker("timeout-checker", 60*time.Second, func(ctx context.Context) {
buildSvc.CheckBuildTimeout(ctx)
deploySvc.CheckDeployTimeout(ctx)
})
wm.AddTicker("metrics-reporter", 30*time.Second, func(ctx context.Context) {
common.ReportQueueMetrics(ctx)
})
// ctx 取消时所有 worker 自动退出
func NewWorkerManager ¶
func NewWorkerManager(ctx context.Context) *WorkerManager
NewWorkerManager 创建后台任务管理器。 ctx 取消或 Close() 调用时所有任务自动退出。
func (*WorkerManager) AddOnce ¶
func (w *WorkerManager) AddOnce(name string, fn func(ctx context.Context))
AddOnce 注册一个一次性任务，在后台执行。
func (*WorkerManager) AddTicker ¶
func (w *WorkerManager) AddTicker(name string, interval time.Duration, fn func(ctx context.Context))
AddTicker 注册一个周期性任务，按 interval 间隔执行 fn。 ctx 取消时自动退出。
func (*WorkerManager) Close ¶
func (w *WorkerManager) Close()
Close 取消 context、阻止新任务注册并等待所有已启动的任务退出。 多次调用是安全的。
Source Files
Directories