ginx

README

ginx

ginx 是基于 Gin 的轻量服务处理器封装，提供：

• 业务函数到 Gin Handler 的路由适配
• Query、JSON、表单和文件参数绑定
• 基于 validator 的参数校验
• 统一成功与错误响应
• 单文件、多文件及数组格式文件字段处理

安装

go get github.com/yushengji/ginx@v0.0.1

使用

package main

import (
	"context"

	"github.com/gin-gonic/gin"
	"github.com/yushengji/ginx"
)

type Query struct {
	Name string `form:"name" validate:"required"`
}

func list(_ context.Context, query *Query) (any, error) {
	return map[string]any{"name": query.Name}, nil
}

func main() {
	engine := gin.Default()
	ginx.WrapRouter(engine.Group("/api")).GET("/items", list)
	_ = engine.Run(":8080")
}

性能测试和指标说明参见 BENCHMARK.md。

Documentation

Index

• Variables
• func BindParam(_ *ServiceContext, c *gin.Context, paramValue reflect.Value) error
• type BusinessError
  • func (e *BusinessError) Error() string
• type FileField
• type FileInfo
• type FileManager
  • func (fm *FileManager) ProcessFileField(ctx *ServiceContext, field *FileField) (any, error)
  • func (fm *FileManager) ProcessFiles(ctx *ServiceContext, fields ...*FileField) (map[string]any, error)
  • func (fm *FileManager) ProcessMultipleFilesFromArrayFormat(ctx *ServiceContext, field *FileField) ([]*FileInfo, error)
• type FileTag
  • func ParseFileTag(tag reflect.StructTag) *FileTag
  • func (ft *FileTag) ToFileField() *FileField
• type Response
• type RouterGroup
  • func WrapRouter(rg *gin.RouterGroup, handler ...*ServiceHandler) *RouterGroup
  • func (rg *RouterGroup) DELETE(path string, handler any) *RouterGroup
  • func (rg *RouterGroup) GET(path string, handler any) *RouterGroup
  • func (rg *RouterGroup) POST(path string, handler any) *RouterGroup
  • func (rg *RouterGroup) PUT(path string, handler any) *RouterGroup
• type ServiceContext
• type ServiceHandler

Variables

var DefaultFileManager = &FileManager{
	BaseDir:        "uploads",
	BaseURL:        "/uploads",
	DefaultMaxSize: 10 * 1024 * 1024,
	DefaultAllowedTypes: []string{
		"image/jpeg", "image/png", "image/gif",
		"application/pdf", "application/zip",
	},
	DefaultNameGenerator: func(originalName string) string {
		ext := filepath.Ext(originalName)
		return fmt.Sprintf("%d_%s%s", time.Now().UnixNano(), uuid.New().String()[:8], ext)
	},
}

DefaultFileManager 默认文件管理器

var DefaultServiceHandler = &ServiceHandler{
	ContextFactory: func(c *gin.Context) *ServiceContext {
		return &ServiceContext{
			Context:    c,
			GinContext: c,
			Metadata:   make(map[string]any),
		}
	},
	Binder:          defaultBinder,
	ResponseHandler: defaultResponseHandler,
	ErrorHandler:    defaultErrorHandler,
	FileHandler:     DefaultFileManager,
}

DefaultServiceHandler 默认处理器

Functions

func BindParam

func BindParam(_ *ServiceContext, c *gin.Context, paramValue reflect.Value) error

BindParam 统一绑定参数

Types

type BusinessError

type BusinessError struct {
	HTTPCode int
	Code     int
	Message  string
}

BusinessError 业务错误

func (*BusinessError) Error

func (e *BusinessError) Error() string

type FileField

type FileField struct {
	// 表单字段名
	FieldName string
	// 是否必需
	Required bool
	// 最大文件大小（字节）
	MaxSize int64
	// 允许的文件类型
	AllowedTypes []string
	// 保存目录（相对于基础目录）
	SaveDir string
	// 文件名生成器
	NameGenerator func(originalName string) string
	// 是否允许多文件
	Multiple bool
	// 最大文件数量（多文件时有效）
	MaxCount int
}

FileField 文件字段配置

type FileInfo

type FileInfo struct {
	FieldName    string `json:"field_name"`
	OriginalName string `json:"original_name"`
	FileName     string `json:"file_name"`
	FilePath     string `json:"file_path"`
	FileURL      string `json:"file_url"`
	Size         int64  `json:"size"`
	MimeType     string `json:"mime_type"`
	Extension    string `json:"extension"`
}

FileInfo 文件信息

type FileManager

type FileManager struct {
	// 基础上传目录
	BaseDir string
	// 基础URL前缀
	BaseURL string
	// 默认文件字段配置
	DefaultMaxSize int64
	// 默认允许的文件类型
	DefaultAllowedTypes []string
	// 默认文件名生成器
	DefaultNameGenerator func(originalName string) string
}

FileManager 文件管理器

func (*FileManager) ProcessFileField

func (fm *FileManager) ProcessFileField(ctx *ServiceContext, field *FileField) (any, error)

ProcessFileField 处理单个文件字段

func (*FileManager) ProcessFiles

func (fm *FileManager) ProcessFiles(ctx *ServiceContext, fields ...*FileField) (map[string]any, error)

ProcessFiles 处理多个文件字段

func (*FileManager) ProcessMultipleFilesFromArrayFormat

func (fm *FileManager) ProcessMultipleFilesFromArrayFormat(ctx *ServiceContext, field *FileField) ([]*FileInfo, error)

ProcessMultipleFilesFromArrayFormat 处理数组格式的多文件（如 ads[0], ads[1], ads[2]）

type FileTag

type FileTag struct {
	// 字段名
	FieldName string
	// 是否必需
	Required bool
	// 最大大小
	MaxSize int64
	// 允许的类型
	AllowedTypes []string
	// 保存目录
	SaveDir string
	// 是否多文件
	Multiple bool
	// 最大数量
	MaxCount int
}

FileTag 文件标签

func ParseFileTag

func ParseFileTag(tag reflect.StructTag) *FileTag

ParseFileTag 解析文件标签

func (*FileTag) ToFileField

func (ft *FileTag) ToFileField() *FileField

ToFileField 转换为FileField

type Response

type Response struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

Response 统一响应结构

type RouterGroup

type RouterGroup struct {
	*gin.RouterGroup
	Handler *ServiceHandler
}

RouterGroup 路由组封装

func WrapRouter

func WrapRouter(rg *gin.RouterGroup, handler ...*ServiceHandler) *RouterGroup

WrapRouter 包装路由组

func (*RouterGroup) DELETE

func (rg *RouterGroup) DELETE(path string, handler any) *RouterGroup

DELETE 处理DELETE请求

func (*RouterGroup) GET

func (rg *RouterGroup) GET(path string, handler any) *RouterGroup

GET 处理GET请求

func (*RouterGroup) POST

func (rg *RouterGroup) POST(path string, handler any) *RouterGroup

POST 处理POST请求

func (*RouterGroup) PUT

func (rg *RouterGroup) PUT(path string, handler any) *RouterGroup

PUT 处理PUT请求

type ServiceContext

type ServiceContext struct {
	context.Context
	GinContext *gin.Context
	// 可扩展字段
	UserID   uint
	TenantID string
	Metadata map[string]any
}

ServiceContext 自定义服务上下文

type ServiceHandler

type ServiceHandler struct {
	// 上下文工厂（可定制）
	ContextFactory func(*gin.Context) *ServiceContext
	// 请求绑定器（可定制）
	Binder func(*ServiceContext, any) error
	// 响应处理器（可定制）
	ResponseHandler func(*ServiceContext, any, error)
	// 错误处理器（可定制）
	ErrorHandler func(*ServiceContext, error)
	// 文件处理器
	FileHandler *FileManager
}

ServiceHandler 服务处理器配置