app

Documentation

Overview

Package app 提供了简便的方式管理 web.Server 的运行

Index

• func Restart[T any](c chan T, a App)
• func SignalHUP(a App)
• type App
  • func New(shutdown time.Duration, newServer func() (web.Server, error)) App
  • func NewCLI[T comparable](o *CLIOptions[T]) App
• type CLIOptions

Functions

func Restart

func Restart[T any](c chan T, a App)

Restart 根据信号 c 重启 a

可以结合其它方法一起使用，比如和 fsnotify 一起使用：

watcher := fsnotify.NewWatcher(...)
Restart(watcher.Event, s)

也可参考 SignalHUP。

func SignalHUP

func SignalHUP(a App)

SignalHUP 让 a 根据 HUP 信号重启服务

app := &App{...}
SignalHUP(app)

Types

type App

type App interface {
	// Exec 运行当前程序
	Exec() error

	// Restart 重启
	//
	// 中止旧的 [web.Server]，再启动一个新的 [web.Server] 对象。
	//
	// NOTE: 如果执行过程中出错，应该尽量阻止旧对象被中止，保证最大限度地可用状态。
	Restart()
}

App web.Server 的管理接口

func New

func New(shutdown time.Duration, newServer func() (web.Server, error)) App

New 声明一个简要的 App 实现

shutdown 每次关闭服务操作的等待时间； newServer 构建新服务的方法。

func NewCLI

func NewCLI[T comparable](o *CLIOptions[T]) App

NewCLI 提供一种简单的命令行生成方式

生成的命令行带以下几个参数：

• -v 显示版本号；
• -h 显示帮助信息；
• -a 执行的指令，该值会传递给 [CLIOptions.NewServer]，由用户根据此值决定初始化方式；
• -d 将当前程序作为守护进程的相关操作；
• -t 测试配置文件的语法是否正确；

T 表示的是配置文件中的用户自定义数据类型，可参考 config.Load 中有关 User 的说明。

如果是 CLIOptions 本身字段设置有问题会直接 panic。

type CLIOptions

type CLIOptions[T comparable] struct {
	ID string // 程序 ID

	// 程序版本
	//
	// 如果为空，则会尝试调用 [web.GetAppVersion] 获得相关的值。
	Version string

	// 初始化 [web.Server]
	//
	// id, version 即为 [CLIOptions.ID] 和 [CLIOptions.Version]；
	// o 和 user 为从配置文件加载的数据信息；
	// action 为 -a 命令行指定的参数；
	NewServer func(id, version string, o *server.Options, user T, action string) (web.Server, error)

	// 以服务运行的指令
	ServeActions []string

	// 命令行输出信息的通道
	//
	// 默认为 [os.Stdout]。
	Out io.Writer

	// 配置文件所在的目录
	//
	// 有以下几种前缀用于指定不同的保存目录：
	//  - ~ 表示系统提供的配置文件目录，比如 Linux 的 XDG_CONFIG、Windows 的 AppData 等；
	//  - @ 表示当前程序的主目录；
	//  - ^ 表示绝对路径；
	//  - # 表示工作路径；
	//  - 其它则是直接采用 [config.Dir] 初始化。
	// 如果为空则采用 [server.DefaultConfigDir] 中指定的值。
	//
	// NOTE: 具体说明可参考 [config.BuildDir] 的 dir 参数。
	ConfigDir string

	// 配置文件的文件名
	//
	// 相对于 ConfigDir 的文件名，不能为空。
	//
	// 需要保证序列化方法已经由 [config.RegisterFileSerializer] 注册；
	ConfigFilename string

	// 本地化的打印对象
	//
	// 若为空，则以 config.NewPrinter("*.yaml", locales.Locales) 进行初始化。
	//
	// 若是自定义，至少需要保证以下几个字符串的翻译项，才有效果：
	//  - cmd.show_version
	//  - cmd.action
	//  - cmd.show_help
	//  - can not be empty
	//  - cmd.test_syntax
	//  - status %v
	//  - syntax OK
	//
	// NOTE: 此设置仅影响命令行的本地化，[web.Server] 的本地化由其自身管理。
	Printer *message.Printer

	// 每次关闭服务操作的等待时间
	ShutdownTimeout time.Duration

	// 在命令行解析出错时的处理方式
	//
	// 默认值为 [flag.ContinueOnError]
	ErrorHandling flag.ErrorHandling

	// 守护进程的设置项
	//
	// 如果该值不为 nil，将会注册 -d 选项，
	// 通过 -d 可以对服务进行以下操作：
	//  - install 安装服务
	//  - uninstall 卸载服务
	//  - start 启动服务
	//  - stop 停止服务
	//  - restart 重启服务
	//  - status 查看服务状态
	Daemon *service.Config
}