Documentation
¶
Overview ¶
Package fastapi FastApi-Python 的Golang实现
其提供了类似于FastAPI的API设计,并提供了接口文档自动生成、请求体自动校验和返回值自动序列化等使用功能;
Index ¶
- Constants
- Variables
- func Iter[T any, S any](seq []S, fc func(elem S) T) []T
- func LazyInit()
- func ParseJsoniterError(err error, loc openapi.RouteParamType, objName string) *openapi.ValidationError
- func ParseValidatorError(err error, loc openapi.RouteParamType, objName string) []*openapi.ValidationError
- func ReleaseResponse(resp *Response)
- func ReplaceLogger(logger LoggerIface)
- type BaseGroupRouter
- func (g *BaseGroupRouter) Description() map[string]string
- func (g *BaseGroupRouter) ErrorFormatter() RouteErrorFormatterdeprecated
- func (g *BaseGroupRouter) InParamsName() map[string]map[int]string
- func (g *BaseGroupRouter) Path() map[string]string
- func (g *BaseGroupRouter) PathSchema() pathschema.RoutePathSchema
- func (g *BaseGroupRouter) Prefix() string
- func (g *BaseGroupRouter) Summary() map[string]string
- func (g *BaseGroupRouter) Tags() []string
- type BaseModel
- type BaseRouter
- type BoolBindMethod
- func (m *BoolBindMethod) Marshal(obj any) ([]byte, error)
- func (m *BoolBindMethod) Name() string
- func (m *BoolBindMethod) New() any
- func (m *BoolBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *BoolBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type Config
- type Context
- func (c *Context) AnyResponse(statusCode int, content any, contentType ...string) *Response
- func (c *Context) ContentType(contentType string)
- func (c *Context) Context() context.Context
- func (c *Context) Done() <-chan struct{}
- func (c *Context) ErrorResponse(content any) *Response
- func (c *Context) F(s ...string) string
- func (c *Context) FileResponse(filepath string) *Response
- func (c *Context) Get(key string) (value any, exists bool)
- func (c *Context) GetBool(key string) (b bool)
- func (c *Context) GetInt64(key string) (i64 int64)
- func (c *Context) GetString(key string) (s string)
- func (c *Context) GetTime(key string) (t time.Time)
- func (c *Context) GetUint64(key string) (ui64 uint64)
- func (c *Context) HTMLResponse(statusCode int, content []byte) *Response
- func (c *Context) JSONResponse(statusCode int, content any) *Response
- func (c *Context) MX() any
- func (c *Context) Marshal(obj any) ([]byte, error)
- func (c *Context) MustGet(key string) any
- func (c *Context) MuxContext() MuxContext
- func (c *Context) OKResponse(content any) *Response
- func (c *Context) PathField(name string, undefined ...string) string
- func (c *Context) Query(name string, undefined ...string) any
- func (c *Context) Response() *Response
- func (c *Context) RootContext() context.Context
- func (c *Context) Set(key string, value any)
- func (c *Context) Status(code int)
- func (c *Context) StreamResponse(statusCode int, reader io.Reader, mime ...string) *Response
- func (c *Context) StringResponse(statusCode int, content string) *Response
- func (c *Context) Unmarshal(data []byte, v interface{}) error
- func (c *Context) Validator() *validator.Validate
- type Ctx
- type DateBindMethod
- func (m *DateBindMethod) Marshal(obj any) ([]byte, error)
- func (m *DateBindMethod) Name() string
- func (m *DateBindMethod) New() any
- func (m *DateBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *DateBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type DateTimeBindMethod
- func (m *DateTimeBindMethod) Marshal(obj any) ([]byte, error)
- func (m *DateTimeBindMethod) Name() string
- func (m *DateTimeBindMethod) New() any
- func (m *DateTimeBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *DateTimeBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type DefaultLogger
- func (l *DefaultLogger) Debug(args ...any)
- func (l *DefaultLogger) Debugf(format string, v ...any)
- func (l *DefaultLogger) Error(args ...any)
- func (l *DefaultLogger) Errorf(format string, v ...any)
- func (l *DefaultLogger) Info(args ...any)
- func (l *DefaultLogger) Warn(args ...any)
- func (l *DefaultLogger) Warnf(format string, v ...any)
- type DependenceHandle
- type Dict
- type Event
- type EventKind
- type FastApi
- type Finder
- type FloatBindMethod
- func (m *FloatBindMethod) Marshal(obj any) ([]byte, error)
- func (m *FloatBindMethod) Name() string
- func (m *FloatBindMethod) New() any
- func (m *FloatBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *FloatBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type GroupRoute
- func (r *GroupRoute) Call(ctx *Context)
- func (r *GroupRoute) HasStructQuery() bool
- func (r *GroupRoute) Id() string
- func (r *GroupRoute) Init() (err error)
- func (r *GroupRoute) NewInParams(ctx *Context) []reflect.Value
- func (r *GroupRoute) NewRequestModel() any
- func (r *GroupRoute) NewStructQuery() any
- func (r *GroupRoute) QueryBinders() []*ParamBinder
- func (r *GroupRoute) RequestBinders() *ParamBinder
- func (r *GroupRoute) ResponseBinder() *ParamBinder
- func (r *GroupRoute) ResponseValidate(c *Context, stopImmediately bool) []*openapi.ValidationError
- func (r *GroupRoute) RouteType() RouteType
- func (r *GroupRoute) Scan() (err error)
- func (r *GroupRoute) ScanInner() (err error)
- func (r *GroupRoute) Swagger() *openapi.RouteSwagger
- type GroupRouteHandler
- type GroupRouter
- type GroupRouterMeta
- type H
- type IndexFinder
- type IntBindMethod
- func (m *IntBindMethod) Marshal(obj any) ([]byte, error)
- func (m *IntBindMethod) Name() string
- func (m *IntBindMethod) New() any
- func (m *IntBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *IntBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type JsonBindMethod
- func (m *JsonBindMethod[T]) Marshal(obj T) ([]byte, error)
- func (m *JsonBindMethod[T]) Name() string
- func (m *JsonBindMethod[T]) New() any
- func (m *JsonBindMethod[T]) Unmarshal(stream []byte, obj T) (ves []*openapi.ValidationError)
- func (m *JsonBindMethod[T]) Validate(ctx context.Context, data T) (T, []*openapi.ValidationError)
- type LoggerIface
- type ModelBindMethod
- type MuxContext
- type MuxHandler
- type MuxWrapper
- type None
- type NothingBindMethod
- func (m *NothingBindMethod) Marshal(obj any) ([]byte, error)
- func (m *NothingBindMethod) Name() string
- func (m *NothingBindMethod) New() any
- func (m *NothingBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *NothingBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type ParamBinder
- type Profile
- type QueryParamMode
- type Response
- type ResponseType
- type RouteErrorFormatter
- type RouteErrorOpt
- type RouteIface
- type RouteType
- type ScanHelper
- func (s ScanHelper) InferBaseQueryParam(param *openapi.RouteParam, routeType RouteType) *openapi.QModel
- func (s ScanHelper) InferBinderMethod(param openapi.SchemaIface, prototypeKind reflect.Kind, ...) ModelBindMethod
- func (s ScanHelper) InferObjectQueryParam(param *openapi.RouteParam) []*openapi.QModel
- func (s ScanHelper) InferQueryBinder(qmodel *openapi.QModel, routeType RouteType) *ParamBinder
- func (s ScanHelper) InferRequestBinder(model *openapi.BaseModelMeta, routeType RouteType) *ParamBinder
- func (s ScanHelper) InferResponseBinder(model *openapi.BaseModelMeta, routeType RouteType) *ParamBinder
- func (s ScanHelper) InferTimeParam(param *openapi.RouteParam) (*openapi.QModel, bool)
- type Scanner
- type SignedInteger
- type SimpleFinder
- type StructQueryBind
- type TimeBindMethod
- func (m *TimeBindMethod) Marshal(obj any) ([]byte, error)
- func (m *TimeBindMethod) Name() string
- func (m *TimeBindMethod) New() any
- func (m *TimeBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *TimeBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type UintBindMethod
- func (m *UintBindMethod) Marshal(obj any) ([]byte, error)
- func (m *UintBindMethod) Name() string
- func (m *UintBindMethod) New() any
- func (m *UintBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
- func (m *UintBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
- type UnsignedInteger
- type UploadFile
- type Wrapper
- func (f *Wrapper) ActivateHotSwitch(s ...int) *Wrapper
- func (f *Wrapper) Config() Config
- func (f *Wrapper) Context() context.Context
- func (f *Wrapper) DisableSwagAutoCreate() *Wrapper
- func (f *Wrapper) Done() <-chan struct{}
- func (f *Wrapper) Handler(ctx MuxContext) error
- func (f *Wrapper) IncludeRouter(router GroupRouter) *Wrapper
- func (f *Wrapper) Mux() MuxWrapper
- func (f *Wrapper) OnEvent(kind EventKind, fc func()) *Wrapper
- func (f *Wrapper) RootCtx() context.Contextdeprecated
- func (f *Wrapper) Run(host, port string)
- func (f *Wrapper) SetDescription(description string) *Wrapper
- func (f *Wrapper) SetHotListener(listener func(wrapper *Wrapper)) *Wrapper
- func (f *Wrapper) SetMux(mux MuxWrapper) *Wrapper
- func (f *Wrapper) SetRouteErrorFormatter(handle RouteErrorFormatter, opt ...RouteErrorOpt) *Wrapper
- func (f *Wrapper) SetRouteErrorResponse(model any) *Wrapper
- func (f *Wrapper) SetRouteErrorStatusCode(statusCode int) *Wrapper
- func (f *Wrapper) SetShutdownTimeout(timeout int) *Wrapper
- func (f *Wrapper) Shutdown()
- func (f *Wrapper) Use(hooks ...DependenceHandle) *Wrapper
- func (f *Wrapper) UseAfter(hooks ...DependenceHandle) *Wrapper
- func (f *Wrapper) UseBeforeWrite(fc func(c *Context)) *Wrapper
- func (f *Wrapper) UseDepends(hooks ...DependenceHandle) *Wrapper
- func (f *Wrapper) UsePrevious(hooks ...DependenceHandle) *Wrapper
Constants ¶
const ( ReceiverParamOffset = 0 // 接收器参数的索引位置 FirstInParamOffset = 1 // 第一个有效参数的索引位置,由于结构体接收器处于第一位置 FirstCustomInParamOffset = FirstInParamOffset + 1 // 第一个自定义参数的索引位置 FirstOutParamOffset = 0 LastOutParamOffset = 1 // 最后一个返回值参数的索引位置 OutParamNum = 2 )
const ( FirstInParamName = "Context" // 第一个入参名称 LastOutParamName = "error" // 最后一个出参名称 )
const ( ModelNotDefine = "Data model is undefined" ModelNotMatch = "Value type mismatch" ModelCannotString = "The return value cannot be a string" ModelCannotNumber = "The return value cannot be a number" ModelCannotInteger = "The return value cannot be a integer" ModelCannotBool = "The return value cannot be a boolean" ModelCannotArray = "The return value cannot be a array" PathPsIsEmpty = "Path must not be empty" QueryPsIsEmpty = "Query must not be empty" )
const ( Version = "0.2.11" Copyright = "chendemo12" Website = "https://github.com/Chendemo12" )
const DefaultErrorStatusCode = http.StatusInternalServerError
const HotSwitchSigint = 30
HotSwitchSigint 默认热调试开关
const HttpMethodMinimumLength = len(http.MethodGet)
const WebsocketMethod = "WS"
Variables ¶
var ( ReflectObjectType = utils.ReflectObjectType SetJsonEngine = utils.SetJsonEngine )
var Debug func(args ...any)
var Debugf func(format string, v ...any)
var Error func(args ...any)
var Errorf func(format string, v ...any)
var (
F = utils.CombineStrings
)
var HttpMethods = []string{ http.MethodGet, http.MethodPost, http.MethodPatch, http.MethodPut, http.MethodDelete, http.MethodOptions, }
var IllegalLastInParamType = append(openapi.IllegalRouteParamType, reflect.Ptr)
IllegalLastInParamType 非法的请求体类型, 不支持指针的指针
var IllegalResponseType = append(openapi.IllegalRouteParamType, reflect.Ptr)
IllegalResponseType 非法的返回值类型, 不支持指针的指针
var Info func(args ...any)
var Warn func(args ...any)
var Warnf func(format string, v ...any)
Functions ¶
func ParseJsoniterError ¶ added in v0.2.0
func ParseJsoniterError(err error, loc openapi.RouteParamType, objName string) *openapi.ValidationError
ParseJsoniterError 将jsoniter 的反序列化错误转换成 接口错误类型
func ParseValidatorError ¶ added in v0.2.0
func ParseValidatorError(err error, loc openapi.RouteParamType, objName string) []*openapi.ValidationError
ParseValidatorError 解析Validator的错误消息 如果不存在错误,则返回nil; 如果 err 是 validator.ValidationErrors 的错误, 则解析并返回详细的错误原因,反之则返回模糊的错误原因
func ReleaseResponse ¶ added in v0.2.0
func ReleaseResponse(resp *Response)
func ReplaceLogger ¶ added in v0.2.9
func ReplaceLogger(logger LoggerIface)
Types ¶
type BaseGroupRouter ¶ added in v0.2.0
type BaseGroupRouter struct { }
BaseGroupRouter (面向对象式)路由组基类 需实现 GroupRouter 接口
其中以 Get,Post,Delete,Patch,Put 字符串(不区分大小写)开头或结尾并以 (XXX, error)形式为返回值的方法会被作为路由处理 其url的确定按照 RoutePathSchema 接口进行解析。
对于作为路由的方法签名有如下要求:
1:参数: 第一个参数必须为 *Context 如果有多个参数, 除第一个参数和最后一个参数允许为结构体外, 其他参数必须为基本数据类型 对于Get/Delete:除第一个参数外的其他参数均被作为查询参数处理,如果为一个结构体,则对结构体字段进行解析并确定是否必选,如果为基本类型则全部为可选参数; 对于Post/Patch/Put: 其最后一个参数必须为一个 struct指针,此参数会作为请求体进行处理,其他参数则=全部为可选的查询参数 2:返回值 有且仅有2个返回值 (XXX, error) 其中XXX会作为响应体模型,若error!=nil则返回错误; 如果返回值XXX=nil则无响应体 对于上述参数和返回值XXX,其数据类型不能是 接口,函数,通道,指针的指针; 只能是以下类型:~int, ~float, ~string, ~slice, ~struct, ~map, 结构体指针; 对于结构体类型,最好实现了 SchemaIface 接口
func (*BaseGroupRouter) Description ¶ added in v0.2.0
func (g *BaseGroupRouter) Description() map[string]string
func (*BaseGroupRouter) ErrorFormatter
deprecated
added in
v0.2.8
func (g *BaseGroupRouter) ErrorFormatter() RouteErrorFormatter
Deprecated: 240426 隐藏此方法
func (*BaseGroupRouter) InParamsName ¶ added in v0.2.0
func (g *BaseGroupRouter) InParamsName() map[string]map[int]string
func (*BaseGroupRouter) Path ¶ added in v0.2.0
func (g *BaseGroupRouter) Path() map[string]string
func (*BaseGroupRouter) PathSchema ¶ added in v0.2.0
func (g *BaseGroupRouter) PathSchema() pathschema.RoutePathSchema
func (*BaseGroupRouter) Prefix ¶ added in v0.2.0
func (g *BaseGroupRouter) Prefix() string
func (*BaseGroupRouter) Summary ¶ added in v0.2.0
func (g *BaseGroupRouter) Summary() map[string]string
func (*BaseGroupRouter) Tags ¶ added in v0.2.0
func (g *BaseGroupRouter) Tags() []string
type BaseModel ¶
type BaseModel struct{}
BaseModel 基本数据模型, 对于上层的路由定义其请求体和响应体都应为继承此结构体的结构体 在 OpenApi 文档模型中,此模型的类型始终为 "object" 对于 BaseModel 其字段仍然可能会是 BaseModel
func (*BaseModel) IsRequired ¶ added in v0.2.0
func (*BaseModel) SchemaDesc ¶ added in v0.2.0
SchemaDesc 结构体文档注释
func (*BaseModel) SchemaType ¶ added in v0.2.0
SchemaType 模型类型
type BaseRouter ¶ added in v0.2.0
type BaseRouter = BaseGroupRouter
type BoolBindMethod ¶ added in v0.2.0
type BoolBindMethod struct {
Title string `json:"title,omitempty"`
}
func (*BoolBindMethod) Marshal ¶ added in v0.2.0
func (m *BoolBindMethod) Marshal(obj any) ([]byte, error)
func (*BoolBindMethod) Name ¶ added in v0.2.0
func (m *BoolBindMethod) Name() string
func (*BoolBindMethod) New ¶ added in v0.2.0
func (m *BoolBindMethod) New() any
New 返回 bool类型而零值false
func (*BoolBindMethod) Unmarshal ¶ added in v0.2.0
func (m *BoolBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
func (*BoolBindMethod) Validate ¶ added in v0.2.0
func (m *BoolBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
Validate data 为字符串类型
type Config ¶ added in v0.1.4
type Config struct { Version string `json:"version,omitempty" description:"APP版本号"` Description string `json:"description,omitempty" description:"APP描述"` Title string `json:"title,omitempty" description:"APP标题"` ShutdownTimeout int `json:"shutdown_timeout,omitempty" description:"平滑关机,单位秒"` DisableSwagAutoCreate bool `json:"disable_swag_auto_create,omitempty" description:"禁用OpenApi文档,但是不禁用参数校验"` StopImmediatelyWhenErrorOccurs bool `json:"stopImmediatelyWhenErrorOccurs" description:"是否在遇到错误字段时立刻停止校验"` ContextAutomaticDerivationDisabled bool `json:"contextAutomaticDerivationDisabled,omitempty" description:"禁止为每一个请求创建单独的Context"` }
type Context ¶
Context 路由上下文信息, 也是钩子函数的操作句柄
此结构体内包含了响应体 Response 以减少在路由处理过程中的内存分配和复制
注意: 当一个路由被执行完毕时, 路由函数中的 Context 将被立刻释放回收, 因此在return之后对 Context 的任何引用都是不对的, 若需在return之后监听 Context.Context() 则应该显式的复制或派生
func (*Context) AnyResponse ¶
AnyResponse 自定义响应体,响应体可是任意类型 (不校验返回值)
@param statusCode int 响应状态码 @param content any 响应体 @param contentType []string 响应头MIME, 默认值为“application/json; charset=utf-8” @return resp *Response response返回体
func (*Context) ContentType ¶ added in v0.2.0
ContentType 允许路由组路由函数修改响应MIME 由于路由组路由函数 GroupRouteHandler 签名的限制;其返回ContentType默认为"application/json; charset=utf-8" 允许通过此方法进行修改
func (*Context) Context ¶ added in v0.2.0
Context 针对此次请求的唯一context, 当路由执行完毕返回时,将会自动关闭 <如果 ContextAutomaticDerivationDisabled = true 则异常>
为每一个请求创建一个新的 context.Context 其代价是非常高的,因此允许通过设置关闭此功能
@return context.Context 当前请求的唯一context
func (*Context) Done ¶
func (c *Context) Done() <-chan struct{}
Done 监听 Context 是否完成退出 <如果 ContextAutomaticDerivationDisabled = true 则异常>
@return chan struct{} 是否退出
func (*Context) ErrorResponse ¶
ErrorResponse 返回一个服务器错误 (不校验返回值)
@param content any 错误消息 @return resp *Response response返回体
func (*Context) FileResponse ¶
FileResponse 返回值为文件对象,如:照片视频文件流等, 若文件不存在,则状态码置为404 (不校验返回值)
@param filepath string 文件路径 @return resp *Response response返回体
func (*Context) Get ¶ added in v0.2.2
Get 从上下文中读取键值, ie: (value, true). 如果不存在则返回 (nil, false) Get returns the value for the given key, ie: (value, true). If the value does not exist it returns (nil, false)
func (*Context) GetBool ¶ added in v0.2.2
GetBool 以bool形式读取键值 GetBool returns the value associated with the key as a boolean.
func (*Context) GetInt64 ¶ added in v0.2.2
GetInt64 以int64形式读取键值 GetInt64 returns the value associated with the key as an integer.
func (*Context) GetString ¶ added in v0.2.2
GetString 以字符串形式读取键值 GetString returns the value associated with the key as a string.
func (*Context) GetTime ¶ added in v0.2.2
GetTime 以time形式读取键值 GetTime returns the value associated with the key as time.
func (*Context) GetUint64 ¶ added in v0.2.2
GetUint64 以uint64形式读取键值 GetUint64 returns the value associated with the key as an unsigned integer.
func (*Context) HTMLResponse ¶
HTMLResponse 返回一段HTML文本 (不校验返回值)
@param statusCode int 响应状态码 @param content string HTML文本字符串 @return resp *Response response返回体
func (*Context) JSONResponse ¶
JSONResponse 仅支持可以json序列化的响应体 (校验返回值)
对于结构体类型: 其返回值为序列化后的json 对于基本数据类型: 其返回值为实际数值
@param statusCode int 响应状态码 @param content any 可以json序列化的类型 @return resp *Response response返回体
func (*Context) MustGet ¶ added in v0.2.2
MustGet 从上下文中读取键值,如果不存在则panic MustGet returns the value for the given key if it exists, otherwise it panics.
func (*Context) MuxContext ¶ added in v0.2.0
func (c *Context) MuxContext() MuxContext
MuxContext 获取web引擎的上下文
func (*Context) OKResponse ¶
OKResponse 返回状态码为200的 JSONResponse (校验返回值)
@param content any 可以json序列化的类型 @return resp *Response response返回体
func (*Context) PathField ¶ added in v0.2.0
PathField 获取路径参数 对于已经在路由处定义的路径参数,首先从 Context.pathFields 内部读取; 对于没有定义的其他查询参数则调用低层 MuxContext 进行解析
func (*Context) Query ¶ added in v0.2.0
Query 获取查询参数 对于已经在路由处定义的查询参数,首先从 Context.queryFields 内部读取 对于没有定义的其他查询参数则调用低层 MuxContext 进行解析
对于路由处定义的查询参数,参数类型会按照以下规则进行转换: int => int64 uint => uint64 float => float64 string => string bool => bool
func (*Context) Response ¶ added in v0.2.2
Response 响应体,配合 Wrapper.UseBeforeWrite 实现在依赖函数中读取响应体内容,以进行日志记录等 !慎重对 Response 进行修改!
func (*Context) RootContext ¶ added in v0.2.3
RootContext 根context 当禁用了context自动派生功能 <ContextAutomaticDerivationDisabled = true>,但又需要一个context时,可获得路由器Wrapper的context
func (*Context) Set ¶ added in v0.2.2
Set 存储一个键值对,延迟初始化 !仅当 MuxContext 未实现此类方法时采用! Set is used to store a new key/value pair exclusively for this context. It also lazy initializes c.Keys if it was not used previously.
func (*Context) Status ¶ added in v0.2.0
Status 修改成功响应的状态码 由于路由组路由函数 GroupRouteHandler 签名的限制;当error!=nil时状态码默认为500,error==nil时默认为200 允许通过此方法修改当error=nil的响应状态码
func (*Context) StreamResponse ¶
StreamResponse 返回值为字节流对象 (不校验返回值)
@param statusCode int 响应状态码 @param reader io.Reader 字节流 @param mime string 返回头媒体资源类型信息,缺省则为"text/plain" @return resp *Response response返回体
func (*Context) StringResponse ¶
StringResponse 返回值为字符串对象 (不校验返回值)
@param statusCode int 响应状态码 @param content string 字符串文本 @return resp *Response response返回体
type DateBindMethod ¶ added in v0.2.0
type DateBindMethod struct {
Title string `json:"title,omitempty" description:"查询参数名"`
}
DateBindMethod 日期校验
func (*DateBindMethod) Marshal ¶ added in v0.2.0
func (m *DateBindMethod) Marshal(obj any) ([]byte, error)
func (*DateBindMethod) Name ¶ added in v0.2.0
func (m *DateBindMethod) Name() string
func (*DateBindMethod) New ¶ added in v0.2.0
func (m *DateBindMethod) New() any
func (*DateBindMethod) Unmarshal ¶ added in v0.2.0
func (m *DateBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
func (*DateBindMethod) Validate ¶ added in v0.2.0
func (m *DateBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
type DateTimeBindMethod ¶ added in v0.2.0
type DateTimeBindMethod struct {
Title string `json:"title,omitempty" description:"查询参数名"`
}
DateTimeBindMethod 日期时间校验
func (*DateTimeBindMethod) Marshal ¶ added in v0.2.0
func (m *DateTimeBindMethod) Marshal(obj any) ([]byte, error)
func (*DateTimeBindMethod) Name ¶ added in v0.2.0
func (m *DateTimeBindMethod) Name() string
func (*DateTimeBindMethod) New ¶ added in v0.2.0
func (m *DateTimeBindMethod) New() any
func (*DateTimeBindMethod) Unmarshal ¶ added in v0.2.0
func (m *DateTimeBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
func (*DateTimeBindMethod) Validate ¶ added in v0.2.0
func (m *DateTimeBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
type DefaultLogger ¶ added in v0.2.0
type DefaultLogger struct {
// contains filtered or unexported fields
}
DefaultLogger 默认的控制台日志具柄
func NewDefaultLogger ¶ added in v0.2.0
func NewDefaultLogger() *DefaultLogger
func NewLogger ¶ added in v0.2.0
func NewLogger(out io.Writer, prefix string, flag int) *DefaultLogger
func (*DefaultLogger) Debug ¶ added in v0.2.0
func (l *DefaultLogger) Debug(args ...any)
func (*DefaultLogger) Debugf ¶ added in v0.2.0
func (l *DefaultLogger) Debugf(format string, v ...any)
func (*DefaultLogger) Error ¶ added in v0.2.0
func (l *DefaultLogger) Error(args ...any)
func (*DefaultLogger) Errorf ¶ added in v0.2.0
func (l *DefaultLogger) Errorf(format string, v ...any)
func (*DefaultLogger) Info ¶ added in v0.2.0
func (l *DefaultLogger) Info(args ...any)
func (*DefaultLogger) Warn ¶ added in v0.2.0
func (l *DefaultLogger) Warn(args ...any)
func (*DefaultLogger) Warnf ¶ added in v0.2.0
func (l *DefaultLogger) Warnf(format string, v ...any)
type DependenceHandle ¶ added in v0.2.4
DependenceHandle 依赖函数 Depends/Hook
type Finder ¶ added in v0.2.0
type Finder[T RouteIface] interface { Init(items []T) // 通过固定元素初始化查找器 Get(id string) (T, bool) Range(fn func(item T) bool) }
Finder 固定元素的查找器 用于从一个固定的元素集合内依据唯一标识来快速查找元素
func DefaultFinder ¶ added in v0.2.0
func DefaultFinder() Finder[RouteIface]
type FloatBindMethod ¶ added in v0.2.0
type FloatBindMethod struct { Title string `json:"title,omitempty"` Kind reflect.Kind `json:"kind,omitempty"` }
func (*FloatBindMethod) Marshal ¶ added in v0.2.0
func (m *FloatBindMethod) Marshal(obj any) ([]byte, error)
func (*FloatBindMethod) Name ¶ added in v0.2.0
func (m *FloatBindMethod) Name() string
func (*FloatBindMethod) Unmarshal ¶ added in v0.2.0
func (m *FloatBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
func (*FloatBindMethod) Validate ¶ added in v0.2.0
func (m *FloatBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
Validate 验证字符串data是否是一个float类型,data 应为string类型
type GroupRoute ¶ added in v0.2.0
type GroupRoute struct {
// contains filtered or unexported fields
}
GroupRoute 路由组路由定义
func NewGroupRoute ¶ added in v0.2.0
func NewGroupRoute(swagger *openapi.RouteSwagger, method reflect.Method, group *GroupRouterMeta) *GroupRoute
func (*GroupRoute) Call ¶ added in v0.2.0
func (r *GroupRoute) Call(ctx *Context)
Call 调用API, 并将响应结果写入 Response 内
func (*GroupRoute) HasStructQuery ¶ added in v0.2.0
func (r *GroupRoute) HasStructQuery() bool
func (*GroupRoute) Id ¶ added in v0.2.0
func (r *GroupRoute) Id() string
func (*GroupRoute) Init ¶ added in v0.2.0
func (r *GroupRoute) Init() (err error)
func (*GroupRoute) NewInParams ¶ added in v0.2.0
func (r *GroupRoute) NewInParams(ctx *Context) []reflect.Value
func (*GroupRoute) NewRequestModel ¶ added in v0.2.0
func (r *GroupRoute) NewRequestModel() any
func (*GroupRoute) NewStructQuery ¶ added in v0.2.0
func (r *GroupRoute) NewStructQuery() any
NewStructQuery 构造一个新的结构体查询参数实例
func (*GroupRoute) QueryBinders ¶ added in v0.2.0
func (r *GroupRoute) QueryBinders() []*ParamBinder
QueryBinders 查询参数校验方法
func (*GroupRoute) RequestBinders ¶ added in v0.2.0
func (r *GroupRoute) RequestBinders() *ParamBinder
func (*GroupRoute) ResponseBinder ¶ added in v0.2.0
func (r *GroupRoute) ResponseBinder() *ParamBinder
func (*GroupRoute) ResponseValidate ¶ added in v0.2.0
func (r *GroupRoute) ResponseValidate(c *Context, stopImmediately bool) []*openapi.ValidationError
ResponseValidate 仅校验“200的JSONResponse”
func (*GroupRoute) RouteType ¶ added in v0.2.0
func (r *GroupRoute) RouteType() RouteType
func (*GroupRoute) Scan ¶ added in v0.2.0
func (r *GroupRoute) Scan() (err error)
func (*GroupRoute) ScanInner ¶ added in v0.2.0
func (r *GroupRoute) ScanInner() (err error)
ScanInner 解析内部 openapi.RouteSwagger 数据
func (*GroupRoute) Swagger ¶ added in v0.2.0
func (r *GroupRoute) Swagger() *openapi.RouteSwagger
type GroupRouteHandler ¶ added in v0.2.0
GroupRouteHandler 路由组路由函数签名,其中any可以是具体的类型,但不应该是 Response
type GroupRouter ¶ added in v0.2.0
type GroupRouter interface { // Prefix 路由组前缀,无需考虑是否以/开头或结尾 // 如果为空则通过 PathSchema 方案进行格式化 Prefix() string // Tags 标签,如果为空则设为结构体名称的大驼峰形式,去掉可能存在的http方法名 Tags() []string // PathSchema 路由解析规则,对路由前缀和路由地址都有效 PathSchema() pathschema.RoutePathSchema // Summary 允许对单个方法路由的文档摘要信息进行定义 // 方法名:摘要信息 Summary() map[string]string // Description 方法名:描述信息 Description() map[string]string // Path 允许对方法的路由进行重载, 方法名:相对路由 // 由于以函数名确定方法路由的方式暂无法支持路径参数, 因此可通过此方式来定义路径参数 // 但是此处定义的路由不应该包含查询参数 // 路径参数以:开头, 查询参数以?开头 Path() map[string]string // InParamsName 允许对函数入参名称进行修改,仅适用于基本类型和time.Time类型的参数 // 由于go在编译后无法获得函数或方法的入参名称,只能获得入参的类型和偏移量, // 因此在openapi的文档生成中,作为查询参数的函数入参无法正确显示出查询参数名称,取而代之的是手动分配的一个虚假参数名,此名称会影响api的调用和查询参数的解析 // 对于此情况,推荐使用结构体来定义查询参数,以获得更好的使用体验 // 此外,对于入参较少的情况,允许通过手动的方式来分配一个名称。 // // // 对于方法:ManyGet(c *Context, age int, name string, graduate bool, source float64) // // 在未手动指定名称的情况下, 查询参数解析为: // age int => int_2 // name string => string_3 // graduate bool => bool_4 // source float64 => float64_5 // // 通过一下方式来手动指定名称: // { // "ManyGet": { // 2: "age", // 3: "name", // 4: "graduate", // 5: "source", // }, // } InParamsName() map[string]map[int]string }
GroupRouter 结构体路由组定义 用法:首先实现此接口,然后通过调用 Wrapper.IncludeRoute 方法进行注册绑定
type GroupRouterMeta ¶ added in v0.2.0
type GroupRouterMeta struct {
// contains filtered or unexported fields
}
GroupRouterMeta 反射构建路由组的元信息
func NewGroupRouteMeta ¶ added in v0.2.0
func NewGroupRouteMeta(router GroupRouter, errorFormatter RouteErrorFormatter) *GroupRouterMeta
NewGroupRouteMeta 构建一个路由组的主入口
func (*GroupRouterMeta) Init ¶ added in v0.2.0
func (r *GroupRouterMeta) Init() (err error)
func (*GroupRouterMeta) Routes ¶ added in v0.2.0
func (r *GroupRouterMeta) Routes() []*GroupRoute
func (*GroupRouterMeta) Scan ¶ added in v0.2.0
func (r *GroupRouterMeta) Scan() (err error)
func (*GroupRouterMeta) ScanInner ¶ added in v0.2.0
func (r *GroupRouterMeta) ScanInner() (err error)
ScanInner 处理内部路由 GroupRoute 的文档等数据
func (*GroupRouterMeta) String ¶ added in v0.2.0
func (r *GroupRouterMeta) String() string
type IndexFinder ¶ added in v0.2.0
type IndexFinder[T RouteIface] struct { // contains filtered or unexported fields }
func (*IndexFinder[T]) Get ¶ added in v0.2.0
func (f *IndexFinder[T]) Get(id string) (T, bool)
func (*IndexFinder[T]) Init ¶ added in v0.2.0
func (f *IndexFinder[T]) Init(items []T)
func (*IndexFinder[T]) Range ¶ added in v0.2.0
func (f *IndexFinder[T]) Range(fn func(item T) bool)
Range if false returned, for-loop will stop
type IntBindMethod ¶ added in v0.2.0
type IntBindMethod struct { Title string `json:"title,omitempty"` Kind reflect.Kind `json:"kind,omitempty"` Maximum int64 `json:"maximum,omitempty"` Minimum int64 `json:"minimum,omitempty"` }
IntBindMethod 有符号数字验证
func (*IntBindMethod) Marshal ¶ added in v0.2.0
func (m *IntBindMethod) Marshal(obj any) ([]byte, error)
func (*IntBindMethod) Name ¶ added in v0.2.0
func (m *IntBindMethod) Name() string
func (*IntBindMethod) Unmarshal ¶ added in v0.2.0
func (m *IntBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
func (*IntBindMethod) Validate ¶ added in v0.2.0
func (m *IntBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
type JsonBindMethod ¶ added in v0.2.0
type JsonBindMethod[T any] struct { Title string `json:"title,omitempty"` RouteParamType openapi.RouteParamType }
JsonBindMethod json数据类型验证器,适用于泛型路由
func (*JsonBindMethod[T]) Marshal ¶ added in v0.2.0
func (m *JsonBindMethod[T]) Marshal(obj T) ([]byte, error)
func (*JsonBindMethod[T]) Name ¶ added in v0.2.0
func (m *JsonBindMethod[T]) Name() string
func (*JsonBindMethod[T]) New ¶ added in v0.2.0
func (m *JsonBindMethod[T]) New() any
func (*JsonBindMethod[T]) Unmarshal ¶ added in v0.2.0
func (m *JsonBindMethod[T]) Unmarshal(stream []byte, obj T) (ves []*openapi.ValidationError)
func (*JsonBindMethod[T]) Validate ¶ added in v0.2.0
func (m *JsonBindMethod[T]) Validate(ctx context.Context, data T) (T, []*openapi.ValidationError)
type LoggerIface ¶ added in v0.2.0
type LoggerIface interface { Debug(args ...any) Info(args ...any) Warn(args ...any) Error(args ...any) Errorf(format string, args ...any) Warnf(format string, args ...any) Debugf(format string, args ...any) }
LoggerIface 自定义logger接口,log及zap等均已实现此接口
type ModelBindMethod ¶ added in v0.2.0
type ModelBindMethod interface { Name() string // 名称 // Validate // 校验方法,对于响应首先校验,然后在 Marshal;对于请求,首先 Unmarshal 然后再校验 // 对于不需要ctx参数的校验方法可默认设置为nil // data 为需要验证的数据模型,如果验证通过,则第一个返回值为做了类型转换的data Validate(ctx context.Context, data any) (any, []*openapi.ValidationError) Marshal(obj any) ([]byte, error) // 序列化方法,通过 ContentType 确定响应体类型 Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError) // 反序列化方法,通过 "http:header:Content-Type" 推断内容类型 New() any // 创建一个新实例 }
type MuxContext ¶ added in v0.2.0
type MuxContext interface { Method() string // [重要方法]获得当前请求方法,取值为 http.MethodGet, http.MethodPost 等 Path() string // [重要方法]获的当前请求的路由模式,而非请求Url Ctx() any // 原始的 Context Set(key string, value any) // Set用于存储专门用于此上下文的新键/值对,如果以前没有使用c.Keys,它也会延迟初始化它 Get(key string) (value any, exists bool) // 从上下文中读取键/值对 ClientIP() string // 获得客户端IP ContentType() string // 请求体的 Content-Type GetHeader(key string) string // 读取请求头 Cookie(name string) (string, error) // 读取cookie Params(key string, undefined ...string) string // 读取路径参数 Query(key string, undefined ...string) string // 读取查询参数 BindQuery(obj any) error // BindQuery 解析查询参数, error应为 validator.ValidationErrors 类型 CustomBindQueryMethod() bool // 是否自定义 BindQuery 方法 ShouldBind(obj any) error // ShouldBind 绑定请求体到obj上 = BodyParser + Validate,error 应为validator.ValidationErrors 类型 BodyParser(obj any) error // 反序列化请求体到 obj 上,作用相当于Unmarshal Validate(obj any) error // 校验请求体, error应为 validator.ValidationErrors 类型 CustomShouldBindMethod() bool // 是否自定义 ShouldBind 方法 Header(key, value string) // 添加响应头 [!!注意是添加响应头,而非读取] SetCookie(cookie *http.Cookie) // 添加cookie Redirect(code int, location string) error // 重定向 Status(code int) // 设置响应状态码 Write(p []byte) (int, error) // 写入响应字节流,当此方法执行完毕时应中断后续流程 SendString(s string) error // 写字符串到响应体,当此方法执行完毕时应中断后续流程 SendStream(stream io.Reader, size ...int) error // 写入消息流到响应体 JSON(code int, data any) error // 写入json响应体 JSONP(code int, data any) error // JSONP 支持 RenderHTML(name string, bind interface{}, layouts ...string) error // 用于返回HTML模板 XML(code int, obj any) error // 写入XML YAML(code int, obj any) error // 写入YAML TOML(code int, obj any) error // 写入TOML File(filepath string) error // 返回文件 FileAttachment(filepath, filename string) error // 将指定的文件以有效的方式写入主体流, 在客户端,文件通常会以给定的文件名下载 }
MuxContext Web引擎的 Context,例如 fiber.Ctx, gin.Context 此接口定义的方法无需全部实现
- Method 和 Path 方法必须实现且不可返回空值,否则将导致 panic
- 对于 MuxContext 缺少的方法,可通过直接调用 Ctx 来实现
- 对于 Set / Get 方法,如果实际的Context未提供,则通过 Context.Get/Context.Set 代替
- GetHeader, Cookie, Query, Params 是必须实现的方法
- BindQuery 存在内置实现,只有在需要自定义校验规则时才需要重写此方法,同时 CustomBindQueryMethod 需要返回 true
- ShouldBind 和 BodyParser + Validate 必须实现一个,如果请求体不是JSON时则重写此方法,同时 CustomShouldBindMethod 需要返回 true
type MuxHandler ¶ added in v0.2.0
type MuxHandler func(c MuxContext) error
type MuxWrapper ¶ added in v0.2.0
type MuxWrapper interface { // Listen 启动http server Listen(addr string) error // ShutdownWithTimeout 优雅关闭 ShutdownWithTimeout(timeout time.Duration) error // BindRoute 注册路由 BindRoute(method, path string, handler MuxHandler) error }
MuxWrapper WEB服务器包装器接口 为兼容不同的 server 引擎,需要对其二次包装
type None ¶ added in v0.2.6
type None struct{}
None 可用于POST/PATH/PUT方法的占位
func (*None) SchemaDesc ¶ added in v0.2.6
type NothingBindMethod ¶ added in v0.2.0
type NothingBindMethod struct{}
NothingBindMethod 空实现,用于什么也不做
func (*NothingBindMethod) Marshal ¶ added in v0.2.0
func (m *NothingBindMethod) Marshal(obj any) ([]byte, error)
func (*NothingBindMethod) Name ¶ added in v0.2.0
func (m *NothingBindMethod) Name() string
func (*NothingBindMethod) New ¶ added in v0.2.0
func (m *NothingBindMethod) New() any
func (*NothingBindMethod) Unmarshal ¶ added in v0.2.0
func (m *NothingBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
func (*NothingBindMethod) Validate ¶ added in v0.2.0
func (m *NothingBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
type ParamBinder ¶ added in v0.2.0
type ParamBinder struct { Method ModelBindMethod `json:"-"` QModel *openapi.QModel `json:"-"` RequestModel *openapi.BaseModelMeta `json:"-"` ResponseModel *openapi.BaseModelMeta `json:"-"` Title string `json:"title,omitempty"` RouteParamType openapi.RouteParamType `json:"route_param_type"` }
ParamBinder 参数验证模型
type Profile ¶ added in v0.2.0
type Profile struct { Host string `json:"host,omitempty" description:"运行地址"` Port string `json:"port,omitempty" description:"运行端口"` Title string `json:"title,omitempty" description:"程序名,同时作为日志文件名"` Version string `json:"version,omitempty" description:"程序版本号"` Description string `json:"description,omitempty" description:"程序描述"` ShutdownTimeout time.Duration `json:"shutdownTimeout,omitempty" description:"平滑关机,单位秒"` SwaggerDisabled bool `json:"swaggerDisabled,omitempty" description:"禁用自动文档"` ContextAutomaticDerivationDisabled bool `json:"contextAutomaticDerivationDisabled,omitempty" description:"禁用context自动派生"` // 默认情况下当请求校验过程遇到错误字段时,仍会继续向下校验其他字段,并最终将所有的错误消息一次性返回给调用方- // 当此设置被开启后,在遇到一个错误的参数时,会立刻停止终止流程,直接返回错误消息 StopImmediatelyWhenErrorOccurs bool `json:"stopImmediatelyWhenErrorOccurs" description:"是否在遇到错误字段时立刻停止校验"` }
type QueryParamMode ¶ added in v0.2.0
type QueryParamMode string
QueryParamMode 查询参数的定义模式,不同模式决定了查询参数的校验方式 对于泛型路由来说,仅存在 结构体查询参数 StructQueryParamMode 一种形式; 对于路由组路由来说,三种形式都存在
const ( // NoQueryParamMode 不存在查询参数 = 0 NoQueryParamMode QueryParamMode = "NoQueryParamMode" // SimpleQueryParamMode 只有基本数据类型的简单查询参数类型,不包含结构体类型的查询参数 = 1 SimpleQueryParamMode QueryParamMode = "SimpleQueryParamMode" // StructQueryParamMode 以结构体形式定义的查询参数模式 = 4 StructQueryParamMode QueryParamMode = "StructQueryParamMode" // MixQueryParamMode 二种形式都有的混合模式 = 7 MixQueryParamMode QueryParamMode = "MixQueryParamMode" )
type Response ¶
type Response struct { Content any `json:"content" description:"响应体"` // 默认情况下由 Type 类型决定 // // 对于 JSON 类型(默认类型), 为 application/json; charset=utf-8 不可更改 // 对于 String 类型, 默认为 text/plain; charset=utf-8; 可以修改 // 对于 Html 类型, 默认为 text/html; charset=utf-8; 不可修改 // 对于 File 类型, 默认为 text/plain; 可以修改 // 对于 Stream 类型, 无默认值; 可以修改 ContentType string `json:"-" description:"响应类型"` Type ResponseType `json:"-" description:"返回体类型"` StatusCode int `json:"-" description:"响应状态码"` }
Response 范型路由返回值 也用于内部直接传递数据,对于 GroupRouteHandler 不应将其作为函数返回值
func AcquireResponse ¶ added in v0.2.0
func AcquireResponse() *Response
type ResponseType ¶
type ResponseType int
const ( JsonResponseType ResponseType = iota + 1 StringResponseType StreamResponseType FileResponseType HtmlResponseType AnyResponseType )
type RouteErrorFormatter ¶ added in v0.2.6
RouteErrorFormatter 路由函数返回错误时的处理函数,可用于格式化错误信息后返回给客户端
程序启动时会主动调用此方法用于生成openApi文档,所以此函数不应返回 map等类型,否则将无法生成openApi文档 当路由函数返回错误时,会调用此函数,返回值会作为响应码和响应内容, 返回值仅限于可以JSON序列化的消息体 默认情况下,错误码为500,错误信息会作为字符串直接返回给客户端
type RouteErrorOpt ¶ added in v0.2.8
type RouteErrorOpt struct { StatusCode int `json:"statusCode" validate:"required" description:"请求错误时的状态码"` ResponseMode any `json:"responseMode" validate:"required" description:"请求错误时的响应体,空则为字符串"` Description string `json:"description,omitempty" description:"错误文档"` }
RouteErrorOpt 错误处理函数选项, 用于在 SetRouteErrorFormatter 方法里同时设置错误码和响应内容等内容
type RouteIface ¶ added in v0.2.0
type RouteIface interface { Scanner RouteType() RouteType Swagger() *openapi.RouteSwagger // 路由文档 QueryBinders() []*ParamBinder // 查询参数的处理接口(查询参数名:处理接口),每一个查询参数都必须绑定一个 ParamBinder RequestBinders() *ParamBinder // 请求体的处理接口,请求体也只有一个 ResponseBinder() *ParamBinder // 响应体的处理接口,响应体只有一个 NewInParams(ctx *Context) []reflect.Value // 创建一个完整的函数入参实例列表, 此方法会在完成请求参数校验 RequestBinders,QueryBinders 之后执行 NewStructQuery() any // 创建一个结构体查询参数实例,对于POST/PATCH/PUT, 即为 NewInParams 的最后一个元素; 对于GET/DELETE则为nil NewRequestModel() any // 创建一个请求体实例,对于POST/PATCH/PUT, 即为 NewInParams 的最后一个元素; 对于GET/DELETE则为nil HasStructQuery() bool // 是否存在结构体查询参数,如果存在则会调用 NewStructQuery 获得结构体实例 Call(ctx *Context) // 调用API, 需要将响应结果写入 Response 内 ResponseValidate(c *Context, stopImmediately bool) []*openapi.ValidationError Id() string }
RouteIface 路由定义 路由组接口定义或泛型接口定义都需实现此接口
type ScanHelper ¶ added in v0.2.0
type ScanHelper struct{}
func (ScanHelper) InferBaseQueryParam ¶ added in v0.2.0
func (s ScanHelper) InferBaseQueryParam(param *openapi.RouteParam, routeType RouteType) *openapi.QModel
InferBaseQueryParam 推断基本类型的查询参数
func (ScanHelper) InferBinderMethod ¶ added in v0.2.0
func (s ScanHelper) InferBinderMethod(param openapi.SchemaIface, prototypeKind reflect.Kind, modelType openapi.RouteParamType) ModelBindMethod
InferBinderMethod 利用反射推断参数的校验器
func (ScanHelper) InferObjectQueryParam ¶ added in v0.2.0
func (s ScanHelper) InferObjectQueryParam(param *openapi.RouteParam) []*openapi.QModel
InferObjectQueryParam 推断结构体类型的查询参数
func (ScanHelper) InferQueryBinder ¶ added in v0.2.0
func (s ScanHelper) InferQueryBinder(qmodel *openapi.QModel, routeType RouteType) *ParamBinder
func (ScanHelper) InferRequestBinder ¶ added in v0.2.0
func (s ScanHelper) InferRequestBinder(model *openapi.BaseModelMeta, routeType RouteType) *ParamBinder
func (ScanHelper) InferResponseBinder ¶ added in v0.2.0
func (s ScanHelper) InferResponseBinder(model *openapi.BaseModelMeta, routeType RouteType) *ParamBinder
InferResponseBinder 推断响应体的校验器
func (ScanHelper) InferTimeParam ¶ added in v0.2.0
func (s ScanHelper) InferTimeParam(param *openapi.RouteParam) (*openapi.QModel, bool)
type Scanner ¶ added in v0.2.0
type Scanner interface { Init() (err error) // 初始化元数据对象 Scan() (err error) // 扫描并初始化自己 ScanInner() (err error) // 扫描并初始化自己包含的字节点,通过 child.Init() 实现 }
Scanner 元数据接口 Init -> Scan -> ScanInner -> Init 级联初始化
type SignedInteger ¶ added in v0.2.0
SignedInteger 有符号数字约束
type SimpleFinder ¶ added in v0.2.0
type SimpleFinder[T RouteIface] struct { // contains filtered or unexported fields }
func (*SimpleFinder[T]) Get ¶ added in v0.2.0
func (s *SimpleFinder[T]) Get(id string) (T, bool)
func (*SimpleFinder[T]) Init ¶ added in v0.2.0
func (s *SimpleFinder[T]) Init(items []T)
func (*SimpleFinder[T]) Range ¶ added in v0.2.0
func (s *SimpleFinder[T]) Range(fn func(item T) bool)
Range if false returned, for-loop will stop
type StructQueryBind ¶ added in v0.2.0
type StructQueryBind struct {
// contains filtered or unexported fields
}
StructQueryBind 结构体查询参数验证器
func (*StructQueryBind) Bind ¶ added in v0.2.0
func (m *StructQueryBind) Bind(params map[string]any, obj any) []*openapi.ValidationError
func (*StructQueryBind) Unmarshal ¶ added in v0.2.0
func (m *StructQueryBind) Unmarshal(params map[string]any, obj any) *openapi.ValidationError
func (*StructQueryBind) Validate ¶ added in v0.2.0
func (m *StructQueryBind) Validate(obj any) []*openapi.ValidationError
type TimeBindMethod ¶ added in v0.2.0
type TimeBindMethod struct {
Title string `json:"title,omitempty" description:"查询参数名"`
}
TimeBindMethod 时间校验方法
func (*TimeBindMethod) Marshal ¶ added in v0.2.0
func (m *TimeBindMethod) Marshal(obj any) ([]byte, error)
func (*TimeBindMethod) Name ¶ added in v0.2.0
func (m *TimeBindMethod) Name() string
func (*TimeBindMethod) New ¶ added in v0.2.0
func (m *TimeBindMethod) New() any
func (*TimeBindMethod) Unmarshal ¶ added in v0.2.0
func (m *TimeBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
Unmarshal time 类型不支持反序列化
func (*TimeBindMethod) Validate ¶ added in v0.2.0
func (m *TimeBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
Validate 验证一个字符串是否是一个有效的时间字符串 @return time.Time
type UintBindMethod ¶ added in v0.2.0
type UintBindMethod struct { Title string `json:"title,omitempty"` Kind reflect.Kind `json:"kind,omitempty"` Maximum uint64 `json:"maximum,omitempty"` Minimum uint64 `json:"minimum,omitempty"` }
UintBindMethod 无符号数字验证
func (*UintBindMethod) Marshal ¶ added in v0.2.0
func (m *UintBindMethod) Marshal(obj any) ([]byte, error)
func (*UintBindMethod) Name ¶ added in v0.2.0
func (m *UintBindMethod) Name() string
func (*UintBindMethod) Unmarshal ¶ added in v0.2.0
func (m *UintBindMethod) Unmarshal(stream []byte, obj any) (ves []*openapi.ValidationError)
func (*UintBindMethod) Validate ¶ added in v0.2.0
func (m *UintBindMethod) Validate(ctx context.Context, data any) (any, []*openapi.ValidationError)
type UnsignedInteger ¶ added in v0.2.0
UnsignedInteger 无符号数字约束
type UploadFile ¶ added in v0.2.0
UploadFile 上传文件 通过声明此类型,以接收来自用户的上传文件
type Wrapper ¶ added in v0.2.0
type Wrapper struct {
// contains filtered or unexported fields
}
Wrapper 服务对象,本质是一个包装器
# usage ./test/group_router_test.go
func Create ¶ added in v0.2.0
Create 创建一个新的 Wrapper 服务 其存在目的在于在同一个应用里创建多个 Wrapper 实例,并允许每个实例绑定不同的服务器实现
getWrapper
func New ¶
New 实例化一个默认 Wrapper, 此方法与 Create 不能同时使用 与 Create 区别在于:Create 每次都会创建一个新的实例,NewNotStruct 多次调用获得的是同一个实例 语义相当于 __new__ 实现的单例
func (*Wrapper) ActivateHotSwitch ¶ added in v0.2.0
ActivateHotSwitch 创建一个热开关,监听信号量(默认值:30),用来触发一个动作
func (*Wrapper) DisableSwagAutoCreate ¶ added in v0.2.0
DisableSwagAutoCreate 禁用文档自动生成
func (*Wrapper) Done ¶ added in v0.2.0
func (f *Wrapper) Done() <-chan struct{}
Done 监听程序是否退出或正在关闭,仅当程序关闭时解除阻塞
func (*Wrapper) Handler ¶ added in v0.2.0
func (f *Wrapper) Handler(ctx MuxContext) error
Handler 路由函数 MuxHandler,实现逻辑类似于装饰器
路由处理方法(装饰器实现),用于请求体校验和返回体序列化,同时注入全局服务依赖, 此方法接收一个业务层面的路由钩子方法 RouteIface.Call
方法首先会查找路由元信息,如果找不到则直接跳过验证环节,由路由器返回404 反之:
- 申请一个 Context, 并初始化请求体、路由参数等
- 之后会校验并绑定路由参数(包含路径参数和查询参数)是否正确,如果错误则直接返回422错误,反之会继续序列化并绑定请求体(如果存在)序列化成功之后会校验请求参数的正确性,
- 校验通过后会调用 RouteIface.Call 并将返回值绑定在 Context 内的 Response 上
- 校验返回值,并返回422或将返回值写入到实际的 response
func (*Wrapper) IncludeRouter ¶ added in v0.2.0
func (f *Wrapper) IncludeRouter(router GroupRouter) *Wrapper
IncludeRouter 注册一个路由组
@param router *Router 路由组
func (*Wrapper) OnEvent ¶ added in v0.2.0
OnEvent 添加事件
@param kind 事件类型,取值需为 "startup"/"shutdown" @param fs func() 事件
func (*Wrapper) Run ¶ added in v0.2.0
Run 启动服务, 此方法会阻塞运行,因此必须放在main函数结尾 此方法已设置关闭事件和平滑关闭. 当 Interrupt 信号被触发时,首先会关闭 根Context,然后逐步执行“关机事件”,最后调用平滑关闭方法,关闭服务 启动前通过 SetShutdownTimeout 设置"平滑关闭异常时"的最大超时时间
func (*Wrapper) SetDescription ¶ added in v0.2.0
SetDescription 设置APP的详细描述信息
@param Description string 详细描述信息
func (*Wrapper) SetHotListener ¶ added in v0.2.6
SetHotListener 设置热开关监听器
func (*Wrapper) SetMux ¶ added in v0.2.0
func (f *Wrapper) SetMux(mux MuxWrapper) *Wrapper
SetMux 设置路由器,必须在启动之前设置
func (*Wrapper) SetRouteErrorFormatter ¶ added in v0.2.6
func (f *Wrapper) SetRouteErrorFormatter(handle RouteErrorFormatter, opt ...RouteErrorOpt) *Wrapper
SetRouteErrorFormatter 设置路由错误信息格式化函数 @param handle RouteErrorFormatter 路由错误信息格式化函数 @param opt RouteErrorOpt 路由错误信息的配置项, 仅用于设置文档显示
func (*Wrapper) SetRouteErrorResponse ¶ added in v0.2.8
SetRouteErrorResponse 描述错误信息格式化函数 RouteErrorFormatter 的响应体
func (*Wrapper) SetRouteErrorStatusCode ¶ added in v0.2.8
SetRouteErrorStatusCode 描述错误信息格式化函数 RouteErrorFormatter 的响应状态码
由于暂无法准确模拟出一个有效的 Context 对象,因此无法通过 RouteErrorFormatter 来推断出错误响应码和错误响应体 故此处需要配合 SetRouteErrorResponse 来显示设置错误响应信息,以生成openApi文档,未设置则不构建此部分的文档
func (*Wrapper) SetShutdownTimeout ¶ added in v0.2.0
SetShutdownTimeout 修改关机前最大等待时间
@param timeout in 修改关机前最大等待时间, 单位秒
func (*Wrapper) Use ¶ added in v0.2.0
func (f *Wrapper) Use(hooks ...DependenceHandle) *Wrapper
Use 添加一个依赖函数(锚点), 数据校验后依赖函数
由于 Wrapper 的核心实现类似于装饰器, 而非常规的中间件,因此无法通过 MuxWrapper 的中间件来影响到 Wrapper 的执行过程; 因此 Wrapper 在关键环节均定义了相关的依赖函数,类似于hook,以此来控制执行流程;
与python-FastApi的Depends不同的地方在于: python-FastApi.Depends接收Request作为入参,并将其返回值作为路由函数Handler的入参; 而此处的hook不返回值,而是通过 Context.Set 和 Context.Get 来进行上下文数据的传递,并通过返回 error 来终止后续的流程; 同时,由于 Context.Set 和 Context.Get 是线程安全的,因此可以放心的在依赖函数中操作 Context; 依赖函数的执行始终是顺序进行的,其执行顺序是固定的: 始终由 UsePrevious -> (请求参数)Validate -> UseAfter -> (路由函数)RouteHandler -> (响应参数)Validate -> UseBeforeWrite -> exit;
此处的依赖函数有校验前依赖函数和校验后依赖函数,分别通过 Wrapper.UsePrevious 和 Wrapper.UseAfter 注册; 当请求参数校验失败时不会执行 Wrapper.UseAfter 依赖函数, 请求参数会在 Wrapper.UsePrevious 执行完成之后被触发; 如果依赖函数要终止后续的流程,应返回 error, 错误消息会作为消息体返回给客户端, 响应数据格式默认为500+string,可通过 Wrapper.SetRouteErrorFormatter 进行修改;
func (*Wrapper) UseAfter ¶ added in v0.2.0
func (f *Wrapper) UseAfter(hooks ...DependenceHandle) *Wrapper
UseAfter 添加一个校验后依赖函数(也即路由前), 此依赖函数会在:请求参数校验后-路由函数调用前执行
func (*Wrapper) UseBeforeWrite ¶ added in v0.2.2
UseBeforeWrite 在数据写入响应流之前执行的钩子方法; 可用于日志记录, 所有请求无论何时终止都会执行此方法
func (*Wrapper) UseDepends ¶ added in v0.2.4
func (f *Wrapper) UseDepends(hooks ...DependenceHandle) *Wrapper
UseDepends 【别名】添加一个数据校验后依赖函数
func (*Wrapper) UsePrevious ¶ added in v0.2.0
func (f *Wrapper) UsePrevious(hooks ...DependenceHandle) *Wrapper
UsePrevious 添加一个校验前依赖函数,此依赖函数会在:请求参数校验前调用