ginrpc

README

ginrpc

An RPC-style web framework based on GIN. You can not only have an RPC-style coding experience, but also enjoy the benefits of gin's complete ecology and REST-style flexibility

Use slog, which will soon be added to the standard library, as the framework's preferred logging component

• go1.19+ golang.org/x/exp/slog
• go1.21+ log/slog

Quick Start

Define input and output parameters

type InRequest struct{
    Name string     `uri:"name" binding:"required"`
}

type OutResponse struct{
    Data string     `json:"data"`
}

Edit handler

func Hello(ctx context.Context, in *InRequest) (*OutRequest, error){
    slog.InfoCtx(ctx, "revice", slog.String("name",in.Name))
    return &OutResponse{
        Data: "hello " + in.Name
    }, nil
}

Register route

srv := ginrpc.New(
    ginrpc.WithAddr(":8082"),
)
srv.Get("/hello/:name", Hello)
srv.Start()

// request http://localhost:8082/hello/afocus
// response {"data":"hello afocus"}

full examples can be checked out from below

Old project transformation 已有项目改造

e:=gin.New()

e.Use(...)

+ srv:=ginrpc.New(
+     ginrpc.WithAddr(":8082"),
+     ginrpc.WithGinEngine(e),
+ )

e.GET("/", func(*gin.Context){})
- e.GET("/userpc", func(*gin.Context){})
+ srv.Get("/userpc", useRpcHandler) // gin style -> rpc style
+ e.GET("/userpc2", srv.HandleFunc(useRpcHandler)) // rpc style -> gin style

- e.Run(":8082")
+ srv.Start()

Incompatible

bind query

gin uses the structure tag:form to support query and only supports GET request

type QueryReq struct{
    // gin
    // Keyword string `form:"q"`
    // ginrpc
    Keyword string `query:"q"`
}

Road map

• support otel tracing
• automatically generate openapi documentation

Documentation

Index

• type Empty
• type Handler
• type Option
  • func WithAddr(addr string) Option
  • func WithDisableAccessLog() Option
  • func WithDumpRequest(o bool) Option
  • func WithGinEngine(e *gin.Engine) Option
  • func WithResponseRender(r Renderer) Option
• type Renderer
• type Router
• type Routes
• type Server
  • func New(opts ...Option) *Server
  • func (s *Server) Engine() *gin.Engine
  • func (s *Server) HandleFunc(v any) gin.HandlerFunc
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() error

Types

type Empty

type Empty struct{}

Empty 空参数定义 此类型不参与参数解析

type Handler

type Handler func(any) gin.HandlerFunc

Handler ginhandler包裹器 负责将rpc模式转为gin handler

type Option

type Option func(*option)

func WithAddr

func WithAddr(addr string) Option

func WithDisableAccessLog

func WithDisableAccessLog() Option

func WithDumpRequest

func WithDumpRequest(o bool) Option

WithDumpRequest Whether to print the request body in the routing log

func WithGinEngine

func WithGinEngine(e *gin.Engine) Option

func WithResponseRender

func WithResponseRender(r Renderer) Option

WithResponseRender custom response rendering

type Renderer

type Renderer func(*gin.Context, any, error)

Renderer 渲染响应

type Router

type Router interface {
	// rpc模式路由方法
	// handler 支持rpc方法和gin.HandleFunc(为了支持gin中间件)
	Get(path string, handler ...any)
	Post(path string, handler ...any)
	Put(path string, handler ...any)
	Patch(path string, handler ...any)
	Delete(path string, handler ...any)
	Handle(method, path string, handler ...any)
	// 同gin
	Use(handler ...gin.HandlerFunc) Router
	Group(path string, handler ...gin.HandlerFunc) Router
}

type Routes

type Routes []*routeInfo

type Server

type Server struct {
	Router
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) *Server

func (*Server) Engine

func (s *Server) Engine() *gin.Engine

Engine return *gin.Engine

func (*Server) HandleFunc

func (s *Server) HandleFunc(v any) gin.HandlerFunc

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

func (*Server) Start

func (s *Server) Start() error