文章首发于个人博客
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实例 | 默认含Logger和Recovery两个中间件 |
| 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框架的运行模式 | 有debug、release和test三种模式 |
| 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切片中 | 内部调用AbortWithStatus和Error |
| AbortWithStatus | 中断请求的后续处理链，并在响应头中返回指定的HTTP状态码 | 内部调用Status和Abort |
| AbortWithStatusJSON | 中断请求的后续处理链，并在响应头中返回指定的HTTP状态码，响应体中返回指定的JSON | 内部调用Abort和JSON |
| 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 | 使用指定的绑定引擎将请求的数据绑定到传入的结构体指针指向的结构体上 | 已弃用，建议使用MustBindWith或ShouldBindWith |
| 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-Type为application/json |
| JSONP | 将给定的结构体序列化为JSON格式，并在响应体中添加填充以实现从与客户端不同域名的服务器请求数据 | 响应的Content-Type为application/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 | 设置Cookie的SameSite属性 | |
| 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写入响应体 |
