app

Documentation

Overview

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

Index

• func Restart[T any](c chan T, s ServerApp)
• func SignalHUP(s ServerApp)
• type App
  • func (app *App) Exec() error
  • func (app *App) RestartServer()
• type CLI
  • func (cmd *CLI[T]) Exec(args []string) (err error)
  • func (cmd *CLI[T]) FlagSet(helpFlag bool, fs *flag.FlagSet) func(io.Writer) error
  • func (cmd *CLI[T]) RestartServer()
• type ServerApp

Functions

func Restart

func Restart[T any](c chan T, s ServerApp)

Restart 根据信号 c 重启 s

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

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

也可参考 SignalHUP。

func SignalHUP

func SignalHUP(s ServerApp)

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

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

Types

type App

type App struct {
	// 构建新服务的方法
	//
	// 每次重启服务时，都将由此方法生成一个新的服务。
	// 只有在返回成功的新实例时，才会替换旧实例，否则旧实例将一直运行。
	NewServer func() (web.Server, error)

	// 每次关闭服务操作的等待时间
	ShutdownTimeout time.Duration
	// contains filtered or unexported fields
}

App 简单的 web.Server 管理

func (*App) Exec

func (app *App) Exec() error

Exec 运行服务

func (*App) RestartServer

func (app *App) RestartServer()

RestartServer 触发重启服务

该方法将关闭现有的服务，并发送运行新服务的指令，不会等待新服务启动完成。

type CLI

type CLI[T any] struct {
	Name    string // 程序名称
	Version string // 程序版本

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

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

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

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

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

	// 本地化的相关设置
	//
	// 若为空，则以 server.NewPrinter(locales.Locales, "*.yaml") 进行初始化。
	//
	// NOTE: 此设置仅影响命令行的本地化(panic 信息不支持本地化)，[web.Server] 的本地化由其自身管理。
	Printer *message.Printer

	// 每次关闭服务操作的等待时间
	ShutdownTimeout time.Duration
	// contains filtered or unexported fields
}

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

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

• -v 显示版本号；
• -h 显示帮助信息；
• -a 执行的指令，该值会传递给 [CLI.NewServer]，由用户根据此值决定初始化方式；

T 表示的是配置文件中的用户自定义数据类型。

func (*CLI[T]) Exec

func (cmd *CLI[T]) Exec(args []string) (err error)

Exec 根据配置运行服务

args 表示命令行参数，一般为 os.Args。

如果是 CLI 本身字段设置有问题会直接 panic，其它错误则返回该错误信息。

func (*CLI[T]) FlagSet

func (cmd *CLI[T]) FlagSet(helpFlag bool, fs *flag.FlagSet) func(io.Writer) error

FlagSet 将当前对象的所有参数向 flag.FlagSet 注册

helpFlag 是否添加帮助选项。 如果是独立使用的建议设置为 true。 作为子命令使用的可以设置为 false。 fs 用于接收命令行的参数。

返回实际执行的函数，其签名为 `func(w io.Writer) error`，w 表示处理过程中的输出通道。

func (*CLI[T]) RestartServer

func (cmd *CLI[T]) RestartServer()

RestartServer 触发重启服务

该方法将关闭现有的服务，并发送运行新服务的指令，不会等待新服务启动完成。

type ServerApp

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

ServerApp 提供了管理 web.Server 的接口