Simplify Go Microservices to RESTful APIs with Ginrest and Generics

Background

In a microservice or service‑oriented architecture, most business‑logic functions are written as long gRPC handlers such as:

func (s *Service) GetUserInfo(ctx context.Context, req *pb.GetUserInfoReq) (*pb.GetUserInfoRsp, error) {
    // business logic
    // ...
}

The client side looks similar:

func (s *Service) GetUserInfo(ctx context.Context, req *pb.GetUserInfoReq, opts ...grpc.CallOption) (*pb.GetUserInfoRsp, error) {
    // business logic
    // ...
}

When exposing these services as RESTful APIs, developers repeatedly write code for HTTP method, URL, authentication, parameter binding, request handling and response handling.

Why Ginrest?

Ginrest is a lightweight Go library that uses Go 1.18 generics to eliminate the repetitive boilerplate. It is not a full‑featured framework, but a set of helpers that wrap the common patterns.

Features

Encapsulate RESTful request and response with a standard Rsp{code, msg, data} format.

Unified numeric error codes ([0, 4XXX, 5XXX]) and error struct Error{code, msg}.

Recovery middleware that returns a consistent panic response.

Context helpers SetKey() and GetKey() for storing generic values. ReqFunc() to populate request structs.

Usage Example

Define error codes, request/response structs and service functions:

const (
    ErrCodeUserNotExists = 40100 // user does not exist
)

type GetUserInfoReq struct {
    UID int `json:"uid"`
}

type GetUserInfoRsp struct {
    UID      int    `json:"uid"`
    Username string `json:"username"`
    Age      int    `json:"age"`
}

func GetUserInfo(ctx context.Context, req *GetUserInfoReq) (*GetUserInfoRsp, error) {
    if req.UID != 10 {
        return nil, ginrest.NewError(ErrCodeUserNotExists, "user not exists")
    }
    return &GetUserInfoRsp{UID: req.UID, Username: "user_10", Age: 10}, nil
}

// UpdateUserInfo implementation omitted for brevity

Register routes with Gin and Ginrest:

func main() {
    e := gin.New()
    e.Use(ginrest.Recovery())
    Register(e)
    if err := e.Run("127.0.0.1:8000"); err != nil {
        log.Println(err)
    }
}

func Register(e *gin.Engine) {
    e.GET("/user/info/get", ginrest.Do(nil, GetUserInfo))
    reqFunc := func(c *gin.Context, req *UpdateUserInfoReq) {
        req.UID = GetUID(c)
    }
    e.POST("/user/info/update", Verify, ginrest.Do(reqFunc, UpdateUserInfo))
}

Running the program and sending HTTP requests yields responses such as:

GET /user/info/get
{ "uid": 10 }
Response:
{ "code": 0, "msg": "ok", "data": { "uid": 10, "username": "user_10", "age": 10 } }

Implementation Details

The public Do() and DoOpt() functions delegate to a generic do[Req any, Rsp any, Opt any] helper that performs:

JSON binding with BindJSON[Req].

Optional request‑side processing via a ReqFunc.

Invocation of the service function or an optional service‑option function.

Response handling through ProcessRsp, which calls Success or Failure based on the error.

Additional helpers include BindJSON, ProcessRsp, Success, Failure, and the error type Error with constructors like NewError.

Conclusion

If the library does not match a specific project’s needs, developers can follow the same pattern to create a custom wrapper that unifies request and response handling, dramatically reducing boilerplate code.