Request ID

X-Request-ID is a common non-standard response fields in HTTP Headers, used to correlate HTTP requests between a client and server. Hertz also provides Request ID middleware that can operate on X-Request-ID, inspired by gin’s implementation.

Install

Download and install

go get github.com/hertz-contrib/requestid

Import into your code

import "github.com/hertz-contrib/requestid"

Example

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/hlog"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
    "github.com/hertz-contrib/requestid"
)

func main() {
    h := server.Default()

    h.Use(
        // provide your own request id generator here
        requestid.New(
            requestid.WithGenerator(func() string {
                return "cloudwego.io"
            }),
            // set custom header for request id
            requestid.WithCustomHeaderStrKey("Your-Customised-Key"),
        ),
    )

    // Example ping request.
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        hlog.Info(string(c.Response.Header.Header()))
        c.JSON(consts.StatusOK, utils.H{"ping": "pong"})
    })

    h.Spin()
}

Config

Hertz is able to add an identifier to the response using the X-Request-ID header, and passes the X-Request-ID value back to the caller if it’s sent in the request headers by using middleware. The Request ID middleware provides the default configuration, you can also customize the following configuration using WithGenerator, WithCustomHeaderStrKey, WithHandler functions according to different scenarios.

configurationDescription
WithGeneratorDefine a function that generates a Request ID. By default, a UUID identifier is generated.
WithCustomHeaderStrKeyDefine the key value of the Request ID. By default, the key value is X-Request-ID.
WithHandlerDefine the handler function of the Request ID.

New

The requestid middleware provides New to add the Request ID field to the response header.

Function signatures:

// Option is an alias for func(*config)
func New(opts ...Option) app.HandlerFunc

Sample Code:

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
    "github.com/hertz-contrib/requestid"
)

func main() {
    h := server.Default()

    h.Use(
        requestid.New(),
    )

    // Example ping request.
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.JSON(consts.StatusOK, utils.H{"ping": "pong"})
    })

    h.Spin()
}

WithCustomHeaderStrKey

The requestid middleware provides WithCustomHeaderStrKey to customize the Request ID key value.

Note: If you want to set up the request id in the request header, you need to keep consistent with the custom request id keys.

Function signatures:

// Option is an alias for func(*config)
func WithCustomHeaderStrKey(s HeaderStrKey) Option

Sample Code:

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
    "github.com/hertz-contrib/requestid"
)

func main() {
    h := server.Default()

    // define your own header to save request id here
    h.Use(
        requestid.New(
            requestid.WithCustomHeaderStrKey("Your-Header-StrKey"),
        ),
    )

    // Example ping request.
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.JSON(consts.StatusOK, utils.H{"ping": "pong"})
    })

    h.Spin()
}

WithGenerator

The requestid middleware provides WithGenerator for custom Request ID value generation.

Function signatures:

// Generator is an alias for func() string
// Option is an alias for func(*config)
func WithGenerator(g Generator) Option

Sample Code:

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
    "github.com/hertz-contrib/requestid"
)

func main() {
    h := server.Default()

    h.Use(
        // define your own request id generator here
        requestid.New(requestid.WithGenerator(func() string {
            return "cloudwego.io"
        })),
    )

    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.JSON(consts.StatusOK, utils.H{"ping": "pong"})
    })

    h.Spin()
}

WithHandler

The requestid middleware provides WithHandler for custom Request ID handlers.

Function signatures:

// Handler is an alias for func(ctx context.Context, c *app.RequestContext, requestID string)
// Option is an alias for func(*config)
func WithHandler(handler Handler) Option

Sample Code:

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
    "github.com/hertz-contrib/requestid"
)

func main() {
    h := server.Default()

    var bar string

    h.Use(
        requestid.New(
            requestid.WithGenerator(func() string {
                return "hello"
            }),
            // define your request id handler here
            requestid.WithHandler(func(ctx context.Context, c *app.RequestContext, requestID string) {
                bar = requestID + " hertz"
            }),
        ),
    )

    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.JSON(consts.StatusOK, utils.H{
            "ping": "pong",
            "foo":  bar, // hello hertz
        })
    })

    h.Spin()
}

Get

requestid middleware provides Get which is a helper function to retrieve request id from request headers. It also works with customised header as defined with requestid.WithCustomHeaderStrKey.

Function signatures:

func Get(c *app.RequestContext) string

Sample Code:

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
    "github.com/hertz-contrib/requestid"
)

func main() {
    h := server.Default()

    h.Use(
        requestid.New(requestid.WithGenerator(func() string {
            return "cloudwego.io"
        })),
    )

    // You may retrieve request id from header by calling requestid.Get
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.JSON(consts.StatusOK, utils.H{
            "ping":       "pong",
            "request-id": requestid.Get(c),
        })
    })

    h.Spin()
}

Full Example

As for usage, you may refer to hertz example


Last modified December 2, 2022 : chore: add lark footer link (#460) (f41a884)