Documentation
¶
Overview ¶
Package app 提供应用引导层: 把配置加载、日志初始化、基础组件装配、资源初始化、 路由注册、HTTP 服务启动与优雅停机收敛为一个入口, 业务 main 只保留配置结构体 与少量钩子。
配置以约定方式加载: 默认扫描 ./ 下 config 前缀的 yaml 文件(如 config-database.yaml), 配置结构体内嵌 app.Base 获得 server / log 两个约定配置节, 其余业务节自行声明。 Run 按固定顺序完成启动并阻塞至优雅停机:
扫描加载配置 -> 日志初始化 -> 组件装配(Wire) -> Init 钩子 -> 路由注册 -> HTTP 服务阻塞运行 -> (收到退出信号, HTTP 优雅停机) -> Close 钩子 -> 组件逆序释放 -> 日志刷盘 -> 停止热更新监听
关停顺序先停 HTTP 再释放资源, 保证处理中的请求不会访问到已关闭的连接。
基础组件(数据库/Redis/链路追踪/雪花 ID/定时任务)经 Wire 声明式接入: 各组件包 提供同构适配器(database.NewBoot / cache.NewBoot / trace.NewBoot / snowflake.NewBoot / cron.NewBoot), 结构化匹配 Component 约定(Init/Close), 组件包不依赖本包; 组件按装配顺序初始化、逆序释放, 初始化失败自动回滚。业务特有逻辑仍走 Init/Close 钩子, 两者可并存; Wire 未设置时行为不变, 也可继续在钩子中手动编排。
与 lifecycle 的分工: HTTP 服务自身的信号处理与优雅停机已内聚在 ginx.Run 中, web 应用经 Run 启动时无需再套 lifecycle(两套信号监听会相互竞争); lifecycle 适用于非 HTTP 长驻组件(后台消费协程、定时任务等), 在 Init 钩子中启动、Close 钩子中停止, 即可与主流程共用同一关停时序。
使用示例:
type Conf struct {
app.Base // server / log 配置节
Database mysql.MySQL `yaml:"database"`
Trace trace.Config `yaml:"trace"`
}
func main() {
app.MustRun(&app.Boot[Conf]{
Watch: true,
Wire: func(c *Conf) []app.Component { // 基础组件一行一个
return []app.Component{
trace.NewBoot(c.Trace), // 链路追踪: 逆序释放时最后关闭
database.NewBoot(&c.Database, &User{}), // 连接 + 自动迁移
}
},
Init: func(c *Conf) error { return orderQueue.Start() }, // 业务特有逻辑
Close: func() { orderQueue.Stop() },
})
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Base ¶
type Base struct {
Server ginx.Gin `yaml:"server" toml:"server" json:"server" mapstructure:"server"` // HTTP 服务配置
Log logger.LogConfig `yaml:"log" toml:"log" json:"log" mapstructure:"log"` // 日志配置
}
Base 应用配置约定段的默认实现, 业务配置结构体内嵌后获得 server / log 两个配置节。
type Boot ¶
type Boot[C any] struct { // ---- 配置加载约定 ---- Suffix string // 配置文件后缀, 默认 yaml Dir string // 扫描目录, 默认 ./ FilePrefix string // 配置文件名前缀, 默认 config(如 config-database.yaml) EnvPrefix string // 环境变量前缀, 为空时不启用环境变量覆盖 Watch bool // 是否开启配置热更新; 开启后文件改动自动回填并触发 OnChange // ---- 组件装配 ---- // Wire 组件装配钩子: 配置加载与日志就绪后、Init 钩子前调用, 返回待接入的基础组件。 // 组件按返回顺序 Init(失败即中断启动并逆序回滚已初始化者); HTTP 优雅停机后先执行 // Close 钩子(业务逻辑), 再逆序释放组件——依赖他者的组件排后面, 需最后释放的 // (如 trace, 关停时刷盘在途 span)排首位。Wire 收敛通用基础组件样板, // 业务特有逻辑仍走 Init/Close 钩子, 两者可并存。 // 注意: Wire 对配置做启动期一次性快照, 组件配置热更新不生效, 重启生效 // (与 server 配置段行为一致)。 Wire func(cfg *C) []Component // ---- 业务钩子(按执行顺序) ---- // Init 资源初始化, 在日志就绪后、路由注册与服务启动前执行, 返回错误会中断启动。 Init func(cfg *C) error // Close 资源释放, 在 HTTP 服务优雅停机后执行, 数据库/缓存等连接在此关闭。 Close func() // OnChange 配置热更新回调: 新配置回填 cfg 后调用(需 Watch 开启)。 // 回调在监听协程中执行, panic 不会杀死进程; 与其他 goroutine 读写配置的同步由业务负责。 OnChange func(cfg *C) // Routes 待注册的路由模块, 在 Init 之后统一注册; 也可在 Run 之前用 ginx.NewGroup 直接注册 Routes []ginx.Router }
Boot 应用引导配置: 以约定方式加载配置并组织启动流程, 未设置的字段自动使用默认值。
type Component ¶ added in v1.0.4
type Component interface {
// Init 资源初始化, 返回错误会中断启动并逆序回滚已初始化的组件。
// panic 不做 recover: 启动期属编程错误, 与 Init 钩子行为一致, 快速失败
Init() error
// Close 资源释放。关停流程中逐个调用且各自带 recover, panic 不会击穿后续释放
Close()
}
Component 可接入 app 生命周期的组件约定, 经 Boot.Wire 装配后由 Run 统一调度: 配置与日志就绪后按装配顺序调用 Init; HTTP 优雅停机后先执行业务 Close 钩子, 再按逆序调用 Close——后初始化的先释放, 依赖他者的组件排在装配列表后面。
接口为结构化匹配: 各组件包提供的适配器(如 database.NewBoot)无需 import 本包。 Close 的语义约定: 尽力释放已占用资源、幂等、nil 安全——组件自身 Init 多步 部分失败时(如连接已建立、迁移失败), 回滚流程仍会调用其 Close 释放已占用部分。
type Config ¶
type Config interface {
// Gin 返回 HTTP 服务配置段; 该段热更新不会重建运行中的引擎, 重启后生效
Gin() *ginx.Gin
// Logging 返回日志配置段
Logging() logger.LogConfig
}
Config 应用配置约定, Run 据此提取 HTTP 服务与日志配置段。 业务配置结构体内嵌 Base 即自动满足, 也可自行实现。
type Middlewarer ¶ added in v1.0.4
type Middlewarer interface {
Middlewares() []gin.HandlerFunc
}
Middlewarer 组件可选实现: 贡献 HTTP 中间件(如 trace 的 span 中间件), Run 在组件初始化完成后、路由构建前按装配顺序追加到 HTTP 引擎的全局中间件。