app

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: 5 Imported by: 0

README

app 应用引导包

把「配置加载 → 日志初始化 → 资源初始化 → 路由注册 → HTTP 启动与优雅停机」的标准样板收敛为一个入口,业务 main 只保留配置结构体与少量钩子,从近百行降到三十行左右。

快速开始

业务配置结构体内嵌 app.Base 获得 server / log 两个约定配置节,其余业务节自行声明:

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"
)

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

func main() {
	app.MustRun(&app.Boot[Conf]{
		EnvPrefix: "MYAPP", // 环境变量前缀
		Watch:     true,    // 配置热更新
		Init: func(c *Conf) error { // 资源初始化
			if err := c.Database.Connect(); err != nil {
				return err
			}
			return c.Redis.Connect()
		},
		Close: func() { database.Close(); cache.Close() }, // HTTP 停机后释放连接
		OnChange: func(c *Conf) { // 热更新: 新配置已回填
			logger.Info("配置热更新完成")
		},
	})
}

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

启动与关停顺序

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

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

Boot 配置

字段 类型 说明
Suffix string 配置文件后缀,默认 yaml
Dir string 配置扫描目录,默认 ./
FilePrefix string 配置文件名前缀,默认 config(如 config-database.yaml)
EnvPrefix string 环境变量前缀,为空时不启用环境变量覆盖
Watch bool 开启配置热更新;文件改动自动回填并触发 OnChange
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 感知
  • 热更新回填的并发同步: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 按固定顺序完成启动并阻塞至优雅停机:

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

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

与 lifecycle 的分工: HTTP 服务自身的信号处理与优雅停机已内聚在 ginx.Run 中, web 应用经 Run 启动时无需再套 lifecycle(两套信号监听会相互竞争); lifecycle 适用于非 HTTP 长驻组件(后台消费协程、定时任务等), 在 Init 钩子中启动、Close 钩子中停止, 即可与主流程共用同一关停时序。

使用示例:

type Conf struct {
    app.Base // server / log 配置节
    Database mysql.MySQL `yaml:"database"`
}

func main() {
    app.MustRun(&app.Boot[Conf]{
        Watch: true,
        Init:  func(c *Conf) error { return c.Database.Connect() },
        Close: func() { database.Close() },
    })
}

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 应用引导入口, 按固定顺序完成整个启动流程并阻塞至服务优雅停机:

扫描加载配置 -> 日志初始化 -> 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

	// ---- 业务钩子(按执行顺序) ----
	// 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 Config

type Config interface {
	// Gin 返回 HTTP 服务配置段; 该段热更新不会重建运行中的引擎, 重启后生效
	Gin() *ginx.Gin
	// Logging 返回日志配置段
	Logging() logger.LogConfig
}

Config 应用配置约定, Run 据此提取 HTTP 服务与日志配置段。 业务配置结构体内嵌 Base 即自动满足, 也可自行实现。

Jump to

Keyboard shortcuts

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