bootstrap

README

bootstrap

应用生命周期引导——统一骨架/资源注册/优雅关停/健康检查

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/bootstrap@v0.4.1

这个仓库做什么

bootstrap 是应用生命周期引导：bootstrap.Run 提供「初始化 → 运行 → 优雅关停」 的统一骨架——资源注册、goroutine 托管、关停顺序、超时兜底全部内建。

快速使用

import (
    "github.com/oekit/bootstrap/bootstrap"
    ekithertz "github.com/oekit/hertz/hertz"
)

bootstrap.Run(cfg, func(app *bootstrap.App) error {
    h := hertzserver.New(...)
    ekithertz.RunServer(app, "my-service", h)   // server 接入生命周期
    app.AddResource("db", func(ctx context.Context) error { return dbPool.Close() })
    app.GoBackground("worker", workerLoop)       // 托管后台 goroutine（panic 兜底）

    <-app.Context().Done() // ★ 长驻服务必须阻塞：返回即视为服务结束
    return nil
})

健康检查

import "github.com/oekit/bootstrap/bootstrap/healthz"

healthz.RegisterCheck("db", pingDB)   // 多 check 并发探测、总超时、panic 隔离
code, body := healthz.Handle(ctx)      // 全通过 200，任一失败 503 + 详情

// Hertz 服务无需手写 handler：github.com/oekit/hertz 的 health 子包
// 提供 RegisterHealthRoutes(h)，内部消费本包 Handle

语义要点

• app.AddResource(name, closer)：关停时按注册逆序释放
• app.GoBackground(name, fn)：托管后台 goroutine（panic 被 recover）
• 时间关系（K8s）：发现延迟 < preStop < server 最大延迟 < ExitWaitTime < terminationGracePeriod

边界

• Hertz/Kitex 的 RunServer 接入本骨架；NNS 注册用 nnsc.RunWithLifecycle

矩阵总览（23 活跃模块，自动生成）

模块	内容	矩阵内依赖
pkg	微工具集 18 合 1（errors/validator/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/uidgen/cache/bufiox/strmap）	—
concurrency	并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）	—
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停	—
core	应用基建件（governance 治理 schema / config 配置加载 / lifecycle 契约 / network IP 工具 / version）	logx
istio	Istio Proxyless——Kitex xDS 动态熔断	—
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge	core、logx
data	缓存检查器（TTL/failTTL/inflight 合并）+ LocalCache	concurrency、logx
gorm	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储	logx、pkg
redis	Redis 全家——客户端封装、缓存后端、分布式锁	concurrency、data、logx
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断/重试/指标/OTel 透传	concurrency、core、logx、metrics、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具、Octopus 推送	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）	concurrency、logx
middleware	Hertz 自研标准中间件栈 + contrib 桥接 + hmw	concurrency、core、logx、metrics、pkg、registry、tracing
nns	NNS 服务治理客户端——provider 无关发现/配置/实例缓存	concurrency、core、logx、registry
nns-endpoint	NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用生命周期引导——bootstrap.Run 骨架 + healthz	concurrency、logx
handler	HTTP handler 层——通用 CRUD Handler、参数绑定、版本端点	concurrency、core、gorm、logx、metrics、middleware、pkg、registry、tracing
hertz	Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel	bootstrap、concurrency、core、logx、metrics、nns、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE