fastapi

package module
v0.2.9 Latest Latest
Warning

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

 Go to latest Published: May 2, 2024 License: MIT Imports: 22 Imported by: 2

README

FastApi-Golang (包装器)

  • 类似python-FastApi的Golang实现;
  • 提供OpenApi文档的自动生成，提供Swagger和Redoc文档;
  • 通过一次代码编写同时生成文档和参数校验，无需编写swagger的代码注释;
  • 直接在路由函数中使用经过校验的请求参数，无需通过ShouldBind等方法;
  • 支持请求参数的自动校验：
    • 包括：Query、Path、Header、Cookie、Form、File 参数的自定校验(Header、Cookie、Form、File正在支持中)
    • Body参数的自动校验，支持json/multipart格式，json 基于validator
  • 包装器，不限制底层的HTTP框架，支持gin、fiber等框架，并可轻松的集成到任何框架中;

Usage 使用说明:

go get https://github.com/Chendemo12/fastapi

1. 快速实现

  1. 创建一个Wrapper对象：
import "github.com/Chendemo12/fastapi"

// 可选的 fastapi.Config 参数
app := fastapi.New(fastapi.Config{
    Version:     "v1.0.0",
    Description: "这是一段Http服务描述信息，会显示在openApi文档的顶部",
    Title:       "FastApi Example",
})

显示效果

显示效果
  1. 指定底层HTTP路由器，也称为Mux, 为兼容不同的Mux，还需要对Mux进行包装，其定义为MuxWrapper：
import "github.com/Chendemo12/fastapi/middleware/fiberWrapper"

// 此处采用默认的内置Fiber实现, 必须在启动之前设置
mux := fiberWrapper.Default()
app.SetMux(mux)

// 或者自定义Fiber实现
fiberEngine := fiber.New(fiber.Config{
    Prefork:       false,                   // 多进程模式
    CaseSensitive: true,                    // 区分路由大小写
    StrictRouting: true,                    // 严格路由
    ServerHeader:  "FastApi",               // 服务器头
    AppName:       "fastapi.fiber",         // 设置为 Response.Header.Server 属性
    ColorScheme:   fiber.DefaultColors,     // 彩色输出
    JSONEncoder:   utils.JsonMarshal,       // json序列化器
    JSONDecoder:   utils.JsonUnmarshal,     // json解码器
})                                          // 创建fiber引擎
mux := fiberWrapper.NewWrapper(fiberEngine) // 创建fiber包装器
app.SetMux(mux)
  1. 创建路由：
  • 实现fastapi.GroupRouter接口，并创建方法以定义路由：
// 创建一个结构体实现fastapi.GroupRouter接口
type ExampleRouter struct {
	fastapi.BaseGroupRouter
}

func (r *ExampleRouter) Prefix() string { return "/api/example" }

func (r *ExampleRouter) GetAppTitle(c *fastapi.Context) (string, error) {
	return "FastApi Example", nil
}

type UpdateAppTitleReq struct {
	Title string `json:"title" validate:"required" description:"App标题"`
}

func (r *ExampleRouter) PatchUpdateAppTitle(c *fastapi.Context, form *UpdateAppTitleReq) (*UpdateAppTitleReq, error) {
	return form, nil
}

// 注册路由
app.IncludeRouter(&ExampleRouter{})

显示效果

显示效果
  1. 启动：
app.Run("0.0.0.0", "8090") // 阻塞运行
  1. 完整示例：
package test

import (
	"github.com/Chendemo12/fastapi"
	"github.com/Chendemo12/fastapi/middleware/fiberWrapper"
	"testing"
)

// ExampleRouter 创建一个结构体实现fastapi.GroupRouter接口
type ExampleRouter struct {
	fastapi.BaseGroupRouter
}

func (r *ExampleRouter) Prefix() string { return "/api/example" }

func (r *ExampleRouter) GetAppTitle(c *fastapi.Context) (string, error) {
	return "FastApi Example", nil
}

type UpdateAppTitleReq struct {
	Title string `json:"title" validate:"required" description:"App标题"`
}

func (r *ExampleRouter) PatchUpdateAppTitle(c *fastapi.Context, form *UpdateAppTitleReq) (*UpdateAppTitleReq, error) {
	return form, nil
}

func TestExampleRouter(t *testing.T) {
	// 可选的 fastapi.Config 参数
	app := fastapi.New(fastapi.Config{
		Version:     "v1.0.0",
		Description: "这是一段Http服务描述信息，会显示在openApi文档的顶部",
		Title:       "FastApi Example",
	})

	// 此处采用默认的内置Fiber实现, 必须在启动之前设置
	mux := fiberWrapper.Default()
	app.SetMux(mux)

	// 注册路由
	app.IncludeRouter(&ExampleRouter{})

	app.Run("0.0.0.0", "8090") // 阻塞运行
}

显示效果

显示效果

2. 详细实现

2.1 路由方法定义

  • 路由定义的关键在于实现GroupRouter 接口:

    // GroupRouter 结构体路由组定义
// 用法：首先实现此接口，然后通过调用 Wrapper.IncludeRoute 方法进行注册绑定
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
}

  • 对于路由组ExampleRouter来说：

    • Tags 为 ExampleRouter
    • 路由组前缀为手动定义的/api/example
2.1.1 满足路由定义的方法要求：
  • 方法需为指针接收器
  • 方法必须是导出方法
  • 方法名必须以HTTP操作名开头或结尾：Post, Patch, Get, Delete, Put
  • 返回值必须为2个参数：(XXX, error), 第二个参数必须是error类型，第一个参数为任意参数，但不建议是map类型，不能是nil
  • 第一个入参必须是fastapi.Context,
    • 对于Post, Patch, Put 至少有一个自定义参数作为请求体，如果不需要请求体参数则用fastapi.None代替
    • 对于Get, Delete 则只能有一个自定义结构体参数作为查询参数，cookies，header等参数
2.1.2 有关方法入参的解析规则：
  • 对于Get，Delete：
    • 有且只有一个结构体入参，被解释为查询/路径等参数
  • 对于Post, Patch, Put:
    • 最后一个入参被解释为请求体，其他入参被解释为查询/路径等参数
2.1.3 参数定义
  • 建议用结构体来定义所有参数：
  • 参数的校验和文档的生成遵循Validator的标签要求
  • 任何情况下json标签都会被解释为参数名，对于查询参数则优先采用query标签名
  • 任何模型都可以通过SchemaDesc() string方法来添加模型说明，作用等同于python.__doc__属性

示例1：

type IPModel struct {
	IP     string `json:"ip" description:"IPv4地址"`
	Detail struct {
		IPv4     string `json:"IPv4" description:"IPv4地址"`
		IPv4Full string `json:"IPv4_full" description:"带端口的IPv4地址"`
		Ipv6     string `json:"IPv6" description:"IPv6地址"`
	} `json:"detail" description:"详细信息"`
}

func (m IPModel) SchemaDesc() string { return "IP信息" }

type DomainRecord struct {
	IP struct {
		Record *IPModel `json:"record" validate:"required" description:"解析记录"`
	} `json:"ip" validate:"required"`
	Addresses []struct {
		Host string `json:"host"`
		Port string `json:"port"`
	} `json:"addresses" validate:"required,gte=1" description:"主机地址"`
	Timestamp int64 `json:"timestamp" description:"时间戳"`
}

  • 其文档如下：

    显示效果

    显示效果
2.1.4 路由url解析 RoutePathSchema

  • 方法开头或结尾中包含的http方法名会被忽略，对于方法中包含多个关键字的仅第一个会被采用：

    • PostDelet - > 路由为delte， 方法为Post

  • 允许通过PathSchema() pathschema.RoutePathSchema来自定义解析规则，支持以下规则：

    • LowerCaseDash：全小写-短横线
    • LowerCaseBackslash：全小写段路由
    • LowerCamelCase：将结构体名称按单词分割后转换为小驼峰的形式后作为相对路由
    • LowerCase：将方法名按单词分割后全部转换为小写字符再直接拼接起来
    • UnixDash/ Dash：将方法名按单词分割后用"-"相连接
    • Underline：将方法名按单词分割后用"_"相连接
    • Backslash：按单词分段，每一个单词都作为一个路由段
    • Original：原始不变，保持结构体方法名(不含HTTP方法名),只拼接成合法的路由
    • AddPrefix：用于在分段路由基础上添加一个前缀字符，作用于每一段路径，通常与其他方案组合使用
    • AddSuffix：用于在分段路由基础上添加一个后缀字符，作用于每一段路径，通常与其他方案组合使用
    • Composition：组合式路由格式化方案, 通过按顺序执行多个 RoutePathSchema 获得最终路由

  • 详细示例可见 pathschema_test.go

    func TestFormat(t *testing.T) {
	type args struct {
		schema       RoutePathSchema
		prefix       string
		relativePath string
	}
	tests := []struct {
		name string
		args args
		want string
	}{
		{
			name: "UnixDash",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       &UnixDash{},
			},
			want: "/api/Read-Unix-Proc-Tree",
		},
		{
			name: "Underline",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       &Underline{},
			},
			want: "/api/Read_Unix_Proc_Tree",
		},
		{
			name: "LowerCamelCase",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       &LowerCamelCase{},
			},
			want: "/api/readUnixProcTree",
		},
		{
			name: "LowerCase",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       &LowerCase{},
			},
			want: "/api/readunixproctree",
		},
		{
			name: "Backslash",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       &Backslash{},
			},
			want: "/api/Read/Unix/Proc/Tree",
		},
		{
			name: "Original",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       &Original{},
			},
			want: "/api/ReadUnixProcTree",
		},
		{
			name: "LowerCaseDash",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       Default(),
			},
			want: "/api/read-unix-proc-tree",
		},
		{
			name: "LowerCaseUnderline",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       NewComposition(&LowerCase{}, &Underline{}),
			},
			want: "/api/read_unix_proc_tree",
		},
		{
			name: "LowerCaseDashUnderline",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       NewComposition(&LowerCase{}, &UnixDash{}, &Underline{}),
			},
			want: "/api/read-_unix-_proc-_tree",
		},
		{
			name: "LowerCaseDashUnderlineBackslash",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       NewComposition(NewComposition(&LowerCase{}, &UnixDash{}), &Underline{}, &Backslash{}),
			},
			want: "/api/read-_/unix-_/proc-_/tree",
		},
		{
			name: "LowerCaseWithPreEqual",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       NewComposition(&LowerCase{}, &AddPrefix{Prefix: "="}, &Backslash{}),
			},
			want: "/api/=read/=unix/=proc/=tree",
		},
		{
			name: "LowerCaseWithPostDash",
			args: args{
				prefix:       "/api",
				relativePath: "ReadUnixProcTree",
				schema:       NewComposition(&LowerCase{}, &AddSuffix{Suffix: "-"}, &Backslash{}),
			},
			want: "/api/read-/unix-/proc-/tree-",
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if got := Format(tt.args.prefix, tt.args.relativePath, tt.args.schema); got != tt.want {
				t.Errorf("Format() = %v, want %v", got, tt.want)
			}
		})
	}
}

示例2：

type DateTime struct {
	Name         *Name     `json:"name" query:"name"`
	Birthday     time.Time `json:"birthday" query:"birthday" description:"生日"` // 日期时间类型
	ImportantDay *struct {
		LoveDay          time.Time   `json:"love_day"`
		NameDay          time.Time   `json:"name_day"`
		ChildrenBirthday []time.Time `json:"children_birthday"`
	} `json:"important_day,omitempty" description:"纪念日"`
}

显示效果

显示效果
2.2 Config 配置项 app.go:Config
参数 作用 是否必选 默认值
Title APP标题 否 1.0.0
Version APP版本号 否 FastAPI Application
Description APP描述 否 FastAPI
ShutdownTimeout 平滑关机,单位秒 否 5
DisableSwagAutoCreate 禁用OpenApi文档，但是不禁用参数校验 否 false
StopImmediatelyWhenErrorOccurs 是否在遇到错误字段时立刻停止校验, 对于有多个请求参数时，默认会检查每一个参数是否合法，并最终返回所有的错误参数信息，设为true以在遇到一个错误参数时停止后续的参数校验并直接返回错误信息。 否 false
ContextAutomaticDerivationDisabled 禁止为每一个请求创建单独的context.Context 。为每一个请求单独创建一个派生自Wrapper.Context()的ctx是十分昂贵的开销，但有时有时十分必要的，禁用后调用 Context.Context() 将会产生错误 否 false
2.3 Wrapper 配置项 app.go:Wrapper
2.3.1 添加启动/关闭前同步事件 ，等同于 FastAPI.on_event(),
  • event_type: startup / shutdown；
  • 同步执行，应避免阻塞；
  • startup 会在初始化完成后、listen之前依次调用；
  • shutdown 会在Context cancel 之后，mux shutdown之前依次调用；
2.3.2 设置设置路由错误信息格式化函数 SetRouteErrorFormatter

  • 由于路由方法handler的定义中，其返回值必须有2个参数，且最后一个参数必须为 error 接口，因此当handler返回错误时，如何合理的返回错误消息也十分的重要；

  • 默认情况下当handler返回错误时，Wrapper 会返回500错误码和string类型的错误消息；

    错误消息

  • 允许通过 Wrapper.SetRouteErrorFormatter 方法来自定义错误消息:

    // 自定义错误格式
type ErrorMessage struct {
	Code      string `json:"code,omitempty" description:"错误码"`
	Message   string `json:"message,omitempty" description:"错误信息"`
	Timestamp int64  `json:"timestamp,omitempty"`
}

// 格式化路由函数错误消息
func FormatErrorMessage(c *fastapi.Context, err error) (statusCode int, message any) {
	return 400, &ErrorMessage{
		Code:      "0x1234",
		Message:   err.Error(),
		Timestamp: time.Now().Unix(),
	}
}

// 自定义错误格式
app.SetRouteErrorFormatter(FormatErrorMessage, fastapi.RouteErrorOpt{
    StatusCode:   400,
    ResponseMode: &ErrorMessage{},
    Description:  "服务器内部发生错误，请稍后重试",
})

    显示效果

    错误文档

  • 此时的接口返回值更新为：

    显示效果

    接口响应

  • RouteErrorFormatter的定义如下：

    // RouteErrorFormatter 路由函数返回错误时的处理函数，可用于格式化错误信息后返回给客户端
//
//	程序启动时会主动调用此方法用于生成openApi文档，所以此函数不应返回 map等类型，否则将无法生成openApi文档
//
//	当路由函数返回错误时，会调用此函数，返回值会作为响应码和响应内容, 返回值仅限于可以JSON序列化的消息体
//	默认情况下，错误码为500，错误信息会作为字符串直接返回给客户端
type RouteErrorFormatter func(c *Context, err error) (statusCode int, resp any)

  • 其中实际接口响应的状态码以RouteErrorFormatter的返回值为准，而非fastapi.RouteErrorOpt中的配置，fastapi.RouteErrorOpt的配置仅仅作用于文档显示。

2.3.3 使用依赖 DependenceHandle
// DependenceHandle 依赖函数 Depends/Hook
type DependenceHandle func(c *Context) error

  • 对于Wrapper而言，其本质是一个装饰器，是对具体的Mux的包装，因此其自身并没有中间件的概念，同时也是为了避免与Mux的中间件引起冲突，有关的Wraper与Mux的核心交互定义如下：

    • Wraper会将使用者定义的每一个handler进行二次包装，并作为Mux的handler注册到路由器上，其包装后的定义如下：
    // Handler 路由函数，实现逻辑类似于装饰器
//
// 路由处理方法(装饰器实现)，用于请求体校验和返回体序列化，同时注入全局服务依赖,
// 此方法接收一个业务层面的路由钩子方法 RouteIface.Call
//
// 方法首先会查找路由元信息，如果找不到则直接跳过验证环节，由路由器返回404
// 反之：
//
//  1. 申请一个 Context, 并初始化请求体、路由参数等
//  2. 之后会校验并绑定路由参数（包含路径参数和查询参数）是否正确，如果错误则直接返回422错误，反之会继续序列化并绑定请求体（如果存在）序列化成功之后会校验请求参数的正确性，
//  3. 校验通过后会调用 RouteIface.Call 并将返回值绑定在 Context 内的 Response 上
//  4. 校验返回值，并返回422或将返回值写入到实际的 response
func (f *Wrapper) Handler(ctx MuxContext) error {}

  • 建议将跨域访问，Recover等方法注册为Mux的中件间；而将日志、认证等业务方法注册为Wraper的依赖，但是其2者并没有十分明显的区别，绝大部分情况都可以互相替换；

  • Wraper.Handler 的实现是一个顺序执行的过程，其作为一个整体，因此是无法在Mux的中间件中对其进行访问和拦截的，为此Wraper暴露出了一些锚点，用于控制Wraper.Handler的执行流：

    • Wrapper.UsePrevious： 添加一个校验前依赖函数，此依赖函数会在：请求参数校验前调用

    • Wrapper.UseAfter： 添加一个校验后依赖函数(也即路由前), 此依赖函数会在：请求参数校验后-路由函数调用前执行

    • Wrapper.UseBeforeWrite： 在数据写入响应流之前执行的钩子方法; 可用于日志记录, 所有请求无论何时终止都会执行此方法

    • Wrapper.UseDepends： UseAfter的别名

    • Wrapper.Use： UseAfter的别名

      // 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 (f *Wrapper) Use(hooks ...DependenceHandle) *Wrapper {
	return f.UseAfter(hooks...)
}

    • 使用示例：

      func BeforeValidate(c *fastapi.Context) error {
	c.Set("before-validate", time.Now())

	return nil
}

func PrintRequestLog(c *fastapi.Context) {
	fastapi.Info("请求耗时: ", time.Since(c.GetTime("before-validate")))
	fastapi.Info("响应状态码: ", c.Response().StatusCode)
}

func returnErrorDeps(c *fastapi.Context) error {
	return errors.New("deps return error")
}

app.UsePrevious(BeforeValidate)
app.Use(returnErrorDeps)
app.UseBeforeWrite(PrintRequestLog)

      显示效果

      显示效果
      ```bash
2024/04/27 17:47:38 group_router_test.go:522: INFO	请求耗时:  10.372µs
2024/04/27 17:47:38 group_router_test.go:523: INFO	响应状态码:  400
2024-04-27 17:47:38    GET	/api/example/error    400
2024/04/27 17:47:38 group_router_test.go:522: INFO	请求耗时:  11.855µs
2024/04/27 17:47:38 group_router_test.go:523: INFO	响应状态码:  400
2024-04-27 17:47:38    GET	/api/example/error    400
2024/04/27 17:47:38 group_router_test.go:522: INFO	请求耗时:  6.739µs
2024/04/27 17:47:38 group_router_test.go:523: INFO	响应状态码:  400
2024-04-27 17:47:38    GET	/api/example/error    400
```

开发选项

TODO

查看在线文档

# 安装godoc
go install golang.org/x/tools/cmd/godoc@latest
godoc -http=:6060

# 或：pkgsite 推荐
go install golang.org/x/pkgsite/cmd/pkgsite@latest
cd fastapi-go/
pkgsite -http=:6060 -list=false
# 浏览器打开：http://127.0.0.1:6060/github.com/Chendemo12/fastapi

struct内存对齐

go install golang.org/x/tools/go/analysis/passes/fieldalignment/cmd/fieldalignment@latest

fieldalignment -fix ./...

打包静态资源文件

# 安装工具
go get -u github.com/go-bindata/go-bindata/...
go install github.com/go-bindata/go-bindata/...

# 下载资源文件
#https://fastapi.tiangolo.com/img/favicon.png
#https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css
#https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js
#https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js

# 打包资源文件到openapi包
go-bindata -o openapi/css.go --pkg openapi internal/static/...

Documentation

Overview

Package fastapi FastApi-Python 的Golang实现

其提供了类似于FastAPI的API设计，并提供了接口文档自动生成、请求体自动校验和返回值自动序列化等使用功能；

Index

Constants

View Source 
const (
	ReceiverParamOffset      = 0                      // 接收器参数的索引位置
	FirstInParamOffset       = 1                      // 第一个有效参数的索引位置，由于结构体接收器处于第一位置
	FirstCustomInParamOffset = FirstInParamOffset + 1 // 第一个自定义参数的索引位置
	FirstOutParamOffset      = 0
	LastOutParamOffset       = 1 // 最后一个返回值参数的索引位置
	OutParamNum              = 2
)
View Source 
const (
	FirstInParamName = "Context" // 第一个入参名称
	LastOutParamName = "error"   // 最后一个出参名称
)
View Source 
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"
)
View Source 
const (
	Version   = "0.2.9"
	Copyright = "chendemo12"
	Website   = "https://github.com/Chendemo12"
)
View Source 
const DefaultErrorStatusCode = http.StatusInternalServerError
View Source 
const HotSwitchSigint = 30

HotSwitchSigint 默认热调试开关

View Source 
const HttpMethodMinimumLength = len(http.MethodGet)
View Source 
const WebsocketMethod = "WS"

Variables

View Source 
var (
	ReflectObjectType = utils.ReflectObjectType
	SetJsonEngine     = utils.SetJsonEngine
)
View Source 
var Debug func(args ...any)
View Source 
var Debugf func(format string, v ...any)
View Source 
var Error func(args ...any)
View Source 
var Errorf func(format string, v ...any)
View Source 
var (
	F = utils.CombineStrings
)
View Source 
var HttpMethods = []string{
	http.MethodGet,
	http.MethodPost,
	http.MethodPatch,
	http.MethodPut,
	http.MethodDelete,
	http.MethodOptions,
}
View Source 
var IllegalLastInParamType = append(openapi.IllegalRouteParamType, reflect.Ptr)

IllegalLastInParamType 非法的请求体类型, 不支持指针的指针

View Source 
var IllegalResponseType = append(openapi.IllegalRouteParamType, reflect.Ptr)

IllegalResponseType 非法的返回值类型, 不支持指针的指针

View Source 
var Info func(args ...any)
View Source 
var Warn func(args ...any)
View Source 
var Warnf func(format string, v ...any)

Functions

func Iter added in v0.2.0 

func Iter[T any, S any](seq []S, fc func(elem S) T) []T

func LazyInit added in v0.2.0 

func LazyInit()

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 (b *BaseModel) IsRequired() bool

func (*BaseModel) SchemaDesc added in v0.2.0 

func (b *BaseModel) SchemaDesc() string

SchemaDesc 结构体文档注释

func (*BaseModel) SchemaType added in v0.2.0 

func (b *BaseModel) SchemaType() openapi.DataType

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 

type Context struct {

	// 每个请求专有的K/V
	Keys map[string]any
	// contains filtered or unexported fields
}

Context 路由上下文信息, 也是钩子函数的操作句柄

此结构体内包含了响应体 Response 以减少在路由处理过程中的内存分配和复制 

注意: 当一个路由被执行完毕时, 路由函数中的 Context 将被立刻释放回收, 因此在return之后对
Context 的任何引用都是不对的, 若需在return之后监听 Context.Context() 则应该显式的复制或派生

func (*Context) AnyResponse 

func (c *Context) AnyResponse(statusCode int, content any, contentType ...string) *Response

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 

func (c *Context) ContentType(contentType string)

ContentType 允许路由组路由函数修改响应MIME 由于路由组路由函数 GroupRouteHandler 签名的限制；其返回ContentType默认为"application/json; charset=utf-8" 允许通过此方法进行修改

func (*Context) Context added in v0.2.0 

func (c *Context) Context() context.Context

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 

func (c *Context) ErrorResponse(content any) *Response

ErrorResponse 返回一个服务器错误 (不校验返回值) 

@param	content	any	错误消息
@return	resp *Response response返回体

func (*Context) F 

func (c *Context) F(s ...string) string

F 合并字符串

func (*Context) FileResponse 

func (c *Context) FileResponse(filepath string) *Response

FileResponse 返回值为文件对象，如：照片视频文件流等, 若文件不存在，则状态码置为404 (不校验返回值) 

@param	filepath	string	文件路径
@return	resp *Response response返回体

func (*Context) Get added in v0.2.2 

func (c *Context) Get(key string) (value any, exists bool)

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 

func (c *Context) GetBool(key string) (b bool)

GetBool 以bool形式读取键值 GetBool returns the value associated with the key as a boolean.

func (*Context) GetInt64 added in v0.2.2 

func (c *Context) GetInt64(key string) (i64 int64)

GetInt64 以int64形式读取键值 GetInt64 returns the value associated with the key as an integer.

func (*Context) GetString added in v0.2.2 

func (c *Context) GetString(key string) (s string)

GetString 以字符串形式读取键值 GetString returns the value associated with the key as a string.

func (*Context) GetTime added in v0.2.2 

func (c *Context) GetTime(key string) (t time.Time)

GetTime 以time形式读取键值 GetTime returns the value associated with the key as time.

func (*Context) GetUint64 added in v0.2.2 

func (c *Context) GetUint64(key string) (ui64 uint64)

GetUint64 以uint64形式读取键值 GetUint64 returns the value associated with the key as an unsigned integer.

func (*Context) HTMLResponse 

func (c *Context) HTMLResponse(statusCode int, content []byte) *Response

HTMLResponse 返回一段HTML文本 (不校验返回值) 

@param	statusCode	int		响应状态码
@param	content		string	HTML文本字符串
@return	resp *Response response返回体

func (*Context) JSONResponse 

func (c *Context) JSONResponse(statusCode int, content any) *Response

JSONResponse 仅支持可以json序列化的响应体 (校验返回值)

对于结构体类型: 其返回值为序列化后的json 对于基本数据类型: 其返回值为实际数值 

@param	statusCode	int	响应状态码
@param	content		any	可以json序列化的类型
@return	resp *Response response返回体

func (*Context) MX added in v0.2.8 

func (c *Context) MX() any

MX shortcut web引擎的上下文

func (*Context) Marshal 

func (c *Context) Marshal(obj any) ([]byte, error)

func (*Context) MustGet added in v0.2.2 

func (c *Context) MustGet(key string) any

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 

func (c *Context) OKResponse(content any) *Response

OKResponse 返回状态码为200的 JSONResponse (校验返回值) 

@param	content	any	可以json序列化的类型
@return	resp *Response response返回体

func (*Context) PathField added in v0.2.0 

func (c *Context) PathField(name string, undefined ...string) string

PathField 获取路径参数 对于已经在路由处定义的路径参数，首先从 Context.pathFields 内部读取； 对于没有定义的其他查询参数则调用低层 MuxContext 进行解析

func (*Context) Query added in v0.2.0 

func (c *Context) Query(name string, undefined ...string) any

Query 获取查询参数 对于已经在路由处定义的查询参数，首先从 Context.queryFields 内部读取 对于没有定义的其他查询参数则调用低层 MuxContext 进行解析 

对于路由处定义的查询参数，参数类型会按照以下规则进行转换：

int 	=> int64
uint 	=> uint64
float 	=> float64
string 	=> string
bool 	=> bool

func (*Context) Response added in v0.2.2 

func (c *Context) Response() *Response

Response 响应体，配合 Wrapper.UseBeforeWrite 实现在依赖函数中读取响应体内容，以进行日志记录等 ！慎重对 Response 进行修改！

func (*Context) RootContext added in v0.2.3 

func (c *Context) RootContext() context.Context

RootContext 根context 当禁用了context自动派生功能 <ContextAutomaticDerivationDisabled = true>，但又需要一个context时，可获得路由器Wrapper的context

func (*Context) Set added in v0.2.2 

func (c *Context) Set(key string, value any)

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 

func (c *Context) Status(code int)

Status 允许路由组路由函数在error=nil时修改响应状态码 由于路由组路由函数 GroupRouteHandler 签名的限制；当error=nil时状态码默认为500，error!=nil时默认为200 允许通过此方法进行修改

func (*Context) StreamResponse 

func (c *Context) StreamResponse(statusCode int, reader io.Reader, mime ...string) *Response

StreamResponse 返回值为字节流对象 (不校验返回值) 

@param	statusCode	int			响应状态码
@param	reader		io.Reader	字节流
@param	mime		string		返回头媒体资源类型信息,缺省则为"text/plain"
@return	resp *Response response返回体

func (*Context) StringResponse 

func (c *Context) StringResponse(statusCode int, content string) *Response

StringResponse 返回值为字符串对象 (不校验返回值) 

@param	statusCode	int		响应状态码
@param	content		string	字符串文本
@return	resp *Response response返回体

func (*Context) Unmarshal 

func (c *Context) Unmarshal(data []byte, v interface{}) error

func (*Context) Validator 

func (c *Context) Validator() *validator.Validate

Validator 获取请求体验证器

type Ctx 

type Ctx = Context

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 

type DependenceHandle func(c *Context) error

DependenceHandle 依赖函数 Depends/Hook

type Dict 

type Dict = map[string]any // python.Dict

type Event 

type Event struct {
	Fc   func()
	Type EventKind // 事件类型：startup 或 shutdown
}

Event 事件

type EventKind 

type EventKind string

EventKind 事件类型 

const (
	StartupEvent  EventKind = "startup"
	ShutdownEvent EventKind = "shutdown"
)

type FastApi 

type FastApi = Wrapper

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) New added in v0.2.0 

func (m *FloatBindMethod) New() any

New 返回float64的零值

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 

type GroupRouteHandler func(c *Context, params ...any) (any, error)

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 H 

type H = map[string]any // gin.H

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) New added in v0.2.0 

func (m *IntBindMethod) New() any

New 返回int的零值

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 此接口定义的方法无需全部实现

  1. Method 和 Path 方法必须实现且不可返回空值，否则将导致 panic
  2. 对于 MuxContext 缺少的方法，可通过直接调用 Ctx 来实现
  3. 对于 Set / Get 方法，如果实际的Context未提供，则通过 Context.Get/Context.Set 代替
  4. GetHeader, Cookie, Query, Params 是必须实现的方法
  5. BindQuery 存在内置实现，只有在需要自定义校验规则时才需要重写此方法，同时 CustomBindQueryMethod 需要返回 true
  6. 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 

func (*None) SchemaDesc() string

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 

type RouteErrorFormatter func(c *Context, err error) (statusCode int, resp any)

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 RouteType added in v0.2.0 

type RouteType string
const (
	RouteTypeGroup   RouteType = "GroupRoute"
	RouteTypeGeneric RouteType = "GenericRouteMeta"
)

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 

type SignedInteger interface {
	~int8 | ~int16 | ~int32 | ~int64 | ~int
}

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) New added in v0.2.0 

func (m *UintBindMethod) New() any

New 返回uint的零值

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 

type UnsignedInteger interface {
	~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uint
}

UnsignedInteger 无符号数字约束

type UploadFile added in v0.2.0 

type UploadFile struct {
	Filename string
	File     io.Reader
	Headers  map[string]string
}

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 

func Create(c Config) *Wrapper

Create 创建一个新的 Wrapper 服务 其存在目的在于在同一个应用里创建多个 Wrapper 实例，并允许每个实例绑定不同的服务器实现

getWrapper

func New 

func New(c ...Config) *Wrapper

New 实例化一个默认 Wrapper, 此方法与 Create 不能同时使用 与 Create 区别在于：Create 每次都会创建一个新的实例，NewNotStruct 多次调用获得的是同一个实例 语义相当于 __new__ 实现的单例

func (*Wrapper) ActivateHotSwitch added in v0.2.0 

func (f *Wrapper) ActivateHotSwitch(s ...int) *Wrapper

ActivateHotSwitch 创建一个热开关，监听信号量(默认值：30)，用来触发一个动作

func (*Wrapper) Config added in v0.2.0 

func (f *Wrapper) Config() Config

func (*Wrapper) Context added in v0.2.3 

func (f *Wrapper) Context() context.Context

Context Wrapper根 context

func (*Wrapper) DisableSwagAutoCreate added in v0.2.0 

func (f *Wrapper) DisableSwagAutoCreate() *Wrapper

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 反之：

  1. 申请一个 Context, 并初始化请求体、路由参数等
  2. 之后会校验并绑定路由参数（包含路径参数和查询参数）是否正确，如果错误则直接返回422错误，反之会继续序列化并绑定请求体（如果存在）序列化成功之后会校验请求参数的正确性，
  3. 校验通过后会调用 RouteIface.Call 并将返回值绑定在 Context 内的 Response 上
  4. 校验返回值，并返回422或将返回值写入到实际的 response

func (*Wrapper) IncludeRouter added in v0.2.0 

func (f *Wrapper) IncludeRouter(router GroupRouter) *Wrapper

IncludeRouter 注册一个路由组 

@param	router	*Router	路由组

func (*Wrapper) Mux added in v0.2.0 

func (f *Wrapper) Mux() MuxWrapper

Mux 获取路由器

func (*Wrapper) OnEvent added in v0.2.0 

func (f *Wrapper) OnEvent(kind EventKind, fc func()) *Wrapper

OnEvent 添加事件 

@param	kind	事件类型，取值需为	"startup"/"shutdown"
@param	fs		func()		事件

func (*Wrapper) RootCtx deprecated added in v0.2.0 

func (f *Wrapper) RootCtx() context.Context

Deprecated: RootCtx 根 context, 使用 Wrapper.Context()

func (*Wrapper) Run added in v0.2.0 

func (f *Wrapper) Run(host, port string)

Run 启动服务, 此方法会阻塞运行，因此必须放在main函数结尾 此方法已设置关闭事件和平滑关闭. 当 Interrupt 信号被触发时，首先会关闭 根Context，然后逐步执行“关机事件”，最后调用平滑关闭方法，关闭服务 启动前通过 SetShutdownTimeout 设置"平滑关闭异常时"的最大超时时间

func (*Wrapper) SetDescription added in v0.2.0 

func (f *Wrapper) SetDescription(description string) *Wrapper

SetDescription 设置APP的详细描述信息 

@param	Description	string	详细描述信息

func (*Wrapper) SetHotListener added in v0.2.6 

func (f *Wrapper) SetHotListener(listener func(wrapper *Wrapper)) *Wrapper

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 

func (f *Wrapper) SetRouteErrorResponse(model any) *Wrapper

SetRouteErrorResponse 描述错误信息格式化函数 RouteErrorFormatter 的响应体

func (*Wrapper) SetRouteErrorStatusCode added in v0.2.8 

func (f *Wrapper) SetRouteErrorStatusCode(statusCode int) *Wrapper

SetRouteErrorStatusCode 描述错误信息格式化函数 RouteErrorFormatter 的响应状态码 

由于暂无法准确模拟出一个有效的 Context 对象，因此无法通过 RouteErrorFormatter 来推断出错误响应码和错误响应体
故此处需要配合 SetRouteErrorResponse 来显示设置错误响应信息，以生成openApi文档，未设置则不构建此部分的文档

func (*Wrapper) SetShutdownTimeout added in v0.2.0 

func (f *Wrapper) SetShutdownTimeout(timeout int) *Wrapper

SetShutdownTimeout 修改关机前最大等待时间 

@param	timeout	in	修改关机前最大等待时间,	单位秒

func (*Wrapper) Shutdown added in v0.2.0 

func (f *Wrapper) Shutdown()

Shutdown 平滑关闭

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 

func (f *Wrapper) UseBeforeWrite(fc func(c *Context)) *Wrapper

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 添加一个校验前依赖函数，此依赖函数会在：请求参数校验前调用

Source Files

View all Source files

Directories

Path Synopsis
middleware
fiberWrapper
ginWrapper
routers
Code generated by go-bindata.
 Code generated by go-bindata.

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.