server

Documentation

Overview

Package server 提供与服务端实现相关的功能

目前实现了三种类型的服务端：

• New 构建普通的 HTTP 服务；
• NewGateway 构建微服务的网关服务；
• NewService 构建微服务；

Index

• Constants
• func AllLevels() []logs.Level
• func CheckConfigSyntax[T any](configDir, filename string) error
• func MergeHandler(w ...logs.Handler) logs.Handler
• func New(name, version string, o *Options) (web.Server, error)
• func NewDispatchHandler(d map[logs.Level]logs.Handler) logs.Handler
• func NewGateway(name, version string, o *Options) (web.Server, error)
• func NewJSONHandler(w ...io.Writer) logs.Handler
• func NewMemcache(addr ...string) cache.Driver
• func NewMemory() (cache.Driver, web.JobFunc)
• func NewNopHandler() logs.Handler
• func NewPrinter(glob string, fsys ...fs.FS) (*localeutil.Printer, error)
• func NewRedisFromURL(url string) (cache.Driver, error)
• func NewRotateFile(format, dir string, size int64) (io.WriteCloser, error)
• func NewSMTP(username, password, subject, host string, sendTo []string) io.Writer
• func NewService(name, version string, o *Options) (web.Server, error)
• func NewTermHandler(w io.Writer, colors map[logs.Level]colors.Color) logs.Handler
• func NewTextHandler(w ...io.Writer) logs.Handler
• func RegisterCache(b CacheBuilder, name ...string)
• func RegisterCompression(id string, c compressor.Compressor)
• func RegisterFileSerializer(name string, m config.MarshalFunc, u config.UnmarshalFunc, ext ...string)
• func RegisterIDGenerator(id string, b IDGeneratorBuilder)
• func RegisterLogsHandler(b LogsHandlerBuilder, name ...string)
• func RegisterMimetype(m web.MarshalFunc, u web.UnmarshalFunc, name string)
• func RegisterOnRender(f func(int, any) (int, any), name string)
• func RegisterRegistryType(f RegistryTypeBuilder, name string)
• func RegisterRouterMatcher(f RouterMatcherBuilder, name string)
• func RegisterStrategy(f StrategyBuilder, name string)
• func Render200(status int, body any) (int, any)
• type CacheBuilder
• type Compression
  • func BestCompressionCompressions(contentType ...string) []*Compression
  • func BestSpeedCompressions(contentType ...string) []*Compression
  • func DefaultCompressions(contentType ...string) []*Compression
• type Config
• type FileSerializer
• type IDGenerator
  • func DateID(buffSize int) (IDGenerator, web.Service)
  • func NumberID(buffSize int) (IDGenerator, web.Service)
  • func StringID(buffSize int) (IDGenerator, web.Service)
• type IDGeneratorBuilder
• type Job
• type Logs
• type LogsHandlerBuilder
• type Mapper
• type Mimetype
  • func APIMimetypes() []*Mimetype
  • func JSONMimetypes() []*Mimetype
  • func XMLMimetypes() []*Mimetype
• type Options
  • func LoadOptions[T any](configDir, filename string) (*Options, *T, error)
• type RegistryTypeBuilder
• type Render200Response
• type RouterMatcherBuilder
• type StrategyBuilder

Constants

const (
	DateMilliLayout = logs.DateMilliLayout
	DateMicroLayout = logs.DateMicroLayout
	DateNanoLayout  = logs.DateNanoLayout

	MilliLayout = logs.MilliLayout
	MicroLayout = logs.MicroLayout
	NanoLayout  = logs.NanoLayout
)

日志的时间格式

const DefaultConfigDir = "@.config" // 默认的配置目录地址

Functions

func AllLevels

func AllLevels() []logs.Level

AllLevels 返回所有的日志类型

func CheckConfigSyntax

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

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

func MergeHandler

func MergeHandler(w ...logs.Handler) logs.Handler

MergeHandler 合并多个 [Handler] 对象

func New

func New(name, version string, o *Options) (web.Server, error)

New 新建 HTTP 服务

name, version 表示服务的名称和版本号； o 指定了一些带有默认值的参数；

func NewDispatchHandler

func NewDispatchHandler(d map[logs.Level]logs.Handler) logs.Handler

NewDispatchHandler 按不同的 [Level] 派发到不同的 [Handler] 对象

func NewGateway

func NewGateway(name, version string, o *Options) (web.Server, error)

NewGateway 声明微服务的网关

func NewJSONHandler

func NewJSONHandler(w ...io.Writer) logs.Handler

NewJSONHandler 声明 JSON 类型的日志输出通道

func NewMemcache

func NewMemcache(addr ...string) cache.Driver

NewMemcache 声明基于 memcache 的缓存对象

参数说明可参考 memcache.New。

func NewMemory

func NewMemory() (cache.Driver, web.JobFunc)

NewMemory 声明基于内在的缓存对象

func NewNopHandler

func NewNopHandler() logs.Handler

func NewPrinter

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

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

语言由 localeutil.DetectUserLanguageTag 决定。 fsys 指定了加载本地化文件的文件系统，glob 则指定了加载的文件匹配规则； 对于文件的序列化方式则是根据后缀名从由 RegisterFileSerializer 注册的项中查找。

func NewRedisFromURL

func NewRedisFromURL(url string) (cache.Driver, error)

NewRedisFromURL 声明基于 redis 的缓存对象

参数说明可参考 redis.NewFromURL。

func NewRotateFile

func NewRotateFile(format, dir string, size int64) (io.WriteCloser, error)

NewRotateFile 按大小分割的文件日志

参数说明参考 rotate.New

func NewSMTP

func NewSMTP(username, password, subject, host string, sendTo []string) io.Writer

NewSMTP 将日志内容发送至指定邮箱

参数说明参考 writers.NewSMTP

func NewService

func NewService(name, version string, o *Options) (web.Server, error)

NewService 声明微服务节点

func NewTermHandler

func NewTermHandler(w io.Writer, colors map[logs.Level]colors.Color) logs.Handler

NewTermHandler 带颜色的终端输出通道

参数说明参考 logs.NewTermHandler

func NewTextHandler

func NewTextHandler(w ...io.Writer) logs.Handler

NewTextHandler 声明文本类型的日志输出通道

func RegisterCache

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

RegisterCache 注册新的缓存方式

name 为缓存的名称，这将在配置文件中被引用，如果存在同名，则会覆盖。

func RegisterCompression

func RegisterCompression(id string, c compressor.Compressor)

RegisterCompression 注册压缩方法

id 表示此压缩方法的唯一 ID，这将在配置文件中被引用；

func RegisterFileSerializer

func RegisterFileSerializer(name string, m config.MarshalFunc, u config.UnmarshalFunc, ext ...string)

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

name 为当前数据的名称，这将在配置文件中被引用，如果存在同名，则会覆盖； ext 为文件的扩展名；

func RegisterIDGenerator

func RegisterIDGenerator(id string, b IDGeneratorBuilder)

RegisterIDGenerator 注册唯一 ID 生成器

id 表示唯一 ID，这将在配置文件中被引用。如果同名会被覆盖；

func RegisterLogsHandler

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

RegisterLogsHandler 注册日志的 [LogsWriterBuilder]

name 为缓存的名称，这将在配置文件中被引用，如果存在同名，则会覆盖。

func RegisterMimetype

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

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

name 为名称，这将在配置文件中被引用，如果存在同名，则会覆盖。

func RegisterOnRender

func RegisterOnRender(f func(int, any) (int, any), name string)

func RegisterRegistryType

func RegisterRegistryType(f RegistryTypeBuilder, name string)

func RegisterRouterMatcher

func RegisterRouterMatcher(f RouterMatcherBuilder, name string)

func RegisterStrategy

func RegisterStrategy(f StrategyBuilder, name string)

func Render200

func Render200(status int, body any) (int, any)

Render200 统一 API 的返回格式

状态码统一为 200；返回对象统一为 Render200Response；

Types

type CacheBuilder

type CacheBuilder = func(dsn string) (drv cache.Driver, job *Job, err error)

CacheBuilder 构建缓存客户端的方法

drv 为缓存客户端对象； 如果是服务端客户端一体的，可通过 job 来指定服务端的定时回收任务；

type Compression

type Compression struct {
	// Compressor 压缩算法
	Compressor compressor.Compressor

	// Types 该压缩对象允许使用的为 content-type 类型
	//
	// 如果是 * 或是空值表示适用所有类型。
	Types []string
}

Compression 有关压缩的设置项

func BestCompressionCompressions

func BestCompressionCompressions(contentType ...string) []*Compression

BestCompressionCompressions 提供当前框架内置的所有压缩算法

如果有性能参数，则选择最快压缩比作为初始化条件。

func BestSpeedCompressions

func BestSpeedCompressions(contentType ...string) []*Compression

BestSpeedCompressions 提供当前框架内置的所有压缩算法

如果有性能参数，则选择最快速度作为初始化条件。

func DefaultCompressions

func DefaultCompressions(contentType ...string) []*Compression

DefaultCompressions 提供当前框架内置的所有压缩算法

contentType 指定所有算法应用的媒体类型，为空则表示对所有的内容都进行压缩。

type Config

type Config struct {
	// Dir 项目配置目录
	//
	// 如果涉及到需要读取配置文件的，可以指定此对象，之后可通过此对象统一处理各类配置文件。
	// 如果为空，则会采用 [DefaultConfigDir]。
	Dir string

	// Serializers 支持的序列化方法列表
	//
	// 如果为空，则会默认支持 yaml、json 两种方式；
	Serializers []*FileSerializer
}

Config 项目配置文件的配置

type FileSerializer

type FileSerializer struct {
	// Exts 支持的扩展名
	Exts []string

	// Marshal 序列化方法
	Marshal config.MarshalFunc

	// Unmarshal 反序列化方法
	Unmarshal config.UnmarshalFunc
}

FileSerializer 对于文件序列化的配置

type IDGenerator

type IDGenerator = func() string

IDGenerator 生成唯一 ID 的函数

func DateID

func DateID(buffSize int) (IDGenerator, web.Service)

DateID 构建日期格式的唯一 ID

NOTE: 基于时间戳，不能保证多实例模式下也具有唯一性。

func NumberID

func NumberID(buffSize int) (IDGenerator, web.Service)

NumberID 构建数字形式的唯一 ID

NOTE: 基于时间戳，不能保证多实例模式下也具有唯一性。

func StringID

func StringID(buffSize int) (IDGenerator, web.Service)

StringID 构建包含任意字符的唯一 ID

NOTE: 基于时间戳，不能保证多实例模式下也具有唯一性。

type IDGeneratorBuilder

type IDGeneratorBuilder = func() (f IDGenerator, s web.Service)

IDGeneratorBuilder 构建生成唯一 ID 的方法

f 表示生成唯一 ID 的方法；s 为 f 依赖的服务，可以为空；

type Job

type Job struct {
	Ticker time.Duration
	Job    scheduled.JobFunc
}

type Logs

type Logs struct {
	// Handler 后端处理接口
	//
	// 内置了以下几种方式：
	//  - [NewNopHandler]
	//  - [NewTermHandler]
	//  - [NewTextHandler]
	//  - [NewJSONHandler]
	Handler logs.Handler

	// 是否带调用堆栈信息
	Location bool

	// 指定创建日志的时间格式，如果为空表示不需要输出时间。
	Created string

	// 允许的日志级别
	Levels []logs.Level

	// 对于 [Logger.Error] 输入 [xerrors.Formatter] 类型时，
	// 是否输出调用堆栈信息。
	StackError bool

	// 是否接管标准库日志的输出
	Std bool
}

Logs 初始化日志的选项

type LogsHandlerBuilder

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

LogsHandlerBuilder 构建 logs.Handler 的方法

type Mapper

type Mapper map[string]web.RouterMatcher

Mapper 微服务名称与路由的匹配关系

在网关中由此列表确定相应的路由由哪个微服务进行代码。

type Mimetype

type Mimetype struct {
	// Mimetype 的名称
	//
	// 比如：application/json
	Name string

	// 对应的错误状态下的 mimetype 值
	//
	// 比如：application/problem+json。
	// 可以为空，表示与 Type 相同。
	Problem string

	// 生成编码方法
	Marshal web.MarshalFunc

	// 解码方法
	Unmarshal web.UnmarshalFunc
}

Mimetype 有关 mimetype 的设置项

func APIMimetypes

func APIMimetypes() []*Mimetype

APIMimetypes 返回以 XML 和 JSON 作为数据交换格式的配置项

func JSONMimetypes

func JSONMimetypes() []*Mimetype

JSONMimetypes 返回以 JSON 作为数据交换格式的配置项

func XMLMimetypes

func XMLMimetypes() []*Mimetype

XMLMimetypes 返回以 XML 作为数据交换格式的配置项

type Options

type Options struct {
	// 项目的配置项
	Config *Config

	// 服务器的时区
	//
	// 默认值为 [time.Local]
	Location *time.Location

	// 缓存系统
	//
	// 内置了以下几种驱动：
	//  - [NewMemory]
	//  - [NewMemcache]
	//  - [NewRedisFromURL]
	// 如果为空，采用 [NewMemory] 作为默认值。
	Cache cache.Driver

	// 日志的相关设置
	//
	// 如果此值为空，表示不会输出任何信息。
	Logs *Logs

	// http.Server 实例的值
	//
	// 可以为零值。
	HTTPServer *http.Server

	// 生成唯一字符串的方法
	//
	// 供 [Server.UniqueID] 使用。
	//
	// 如果为空，将采用 [unique.NewString] 作为生成方法。
	//
	// NOTE: 该值的修改，可能造成项目中的唯一 ID 不再唯一。
	IDGenerator IDGenerator

	// 路由选项
	//
	// 如果为空，会添加 [web.Recovery] 作为默认值。
	RoutersOptions []web.RouterOption

	// 指定获取 x-request-id 内容的报头名
	//
	// 如果为空，则采用 [header.XRequestID] 作为默认值
	RequestIDKey string

	// 可用的压缩类型
	//
	// 默认为空。表示不需要该功能。
	Compressions []*Compression

	// 指定可用的 mimetype
	//
	// 默认采用 [JSONMimetypes]。
	Mimetypes []*Mimetype

	// 默认的语言标签
	//
	// 在用户请求的报头中没有匹配的语言标签时，会采用此值作为该用户的本地化语言，
	// 同时也用来初始化 [Server.Locale.Printer]。
	//
	// 框架中的日志输出时，如果该信息实现了 [web.LocaleStringer] 接口，
	// 将会转换成此设置项的语言。
	//
	// 如果为空，则会尝试读取当前系统的本地化信息。
	Language language.Tag

	// 本地化的数据
	//
	// 如果为空，则会被初始化成一个空对象。
	// Catalog 中会强行插入一条 tag 与 [Options.Language] 相同的翻译项，
	// 以保证能正确构建 [web.Server.Printer] 对象。
	Catalog *catalog.Builder

	// ProblemTypePrefix 所有 type 字段的前缀
	//
	// 如果该值为 [web.ProblemAboutBlank]，将不输出 ID 值；其它值则作为前缀添加。
	// 空值是合法的值，表示不需要添加前缀。
	ProblemTypePrefix string

	// OnRender 可实现对渲染结果的调整
	//
	// NOTE: 该值的修改，可能造成所有接口返回数据结构的变化。
	OnRender func(status int, body any) (int, any)

	// Init 其它的一些初始化操作
	//
	// 在此可以让用户能实际操作 [Server] 之前对其进行一些修改。
	Init []func(web.Server)

	// Registry 作为微服务时的注册中心实例
	//
	// NOTE: 仅在 [NewService] 和 [NewGateway] 中才会有效果。
	Registry registry.Registry

	// Peer 作为微服务终端时的地址
	//
	// NOTE: 仅在 [NewService] 中才会有效果。
	Peer selector.Peer

	// Mapper 作为微服务网关时的 URL 映射关系
	//
	// NOTE: 仅在 [NewGateway] 中才会有效果。
	Mapper Mapper
	// contains filtered or unexported fields
}

Options web.Server 的初始化参数

这些参数都有默认值，且无法在 web.Server 初始化之后进行更改。

初始化方式，可以直接采用 &Options{...} 的方式，表示所有项都采用默认值。 也可以采用 LoadOptions 从配置文件中加载相应在的数据进行初始化。

func LoadOptions

func LoadOptions[T any](configDir, filename string) (*Options, *T, error)

LoadOptions 从配置文件初始化 Options 对象

configDir 项目配置文件所在的目录； filename 用于指定项目的配置文件，相对于 configDir 文件系统。 如果此值为空，将返回 &Options{Config: &Config{Dir: configDir}}；

序列化方法由 RegisterFileSerializer 注册的列表中根据 filename 的扩展名进行查找。

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

配置文件

对于配置文件各个字段的定义，可参考当前目录下的 CONFIG.html。 配置文件中除了固定的字段之外，还提供了泛型变量 User 用于指定用户自定义的额外字段。

注册函数

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

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

type RegistryTypeBuilder

type RegistryTypeBuilder = func(web.Cache, *registry.Strategy, ...string) registry.Registry

RegistryTypeBuilder 生成 registry.Registry 的方法

第一个参数为 web.Cache 类型，如果返回的 registry.Registry 为非 cache 时则第一个参数可以为 nil。

type Render200Response

type Render200Response struct {
	XMLName struct{} `json:"-" yaml:"-" xml:"body"`
	OK      bool     `json:"ok" yaml:"ok" xml:"ok,attr"`
	Status  int      `json:"status" yaml:"status" xml:"status,attr"`
	Body    any      `json:"body" yaml:"body" xml:"body"`
}

Render200Response API 统一的返回格式

type RouterMatcherBuilder

type RouterMatcherBuilder = func(...string) web.RouterMatcher

type StrategyBuilder

type StrategyBuilder = func() *registry.Strategy

StrategyBuilder 构建负载均衡算法的函数