Router Method Definition

From the example above, we can see that the router method definition uses a fixed format:

func Handler(ctx context.Context, req *Request) (res *Response, err error)

Among them, both the input and output parameters are two, and they are all required without any omission. Briefly described as:

Parameter	Description	Note
ctx context.Context	Context	The Server component will automatically fetch and pass it to the API method from the request.
req *Request	Request Object	Even if no parameters are received, it must be defined because the request structure not only contains the request parameter definition but also the request definition of the API.
res *Response	Response Object	Even if there are no return parameters, it must be defined because the return structure not only contains the return parameter definition but also can include the API return definition.
err error	Error Object	Server uses this parameter to determine whether the API execution is successful or failed.

Unified Router Registration

Group.Bind Method

We recommend using an object-oriented approach to manage all router methods and perform unified registration through the Bind method of grouped routers. It should be noted that in a normalized routing manner, the routing address and request method will be defined through tags in the g.Meta metadata object in the request structure. The grouped router can define all the routing prefixes under the group.

BindHandler Method

We can also register the normalized router through the basic BindHandler method, but this method can only register one router function. Usage example:

s := g.Server()
s.BindHandler("/user/{uid}", func(ctx context.Context, req *SaveReq) (res *SaveRes, err error) {
    // ...
})

Standardized Parameter Structure

In normalized router registration, the definition of the request/response parameter structure is very important. This structure not only contains the input parameter definition but also includes the API definition, especially information such as routing address, request method, and API description. Maintaining parameter structures in a structured data approach facilitates richer API capability expansion, team API interaction, long-term API maintenance, and automated API documentation generation.

To ensure naming normalization, input data structures are named in the XxxReq way, and output data structures are named in the XxxRes way. Even when input or output parameters are null, the corresponding data structures need to be defined for future expansion and API information management. For a description of the tags involved in OpenAPIv3 in the structure, please refer to the subsequent chapters.

tip

Request parameters are automatically converted to request data structures, and field mapping conversions are case insensitive and will automatically ignore special characters.

Input Data Validation

The request structure will be automatically validated before being executed by the API API. If one of the rule validations fails, the subsequent validations will be terminated (using the bail validation modification rule automatically). The validation function uses the unified validation component of the framework, please refer to: Data Validation

warning

Special attention should be paid: if there are multiple validation rules for parameter validation and there is a required* rule in the rules, it is recommended to place the required* validation rule before all rules. Otherwise, the feature of the bail validation rule enabled in the built-in standardized router (terminate further validation upon failure) may cause subsequent required* rules to be ineffective.

Unified Return Middleware

The data return processing for the API requires setting up a unified post-middleware, and you can also use the data return middleware provided by Server by default. When developers customize middleware, they can refer to the middleware MiddlewareHandlerResponse provided by Server.

By the way, here is an important method when customizing the return middleware:

// GetHandlerResponse retrieves and returns the handler response object and its error.
func (r *Request) GetHandlerResponse() interface{}

When executing via the post-middleware, use the GetHandlerResponse method of the request object to get the result of the current business execution and handle it accordingly.

Extended Introduction

OpenAPIv3 Protocol

The API documentation automatically generated by the Server component uses the latest OpenAPIv3 protocol. For more details, please refer to the chapter: API Document

Request Object in Ctx

We can get the Request object from ctx using the RequestFromCtx/g.RequestFromCtx method.

Method definition:

func RequestFromCtx(ctx context.Context) *Request

Usage example:

func (c *cHello) Hello(ctx context.Context, req *apiv1.HelloReq) (res *apiv1.HelloRes, err error) {
    g.RequestFromCtx(ctx).Response.Writeln("Hello World!")
    return
}