hertzer

1. a gin webserver which bases on cloudwebgo/hertz
2. inspired by cobra for the RouterGroup management

1. Usage

go to example/demo

go get -u github.com/go-jarvis/hertzer

2. Server

func main() {

// define a server
	s := &hertzer.Server{
		Listen: ":8081",
	}

// set server options, sam eas hertz
	s.WithOptions(
		server.WithBasePath("/api"),
		server.WithIdleTimeout(10),
	)

// add middlewares, same as the hertz
	s.Use(prefunc(), postfunc())

// handle a router handler
	s.Handle(&Ping{})

// Run server
	if err := s.Run(); err != nil {
		panic(err)
	}
}

3. Router Handler

Main Router HandlerFunc

type Ping struct {
	httpx.MethodPost `route:"/ping/:name"` // define method and path

// define the body
	Name      string  `path:"name"`
	Age       int     `query:"age"`
	AuthToken string  `header:"AuthToken"`
	Address   Address `json:"address"`
	Score     int     `json:"score" form:"score"`
}


// Handle method must exists.
// reqeust data will be binded into p automaticly.
// it can be used directly.
func (p *Ping) Handle(ctx context.Context, arc *app.RequestContext) (any, error) {

	fmt.Println(p.Address)

	ret := resp.NewStatusResponse(consts.StatusAccepted, *p)
	return ret, nil
}

So that, the default handler will be like:

// r.Handle(httpMethod, relativePath string, handlers ...app.HandlerFunc)
r.Handle("POST","/ping/:name", handler)

3.1. Hanlder's HandlerFuncChain

Add the PreHandlers and PostHandlers to combine the HandlerFunc Chain. NOTE: PreHandlers and PostHandlers as optional.

func (Ping) PreHandlers() []app.HandlerFunc {
	return []app.HandlerFunc{
		prefunc(),
	}
}

func (Ping) PostHandlers() []app.HandlerFunc {
	return []app.HandlerFunc{
		postfunc(),
	}
}

The Registered Router will be like

// r.Handle(httpMethod, relativePath string, handlers ...app.HandlerFunc)
r.Handle("POST","/ping/:name", [pre...,] handler, [post...])

3.2 RouterGroup

As metioned before, the RouterGroups like the carriages of a train. They are not only mounted one by one, and but also can be mounted to any RouterGroup.

NOTE: The Mounted Ring is forbidden. And Directed Acyclic Graph(DAG) of RouterGroups are required.

1. Using v1:=hertzer.NewRouterGroup(v1) to create a new RouterGroup
2. Using v2.AddGroup(v2) to add children RouterGroup(s).

// define a server
	s := &hertzer.Server{
		Listen: ":8081",
	}

// define Router Groups
	v1 := hertzer.NewRouterGroup("/v1")
	v1.Handle(&Ping{})

	v2 := hertzer.NewRouterGroup("/v2")

// mount children RouterGroup(s)
	s.AddGroup(v1)
	v1.AddGroup(v2)
	s.AddGroup(v2)

4. Response and Error

By default,

func (p *Ping) Handle(...) (result any, err error) {}

Typically, the response will be

1. if the error is nil:

   • status code = 200 // http.StatusOK
   • the data is "result"

2. if the error is not nil:

   • status code = 500 // http.StatusInternalServerError
   • the data is "err.Error()"

the 3rd response is special, Router Binding error. + status code = 400 // StatusBadRequest + the data is actual value of binding error

4.1. Status Reponse

However, you may use resp.NewStatusResponse to set the HTTP Status Code whatever you need.

// define
func NewStatusResponse(code int, meta interface{}) StatusResponse {
	return &statusResponse{
		code: code,
		meta: meta,
	}
}

// usage
ret := resp.NewStatusResponse(consts.StatusBadGateway, *p)
return ret, nil

4.2. Status Error

By the way, you can use errors.New to create a status error.

// define
func New(err error, meta any) *StatusError {
	return &StatusError{
		Err:  err,
		Meta: meta,
		Message: "",
	}
}

// usage
serr := errors.New(err, *p)
serr = serr.SetMessage("Error Message")

By default the Message will be the HTTP Status Message/Define if you don't SetMessage