app

Documentation

Overview

Package app 提供了简便的方式初始化 server.Server

目前有以下几种方式：

• App 简要的 server.Server 管理；
• NewServerOf 从配置文件构建 server.Server 对象；
• CLIOf 直接生成一个简单的命令行程序，结合了 App 和 NewServerOf 两者的功能；

NOTE: 这并不一个必需的包，如果觉得不适用，可以直接采用 server.New 初始化服务。

配置文件

NewServerOf 和 CLIOf 都是通过加载配置文件对项目进行初始化。 对于配置文件各个字段的定义，可参考源代码，入口在 config.go 文件的 configOf 对象。 配置文件中除了固定的字段之外，还提供了泛型变量 User 用于指定用户自定义的额外字段。

注册函数

当前包提供大量的注册函数，以用将某些无法直接采用序列化的内容转换可序列化的。 比如通过 RegisterEncoding 将 `gzip-default` 等字符串表示成压缩算法， 以便在配置文件进行指定。

所有的注册函数处理逻辑上都相似，碰上同名的会覆盖，否则是添加。 且默认情况下都提供了一些可选项，只有在用户需要额外添加自己的内容时才需要调用注册函数。

Index

• func CheckConfigSyntax[T any](configDir, filename string) error
• func NewPrinter(fsys fs.FS, glob string) *localeutil.Printer
• func NewServerOf[T any](name, version string, configDir, filename string) (*server.Server, *T, error)
• func RegisterCache(b CacheBuilder, name ...string)
• func RegisterEncoding(id, name string, f server.NewEncodingFunc)
• func RegisterFileSerializer(m MarshalFileFunc, u UnmarshalFileFunc, ext ...string)
• func RegisterLogsHandler(b LogsHandlerBuilder, name ...string)
• func RegisterMimetype(m server.MarshalFunc, u server.UnmarshalFunc, name string)
• func RegisterProblemBuilder(name string, b server.BuildProblemFunc)
• func RegisterUniqueGenerator(id string, b UniqueGeneratorBuilder)
• func SignalHUP(s ServerApp)
• type App
  • func (app *App) Exec() (err error)
  • func (app *App) RestartServer()
• type CLIOf
  • func (cmd *CLIOf[T]) Exec(args []string) (err error)
  • func (cmd *CLIOf[T]) FlagSet(helpFlag bool, fs *flag.FlagSet) (do func(io.Writer) error)
  • func (cmd *CLIOf[T]) RestartServer()
• type CacheBuilder
• type LogsHandlerBuilder
• type MarshalFileFunc
• type ServerApp
• type UniqueGeneratorBuilder
• type UnmarshalFileFunc

Functions

func CheckConfigSyntax

func CheckConfigSyntax[T any](configDir, filename string) error

CheckConfigSyntax 检测配置项语法是否正确

func NewPrinter

func NewPrinter(fsys fs.FS, glob string) *localeutil.Printer

NewPrinter 根据参数构建一个本地化的打印对象

语言由 localeutil.DetectUserLanguageTag 决定。 参数指定了本地化的文件内容。

func NewServerOf

func NewServerOf[T any](name, version string, configDir, filename string) (*server.Server, *T, error)

NewServerOf 从配置文件初始化 server.Server 对象

configDir 项目配置文件所在的目录； filename 用于指定项目的配置文件，相对于 configDir 文件系统。 序列化方法由 RegisterFileSerializer 注册的列表中根据 filename 的扩展名进行查找。 如果此值为空，将以 &server.Options{FS: fsys} 初始化 server.Server；

T 表示用户自定义的数据项，该数据来自配置文件中的 user 字段。 如果实现了 config.Sanitizer 接口，则在加载后进行自检；

func RegisterCache

func RegisterCache(b CacheBuilder, name ...string)

RegisterCache 注册新的缓存方式

name 为缓存的名称，如果存在同名，则会覆盖。

func RegisterEncoding

func RegisterEncoding(id, name string, f server.NewEncodingFunc)

RegisterEncoding 注册压缩方法

id 表示此压缩方法的唯一 ID，这将在配置文件中被引用； name 表示此压缩方法的名称，可以相同； f 生成压缩对象的方法；

func RegisterFileSerializer

func RegisterFileSerializer(m MarshalFileFunc, u UnmarshalFileFunc, ext ...string)

RegisterFileSerializer 注册用于文件序列化的方法

ext 为文件的扩展名，如果存在同名，则会覆盖。

func RegisterLogsHandler

func RegisterLogsHandler(b LogsHandlerBuilder, name ...string)

RegisterLogsHandler 注册日志的 [LogsWriterBuilder]

name 为缓存的名称，如果存在同名，则会覆盖。

func RegisterMimetype

func RegisterMimetype(m server.MarshalFunc, u server.UnmarshalFunc, name string)

RegisterMimetype 注册用于序列化用户提交数据的方法

name 为名称，如果存在同名，则会覆盖。

func RegisterProblemBuilder

func RegisterProblemBuilder(name string, b server.BuildProblemFunc)

RegisterProblemBuilder 注册用于生成 server.Problem 对象的方法

如果存在同名，则会覆盖。

func RegisterUniqueGenerator

func RegisterUniqueGenerator(id string, b UniqueGeneratorBuilder)

RegisterUniqueGenerator 注册唯一 ID 生成器

如果同名会被覆盖。

func SignalHUP

func SignalHUP(s ServerApp)

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

Types

type App

type App struct {
	// 构建新服务的方法
	//
	// 每次重启服务时，都将由此方法生成一个新的服务。
	NewServer func() (*server.Server, error)

	// 重启之前需要做的操作
	//
	// 可以为空。如果返回值不为 nil，将中止当前操作，但不影响旧服务。
	Before func() error

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

App 简要的服务管理功能

这是对 ServerApp 的实现。

func (*App) Exec

func (app *App) Exec() (err error)

Exec 运行服务

func (*App) RestartServer

func (app *App) RestartServer()

RestartServer 触发重启服务

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

type CLIOf

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

	// 在运行服务之前对 [server.Server] 的额外操作
	//
	// user 为用户自定义的数据结构；
	// action 为 -a 命令行指定的参数；
	Init func(s *server.Server, user *T, action string) error

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

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

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

	// 配置文件的文件名
	//
	// 相对于 ConfigDir 的文件名。如果为空，表示不采用配置文件，
	// 由一个空的 [server.Options] 初始化对象，具体可以查看 [NewServerOf] 的实现。
	//
	// 需要保证序列化方法已经由 [RegisterFileSerializer] 注册；
	ConfigFilename string

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

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

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

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

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

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

func (*CLIOf[T]) Exec

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

Exec 根据配置运行服务

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

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

func (*CLIOf[T]) FlagSet

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

FlagSet 将当前对象与 flag.FlagSet 关联

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

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

func (*CLIOf[T]) RestartServer

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

RestartServer 触发重启服务

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

type CacheBuilder

type CacheBuilder func(dsn string) (cache.Driver, error)

type LogsHandlerBuilder

type LogsHandlerBuilder func(args []string) (logs.Handler, func() error, error)

LogsHandlerBuilder 构建 logs.Handler 的方法

type MarshalFileFunc

type MarshalFileFunc = config.MarshalFunc

type ServerApp

type ServerApp interface {
	// RestartServer 重启服务
	//
	// 中止旧的 [server.Server]，再启动一个新的 [server.Server] 对象。
	RestartServer()
}

ServerApp 实现对 server.Server 的管理

type UniqueGeneratorBuilder

type UniqueGeneratorBuilder func() server.UniqueGenerator

type UnmarshalFileFunc

type UnmarshalFileFunc = config.UnmarshalFunc