Request
URI
func (ctx *RequestContext) Host() []byte
func (ctx *RequestContext) FullPath() string
func (ctx *RequestContext) SetFullPath(p string)
func (ctx *RequestContext) Path() []byte
func (ctx *RequestContext) Param(key string) string
func (ctx *RequestContext) Query(key string) string
func (ctx *RequestContext) DefaultQuery(key, defaultValue string) string
func (ctx *RequestContext) GetQuery(key string) (string, bool)
func (ctx *RequestContext) QueryArgs() *protocol.Args
func (ctx *RequestContext) URI() *protocol.URI
Host
Obtain the requested host address.
Function Signature:
func (ctx *RequestContext) Host() []byte
Example Code:
// GET http://example.com
h.GET("/", func(ctx context.Context, c *app.RequestContext) {
host := c.Host() // host == []byte("example.com")
})
FullPath
Get the complete path of the matched route, and return an empty string for the unmatched route.
Function Signature:
func (ctx *RequestContext) FullPath() string
Example Code:
h := server.Default(server.WithHandleMethodNotAllowed(true))
// GET http://example.com/user/bar
h.GET("/user/:name", func(ctx context.Context, c *app.RequestContext) {
fpath := c.FullPath() // fpath == "/user/:name"
})
// GET http://example.com/bar
h.NoRoute(func(ctx context.Context, c *app.RequestContext) {
fpath := c.FullPath() // fpath == ""
})
// POST http://example.com/user/bar
h.NoMethod(func(ctx context.Context, c *app.RequestContext) {
fpath := c.FullPath() // fpath == ""
})
SetFullPath
Set the value of FullPath.
Note: FullPath is assigned during routing lookup, and usually you do not need to use SetFullPath to overwrite it.
Function Signature:
func (ctx *RequestContext) SetFullPath(p string)
Example Code:
h.GET("/user/:name", func(ctx context.Context, c *app.RequestContext) {
c.SetFullPath("/v1/user/:name")
fpath := c.FullPath() // fpath == "/v1/user/:name"
})
Path
Obtain the path of the request.
Note: When parameter routing occurs,
Path
provides the named path after parameter matching, whileFullPath
provides the original path.
Function Signature:
func (ctx *RequestContext) Path() []byte
Example Code:
// GET http://example.com/user/bar
h.GET("/user/:name", func(ctx context.Context, c *app.RequestContext) {
path := c.Path() // path == []byte("/user/bar")
})
Param
Obtain the value of routing parameters.
Function Signature:
func (ctx *RequestContext) Param(key string) string
Example Code:
// GET http://example.com/user/bar
h.GET("/user/:name", func(ctx context.Context, c *app.RequestContext) {
name := c.Param("name") // name == "bar"
id := c.Param("id") // id == ""
})
Query
Get the value of the attribute specified in the route Query String
parameter. If no empty string is returned.
Function Signature:
func (ctx *RequestContext) Query(key string) string
Example Code:
// GET http://example.com/user?name=bar
h.GET("/user", func(ctx context.Context, c *app.RequestContext) {
name := c.Query("name") // name == "bar"
id := c.Query("id") // id == ""
})
DefaultQuery
Obtain the value of the specified attribute in the Query String
parameter of the route, and if it does not return the default value set.
Function Signature:
func (ctx *RequestContext) DefaultQuery(key, defaultValue string) string
Example Code:
// GET http://example.com/user?name=bar&&age=
h.GET("/user", func(ctx context.Context, c *app.RequestContext) {
name := c.DefaultQuery("name", "tom") // name == "bar"
id := c.DefaultQuery("id", "123") // id == "123"
age := c.DefaultQuery("age", "45") // age == ""
})
GetQuery
Obtain the value of the specified attribute in the Query String
parameter of the route and whether the attribute exists.
Function Signature:
func (ctx *RequestContext) GetQuery(key string) (string, bool)
Example Code:
// GET http://example.com/user?name=bar&&age=
h.GET("/user", func(ctx context.Context, c *app.RequestContext) {
name, hasName := c.GetQuery("name") // name == "bar", hasName == true
id, hasId := c.GetQuery("id") // id == "", hasId == false
age, hasAge := c.GetQuery("age") // age == "", hasAge == true
})
QueryArgs
Obtain the Query String
parameter object for the route.
Function Signature:
func (ctx *RequestContext) QueryArgs() *protocol.Args
Args
The Args object provides the following methods to obtain/set Query String
parameters.
Function Signature | Description |
---|---|
func (a *Args) Set(key, value string) | Set the value of Args object key |
func (a *Args) Reset() | Reset Args Object |
func (a *Args) CopyTo(dst *Args) | Copy Args object to dst |
func (a *Args) Del(key string) | Delete the key value pair of Args object key |
func (a *Args) DelBytes(key []byte) | Delete key value pairs of Args object byte array type key |
func (a *Args) Has(key string) bool | Obtain whether the Args object has a key value pair for the key |
func (a *Args) String() string | Convert Args object to Query String of string type |
func (a *Args) QueryString() []byte | Convert Args object to a Query String of byte array type |
func (a *Args) ParseBytes(b []byte) | Parsing byte arrays and storing key value pairs in Args object |
func (a *Args) Peek(key string) []byte | Obtain the value of Args object key |
func (a *Args) PeekExists(key string) (string, bool) | Obtain the value of Args object key and its existence |
func (a *Args) PeekAll(key string) [][]byte | Obtain all values of Args object key |
func (a *Args) Len() int | Obtain the number of Args object key-value pairs |
func (a *Args) AppendBytes(dst []byte) []byte | Append Args object Query String to dst and return |
func (a *Args) VisitAll(f func(key, value []byte)) | Visit all key value pairs of Args object |
func (a *Args) WriteTo(w io.Writer) (int64, error) | Write Args object Query String to io.Writer |
func (a *Args) Add(key, value string) | Add Args object key as key value |
Example Code:
// GET http://example.com/user?name=bar&&age=&&pets=dog&&pets=cat
h.GET("/user", func(ctx context.Context, c *app.RequestContext) {
args := c.QueryArgs()
// get information from args
s := args.String() // s == "name=bar&age=&pets=dog&pets=cat"
qs := args.QueryString() // qs == []byte("name=bar&age=&pets=dog&pets=cat")
cpqs := args.AppendBytes([]byte(nil)) // cpqs == []byte("name=bar&age=&pets=dog&pets=cat")
name := args.Peek("name") // name == []byte("bar")
hasName := args.Has("name") // hasName == true
age, hasAge := args.PeekExists("age") // age == "", hasAge == true
len := args.Len() // len == 4
args.VisitAll(func(key, value []byte) {
// 1. key == []byte("name"), value == []byte("bar")
// 2. key == []byte("age"), value == nil
// 3. key == []byte("pets"), value == []byte("dog")
// 4. key == []byte("pets"), value == []byte("cat")
})
pets := args.PeekAll("pets") // pets == [][]byte{[]byte("dog"), []byte("cat")}
// send information to io.Writer
req := protocol.AcquireRequest()
n, err := args.WriteTo(req.BodyWriter())
// n == 31 err == nil
s := req.BodyBuffer().String()
// s == "name=bar&age=&pets=dog&pets=cat"
// change args
var newArgs protocol.Args
args.CopyTo(&newArgs)
newArgs.Set("version", "v1")
version := newArgs.Peek("version") //version == []byte("v1")
newArgs.Del("age")
hasAgeAfterDel := newArgs.Has("age") // hasAgeAfterDel == false
newArgs.DelBytes([]byte("name"))
hasNameAfterDel := newArgs.Has("name") // hasNameAfterDel == false
newArgs.Add("name", "foo")
newName := newArgs.Peek("name") //newName == []byte("foo")
newArgs.Reset()
empty := newArgs.String() // empty == ""
// parse args
var newArgs2 protocol.Args
newArgs2.ParseBytes([]byte("name=bar&age=20"))
nqs2 := newArgs2.String() // nqs2 == "name=bar&age=20"
})
URI
Return the requested URI
object.
Function Signature:
func (ctx *RequestContext) URI() *protocol.URI
URI Object
The URI object provides the following methods to obtain/set URI.
Function Signature | Description |
---|---|
func (u *URI) CopyTo(dst *URI) | Copy a copy of the URI object to dst |
func (u *URI) QueryArgs() *Args | Get Args |
func (u *URI) Hash() []byte | Obtain Hash value, such as http://example.com/user?baz=123#qwe Hash is qwe |
func (u *URI) SetHash(hash string) | Set Hash |
func (u *URI) SetHashBytes(hash []byte) | Set Hash of type []byte |
func (u *URI) Username() []byte | Get Username |
func (u *URI) SetUsername(username string) | Set Username |
func (u *URI) SetUsernameBytes(username []byte) | Set Username of type []byte |
func (u *URI) Password() []byte | Get Password |
func (u *URI) SetPassword(password string) | Set Password |
func (u *URI) SetPasswordBytes(password []byte) | Set Password of type []byte |
func (u *URI) QueryString() []byte | Get Query String , such as http://example.com/user?baz=123 Query String is baz=123 |
func (u *URI) SetQueryString(queryString string) | Set Query String , note that after this method, use RequestHeader.SetRequestURI may overwrite the originally intended value |
func (u *URI) SetQueryStringBytes(queryString []byte) | Set Query String of type []byte , note that after this method, use RequestHeader.SetRequestURI may overwrite the originally intended value |
func (u *URI) Path() []byte | Get Path, such as http://example.com/user/he%20rtz Path is /user/he rtz |
func (u *URI) PathOriginal() []byte | Get Unescaped Path, such as http://example.com/user/he%20rtz Path is /user/he%20rtz |
func (u *URI) SetPath(path string) | Set Path |
func (u *URI) SetPathBytes(path []byte) | Set Path of type []byte |
func (u *URI) String() string | Obtain the complete URI, such as http://example.com/user?baz=123 complete URI is http://example.com/user?baz=123 |
func (u *URI) FullURI() []byte | Obtain the complete URI of type []byte |
func (u *URI) Scheme() []byte | Obtain protocol, such as http |
func (u *URI) SetScheme(scheme string) | Set protocol |
func (u *URI) SetSchemeBytes(scheme []byte) | Set protocol of type []byte |
func (u *URI) Host() []byte | Set Host, such as http://example.com/user Host is example.com |
func (u *URI) SetHost(host string) | Set Host |
func (u *URI) SetHostBytes(host []byte) | Set Host of type []byte |
func (u *URI) LastPathSegment() []byte | Obtain the last part of Path, for example, the last part of Path /foo/bar/baz.html is baz.html |
func (u *URI) Update(newURI string) | Update URI |
func (u *URI) UpdateBytes(newURI []byte) | Update URI of type []byte |
func (u *URI) Parse(host, uri []byte) | Initialize URI |
func (u *URI) AppendBytes(dst []byte) []byte | Assign the complete URI to dst and return dst |
func (u *URI) RequestURI() []byte | Get RequestURI, such as http://example.com/user?baz=123 RequestURI is /user?baz=123 |
func (u *URI) Reset() | Reset URI |
Header
// RequestHeader
func (h *RequestHeader) Add(key, value string)
func (h *RequestHeader) Set(key, value string)
func (h *RequestHeader) Header() []byte
func (h *RequestHeader) String() string
func (h *RequestHeader) VisitAll(f func(key, value []byte))
// RequestContext
func (ctx *RequestContext) IsGet() bool
func (ctx *RequestContext) IsHead() bool
func (ctx *RequestContext) IsPost() bool
func (ctx *RequestContext) Method() []byte
func (ctx *RequestContext) ContentType() []byte
func (ctx *RequestContext) IfModifiedSince(lastModified time.Time) bool
func (ctx *RequestContext) Cookie(key string) []byte
func (ctx *RequestContext) UserAgent() []byte
func (ctx *RequestContext) GetHeader(key string) []byte
Add
Add or set the header with the key as key.
Note: Add is usually used to set multiple headers for the same key. To set a single header for the same key, use Set. When used as a header for Content Type, Content Length, Connection, Cookie, Transfer Encoding, Host, User Agent, etc., using multiple Add will overwrite the old values.
Function Signature:
func (h *RequestHeader) Add(key, value string)
Example Code:
hertz.GET("/example", func(ctx context.Context, c *app.RequestContext) {
c.Request.Header.Add("hertz1", "value1")
c.Request.Header.Add("hertz1", "value2")
c.Request.Header.SetContentTypeBytes([]byte("application/x-www-form-urlencoded"))
contentType1 := c.Request.Header.ContentType()
// contentType1 == []byte("application/x-www-form-urlencoded")
c.Request.Header.Add("Content-Type", "application/json; charset=utf-8")
hertz1 := c.Request.Header.GetAll("hertz1")
// hertz1 == []string{"value1", "value2"}
contentType2 := c.Request.Header.ContentType()
// contentType2 == []byte("application/json; charset=utf-8")
})
Set
Set the Header key value.
Note: Set is usually used to set a single header for the same key. To set multiple headers for the same key, use Add.
Function Signature:
func (h *RequestHeader) Set(key, value string)
Example Code:
hertz.GET("/example", func(ctx context.Context, c *app.RequestContext) {
c.Request.Header.Set("hertz1", "value1")
c.Request.Header.Set("hertz1", "value2")
c.Request.Header.SetContentTypeBytes([]byte("application/x-www-form-urlencoded"))
contentType1 := c.Request.Header.ContentType()
// contentType1 == []byte("application/x-www-form-urlencoded")
c.Request.Header.Set("Content-Type", "application/json; charset=utf-8")
hertz1 := c.Request.Header.GetAll("hertz1")
// hertz1 == []string{"value2"}
contentType2 := c.Request.Header.ContentType()
// contentType2 == []byte("application/json; charset=utf-8")
})
Header
Obtain the complete header of type []byte
.
Function Signature:
func (h *RequestHeader) Header() []byte
Example Code:
hertz.GET("/example", func(ctx context.Context, c *app.RequestContext) {
c.Request.Header.Set("hertz1", "value1")
header := c.Request.Header.Header()
// header == []byte("GET /example HTTP/1.1
//User-Agent: PostmanRuntime-ApipostRuntime/1.1.0
//Host: localhost:8888
//Cache-Control: no-cache
//Accept: */*
//Accept-Encoding: gzip, deflate, br
//Connection: keep-alive
//Hertz1: value1")
})
String
Obtain the complete header.
Function Signature:
func (h *RequestHeader) String() string
Example Code:
hertz.GET("/example", func(ctx context.Context, c *app.RequestContext) {
c.Request.Header.Set("hertz1", "value1")
header := c.Request.Header.String()
// header == "GET /example HTTP/1.1
//User-Agent: PostmanRuntime-ApipostRuntime/1.1.0
//Host: localhost:8888
//Cache-Control: no-cache
//Accept: */*
//Accept-Encoding: gzip, deflate, br
//Connection: keep-alive
//Hertz1: value1"
})
VisitAll Header
Traverse the key values of all headers and execute the f function.
Function Signature:
func (h *RequestHeader) VisitAll(f func(key, value []byte))
Example Code:
hertz.GET("/example", func(ctx context.Context, c *app.RequestContext) {
c.Request.Header.Add("Hertz1", "value1")
c.Request.Header.Add("Hertz1", "value2")
var hertzString []string
c.Request.Header.VisitAll(func(key, value []byte) {
if string(key) == "Hertz1" {
hertzString = append(hertzString, string(value))
}
})
// hertzString == []string{"value1", "value2"}
})
Method
Get the type of the request method.
Function Signature:
func (ctx *RequestContext) Method() []byte
Example Code:
// POST http://example.com/user
h.Any("/user", func(ctx context.Context, c *app.RequestContext) {
method := c.Method() // method == []byte("POST")
})
ContentType
Obtain the value of the request header Content Type
.
Function Signature:
func (ctx *RequestContext) ContentType() []byte
Example Code:
// POST http://example.com/user
// Content-Type: application/json
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
contentType := c.ContentType() // contentType == []byte("application/json")
})
IfModifiedSince
Determine if the time has exceeded the value of the request header If Modified Since
.
Note: If the request header does not contain
If Modified Since
, it also returns true.
Function Signature:
func (ctx *RequestContext) IfModifiedSince(lastModified time.Time) bool
Example Code:
// POST http://example.com/user
// If-Modified-Since: Wed, 21 Oct 2023 07:28:00 GMT
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
t2022, _ := time.Parse(time.RFC1123, "Wed, 21 Oct 2022 07:28:00 GMT")
ifModifiedSince := c.IfModifiedSince(t2022) // ifModifiedSince == false
t2024, _ := time.Parse(time.RFC1123, "Wed, 21 Oct 2024 07:28:00 GMT")
ifModifiedSince = c.IfModifiedSince(t2024) // ifModifiedSince == true
})
Cookie
Obtain the value of the key in the request header Cookie
.
Function Signature:
func (ctx *RequestContext) Cookie(key string) []byte
Example Code:
// POST http://example.com/user
// Cookie: foo_cookie=choco; bar_cookie=strawberry
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
fCookie := c.Cookie("foo_cookie") // fCookie == []byte("choco")
bCookie := c.Cookie("bar_cookie") // bCookie == []byte("strawberry")
noneCookie := c.Cookie("none_cookie") // noneCookie == nil
})
UserAgent
Obtain the value of the request header User Agent
.
Function Signature:
func (ctx *RequestContext) UserAgent() []byte
Example Code:
// POST http://example.com/user
// User-Agent: Chrome/51.0.2704.103 Safari/537.36
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
ua := c.UserAgent() // ua == []byte("Chrome/51.0.2704.103 Safari/537.36")
})
GetHeader
Obtain the value of the key in the request header.
Function Signature:
func (ctx *RequestContext) GetHeader(key string) []byte
Example Code:
// POST http://example.com/user
// Say-Hello: hello
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
customHeader := c.GetHeader("Say-Hello") // customHeader == []byte("hello")
})
RequestHeader Object
Use RequestContext.Request.Header
to obtain the RequestHeader object, which provides the following methods to obtain/set the request header.
Function Signature | Description |
---|---|
func (h *RequestHeader) Method() []byte | Get Method |
func (h *RequestHeader) SetMethod(method string) | Set Method |
func (h *RequestHeader) SetMethodBytes(method []byte) | Set Method of type []byte |
func (h *RequestHeader) IsGet() bool | Determine if Method is GET |
func (h *RequestHeader) IsHead() bool | Determine if Method is HEAD |
func (h *RequestHeader) IsPost() bool | Determine if Method is POST |
func (h *RequestHeader) IsPut() bool | Determine if Method is PUT |
func (h *RequestHeader) IsDelete() bool | Determine if Method is DELETE |
func (h *RequestHeader) IsConnect() bool | Determine if Method is CONNECT |
func (h *RequestHeader) IsOptions() bool | Determine if Method is OPTIONS |
func (h *RequestHeader) IsTrace() bool | Determine if Method is TRACE |
func (h *RequestHeader) IgnoreBody() bool | Determine whether to ignore Body (Method GET/HEAD ignores Body) |
func (h *RequestHeader) RequestURI() []byte | Get RequestURI |
func (h *RequestHeader) SetRequestURI(requestURI string) | Set RequestURI |
func (h *RequestHeader) SetRequestURIBytes(requestURI []byte) | Set RequestURI of type []byte |
func (h *RequestHeader) SetProtocol(p string) | Set protocol type, such as HTTP/1.0 |
func (h *RequestHeader) GetProtocol() string | Get protocol type, such as HTTP/1.1 |
func (h *RequestHeader) IsHTTP11() bool | Determine if it is HTTP/1.1 |
func (h *RequestHeader) SetNoHTTP11(b bool) | Setting is not HTTP/1.1 |
func (h *RequestHeader) Host() []byte | Get Host |
func (h *RequestHeader) SetHost(host string) | Set Host |
func (h *RequestHeader) SetHostBytes(host []byte) | Set Host of type []byte |
func (h *RequestHeader) ContentLength() int | Get Content-Length |
func (h *RequestHeader) ContentLengthBytes() []byte | Get Content-Length of type []byte |
func (h *RequestHeader) SetContentLength(contentLength int) | Set Content-Length |
func (h *RequestHeader) SetContentLengthBytes(contentLength []byte) | Set Content-Length of type []byte |
func (h *RequestHeader) InitContentLengthWithValue(contentLength int) | Initialize Content-Length |
func (h *RequestHeader) ContentType() []byte | Get Content-Type |
func (h *RequestHeader) SetContentTypeBytes(contentType []byte) | Set Content-Type |
func (h *RequestHeader) SetNoDefaultContentType(b bool) | Control the default sending behavior when Content Type is not specified, false sends the default Content Type value, true does not send Content Type |
func (h *RequestHeader) UserAgent() []byte | Get User-Agent |
func (h *RequestHeader) SetUserAgentBytes(userAgent []byte) | Set User-Agent |
func (h *RequestHeader) ConnectionClose() bool | Determine if it contains Connection: close |
func (h *RequestHeader) SetConnectionClose(close bool) | Set connectionClose |
func (h *RequestHeader) ResetConnectionClose() | Reset connectionClose to false and delete Connection Header |
func (h *RequestHeader) SetByteRange(startPos, endPos int) | Set Range (Range: bytes=startPos-endPos) |
func (h *RequestHeader) SetMultipartFormBoundary(boundary string) | Set the boundary for Content-Type=multipart/form data |
func (h *RequestHeader) MultipartFormBoundary() []byte | Get the value of boundary |
func (h *RequestHeader) Trailer() *Trailer | Get Trailer |
func (h *RequestHeader) Cookie(key string) []byte | Obtain the value of Cookie key as key |
func (h *RequestHeader) SetCookie(key, value string) | Set Cookie Key Values |
func (h *RequestHeader) DelCookie(key string) | Delete the cookie whose key is key |
func (h *RequestHeader) DelAllCookies() | Delete all Cookies |
func (h *RequestHeader) FullCookie() []byte | Get all Cookies |
func (h *RequestHeader) Cookies() []*Cookie | Get all Cookie objects |
func (h *RequestHeader) VisitAllCookie(f func(key, value []byte)) | Traverse the key values of all cookies and execute the f function |
func (h *RequestHeader) Peek(key string) []byte | Obtain the value of key for type []byte |
func (h *RequestHeader) Get(key string) string | Obtain the value of key as key |
func (h *RequestHeader) PeekArgBytes(key []byte) []byte | Obtain the value of key as key |
func (h *RequestHeader) PeekAll(key string) [][]byte | Obtain all values of key for type []byte (used to obtain multiple values with the same key) |
func (h *RequestHeader) GetAll(key string) []string | Obtain all values with key as key |
func (h *RequestHeader) PeekIfModifiedSinceBytes() []byte | Get If-Modified-Since |
func (h *RequestHeader) PeekContentEncoding() []byte | Get Content-Encoding |
func (h *RequestHeader) PeekRange() []byte | Get Range |
func (h *RequestHeader) HasAcceptEncodingBytes(acceptEncoding []byte) bool | Determine whether Accept-Encoding exists and whether Accept-Encoding includes acceptEncoding |
func (h *RequestHeader) RawHeaders() []byte | Get original Header |
func (h *RequestHeader) SetRawHeaders(r []byte) | Set original Header |
func (h *RequestHeader) Add(key, value string) | Set the header key value to set multiple headers for the same key, but the key will overwrite the following headers: Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, User-Agent |
func (h *RequestHeader) InitBufValue(size int) | Initialize buffer size |
func (h *RequestHeader) GetBufValue() []byte | Get the value of the buffer |
func (h *RequestHeader) SetCanonical(key, value []byte) | Set the Header key value, assuming that the key is in canonical form |
func (h *RequestHeader) Set(key, value string) | Set the header key value to set a single header for the same key |
func (h *RequestHeader) SetBytesKV(key, value []byte) | Set the header key value of type []byte to set a single header for the same key |
func (h *RequestHeader) DelBytes(key []byte) | Delete key value pairs with key in the header |
func (h *RequestHeader) AddArgBytes(key, value []byte, noValue bool) | Add Header key value (different from Add , the key must not be normalized and will not undergo special processing when it is Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, or User-Agent) |
func (h *RequestHeader) SetArgBytes(key, value []byte, noValue bool) | Set Header key value (different from Set , The key must not be normalized and will not undergo special processing when it is Content-Type, Content-Length, Connection, Cookie, Transfer-Encoding, Host, or User-Agent) |
func (h *RequestHeader) AppendBytes(dst []byte) []byte | Attach the complete header to the dst and return |
func (h *RequestHeader) Header() []byte | Obtain the complete header of type []byte |
func (h *RequestHeader) String() string | Obtain the complete header |
func (h *RequestHeader) CopyTo(dst *RequestHeader) | Obtain a copy of RequestHeader |
func (h *RequestHeader) VisitAll(f func(key, value []byte)) | Traverse the key values of all headers and execute the f function |
func (h *RequestHeader) VisitAllCustomHeader(f func(key, value []byte)) | Traverse the key values of all headers and execute the f function, except for Content-Type, Content-Length, Cookie, Host, User-Agent |
func (h *RequestHeader) Len() int | Return the number of key value pairs in the header |
func (h *RequestHeader) DisableNormalizing() | Disable the normalization of header name (capitalize the first letter and the first letter after the Em dash) |
func (h *RequestHeader) IsDisableNormalizing() bool | Whether to disable standardized for header name, default not disabled |
func (h *RequestHeader) ResetSkipNormalize() | Reset Headers except for disableNormalizing status |
func (h *RequestHeader) Reset() | Reset Headers |
Body
func (ctx *RequestContext) GetRawData() []byte
func (ctx *RequestContext) Body() ([]byte, error)
func (ctx *RequestContext) RequestBodyStream() io.Reader
func (ctx *RequestContext) MultipartForm() (*multipart.Form, error)
func (ctx *RequestContext) PostForm(key string) string
func (ctx *RequestContext) DefaultPostForm(key, defaultValue string) string
func (ctx *RequestContext) GetPostForm(key string) (string, bool)
func (ctx *RequestContext) PostArgs() *protocol.Args
func (ctx *RequestContext) FormValue(key string) []byte
func (ctx *RequestContext) SetFormValueFunc(f FormValueFunc)
Body
Obtain the requested body data and return an error if an error occurs.
Function Signature:
func (ctx *RequestContext) Body() ([]byte, error)
Example Code:
// POST http://example.com/pet
// Content-Type: application/json
// {"pet":"cat"}
h.Post("/pet", func(ctx context.Context, c *app.RequestContext) {
data, err := c.Body() // data == []byte("{\"pet\":\"cat\"}") , err == nil
})
RequestBodyStream
Obtain the requested BodyStream.
Function Signature:
func (ctx *RequestContext) RequestBodyStream() io.Reader
Example Code:
// POST http://example.com/user
// Content-Type: text/plain
// abcdefg
h := server.Default(server.WithStreamBody(true))
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
sr := c.RequestBodyStream()
data, _ := io.ReadAll(sr) // data == []byte("abcdefg")
})
MultipartForm
Obtain the multipart.Form
object. (For more information, please refer to multipart#Form)
Note: This function can obtain both ordinary values and files. Here is an example code for obtaining ordinary values. The example code for obtaining files can be found in MultipartForm.
Function Signature:
func (ctx *RequestContext) MultipartForm() (*multipart.Form, error)
Example Code:
// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="name"
// tom
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
form, err := c.MultipartForm()
name := form.Value["name"][0] // name == "tom"
})
PostForm
Retrieve multipart.Form.Value
by name and return the first value of the given name.
Note: This function supports obtaining values from content-type of application/x-www form urlencoded and multipart/form data, and does not support obtaining file values.
Function Signature:
func (ctx *RequestContext) PostForm(key string) string
Example Code:
// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="name"
// tom
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
name := c.PostForm("name") // name == "tom"
})
DefaultPostForm
Retrieve multipart.Form.Value
by name and return the first value of the given name. If it does not exist, return defaultValue.
Note: This function supports obtaining values from content-type of application/x-www form urlencoded and multipart/form data, and does not support obtaining file values.
Function Signature:
func (ctx *RequestContext) DefaultPostForm(key, defaultValue string) string
Example Code:
// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="name"
// tom
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
name := c.PostForm("name", "jack") // name == "tom"
age := c.PostForm("age", "10") // age == "10"
})
PostArgs
Obtain the application/x-www form urlencoded
parameter object. (For more information, please refer to Args)
Function Signature:
func (ctx *RequestContext) PostArgs() *protocol.Args
Example Code:
// POST http://example.com/user
// Content-Type: application/x-www-form-urlencoded
// name=tom&pet=cat&pet=dog
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
args := c.PostArgs()
name := args.Peek("name") // name == "tom"
var pets []string
args.VisitAll(func(key, value []byte) {
if string(key) == "pet" {
pets = append(pets, string(value))
}
})
// pets == []string{"cat", "dog"}
})
FormValue
Obtain the values of keys in the following order.
- Obtain values from QueryArgs.
- Obtain values from PostArgs.
- Obtain values from MultipartForm.
Function Signature:
func (ctx *RequestContext) FormValue(key string) []byte
Example Code:
// POST http://example.com/user?name=tom
// Content-Type: application/x-www-form-urlencoded
// age=10
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
name := c.FormValue("name") // name == []byte("tom"), get by QueryArgs
age := c.FormValue("age") // age == []byte("10"), get by PostArgs
})
// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="name"
// tom
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
name := c.FormValue("name") // name == []byte("tom"), get by MultipartForm
})
SetFormValueFunc
If the default method provided by the FormValue function to obtain the value of the key does not meet the requirements, users can use this function to customize the method of obtaining the value of the key.
Function Signature:
func (ctx *RequestContext) SetFormValueFunc(f FormValueFunc)
Example Code:
// POST http://example.com/user?name=tom
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="age"
// 10
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
// only return multipart form value
c.SetFormValueFunc(func(rc *app.RequestContext, s string) []byte {
mf, err := rc.MultipartForm()
if err == nil && mf.Value != nil {
vv := mf.Value[s]
if len(vv) > 0 {
return []byte(vv[0])
}
}
return nil
})
name := c.FormValue("name") // name == nil
age := c.FormValue("age") // age == []byte("10")
})
File Operation
func (ctx *RequestContext) MultipartForm() (*multipart.Form, error)
func (ctx *RequestContext) FormFile(name string) (*multipart.FileHeader, error)
func (ctx *RequestContext) SaveUploadedFile(file *multipart.FileHeader, dst string) error
MultipartForm
Obtain the multipart.Form
object. (For more information, please refer to multipart#Form)
Note: This function can obtain both ordinary values and files. Here is an example code for obtaining file values. The example code for obtaining ordinary values can be found in MultipartForm.
Function Signature:
func (ctx *RequestContext) MultipartForm() (*multipart.Form, error)
Example Code:
// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="avatar"; filename="abc.jpg"
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
form, err := c.MultipartForm()
avatarFile := form.File["avatar"][0] // avatarFile.Filename == "abc.jpg"
})
FormFile
Retrieve multipart.Form.File
by name and return the first multipart.FileHeader
of the given name. (For more information, please refer to multipart#FileHeader)
Function Signature:
func (ctx *RequestContext) FormFile(name string) (*multipart.FileHeader, error)
Example Code:
// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="avatar"; filename="abc.jpg"
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
avatarFile, err := c.FormFile("avatar") // avatarFile.Filename == "abc.jpg", err == nil
})
SaveUploadedFile
Save the multipart file to disk.
Function Signature:
func (ctx *RequestContext) SaveUploadedFile(file *multipart.FileHeader, dst string) error
Example Code:
// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="avatar"; filename="abc.jpg"
h.Post("/user", func(ctx context.Context, c *app.RequestContext) {
avatarFile, err := c.FormFile("avatar") // avatarFile.Filename == "abc.jpg", err == nil
// save file
c.SaveUploadedFile(avatarFile, avatarFile.Filename) // save file "abc.jpg"
})
RequestContext Metadata Store
Note: RequestContext will be reclaimed after the request ends, and the metadata will be set to nil. To use asynchronously, please use the Copy method.
Function Signature | Description |
---|---|
func (ctx *RequestContext) Set(key string, value interface{}) | Store key value pairs in requestContext |
func (ctx *RequestContext) Value(key interface{}) interface{} | Gets the value of the requestContext key as key |
func (ctx *RequestContext) Get(key string) (value interface{}, exists bool) | Obtain the value of the requestContext key as key and whether the key exists |
func (ctx *RequestContext) MustGet(key string) interface{} | Obtain the value of the requestContext key as key. If it does not exist, a panic will occur |
func (ctx *RequestContext) GetString(key string) (s string) | Obtain the value of the requestContext key as key and convert it to type string |
func (ctx *RequestContext) GetBool(key string) (b bool) | Obtain the value of the requestContext key as key and convert it to type bool |
func (ctx *RequestContext) GetInt(key string) (i int) | Obtain the value of the requestContext key as key and convert it to type int |
func (ctx *RequestContext) GetInt32(key string) (i32 int32) | Obtain the value of the requestContext key as key and convert it to type int32 |
func (ctx *RequestContext) GetInt64(key string) (i64 int64) | Obtain the value of the requestContext key as key and convert it to type int64 |
func (ctx *RequestContext) GetUint(key string) (ui uint) | Obtain the value of the requestContext key as key and convert it to type uint |
func (ctx *RequestContext) GetUint32(key string) (ui32 uint32) | Obtain the value of the requestContext key as key and convert it to type uint32 |
func (ctx *RequestContext) GetUint64(key string) (ui64 uint64) | Obtain the value of the requestContext key as key and convert it to type uint64 |
func (ctx *RequestContext) GetFloat32(key string) (f32 float32) | Obtain the value of the requestContext key as key and convert it to type float32 |
func (ctx *RequestContext) GetFloat64(key string) (f64 float64) | Obtain the value of the requestContext key as key and convert it to type float64 |
func (ctx *RequestContext) GetTime(key string) (t time.Time) | Obtain the value of the requestContext key as key and convert it to type time.Time |
func (ctx *RequestContext) GetDuration(key string) (d time.Duration) | Obtain the value of the requestContext key as key and convert it to type time.Duration |
func (ctx *RequestContext) GetStringSlice(key string) (ss []string) | Obtain the value of the requestContext key as key and convert it to type []string |
func (ctx *RequestContext) GetStringMap(key string) (sm map[string]interface{}) | Obtain the value of the requestContext key as key and convert it to type map[string]interface{} |
func (ctx *RequestContext) GetStringMapString(key string) (sms map[string]string) | Obtain the value of the requestContext key as key and convert it to type map[string]string |
func (ctx *RequestContext) GetStringMapStringSlice(key string) (smss map[string][]string) | Obtain the value of the requestContext key as key and convert it to type map[string][]string |
func (ctx *RequestContext) ForEachKey(fn func(k string, v interface{})) | Call fn for each key value pair in the context |
Example Code:
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
c.Set("version1", "v1")
v := c.Value("version1") // v == interface{}(string) "v1"
c.Set("version2", "v2")
v, exists := c.Get("version2") // v == interface{}(string) "v2", exists == true
v, exists = c.Get("pet") // v == interface{} nil, exists == false
c.Set("version3", "v3")
v := c.MustGet("version3") // v == interface{}(string) "v3"
c.Set("version4", "v4")
vString := c.GetString("version4") // vString == "v4"
c.Set("isAdmin", true)
vBool := c.GetBool("isAdmin") // vBool == true
c.Set("age1", 20)
vInt := c.GetInt("age1") // vInt == 20
c.Set("age2", int32(20))
vInt32 := c.GetInt32("age2") // vInt32 == 20
c.Set("age3", int64(20))
vInt64 := c.GetInt64("age3") // vInt64 == 20
c.Set("age4", uint(20))
vUInt := c.GetUint("age4") // vUInt == 20
c.Set("age5", uint32(20))
vUInt32 := c.GetUint32("age5") // vUInt32 == 20
c.Set("age6", uint64(20))
vUInt64 := c.GetUint64("age6") // vUInt64 == 20
c.Set("age7", float32(20.1))
vFloat32 := c.GetFloat32("age7") // vFloat32 == 20.1
c.Set("age8", 20.1)
vFloat64 := c.GetFloat64("age8") // vFloat64 == 20.1
t2022, _ := time.Parse(time.RFC1123, "Wed, 21 Oct 2022 07:28:00 GMT")
c.Set("birthday", t2022)
vTime := c.GetTime("birthday") // vTime == t2022
c.Set("duration", time.Minute)
vDuration := c.GetDuration("duration") // vDuration == time.Minute
c.Set("pet", []string{"cat", "dog"})
vStringSlice := c.GetStringSlice("pet") // vStringSlice == []string{"cat", "dog"}
c.Set("info1", map[string]interface{}{"name": "tom"})
vStringMap := c.GetStringMap("info1") // vStringMap == map[string]interface{}{"name": "tom"}
c.Set("info2", map[string]string{"name": "tom"})
vStringMapString := c.GetStringMapString("info2")
// vStringMapString == map[string]string{}{"name": "tom"}
c.Set("smss", map[string][]string{"pets": {"cat", "dog"}})
vStringMapStringSlice := c.GetStringMapStringSlice("smss")
// vStringMapStringSlice == map[string][]string{"pets": {"cat", "dog"}}
c.Set("duration", time.Minute)
c.Set("version", "v1")
c.ForEachKey(func(k string, v interface{}) {
// 1. k == "duration", v == interface{}(time.Duration) time.Minute
// 2. k == "version", v == interface{}(string) "v1"
})
})
Handler
func (ctx *RequestContext) Next(c context.Context)
func (ctx *RequestContext) Handlers() HandlersChain
func (ctx *RequestContext) Handler() HandlerFunc
func (ctx *RequestContext) SetHandlers(hc HandlersChain)
func (ctx *RequestContext) HandlerName() string
func (ctx *RequestContext) GetIndex() int8
func (ctx *RequestContext) Abort()
func (ctx *RequestContext) IsAborted() bool
Next
Execute the next handler, which is typically used in middleware handlers.
Function Signature:
func (ctx *RequestContext) Next(c context.Context)
Example Code:
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
c.Next(ctx)
v := c.GetString("version") // v == "v1"
}, func(ctx context.Context, c *app.RequestContext) {
c.Set("version", "v1")
})
Handlers
Get handlers chain.
Function Signature:
func (ctx *RequestContext) Handlers() HandlersChain
Example Code:
middleware1 := func(ctx context.Context, c *app.RequestContext) {
}
handler1 := func(ctx context.Context, c *app.RequestContext) {
handlers := c.Handlers() // []Handler{middleware1, handler1}
}
h.POST("/user", middleware1, handler1)
Handler
Obtain the last handler of the handlers chain. Generally speaking, the last handler is the main handler.
Function Signature:
func (ctx *RequestContext) Handler() HandlerFunc
Example Code:
middleware1 := func(ctx context.Context, c *app.RequestContext) {
lastHandler := c.Handler() // lastHandler == handler1
}
handler1 := func(ctx context.Context, c *app.RequestContext) {
}
h.POST("/user", middleware1, handler1)
SetHandlers
Set handlers chain.
Function Signature:
func (ctx *RequestContext) SetHandlers(hc HandlersChain)
Example Code:
handler1 := func(ctx context.Context, c *app.RequestContext) {
c.Set("current", "handler1")
}
handler := func(ctx context.Context, c *app.RequestContext) {
hc := app.HandlersChain{c.Handlers()[0], handler1} // append handler1 into handlers chain
c.SetHandlers(hc)
c.Next(ctx)
current := c.GetString("current") // current == "handler1"
c.String(consts.StatusOK, current)
}
h.POST("/user", handler)
HandlerName
Get the function name of the last handler.
Function Signature:
func (ctx *RequestContext) HandlerName() string
Example Code:
package main
func main() {
h := server.New()
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
hn := c.HandlerName() // hn == "main.main.func1"
})
}
GetIndex
Obtain the index of the currently executing handler in the handlers chain.
Function Signature:
func (ctx *RequestContext) GetIndex() int8
Example Code:
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
index := c.GetIndex() // index == 0
}, func(ctx context.Context, c *app.RequestContext) {
index := c.GetIndex() // index == 1
})
Abort
Terminate subsequent handler execution.
Function Signature:
func (ctx *RequestContext) Abort()
Example Code:
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
c.Abort()
}, func(ctx context.Context, c *app.RequestContext) {
// will not execute
})
IsAborted
Obtain whether the subsequent handler execution status has been terminated.
Function Signature:
func (ctx *RequestContext) IsAborted() bool
Example Code:
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
c.Abort()
isAborted := c.IsAborted() // isAborted == true
}, func(ctx context.Context, c *app.RequestContext) {
// will not execute
})
Binding and validate
(For more information, please refer to binding-and-validate)
func (ctx *RequestContext) Bind(obj interface{}) error
func (ctx *RequestContext) Validate(obj interface{}) error
func (ctx *RequestContext) BindAndValidate(obj interface{}) error
Get ClientIP
func (ctx *RequestContext) ClientIP() string
func (ctx *RequestContext) SetClientIPFunc(f ClientIP)
ClientIP
Obtain the address of the client IP.
The default behavior of this function: If there is an ip in the X-Forwarded-For
or X-Real-IP
headers, read the ip from these two headers and return it (priority X-Forwarded-For
greater than X-Real-IP
), otherwise return remote address.
Function Signature:
func (ctx *RequestContext) ClientIP() string
Example Code:
// X-Forwarded-For: 20.20.20.20, 30.30.30.30
// X-Real-IP: 10.10.10.10
h.Use(func(ctx context.Context, c *app.RequestContext) {
ip := c.ClientIP() // 20.20.20.20
})
SetClientIPFunc
If the default method provided by the ClientIP function does not meet the requirements, users can use this function to customize the way to obtain the client ip.
Users can implement custom functions themselves or by setting app.ClientIPOptions
.
Note: When setting
app.ClientIPOptions
,TrustedCIDRs
requires user customization(if not set, fixed return to remote address), representing trusted routes. If the remote address is within the trusted routing range, it will choose to obtain the ip fromRemoteIPHeaders
, otherwise it will return the remote address.
Function Signature:
func (ctx *RequestContext) SetClientIPFunc(f ClientIP)
Example Code:
// POST http://example.com/user
// X-Forwarded-For: 30.30.30.30
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
// method 1
customClientIPFunc := func(c *app.RequestContext) string {
return "127.0.0.1"
}
c.SetClientIPFunc(customClientIPFunc)
ip := c.ClientIP() // ip == "127.0.0.1"
// method 2
_, cidr, _ := net.ParseCIDR("127.0.0.1/32")
opts := app.ClientIPOptions{
RemoteIPHeaders: []string{"X-Forwarded-For", "X-Real-IP"},
TrustedCIDRs: []*net.IPNet{cidr},
}
c.SetClientIPFunc(app.ClientIPWithOption(opts))
ip = c.ClientIP() // ip == "30.30.30.30"
})
Concurrent Security
func (ctx *RequestContext) Copy() *RequestContext
Copy
Copy a copy of RequestContext to provide secure access to the coroutine.
Function Signature:
func (ctx *RequestContext) Copy() *RequestContext
Example Code:
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
ctx1 := c.Copy()
go func(context *app.RequestContext) {
// safely
}(ctx1)
})