Gin framework: RPC error code design

Introduce

Through a complete example , How to Gin Reasonable design under the frame API Error code .

We will use rk-boot To start up Gin Framework based microservices .

Please visit the following address for a complete tutorial ：

• https://rkdocs.netlify.app/cn

The scope of consideration

A reasonable RPC error , The following aspects need to be considered .

• Contains error code , error message
• Error messages are extensible
• Consider readability
• Analyzability , namely , The user can parse the error code through the code , And take effective actions
• The benefits of avoiding internal errors , for example ,Nil point error

Error code structure

{
    "error":{
        "code":500,
        "status":"Internal Server Error",
        "message":"Panic manually!",
        "details":[]
    }
}

install

go get github.com/rookie-ninja/rk-boot
go get github.com/rookie-ninja/rk-gin

Quick start

adopt rk-boot , Users can easily build Gin Framework microservices ,rk-boot Integrated Panic Capture and standard error types .

Complete example

1. establish boot.yaml

boot.yaml The document describes Gin Original information of framework startup ,rk-boot By reading the boot.yaml To start up Gin.

---
gin:
  - name: greeter
    port: 8080
    enabled: true

2. establish main.go

Give Way /v1/greeter Return an error .

// Copyright (c) 2021 rookie-ninja
//
// Use of this source code is governed by an Apache-style
// license that can be found in the LICENSE file.
package main

import (
	"context"
	"github.com/gin-gonic/gin"
	"github.com/rookie-ninja/rk-boot"
	"github.com/rookie-ninja/rk-gin/boot"
	"net/http"
)

// @title RK Swagger for Gin
// @version 1.0
// @description This is a greeter service with rk-boot.

// Application entrance.
func main() {
	// Create a new boot instance.
	boot := rkboot.NewBoot()

	// Register handler
	boot.GetEntry("greeter").(*rkgin.GinEntry).Router.GET("/v1/greeter", Greeter)

	// Bootstrap
	boot.Bootstrap(context.Background())

	// Wait for shutdown sig
	boot.WaitForShutdownSig(context.Background())
}

// @Summary Greeter service
// @Id 1
// @version 1.0
// @produce application/json
// @Param name query string true "Input name"
// @Success 200 {object} GreeterResponse
// @Router /v1/greeter [get]
func Greeter(ctx *gin.Context) {
	err := rkerror.New(
		rkerror.WithHttpCode(http.StatusAlreadyReported),
		rkerror.WithMessage("Trigger manually!"),
		rkerror.WithDetails("This is detail.", false, -1, 0.1))

	ctx.JSON(http.StatusAlreadyReported, err)
}

// Response.
type GreeterResponse struct {
	Message string
}

3. start-up main.go

$ go run main.go

4. verification

$ curl "localhost:8080/v1/greeter?name=rk-dev"
{
    "error":{
        "code":208,
        "status":"Already Reported",
        "message":"Trigger manually!",
        "details":[
            "This is detail.",
            false,
            -1,
            0.1
        ]
    }
}

Capture Panic（ System crash ）

We still use demo Code as an example .

stay RPC In the implementation , We tried to crash the system , have a look rk-boot How will it be captured automatically , And what information is returned to the user .

1. modify main.go

// Copyright (c) 2021 rookie-ninja
//
// Use of this source code is governed by an Apache-style
// license that can be found in the LICENSE file.
package main

import (
	"context"
	"github.com/gin-gonic/gin"
	"github.com/rookie-ninja/rk-boot"
	"github.com/rookie-ninja/rk-gin/boot"
)

// @title RK Swagger for Gin
// @version 1.0
// @description This is a greeter service with rk-boot.

// Application entrance.
func main() {
	// Create a new boot instance.
	boot := rkboot.NewBoot()

	// Register handler
	boot.GetEntry("greeter").(*rkgin.GinEntry).Router.GET("/v1/greeter", Greeter)

	// Bootstrap
	boot.Bootstrap(context.Background())

	// Wait for shutdown sig
	boot.WaitForShutdownSig(context.Background())
}

// @Summary Greeter service
// @Id 1
// @version 1.0
// @produce application/json
// @Param name query string true "Input name"
// @Success 200 {object} GreeterResponse
// @Router /v1/greeter [get]
func Greeter(ctx *gin.Context) {
	panic("Panic manually!")
}

2. verification

$ curl "localhost:8080/v1/greeter?name=rk-dev"
{
    "error":{
        "code":500,
        "status":"Internal Server Error",
        "message":"Panic manually!",
        "details":[

        ]
    }
}

Source code

rk-boot Error handling in , To achieve in rk-common/error in .

More examples

Please refer to ：rk-demo Get more examples .