server

package
v0.64.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 15, 2023 License: MIT Imports: 39 Imported by: 2

Documentation

Overview

Package server 服务管理

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BuildProblemFunc added in v0.55.0 

type BuildProblemFunc func(id, title string, status int) Problem

BuildProblemFunc 生成 Problem 对象的方法

id 表示当前错误信息的唯一值，该值有可能为 about:blank，表示不想向用户展示具体的值； title 错误信息的简要描述； status 输出的状态码；

type CTXSanitizer 

type CTXSanitizer interface {
	// CTXSanitize 验证和修正当前对象的数据
	CTXSanitize(*Validation)
}

CTXSanitizer 在 Context 关联的上下文环境中对数据进行验证和修正

在 Context.Read、Context.QueryObject 以及 Queries.Object 中会在解析数据成功之后会调用该接口。

type Context 

type Context struct {

	// 保存 Context 在存续期间的可复用变量
	//
	// 这是比 context.Value 更经济的传递变量方式，但是这并不是协程安全的。
	Vars map[any]any
	// contains filtered or unexported fields
}

Context 根据当次 HTTP 请求生成的上下文内容

Context 同时也实现了 http.ResponseWriter 接口， 但是不推荐非必要情况下直接使用 http.ResponseWriter 的接口方法， 而是采用返回 Responser 的方式向客户端输出内容。

func (*Context) Body 

func (ctx *Context) Body() (body []byte, err error)

Body 获取用户提交的内容

相对于 Context.Request().Body，此函数可多次读取。不存在 body 时，返回 nil

func (*Context) Charset added in v0.60.0 

func (ctx *Context) Charset() string

Charset 输出的字符集

func (*Context) ClientIP 

func (ctx *Context) ClientIP() string

ClientIP 返回客户端的 IP 地址及端口

获取顺序如下：

  • X-Forwarded-For 的第一个元素
  • Remote-Addr 报头
  • X-Read-IP 报头

func (*Context) Encoding added in v0.60.0 

func (ctx *Context) Encoding() string

Encoding 输出的压缩编码名称

func (*Context) Error 

func (ctx *Context) Error(id string, level logs.Level, err error) Problem

Error 将 err 输出到日志并以指定 id 的 Problem 返回

func (*Context) Header added in v0.48.0 

func (ctx *Context) Header() http.Header

func (*Context) InternalServerError added in v0.49.0 

func (ctx *Context) InternalServerError(err error) Problem

InternalServerError 输出 ERROR 通道并向返回 500 表示的 Problem 对象

func (*Context) IsXHR added in v0.44.0 

func (ctx *Context) IsXHR() bool

func (*Context) LanguageTag added in v0.49.0 

func (ctx *Context) LanguageTag() language.Tag

func (*Context) LocalePrinter 

func (ctx *Context) LocalePrinter() *message.Printer

func (*Context) Logs added in v0.44.0 

func (ctx *Context) Logs() *logs.Logs

func (*Context) Marshal 

func (ctx *Context) Marshal(status int, body any, problem bool) error

Marshal 向客户端输出内容

status 想输出给用户状态码，如果出错，那么最终展示给用户的状态码可能不是此值； body 表示输出的对象，该对象最终调用 ctx.outputMimetype 编码； problem 表示 body 是否为 Problem 对象，对于 Problem 对象可能会有特殊的处理；

func (*Context) Mimetype added in v0.60.0 

func (ctx *Context) Mimetype(problem bool) string

Mimetype 输出编码名称

problem 表示是否返回 problem 时的 mimetype 值。该值由 Mimetypes 设置。

func (*Context) NewValidation added in v0.52.0 

func (ctx *Context) NewValidation(exitAtError bool) *Validation

NewValidation 声明验证对象

func (*Context) NotFound 

func (ctx *Context) NotFound() Problem

NotFound 返回 id 值为 404 的 Problem 对象

func (*Context) NotImplemented 

func (ctx *Context) NotImplemented() Problem

func (*Context) OnExit added in v0.49.0 

func (ctx *Context) OnExit(f func(int))

OnExit 注册退出当前请求时的处理函数

f 为退出时的处理方法，其原型为： 

func(status int)

其中 status 为最终输出到客户端的状态码， 如果用户是通过 Context.Unwrap 返回的对象写入报头的，那么该值可能并不是用户期待的值。

func (*Context) ParamID 

func (ctx *Context) ParamID(key, id string) (int64, Responser)

ParamID 获取地址参数中表示 key 的值并并转换成大于 0 的 int64

NOTE: 若需要获取多个参数，使用 Context.Params 会更方便。

func (*Context) ParamInt64 

func (ctx *Context) ParamInt64(key, id string) (int64, Responser)

ParamInt64 取地址参数中的 key 表示的值并尝试工转换成 int64 类型

NOTE: 若需要获取多个参数，可以使用 Context.Params 获取会更方便。

func (*Context) ParamString 

func (ctx *Context) ParamString(key, id string) (string, Responser)

ParamString 取地址参数中的 key 表示的值并尝试工转换成 string 类型

NOTE: 若需要获取多个参数，可以使用 Context.Params 获取会更方便。

func (*Context) Params 

func (ctx *Context) Params(exitAtError bool) *Params

Params 声明一个用于获取路径参数的对象

返回对象的生命周期在 Context 结束时也随之结束。

func (*Context) Problem added in v0.55.0 

func (ctx *Context) Problem(id string) Problem

Problem 返回批定 id 的错误信息

id 通过此值从 Problems 中查找相应在的 title 并赋值给返回对象；

func (*Context) Queries 

func (ctx *Context) Queries(exitAtError bool) (*Queries, error)

Queries 声明一个用于获取查询参数的对象

返回对象的生命周期在 Context 结束时也随之结束。

func (*Context) QueryObject 

func (ctx *Context) QueryObject(exitAtError bool, v any, id string) Responser

QueryObject 将查询参数解析到一个对象中

func (*Context) Read 

func (ctx *Context) Read(exitAtError bool, v any, id string) Responser

Read 从客户端读取数据并转换成 v 对象

如果 v 实现了 CTXSanitizer 接口，则在读取数据之后，会调用其接口函数。 如果验证失败，会输出以 id 作为错误代码的 Responser 对象。

func (*Context) Request 

func (ctx *Context) Request() *http.Request

Request 返回原始的请求对象

func (*Context) Route added in v0.55.3 

func (ctx *Context) Route() types.Route

Route 关联的路由信息

func (*Context) Server 

func (ctx *Context) Server() *Server

Server 获取关联的 Server 实例

func (*Context) SetCharset added in v0.60.0 

func (ctx *Context) SetCharset(charset string)

SetCharset 设置输出的字符集

NOTE: 不会影响 Context.Request 的返回对象。

func (*Context) SetEncoding added in v0.60.0 

func (ctx *Context) SetEncoding(enc string)

SetEncoding 设置压缩编码

NOTE: 不会影响 Context.Request 的返回对象。

func (*Context) SetLanguage added in v0.49.0 

func (ctx *Context) SetLanguage(tag language.Tag)

SetLanguage 修改输出的语言

NOTE: 不会影响 Context.Request 的返回对象。

func (*Context) SetMimetype added in v0.60.0 

func (ctx *Context) SetMimetype(mimetype string)

SetMimetype 设置输出的格式

NOTE: 不会影响 Context.Request 的返回对象。

func (*Context) Sprintf 

func (ctx *Context) Sprintf(key message.Reference, v ...any) string

Sprintf 将内容翻译成当前请求的语言

func (*Context) Unmarshal 

func (ctx *Context) Unmarshal(v any) error

Unmarshal 将提交的内容转换成 v 对象

func (*Context) Unwrap added in v0.60.0 

func (ctx *Context) Unwrap() http.ResponseWriter

https://github.com/golang/go/blob/master/src/net/http/responsecontroller.go#L41

func (*Context) Write added in v0.48.0 

func (ctx *Context) Write(bs []byte) (int, error)

func (*Context) WriteHeader added in v0.48.0 

func (ctx *Context) WriteHeader(status int)

func (*Context) Wrote added in v0.59.7 

func (ctx *Context) Wrote() bool

Wrote 是否已经有内容输出

type Encodings added in v0.55.1 

type Encodings interface {
	// Add 添加压缩算法
	//
	// id 表示当前算法的唯一名称，在 Allow 中可以用来查找使用；
	// name 表示通过 Accept-Encoding 匹配的名称；
	// f 表示生成压缩对象的方法；
	Add(id, name string, f NewEncodingFunc)

	// Allow 允许 contentType 采用的压缩方式
	//
	// id 是指由 Add 中指定的值；
	// contentType 表示经由 Accept-Encoding 提交的值，该值不能是 identity 和 *；
	//
	// 如果未添加任何算法，则每个请求都相当于是 identity 规则。
	Allow(contentType string, id ...string)
}

type Files added in v0.61.0 

type Files = files.Files

type HandlerFunc 

type HandlerFunc func(*Context) Responser

HandlerFunc 路由项处理函数原型

type MarshalFunc added in v0.61.0 

type MarshalFunc func(*Context, any) ([]byte, error)

MarshalFunc 序列化函数原型

NOTE: MarshalFunc 的实现中不能调用 Context.Marshal 方法。

type Middleware added in v0.48.0 

type Middleware = types.MiddlewareOf[HandlerFunc]

type MiddlewareFunc added in v0.48.0 

type MiddlewareFunc = types.MiddlewareFuncOf[HandlerFunc]

type Mimetypes added in v0.61.0 

type Mimetypes interface {
	// Exists 是否存在同名的
	Exists(string) bool

	// Delete 删除指定名称的编码方法
	Delete(string)

	// Add 添加新的编码方法
	//
	// name 为编码名称；
	// problem 为该编码在返回 [Problem] 对象时的 mimetype 报头值，如果为空，则会被赋予 name 相同的值；
	Add(name string, m MarshalFunc, u UnmarshalFunc, problem string)

	// Set 修改指定名称的相关配置
	//
	// name 用于查找相关的编码方法；
	// 如果 problem 为空，会被赋予与 name 相同的值；
	Set(name string, m MarshalFunc, u UnmarshalFunc, problem string)

	Len() int
}

type NewEncodingFunc added in v0.55.0 

type NewEncodingFunc = encoding.NewEncodingFunc

func EncodingBrotli added in v0.55.1 

func EncodingBrotli(o brotli.WriterOptions) NewEncodingFunc

EncodingBrotli 返回指定配置的 br 算法

func EncodingCompress added in v0.55.1 

func EncodingCompress(order lzw.Order, width int) NewEncodingFunc

EncodingCompress 返回指定配置的 compress 算法

func EncodingDeflate added in v0.55.1 

func EncodingDeflate(level int) NewEncodingFunc

EncodingDeflate 返回指定配置的 deflate 算法

func EncodingGZip added in v0.55.1 

func EncodingGZip(level int) NewEncodingFunc

EncodingGZip 返回指定配置的 gzip 算法

func EncodingZstd added in v0.59.0 

func EncodingZstd(o ...zstd.EOption) NewEncodingFunc

EncodingZstd 返回指定配置的 zstd 算法

type Options 

type Options struct {
	// 项目默认可存取的文件系统
	//
	// 默认情况下为可执行文件所在的目录。
	FS fs.FS

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

	// 缓存系统
	//
	// 默认值为内存类型。
	Cache cache.Driver

	// 日志的输出通道设置
	//
	// 如果此值为空，那么在被初始化 logs.New(nil) 值，表示不会输出到任何通道。
	Logs *logs.Logs

	// 生成 [Problem] 对象的方法
	//
	// 如果为空，那么将采用 [RFC7807Builder] 作为默认值。
	ProblemBuilder BuildProblemFunc

	// 默认的语言标签
	//
	// 在用户请求的报头中没有匹配的语言标签时，会采用此值作为该用户的本地化语言，
	// 同时也用来初始化 [Server.LocalePrinter]。
	//
	// 如果为空，则会尝试读取当前系统的本地化信息。
	LanguageTag language.Tag

	// http.Server 实例的值
	//
	// 如果为空，表示 &http.Server{} 对象。
	HTTPServer *http.Server

	// 路由选项
	//
	// 将应用 [Server.Routers] 对象之上。
	RoutersOptions []mux.Option
}

type Params 

type Params struct {
	// contains filtered or unexported fields
}

func (*Params) Bool 

func (p *Params) Bool(key string) bool

Bool 获取参数 key 所代表的值并转换成 bool

由 strconv.ParseBool 进行转换。

func (*Params) Float64 

func (p *Params) Float64(key string) float64

Float64 获取参数 key 所代表的值并转换成 float64

func (*Params) ID 

func (p *Params) ID(key string) int64

ID 返回 key 所表示的值且必须大于 0

func (*Params) Int64 

func (p *Params) Int64(key string) int64

Int64 获取参数 key 所代表的值并转换成 int64 类型

func (*Params) Problem added in v0.55.0 

func (p *Params) Problem(id string) Responser

Problem 将当前对象转换成 Problem 对象

仅在处理参数时有错误的情况下，才会转换成 Problem 对象，否则将返回空值。

func (*Params) String 

func (p *Params) String(key string) string

String 获取参数 key 所代表的值并转换成 string

type Problem added in v0.55.0 

type Problem interface {
	Responser

	// With 添加新的输出字段
	//
	// 如果添加的字段名称与现有的字段重名，应当 panic。
	With(key string, val any)

	// AddParam 添加数据验证错误信息
	AddParam(name string, reason string)
}

Problem API 错误信息对象需要实现的接口

Problem 是对 Responser 细化，用于反馈给用户非正常状态下的数据， 比如用户提交的数据错误，往往会返回 400 的状态码， 并附带一些具体的字段错误信息，此类数据都可以以 Problem 对象的方式反馈给用户。

除了当前接口，该对象可能还要实现相应的序列化接口，比如要能被 JSON 解析， 就要实现 json.Marshaler 接口或是相应的 struct tag。

并未规定实现者输出的字段名和布局，实现者可以根据 BuildProblemFunc 给定的参数，结合自身需求决定。比如 RFC7807Builder 是对 RFC7807 的实现。

func RFC7807Builder added in v0.55.0 

func RFC7807Builder(id, title string, status int) Problem

RFC7807Builder BuildProblemFunc 的 RFC7807 标准实现

NOTE: 由于 www-form-urlencoded 对复杂对象的表现能力有限， 在此模式下将忽略由 [Problem.With] 添加的复杂类型，只保留基本类型。

type Problems added in v0.55.0 

type Problems interface {
	// TypePrefix [BuildProblemFunc] 参数 id 的前缀
	TypePrefix() string

	// SetTypePrefix 设置 id 的前缀
	//
	// 如果设置成 about:blank 那么将不输出 id
	SetTypePrefix(string)

	// Add 添加新的错误类型
	Add(...*StatusProblem)

	Exists(id string) bool

	Problems() []*StatusProblem

	// Problem 根据 id 生成 [Problem] 对象
	Problem(printer *message.Printer, id string) Problem

	// Status 添加一组固定状态码的错误码
	Status(int) *problems.StatusProblems[Problem]
}

type Queries 

type Queries struct {
	// contains filtered or unexported fields
}

func (*Queries) Bool 

func (q *Queries) Bool(key string, def bool) bool

Bool 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。若是无法转换，则会保存错误信息并返回 def。

func (*Queries) Float64 

func (q *Queries) Float64(key string, def float64) float64

Float64 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。若是无法转换，则会保存错误信息并返回 def。

func (*Queries) Int 

func (q *Queries) Int(key string, def int) int

Int 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。若是无法转换，则会保存错误信息并返回 def。

func (*Queries) Int64 

func (q *Queries) Int64(key string, def int64) int64

Int64 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。若是无法转换，则会保存错误信息并返回 def。

func (*Queries) Object 

func (q *Queries) Object(v any, id string)

Object 将查询参数解析到一个对象中

具体的文档信息可以参考 https://github.com/issue9/query

如果 v 实现了 CTXSanitizer 接口，则在读取数据之后，会调用其接口函数。

func (*Queries) Problem added in v0.55.0 

func (q *Queries) Problem(id string) Responser

Problem 将当前对象转换成 Problem 对象

仅在处理参数时有错误的情况下，才会转换成 Problem 对象，否则将返回空值。

func (*Queries) String 

func (q *Queries) String(key, def string) string

String 从查询参数中获取指定名称的值

若不存在则返回 def 作为其默认值。

type Responser added in v0.40.0 

type Responser interface {
	// Apply 通过 [Context] 将当前内容渲染到客户端
	//
	// 在调用 Apply 之后，就不再使用 Responser 对象，
	// 如果你的对象支持 sync.Pool 复用，可以在 Apply 退出之际回收。
	Apply(*Context)
}

Responser 表示向客户端输出对象最终需要实现的接口

type ResponserFunc added in v0.55.0 

type ResponserFunc func(*Context)

func (ResponserFunc) Apply added in v0.55.0 

func (f ResponserFunc) Apply(c *Context)

type Router 

type Router = mux.RouterOf[HandlerFunc]

type Routers added in v0.48.0 

type Routers = group.GroupOf[HandlerFunc]

type Rule added in v0.57.0 

type Rule struct {
	// contains filtered or unexported fields
}

func NewRule added in v0.57.0 

func NewRule(message localeutil.LocaleStringer, validator Validator) *Rule

NewRule 声明一条验证规则

message 表示在验证出错时的错误信息；

func NewRuleFunc added in v0.57.0 

func NewRuleFunc(message localeutil.LocaleStringer, f func(any) bool) *Rule

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server web 服务对象

func New 

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

New 新建 web 服务

name, version 表示服务的名称和版本号； o 指定了初始化 Server 一些非必要参数。

func (*Server) Cache 

func (srv *Server) Cache() cache.CleanableCache

Cache 返回缓存的相关接口

func (*Server) CatalogBuilder added in v0.55.0 

func (srv *Server) CatalogBuilder() *catalog.Builder

func (*Server) Close 

func (srv *Server) Close(shutdownTimeout time.Duration) error

Close 触发关闭操作

需要等待 Server.Serve 返回才能证明整个服务被关闭。

func (*Server) Encodings added in v0.48.0 

func (srv *Server) Encodings() Encodings

Encodings 返回压缩编码管理

func (*Server) FileServer added in v0.44.0 

func (srv *Server) FileServer(fsys fs.FS, name, index string) HandlerFunc

FileServer 构建静态文件服务对象

fsys 为文件系统，如果为空则采用 Server 本身； name 表示地址中表示文件名部分的参数名称； index 表示目录下的默认文件名；

func (*Server) Files added in v0.41.0 

func (srv *Server) Files() *Files

Files 配置文件的相关操作

func (*Server) LanguageTag added in v0.56.0 

func (srv *Server) LanguageTag() language.Tag

LanguageTag 返回默认的语言标签

func (*Server) LoadLocales added in v0.61.0 

func (srv *Server) LoadLocales(fsys fs.FS, glob string) error

LoadLocales 加载本地化的内容

func (*Server) LocalePrinter added in v0.41.0 

func (srv *Server) LocalePrinter() *message.Printer

func (*Server) Location 

func (srv *Server) Location() *time.Location

Location 指定服务器的时区信息

func (*Server) Logs 

func (srv *Server) Logs() *logs.Logs

Logs 返回关联的 logs.Logs 实例

func (*Server) Mimetypes 

func (srv *Server) Mimetypes() Mimetypes

Mimetypes 编解码控制

func (*Server) Name 

func (srv *Server) Name() string

Name 应用的名称

func (*Server) NewPrinter added in v0.55.0 

func (srv *Server) NewPrinter(tag language.Tag) *message.Printer

func (*Server) Now 

func (srv *Server) Now() time.Time

Now 返回当前时间

与 time.Now 的区别在于 Now() 基于当前时区

func (*Server) OnClose added in v0.44.0 

func (srv *Server) OnClose(f ...func() error)

OnClose 注册关闭服务时需要执行的函数

NOTE: 按注册的相反顺序执行。

func (*Server) Open 

func (srv *Server) Open(name string) (fs.File, error)

func (*Server) ParseTime 

func (srv *Server) ParseTime(layout, value string) (time.Time, error)

ParseTime 分析基于当前时区的时间

func (*Server) Problems added in v0.55.0 

func (srv *Server) Problems() Problems

func (*Server) Routers added in v0.44.0 

func (srv *Server) Routers() *Routers

Routers 路由管理接口

func (*Server) Serve 

func (srv *Server) Serve() (err error)

Serve 启动服务

会等待 Server.Close 执行完之后，此函数才会返回，这一点与 http.ListenAndServe 稍有不同。 一旦返回，整个 Server 对象将处于不可用状态。

func (*Server) Services 

func (srv *Server) Services() *Services

Services 服务管理

func (*Server) Uptime 

func (srv *Server) Uptime() time.Time

Uptime 当前服务的运行时间

func (*Server) Vars added in v0.42.0 

func (srv *Server) Vars() *sync.Map

Vars 操纵共享变量的接口

func (*Server) Version 

func (srv *Server) Version() string

Version 应用的版本

type Services added in v0.61.0 

type Services = service.Server

type StatusProblem added in v0.61.0 

type StatusProblem = problems.StatusProblem

type UnmarshalFunc added in v0.61.0 

type UnmarshalFunc func([]byte, any) error

UnmarshalFunc 反序列化函数原型

type ValidateFunc added in v0.57.0 

type ValidateFunc func(any) bool

ValidateFunc 用于验证指定数据的合法性

func (ValidateFunc) IsValid added in v0.57.0 

func (f ValidateFunc) IsValid(v any) bool

type Validation added in v0.56.0 

type Validation struct {
	// contains filtered or unexported fields
}

Validation 数据验证工具

func (*Validation) Add added in v0.57.0 

func (v *Validation) Add(name string, reason localeutil.LocaleStringer) *Validation

Add 直接添加一条错误信息

func (*Validation) AddField added in v0.56.0 

func (v *Validation) AddField(val any, name string, rules ...*Rule) *Validation

AddField 验证新的字段

val 表示需要被验证的值； name 表示当前字段的名称，当验证出错时，以此值作为名称返回给用户； rules 表示验证的规则，按顺序依次验证。

func (*Validation) AddMapField added in v0.56.0 

func (v *Validation) AddMapField(val any, name string, rules ...*Rule) *Validation

AddMapField 验证 map 字段

如果字段类型不是 map，将添加一条错误信息，并退出验证。

func (*Validation) AddSliceField added in v0.56.0 

func (v *Validation) AddSliceField(val any, name string, rules ...*Rule) *Validation

AddSliceField 验证数组字段

如果字段类型不是数组或是字符串，将添加一条错误信息，并退出验证。

func (*Validation) Context added in v0.59.4 

func (v *Validation) Context() *Context

func (*Validation) Len added in v0.62.0 

func (v *Validation) Len() int

func (*Validation) Problem added in v0.56.0 

func (v *Validation) Problem(id string) Problem

Problem 转换成 Problem 对象

如果当前对象没有收集到错误，那么将返回 nil。

func (*Validation) When added in v0.56.0 

func (v *Validation) When(cond bool, f func(v *Validation)) *Validation

When 只有满足 cond 才执行 f 中的验证

f 中的 v 即为当前对象；

type Validator added in v0.57.0 

type Validator interface {
	IsValid(v any) bool
}

Validator 用于验证指定数据的合法性

func AndValidateFunc added in v0.57.0 

func AndValidateFunc(f ...func(any) bool) Validator

func AndValidator added in v0.57.0 

func AndValidator(v ...Validator) Validator

AndValidator 将多个验证函数以与的形式合并为一个验证函数

func OrValidateFunc added in v0.57.0 

func OrValidateFunc(f ...func(any) bool) Validator

func OrValidator added in v0.57.0 

func OrValidator(v ...Validator) Validator

OrValidator 将多个验证函数以或的形式合并为一个验证函数

Source Files

View all Source files

Directories

Path Synopsis
Package servertest 针对 server 的测试用例
 Package servertest 针对 server 的测试用例

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.