gin版本v1.10.0

包函数

方法 含义 说明
BasicAuth 创建一个HTTP基本认证(Basic HTTP Authorization)的中间件 底层调用BasicAuthForRealm
BasicAuthForProxy 创建一个HTTP代理基本认证(Basic HTTP Proxy - Authorization)的中间件
BasicAuthForRealm 创建一个HTTP基本认证(Basic HTTP Authorization)的中间件
Bind 创建一个用于将请求中的数据绑定到指定的接口对象上的中间件
CreateTestContext 创建一个干净的Engine实例和一个与之关联的上下文对象用于测试
CreateTestContextOnly 在已有的Engine实例基础上创建一个独立的上下文用于测试
CustomRecovery 根据自定义的处理函数创建一个恢复中间件 底层调用CustomRecoveryWithWriter
CustomRecoveryWithWriter 创建一个自定义的恢复中间件
Default 返回一个默认的Engine实例 默认含LoggerRecovery两个中间件
Dir 返回一个http.FileSystem接口的实现,该实现可被http.FileServer使用
DisableBindValidation 关闭默认的验证器
DisableConsoleColor 禁用控制台的颜色输出
EnableJsonDecoderDisallowUnknownFields 开启JSON解码器的DisallowUnknownFields功能 即遇到未知字段时就报错
EnableJsonDecoderUseNumber 开启JSON解码器的UseNumber功能 即将数字解码为json.Number类型,而不是float64,以在需要时精确地转换为整数或浮点数,从而避免精度丢失的问题
ErrorLogger 创建一个能够处理任意类型的错误的中间件 底层调用ErrorLoggerT
ErrorLoggerT 创建一个能够处理指定类型的错误的中间件
ForceConsoleColor 强制在控制台输出带有颜色的内容
IsDebugging 判断当前框架是否处于调试模式
Logger 使用默认配置来创建一个日志中间件 底层调用LoggerWithConfig
LoggerWithConfig 根据传入的配置来创建一个日志中间件
LoggerWithFormatter 根据指定的格式来创建一个日志中间件 底层调用LoggerWithConfig
LoggerWithWriter 根据指定的输出目标创建一个日志中间件 底层调用LoggerWithConfig
Mode 返回当前Gin框架的运行模式 debugreleasetest三种模式
New 返回一个全新的、没有任何中间件的Engine实例
Recovery 使用默认配置创建一个恢复中间件 底层调用RecoveryWithWriter
RecoveryWithWriter 根据指定输出目标创建一个恢复中间件 底层调用CustomRecoveryWithWriter
SetMode 设置gin框架的运行模式
WrapF 将标准的http.HandlerFunc类型的处理函数包装成Gin框架的中间件
WrapH 将标准的http.Handler类型的对象包装成Gin框架的中间件

IRouter接口

IRouter定义了所有的路由处理接口,包括单个路由和分组路由的处理接口。

方法 含义 说明
Any 注册一个能匹配所有HTTP方法的路由
DELETE 注册一个DELETE方法的路由
GET 注册一个GET方法的路由
Group 创建一个路由组,可以将所有具有共同中间件或相同路径前缀的路由添加到这个组中
HEAD 注册一个HEAD方法的路由
Handle 根据给定的路径和HTTP方法注册一个新的请求处理函数和中间件
Match 注册一个能匹配指定HTTP方法的路由 通常用于多个方法
OPTIONS 注册一个OPTIONS方法的路由
PATCH 注册一个PATCH方法的路由
POST 注册一个POST方法的路由
PUT 注册一个PUT方法的路由
Static 从指定的文件系统根目录提供静态文件服务 底层调用StaticFS
StaticFS 从自定义的http.FileSystem接口实现提供静态文件服务
StaticFile 注册一个单独的路由,以提供本地文件系统中的单个文件的服务 favicon.ico
StaticFileFS 从自定义的http.FileSystem接口实现提供单个文件的服务
Use 为路由组添加中间件

RouterGroup

RouterGroup实现了IRouter接口。

方法 含义 说明
BasePath 返回路由组的基础路径

Engine

Engine是框架的实例(基于RouterGroup),包含了路由多路复用器、中间件和配置设置。

方法 含义 说明
Delims 用于设置模板的左右分隔符
HandleContext 用于重新处理一个已被重写的上下文 可能会陷入循环处理的情况,慎用
Handler
LoadHTMLFiles 加载一个HTML文件切片,并将加载结果与HTML渲染器关联起来
LoadHTMLGlob 通过glob模式来识别并加载HTML文件,然后将加载结果与HTML渲染器关联起来
NoMethod 设置当Engine.HandleMethodNotAllowed=true时被调用的处理函数 当出现方法不允许的情况时,这些处理函数会被调用,从而可以返回自定义的错误信息、页面或执行其他逻辑
NoRoute 为未匹配到路由的情况添加处理函数
Routes 返回一个已注册路由的切片
Run 根据指定的网络地址启动http服务
RunFd 根据指定的文件描述符启动http服务 底层调用RunListener
RunListener 根据已有的net.Listener接口启动http服务
RunTLS 根据指定的网络地址、证书等启动https服务
RunUnix 根据指定的Unix套接字文件启动http服务
SecureJsonPrefix 用于设置c.SecureJSON方法中所使用的安全JSON前缀 在调用c.SecureJSON返回JSON数组时生效
ServeHTTP
SetFuncMap 用于设置template.FuncMap所使用的函数映射
SetHTMLTemplate 用于将一个模板与HTML渲染器关联起来
SetTrustedProxies 用于设置一个受信任的网络源列表
With 使用所提供的选项创建并返回一个新的Engine实例

Context

方法 含义 说明
Abort 中断请求的后续处理链,但不影响当前正在执行的处理
AbortWithError 中断请求的后续处理链,并将错误信息记录到c.Errors切片中 内部调用AbortWithStatusError
AbortWithStatus 中断请求的后续处理链,并在响应头中返回指定的HTTP状态码 内部调用StatusAbort
AbortWithStatusJSON 中断请求的后续处理链,并在响应头中返回指定的HTTP状态码,响应体中返回指定的JSON 内部调用AbortJSON
AddParam 将参数添加到Gin的上下文对象中;另一个重要作用是为了端到端测试
AsciiJSON 将一个结构体序列化为JSON格式(其中的Unicode字符转换为ASCII字符)响应
Bind 根据请求的方法和Content-Type头信息自动选择合适的绑定引擎,将请求体中的数据解析并绑定到指定的结构体指针中 内部调用MustBindWith
BindHeader 使用binding.Header绑定请求的数据 内部调用MustBindWith
BindJSON 使用binding.JSON绑定请求的数据 内部调用MustBindWith
BindQuery 使用binding.Query绑定请求的数据 内部调用MustBindWith
BindTOML 使用binding.TOML绑定请求的数据 内部调用MustBindWith
BindUri 将请求的URI(统一资源标识符)中的参数绑定到传入的结构体指针指向的结构体上 内部调用ShouldBindUri
BindWith 使用指定的绑定引擎将请求的数据绑定到传入的结构体指针指向的结构体上 已弃用,建议使用MustBindWithShouldBindWith
BindXML 使用binding.XML绑定请求的数据 内部调用MustBindWith
BindYAML 使用binding.YAML绑定请求的数据 内部调用MustBindWith
ClientIP 通过一种尽力而为的算法来获取发起请求的真实客户端IP地址
ContentType 返回请求中Content-Type请求头的值
Cookie 从请求中获取指定名称的Cookie 返回的Cookie值是经过反编码处理的,且同名的Cookie只会返回其中一个
Copy 返回当前上下文的一个副本 需要将上下文传递给一个新的goroutine时必须使用
Data 将指定的数据写入响应的主体流中,同时更新响应的状态码 内部调用Render
DataFromReader 将指定的io.Reader中的数据写入到响应的主体流中,同时更新响应的状态码 内部调用Render
Deadline 返回该上下文的截止时间
DefaultPostForm POST请求的application/x-www-form-urlencoded格式表单或multipart/form-data格式表单中获取指定键对应的值,若不存在则使用默认值 内部使用GetPostForm
DefaultQuery 从请求的URL查询字符串中获取指定键对应的值,若不存在则使用默认值 内部使用GetQuery
Done 返回一个只读通道,当上下文被取消(比如调用c.CancelFunc)或者超时(使用c.WithTimeout等方法)时,该通道会被关闭。可以通过监听这个通道来感知上下文的状态变化,从而做出相应的处理
Err 用于获取上下文被取消或超时时的错误信息
Error 将错误信息附加到当前的上下文(Context)中的错误列表里,以便后续统一处理 传入nil错误会导致panic
File 将指定的文件以高效的方式写入响应的主体流中
FileAttachment 将指定的文件以高效的方式写入响应的主体流中,并设置响应头中的Content-Disposition字段
FileFromFS 从指定的http.FileSystem中读取文件,并将文件内容以高效的方式写入响应的主体流中
FormFile POST请求的表单数据(通常是multipart/form-data格式)中获取指定表单键对应的第一个文件
FullPath 返回当前请求所匹配到的路由的完整路径
Get 从上下文中获取指定键对应的值,同时返回该键是否存在
GetBool 从上下文中获取指定键对应的值,并将其转换为bool类型返回 内部调用Get
GetDuration 从上下文中获取指定键对应的值,并将其转换为duration类型返回 内部调用Get
GetFloat64 从上下文中获取指定键对应的值,并将其转换为float64类型返回 内部调用Get
GetHeader 从请求头中获取指定键对应的值
GetInt 从上下文中获取指定键对应的值,并将其转换为int类型返回 内部调用Get
GetInt64 从上下文中获取指定键对应的值,并将其转换为int64类型返回 内部调用Get
GetPostForm POST请求的application/x-www-form-urlencoded格式表单或multipart/form-data格式表单中获取指定键对应的值 内部调用GetPostFormArray
GetPostFormArray POST请求的application/x-www-form-urlencoded格式表单或multipart/form-data格式表单中获取指定键对应的所有值,并以字符串切片的形式返回;同时返回该键是否至少存在一个与之对应的值
GetPostFormMap POST请求的表单数据里获取指定键对应的map类型的值,并返回该键是否存在
GetQuery 从请求的URL查询字符串中获取指定键对应的值,并返回该键是否存在 内部调用GetQueryArray
GetQueryArray 从请求的URL查询字符串中获取指定键对应的所有值,并以字符串切片的形式返回;同时返回该键是否至少存在一个与之对应的值
GetQueryMap 从请求的URL查询字符串里获取指定键对应的map类型的值,并返回该键是否存在
GetRawData 获取请求体中的原始数据流数据
GetString 从上下文中获取指定键对应的值,并将其转换为string类型返回 内部调用Get
GetStringMap 从上下文中获取指定键对应的值,并将其转换为map[string]any类型返回 内部调用Get
GetStringMapString 从上下文中获取指定键对应的值,并将其转换为map[string]string类型返回 内部调用Get
GetStringMapStringSlice 从上下文中获取指定键对应的值,并将其转换为map[string][]string类型返回 内部调用Get
GetStringSlice 从上下文中获取指定键对应的值,并将其转换为[]string类型返回 内部调用Get
GetTime 从上下文中获取指定键对应的值,并将其转换为time.Time类型返回 内部调用Get
GetUint 从上下文中获取指定键对应的值,并将其转换为uint类型返回 内部调用Get
GetUint64 从上下文中获取指定键对应的值,并将其转换为uint64类型返回 内部调用Get
HTML 渲染指定文件名的HTTP模板,同时更新响应状态码
Handler 返回主处理器,即最后一个处理函数
HandlerName 返回主处理器的名称 名称会包含包名
HandlerNames 返回当前上下文中所有已注册处理器的名称列表
Header 设置响应头信息,若值为空字符串则删除对应项
IndentedJSON 将给定的结构体序列化为格式化后的JSON(带有缩进和换行符)写入响应体 比较消耗资源和带宽
IsAborted 判断当前的上下文是否已经被中止
IsWebsocket 判断客户端发送的请求是否是WebSocket握手
JSON 将给定的结构体序列化为JSON写入响应体 响应的Content-Typeapplication/json
JSONP 将给定的结构体序列化为JSON格式,并在响应体中添加填充以实现从与客户端不同域名的服务器请求数据 响应的Content-Typeapplication/javascript
MultipartForm 获取multipart/form-data类型的表单请求的解析结果,包含了表单中的所有字段和上传的文件信息
MustBindWith 使用指定的绑定引擎将请求的数据绑定到传入的结构体指针上 内部调用ShouldBindWith
MustGet 从上下文中获取指定键对应的值,若不存在则触发panic 内部调用Get
Negotiate 根据客户端请求头中Accept字段指定的可接受格式,调用不同的渲染器生成合适的响应内容 内部用到了NegotiateFormat
NegotiateFormat 从客户端请求头的Accept字段里,结合服务器所支持的格式,协商出一个可接受的响应格式并返回
Next 用于中间件中,让当前处理流程继续执行后续的中间件和最终的处理函数,当后续的处理完成后,控制权会返回到调用Next方法的位置,继续执行该中间件剩余的代码 专为中间件设计,不应在普通的路由处理函数中使用
Param URL路径中提取指定参数的值
PostForm POST请求的application/x-www-form-urlencoded格式表单或multipart/form-data格式表单中获取指定键对应的值 内部调用GetPostForm
PostFormArray POST请求的application/x-www-form-urlencoded格式表单或multipart/form-data格式表单中获取指定键对应的所有值 内部调用GetPostFormArray
PostFormMap POST请求的表单数据中获取指定表单键所对应的map[string]string类型的值 内部调用GetPostFormMap
ProtoBuf 将给定的结构体序列化为ProtoBuf写入响应体
PureJSON 将给定的结构体序列化为JSON写入响应体,但会直接保留原始的特殊HTML字符
Query 从请求的URL查询字符串中获取指定键对应的值,若不存在返回空字符串 内部调用GetQuery
QueryArray 从请求的URL查询字符串中获取指定键对应的所有值,并以字符串切片的形式返回 内部调用GetQueryArray
QueryMap 从请求的URL查询字符串中获取指定键对应的map[string]string 内部调用GetQuery
Redirect 将客户端的请求重定向到指定的位置
RemoteIP 从请求的Request.RemoteAddr字段中解析出客户端的IP地址
Render 设置响应头信息,然后调用传入的渲染器的Render方法来将数据渲染到响应体中
SSEvent 向响应的主体流中写入一个服务器发送事件SSE 单向通信,即只能服务器向客户端推送数据
SaveUploadedFile 将客户端通过表单上传的文件保存到服务器指定的目标路径
SecureJSON 将给定的结构体序列化为JSON写入响应体,若数据为数组则在前面添加安全前缀 默认前缀为while(1),
Set 在当前的上下文中存储一个新的键值对 常用于在不同中间件和处理函数之间方便地共享数据
SetAccepted 设置请求头中的Accept字段的数据
SetCookie 在响应头中添加Set-Cookie字段,从而在客户端浏览器中设置Cookie
SetSameSite 设置CookieSameSite属性
ShouldBind 依据请求的方法和Content-Type头,自动挑选合适的绑定引擎,把请求体中的数据绑定到指定的结构体指针上 绑定失败不会自动设置响应状态码或终止请求处理。内部调用ShouldBindWith
ShouldBindBodyWith 使用指定的绑定引擎将请求中的数据绑定到传入的结构体指针上,但会将请求体的数据存储在上下文中
ShouldBindBodyWithJSON 使用binding.JSON绑定引擎将请求中的数据绑定到传入的结构体指针上,并将请求体的数据存储在上下文中 内部调用ShouldBindBodyWith
ShouldBindBodyWithTOML 使用binding.TOML绑定引擎将请求中的数据绑定到传入的结构体指针上,并将请求体的数据存储在上下文中 内部调用ShouldBindBodyWith
ShouldBindBodyWithXML 使用binding.XML绑定引擎将请求中的数据绑定到传入的结构体指针上,并将请求体的数据存储在上下文中 内部调用ShouldBindBodyWith
ShouldBindBodyWithYAML 使用binding.YAML绑定引擎将请求中的数据绑定到传入的结构体指针上,并将请求体的数据存储在上下文中 内部调用ShouldBindBodyWith
ShouldBindHeader 使用binding.Header绑定引擎将请求中的数据绑定到传入的结构体指针上 内部调用ShouldBindWith
ShouldBindJSON 使用binding.JSON绑定引擎将请求中的数据绑定到传入的结构体指针上 内部调用ShouldBindWith
ShouldBindQuery 使用binding.Query绑定引擎将请求中的数据绑定到传入的结构体指针上 内部调用ShouldBindWith
ShouldBindTOML 使用binding.TOML绑定引擎将请求中的数据绑定到传入的结构体指针上 内部调用ShouldBindWith
ShouldBindUri 使用指定的绑定引擎将请求的URI中的参数绑定到传入的结构体指针所指向的结构体实例上
ShouldBindWith 使用指定的绑定引擎将请求中的数据绑定到传入的结构体指针上
ShouldBindXML 使用binding.XML绑定引擎将请求中的数据绑定到传入的结构体指针上 内部调用ShouldBindWith
ShouldBindYAML 使用binding.YAML绑定引擎将请求中的数据绑定到传入的结构体指针上 内部调用ShouldBindWith
Status 设置响应的状态码
Stream 用于发送流式响应
String 将给定的字符串写入响应体中
TOML 将给定的结构体序列化为TOML写入响应体
Value 从当前的Context中获取与指定键关联的值 内部调用Get
XML 将给定的结构体序列化为XML写入响应体
YAML 将给定的结构体序列化为YAML写入响应体

使用小结

读取请求

来源 详情 方法 备注
请求路径 路由参数 ParamBindUriShouldBindUriFullPath 适用于RESTful参数,如:http://localhost/user/123
- 查询参数 QueryDefaultQueryGetQueryQueryArrayGetQueryArrayQueryMapGetQueryMap 适用于传统查询参数,如:http://localhost/user?id=123
请求体 表单 DefaultPostFormGetPostFormGetPostFormArrayGetPostFormMapMultipartForm application/x-www-form-urlencodedmultipart/form-data
- 文件 FormFileSaveUploadedFile multipart/form-data
- 原始流 GetRawData
- json BindJSONShouldBindBodyWithJSON
- xml BindXMLShouldBindBodyWithXML
- toml BindTOMLShouldBindBodyWithTOML
- yaml BindYAMLShouldBindBodyWithYAML
请求头 Cookies Cookie
- Content-Type ContentType
- 普通头 GetHeaderBindHeaderShouldBindHeader

响应

位置 详情 方法 备注
响应状态码 Status
响应头 普通头 Header
- Accept SetAccepted
- Cookies SetCookie
响应体 普通文本 String
- 页面 HTML
- json JSONJSONPIndentedJSONAsciiJSONPureJSONSecureJSON
- xml XML
- ProtoBuf ProtoBuf
- toml TOML
- yaml YAML
- Stream
- 文件 FileFileAttachmentFileFromFS
- SSE事件 SSEvent

流程控制

类型 方法 备注
中止 AbortAbortWithErrorAbortWithStatusAbortWithStatusJSON
继续下一个 Next 对中间件很重要
重定向 Redirect