app

package
v1.0.4 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

app 应用引导包

把「配置加载 → 日志初始化 → 基础组件装配 → 资源初始化 → 路由注册 → HTTP 启动与优雅停机」的标准样板收敛为一个入口,业务 main 只保留配置结构体与少量钩子;基础组件(数据库、Redis、链路追踪、定时任务等)经 Wire 一行一个接入,业务特有逻辑走 Init / Close 钩子。

快速开始

业务配置结构体内嵌 app.Base 获得 server / log 两个约定配置节,其余业务节自行声明;基础组件经 Wire 装配(各组件包提供一行式适配器 NewBoot):

package main

import (
	"gitee.com/usmos/basic-go/app"
	"gitee.com/usmos/basic-go/cache"
	"gitee.com/usmos/basic-go/database"
	"gitee.com/usmos/basic-go/database/mysql"
	"gitee.com/usmos/basic-go/logger"
	"gitee.com/usmos/basic-go/trace"
)

// Conf 配置文件: server / log 节来自 app.Base, 业务节自行声明
type Conf struct {
	app.Base
	Database mysql.MySQL  `yaml:"database"`
	Redis    cache.Redis  `yaml:"redis"`
	Trace    trace.Config `yaml:"trace"`
}

func main() {
	app.MustRun(&app.Boot[Conf]{
		EnvPrefix: "MYAPP", // 环境变量前缀
		Watch:     true,    // 配置热更新
		Wire: func(c *Conf) []app.Component { // 基础组件一行一个: 按序 Init, 逆序 Close
			return []app.Component{
				trace.NewBoot(c.Trace),                 // 首位: 逆序释放时最后关闭(在途 span 全量刷盘)
				database.NewBoot(&c.Database, &User{}), // 连接 + 自动迁移
				cache.NewBoot(&c.Redis),                // 连接(含探活)
			}
		},
		Init:  func(c *Conf) error { return orderQueue.Start() }, // 业务特有逻辑
		Close: func() { orderQueue.Stop() }, // HTTP 停机后先释放业务组件, 再逆序释放 Wire 组件
		OnChange: func(c *Conf) { // 热更新: 新配置已回填
			logger.Info("配置热更新完成")
		},
	})
}

路由注册直接在 Run 之前用 ginx.NewGroup 完成,或声明 Boot.Routes 交给引导层统一注册。

组件快捷接入(Wire)

Wire 收敛基础组件的接入样板(连接、全局注入、关停配对),组件包提供同构适配器,一行一个:

适配器 Init Close 说明
trace.NewBoot(c.Trace) 初始化 TracerProvider 刷盘在途 span Wire 放首位(最后释放);贡献 span 中间件,接管 X-Request-Id
snowflake.NewBoot() workerID 环境变量 → 出口 IP 推导 空实现 雪花全局节点
database.NewBoot(&c.Database, &User{}) 连接 + AutoMigrate 释放连接 全局单数据源约定
cache.NewBoot(&c.Redis) 连接 + Ping 探活 释放连接 全局单例
cron.NewBoot(c.Cron, cron.Job{...}) 建调度器 + 注册任务 + 启动 停止并等待在途任务 表达式注册期校验

装配语义:

  • 顺序:组件按 Wire 返回顺序 Init(失败即中断启动);HTTP 优雅停机后先执行业务 Close 钩子,再逆序释放组件——依赖他者的组件排后面,需最后释放的(如 trace)排首位
  • 回滚:任一组件初始化失败,已初始化组件(含失败者自身已占用的部分资源,如连接已建而迁移失败)会被逆序 Close;单个组件关停 panic 被 recover,不影响其余组件释放
  • 接口:Component(Init / Close,结构化匹配——自定义组件实现同名方法即可接入,无需 import app)、可选 Middlewarer(贡献 HTTP 中间件,路由构建前按装配顺序注入)、可选 Namer(日志标识)
  • 快照:Wire 对配置做启动期一次性快照,组件配置热更新不生效、重启生效(与 server 节一致)

也可继续在 Init / Close 钩子手动编排组件(Wire 未设置时行为与旧版完全一致)。

启动与关停顺序

扫描加载配置 -> 日志初始化 -> 组件装配(Wire, 按序 Init) -> Init 钩子 -> 路由注册 -> HTTP 服务阻塞运行
-> (收到退出信号, HTTP 优雅停机) -> Close 钩子 -> 组件逆序释放 -> 日志刷盘 -> 停止热更新监听

关停顺序先停 HTTP 再释放资源,保证处理中的请求不会访问到已关闭的连接。

Boot 配置

字段 类型 说明
Suffix string 配置文件后缀,默认 yaml
Dir string 配置扫描目录,默认 ./
FilePrefix string 配置文件名前缀,默认 config(如 config-database.yaml)
EnvPrefix string 环境变量前缀,为空时不启用环境变量覆盖
Watch bool 开启配置热更新;文件改动自动回填并触发 OnChange
Wire func(*C) []Component 组件装配钩子,配置/日志就绪后、Init 钩子前调用;组件按序 Init、逆序 Close,失败自动回滚
Init func(*C) error 资源初始化钩子,日志就绪后、服务启动前执行,返回错误中断启动
Close func() 资源释放钩子,HTTP 优雅停机后执行
OnChange func(*C) 热更新回调,新配置回填后调用(需 Watch 开启)
Routes []ginx.Router 待注册路由模块,Init 之后统一注册

Config 约定

Run 从配置结构体中提取 server / log 两个约定节,通过 Config 接口完成:

类型 / 方法 说明
app.Base 约定段默认实现(Server ginx.Gin + Log logger.LogConfig),业务结构体内嵌即满足
Config.Gin() 返回 HTTP 服务配置段
Config.Logging() 返回日志配置段

不内嵌 Base 时可自行实现两个方法(如需要更灵活的配置拆分)。

与 lifecycle 的分工

HTTP 服务自身的信号处理与优雅停机已内聚在 ginx.Run 中,web 应用经 app.Run 启动时无需再套 lifecycle——两套信号监听会相互竞争,且 lifecycle 的 Stop 无法联动 ginx 的停机。

lifecycle 适用于非 HTTP 长驻组件(后台消费协程、定时任务等):在 Init 钩子中创建 lifecycle.App 并 Start,Close 钩子中 Stop,即可与主流程共用同一关停时序。

注意事项

  • server 配置节热更新不生效:引擎与 http.Server 在启动时已构建,server 节的改动(如端口)需重启生效;动态配置请放业务节并经 OnChange 感知
  • 组件配置热更新不生效:Wire 装配发生在启动期,组件对配置做一次性快照,组件节的改动需重启生效(与 server 节一致)
  • 热更新回填的并发同步:OnChange 在监听协程中回填配置结构体,其他 goroutine 读取时的同步由业务负责(回调 panic 由 config 包捕获,不会杀死进程)
  • 日志节缺失也可用:log 节缺失时按零值初始化(level 回退 info,输出 stderr)
  • 配置文件约定:默认只扫描 Dir 下 FilePrefix 前缀的同后缀文件,按文件名排序合并;需要其他加载方式(多目录、指定文件)时用 config 包自行组装

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

func MustRun

func MustRun[C any](b *Boot[C])

MustRun Run 的 panic 版本, 供 main 一行启动使用。

func Run

func Run[C any](b *Boot[C]) error

Run 应用引导入口, 按固定顺序完成整个启动流程并阻塞至服务优雅停机:

扫描加载配置 -> 日志初始化 -> 组件装配(Wire) -> Init 钩子 -> 路由注册
-> HTTP 服务阻塞运行 -> (收到退出信号, HTTP 优雅停机) -> Close 钩子
-> 组件逆序释放 -> 日志刷盘 -> 停止热更新监听

关停顺序先停 HTTP 再释放资源, 保证处理中的请求不会访问到已关闭的连接。

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 两个配置节。

func (*Base) Gin

func (b *Base) Gin() *ginx.Gin

Gin 返回 HTTP 服务配置段。

func (*Base) Logging

func (b *Base) Logging() logger.LogConfig

Logging 返回日志配置段。

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 引擎的全局中间件。

type Namer added in v1.0.4

type Namer interface {
	Name() string
}

Namer 组件可选实现: 返回组件名, 用于启动失败错误与关停日志的标识; 未实现时回退为类型名(%T)。

Jump to

Keyboard shortcuts

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