The highest tagged major version is v2.

rk-gin

module

v1.2.22 Latest Latest Go to latest Published: Feb 20, 2022 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/rookie-ninja/rk-gin

Links

Open Source Insights

README ¶

rk-gin

Interceptor & bootstrapper designed for gin-gonic/gin web framework. Documentation.

This belongs to rk-boot family. We suggest use this lib from rk-boot.

Table of Contents generated with DocToc

Architecture
Supported bootstrap
Supported instances
Supported middlewares
Installation
Quick Start
YAML Options
- Gin
- CommonService
- Swagger
- Prom Client
- TV
- Static file handler
- Middlewares
  - Log
  - Metrics
  - Auth
  - Meta
  - Tracing
  - RateLimit
  - Timeout
  - Gzip
  - CORS
  - JWT
  - Secure
  - CSRF
- Full YAML
- Development Status: Stable
Build instruction
Test instruction
Contributing

Architecture

Supported bootstrap

Bootstrap	Description
YAML based	Start gin-gonic/gin microservice from YAML
Code based	Start gin-gonic/gin microservice from code

Supported instances

All instances could be configured via YAML or Code.

User can enable anyone of those as needed! No mandatory binding!

Instance	Description
gin.Router	Compatible with original gin-gonic/gin service functionalities
Config	Configure spf13/viper as config instance and reference it from YAML
Logger	Configure uber-go/zap logger configuration and reference it from YAML
EventLogger	Configure logging of RPC with rk-query and reference it from YAML
Credential	Fetch credentials from remote datastore like ETCD.
Cert	Fetch TLS/SSL certificates from remote datastore like ETCD and start microservice.
Prometheus	Start prometheus client at client side and push metrics to pushgateway as needed.
Swagger	Builtin swagger UI handler.
CommonService	List of common APIs.
TV	A Web UI shows microservice and environment information.
StaticFileHandler	A Web UI shows files could be downloaded from server, currently support source of local and pkger.

Supported middlewares

All middlewares could be configured via YAML or Code.

User can enable anyone of those as needed! No mandatory binding!

Middleware	Description
Metrics	Collect RPC metrics and export to prometheus client.
Log	Log every RPC requests as event with rk-query.
Trace	Collect RPC trace and export it to stdout, file or jaeger with open-telemetry/opentelemetry-go.
Panic	Recover from panic for RPC requests and log it.
Meta	Send micsroservice metadata as header to client.
Auth	Support [Basic Auth] and [API Key] authorization types.
RateLimit	Limiting RPC rate globally or per path.
Timeout	Timing out request by configuration.
Gzip	Compress and Decompress message body based on request header with gzip format .
CORS	Server side CORS validation.
JWT	Server side JWT validation.
Secure	Server side secure validation.
CSRF	Server side csrf validation.

Installation

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

Quick Start

In the bellow example, we will start microservice with bellow functionality and middlewares enabled via YAML.

gin-gonic/gin server
Swagger UI
CommonService
TV
Prometheus Metrics (middleware)
Logging (middleware)
Meta (middleware)

Please refer example at example/boot/simple.

1.Create boot.yaml

boot.yaml

---
gin:
  - name: greeter                     # Required
    port: 8080                        # Required
    enabled: true                     # Required
    tv:
      enabled: true                   # Optional, default: false
    prom:
      enabled: true                   # Optional, default: false
    sw:                               # Optional
      enabled: true                   # Optional, default: false
    commonService:                    # Optional
      enabled: true                   # Optional, default: false
    interceptors:
      loggingZap:
        enabled: true
      metricsProm:
        enabled: true
      meta:
        enabled: true

2.Create main.go

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"
	"fmt"
	"github.com/gin-gonic/gin"
	"github.com/rookie-ninja/rk-entry/entry"
	"github.com/rookie-ninja/rk-gin/boot"
	"net/http"
)

func main() {
	// Bootstrap basic entries from boot config.
	rkentry.RegisterInternalEntriesFromConfig("example/boot/simple/boot.yaml")

	// Bootstrap gin entry from boot config
	res := rkgin.RegisterGinEntriesWithConfig("example/boot/simple/boot.yaml")

	// Get GinEntry
	ginEntry := res["greeter"].(*rkgin.GinEntry)
	// Use *gin.Router adding handler.
	ginEntry.Router.GET("/v1/greeter", Greeter)

	// Bootstrap gin entry
	ginEntry.Bootstrap(context.Background())

	// Wait for shutdown signal
	rkentry.GlobalAppCtx.WaitForShutdownSig()

	// Interrupt gin entry
	ginEntry.Interrupt(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) {
	ctx.JSON(http.StatusOK, &GreeterResponse{
		Message: fmt.Sprintf("Hello %s!", ctx.Query("name")),
	})
}

// Response.
type GreeterResponse struct {
	Message string
}

3.Start server

$ go run main.go

4.Validation