Request

The functions related to the request in RequestContext.

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, while FullPath 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
// 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
})

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) PostFormArray(key string) []string
func (ctx *RequestContext) PostFormMap(key string) map[string][]string
func (ctx *RequestContext) DefaultPostForm(key, defaultValue string) string
func (ctx *RequestContext) GetPostForm(key string) (string, bool)
func (ctx *RequestContext) GetPostFormArray(key string) ([]string, bool)
func (ctx *RequestContext) GetPostFormMap(key string) map[string][]string
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"
})

PostFormArray

Retrieve multipart.Form.Value by name and return all values 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) PostFormArray(key string) []string

Example Code:

// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="pet"; value="cat"
// Content-Disposition: form-data; name="pet"; value="dog"
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
    pets := c.PostFormArray("pet") // pets == []string{"cat", "dog"}
})

PostFormMap

Retrieve multipart.Form.Value by name and return a map of all values 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) PostFormMap(key string) map[string][]string

Example Code:

// POST http://example.com/user
// Content-Type: multipart/form-data;
// Content-Disposition: form-data; name="attr[k1]"; value="v1"
// Content-Disposition: form-data; name="attr[k2]"; value="v2"
h.POST("/user", func(ctx context.Context, c *app.RequestContext) {
    attrs := c.PostFormMap("attr") // attrs == map[string][]string{"k1": "v1", "k2": "v2"}
})

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.

  1. Obtain values from QueryArgs.
  2. Obtain values from PostArgs.
  3. 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 from RemoteIPHeaders, 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)
})