ginx

README

go-ginx: gin框架的增强工具

gin框架是目前非常流行的http框架，但是由于gin本身设计的比较简单，以至于我们在开发项目的时候需要自行开发辅助函数或者使用一个封装好的脚手架。鉴于此，ginx出现了。

ginx本身并不是一个框架，它只是一个基于gin框架的增加工具集，ginx存在的目的只是帮助开发者用最小的修改来更快速的开发gin项目

ginx解决的痛点

• 对泛型的支持
• 请求参数自动解析
• 响应包装
• 自动生成接口文档
• 封装常用的中间件
• 支持SSE

代码示例

package main

import (
    "log/slog"

    "github.com/gin-gonic/gin"
    "github.com/pkg/errors"

    "github.com/codeyifei/go-ginx"
)

type GetRequest struct {
    Source                 string `form:"source"` // 使用form tag，可以自动绑定及验证query参数
    Id                     uint   `uri:"id"`      // 使用uri tag，可以自动绑定及验证path参数
    ginx.PaginationRequest                        // 合并分页请求，会自动绑定query中的page和page_size参数，并设置默认值，page = 1, page_size = 20
}

type GetResponseItem struct {
    Id       uint   `json:"id"`
    Username string `json:"username"`
}

type GetResponse ginx.PaginationWrapper[*GetResponseItem]

func GetHandleFunc(c *gin.Context, req *GetRequest) (*GetResponse, error) {
    slog.Info("Get Request", "source", req.Source, "id", req.Id, "page", req.Page, "pageSize", req.PageSize)

    return &GetResponse{
        List: []*GetResponseItem{
            {Id: 1, Username: "Username1"},
            {Id: 2, Username: "Username2"},
        },
        Meta: req.ToMeta(2),
    }, nil
}

type PostRequest struct {
    Authorization string `header:"Authorization"` // 使用header tag，可以自动绑定及验证header参数
    Username      string `json:"username"`        // 使用json tag，可以自动绑定及验证json参数
}

func PostHandleFunc(c *gin.Context, req *PostRequest) (*ginx.NilResponse, error) {
    slog.Info("Post Request", "authorization", req.Authorization, "username", req.Username)

    return ginx.NewNilResponse, nil
}

func main() {
    r := gin.Default()
    ginx.Get(r, "/", GetHandleFunc)
    ginx.Post(r, "/", PostHandleFunc)
    if err := r.Run(); err != nil {
        panic(errors.Wrap(err, "启动服务失败"))
    }
}

Documentation

Index

• Variables
• func Delete[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])
• func Get[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])
• func Group(r gin.IRouter, groupName string, fn func(gin.IRouter))
• func Handle[Req any, Resp any](r gin.IRouter, handlerFunc HandlerFunc[Req, Resp])
• func Head[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])
• func Options[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])
• func Patch[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])
• func Post[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])
• func Put[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])
• type BindingType
  • func ParseBindingType(s string) BindingType
• type BindingTypes
  • func (b BindingTypes) Len() int
  • func (b BindingTypes) Less(i, j int) bool
  • func (b BindingTypes) Swap(i, j int)
• type DefaultResponseWrapper
  • func (w *DefaultResponseWrapper) Response(resp any, err error) (int, render.Render)
• type Error
  • func NewError(code int, message string) *Error
  • func WrapError(err error, code int, message string) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type HandlerFunc
• type IPagination
• type IResponseWrapper
• type Meta
• type NilResponse
• type PaginationMeta
• type PaginationRequest
  • func (r *PaginationRequest) ToMeta(total int) *PaginationMeta
  • func (r *PaginationRequest) ToSqlPagination() (offset, limit int)
• type PaginationWrapper

Variables

var NewNilResponse = &NilResponse{}

Functions

func Delete

func Delete[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])

func Get

func Get[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])

func Group

func Group(r gin.IRouter, groupName string, fn func(gin.IRouter))

func Handle

func Handle[Req any, Resp any](r gin.IRouter, handlerFunc HandlerFunc[Req, Resp])

func Head

func Head[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])

func Options

func Options[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])

func Patch

func Patch[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])

func Post

func Post[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])

func Put

func Put[Req any, Resp any](r gin.IRouter, path string, handlerFunc HandlerFunc[Req, Resp])

Types

type BindingType

type BindingType uint16

const (
	BindingTypeUnknown BindingType = iota
	BindingTypeDefault
	BindingTypePath
	BindingTypeQuery
	BindingTypeJson
	BindingTypeHeader
)

func ParseBindingType

func ParseBindingType(s string) BindingType

type BindingTypes

type BindingTypes []BindingType

func (BindingTypes) Len

func (b BindingTypes) Len() int

func (BindingTypes) Less

func (b BindingTypes) Less(i, j int) bool

func (BindingTypes) Swap

func (b BindingTypes) Swap(i, j int)

type DefaultResponseWrapper

type DefaultResponseWrapper struct{}

func (*DefaultResponseWrapper) Response

func (w *DefaultResponseWrapper) Response(resp any, err error) (int, render.Render)

type Error

type Error struct {
	// contains filtered or unexported fields
}

func NewError

func NewError(code int, message string) *Error

NewError 创建一个ginx错误 Example： err := ginx.NewError(101, "参数错误")

func WrapError

func WrapError(err error, code int, message string) *Error

WrapError 包装成ginx错误 Example: err = ginx.WrapError(err, 101, "参数错误")

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type HandlerFunc

type HandlerFunc[Req any, Resp any] func(c *gin.Context, req *Req) (resp *Resp, err error)

type IPagination

type IPagination interface {
	Page() int
	PageSize() int
}

type IResponseWrapper

type IResponseWrapper interface {
	Response(resp any, err error) (code int, render render.Render)
}

var ResponseWrapper IResponseWrapper = &DefaultResponseWrapper{}

type Meta

type Meta struct{}

type NilResponse

type NilResponse struct{}

type PaginationMeta

type PaginationMeta struct {
	Total    int `json:"total"`
	Page     int `json:"page"`
	PageSize int `json:"pageSize"`
}

type PaginationRequest

type PaginationRequest struct {
	Page     int `form:"page" default:"1"`
	PageSize int `form:"page_size" default:"20"`
}

func (*PaginationRequest) ToMeta

func (r *PaginationRequest) ToMeta(total int) *PaginationMeta

func (*PaginationRequest) ToSqlPagination

func (r *PaginationRequest) ToSqlPagination() (offset, limit int)

type PaginationWrapper

type PaginationWrapper[T any] struct {
	List []T             `json:"list"`
	Meta *PaginationMeta `json:"meta"`
}