GinX

gin框架轻量级封装

1. Golang版本要求

go.version >= 1.24.0

2. 设计目标

• 三方库轻量封装，开箱即用
• 集成系统可观测性组件:
  • log
  • trace
  • metrics (本期暂未集成，后续待补充)
• 集成其它通用组件:
  • gin-swagger
  • 参数校验，参数错误时，错误信息的中文翻译

3. GinX使用

3.1 相关文档

GinX是对gin的轻量级封装，因此可以直接参考gin官方文档

• gin中文文档
• gin参数绑定 & 校验器 & 错误信息翻译
• gin-swagger

3.2 gin-swagger使用步骤

1. 安装swag: go install github.com/swaggo/swag/cmd/swag@latest
2. 在Handler上加上swagger的注释文档
3. 执行swag init生成docs.go
4. import "${你的项目}/docs" 将swagger信息注册到web应用中，建议参考3.3.3的demo用法

3.3 使用demo

3.3.1 方式一: 获取*gin.Engine再运行

package main

import (
	"net/http"

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

func main() {
	// 获取到*gin.Engine()，封装了一下log，trace等middleware
	engine := ginx.New().Engine()

	// 后续直接操作gin
	engine.GET("/ping", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "pong",
		})
	})
	engine.Run()
}

3.3.2 方式二: 通过ginx直接运行

package main

import (
	"net/http"

	"github.com/xiaoshicae/ginx"
	"github.com/xiaoshicae/ginx/options"

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

func main() {
	// 详细参数参数方式三
	gx := ginx.New(options.Addr("0.0.0.0:9000")).WithRouteRegister(MyRouteRegister)
	// 直接操作通过gx运行服务
	if err := gx.Run(); err != nil {
		panic(err)
	}
}

func MyRouteRegister(engine *gin.Engine) {
	engine.GET("/ping", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "pong",
		})
	})
}

3.3.3 方式三(推荐): 通过XOne运行

• 第一步: 配置

Server:
  Name: "a.b.c"      # 服务名称(required)，log/trace都会需要这个配置
  Version: "v2.0.0"  # 服务版本号(optional default "v0.0.1")，trace上报，swagger版本显示等需要使用该配置

  Gin: # gin相关配置(optional default nil)
    Host: "0.0.0.0"    # 服务监听host(optional default "0.0.0.0")
    Port: 9000         # 服务端口号(optional default 8080)
    UseHttp2: false    # 是否使用http2协议(optional default false)

    # 具体参数含义请参考: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#%E9%80%9A%E7%94%A8api%E4%BF%A1%E6%81%AF
    GinSwagger: # gin-swagger管理后台相关配置(optional default nil)
      Host: "https://xxx.xxx"       # 提供api服务的host(optional default nil)
      BasePath: "/api/v1"           # 公共url前缀(optional default nil)
      Title: "API接口文档"           # 标题(optional default nil)
      Description: "xxx"            # 描述信息(optional default nil)

• 第二步: 通过xone.RunGin(*gin.Engine)启动服务

package main

import (
	"fmt"
	"net/http"

	"your_project/docs" // 你的当前项目gin-swagger生成的文件

	"github.com/gin-gonic/gin"
	"github.com/xiaoshicae/ginx"
	"github.com/xiaoshicae/ginx/options"
	"github.com/xiaoshicae/xone"
)

func main() {

	engine := ginx.New(
		options.EnableLogMiddleware(false),   // log middle，默认启用
		options.EnableTraceMiddleware(false), // trace middle，默认启用
		options.EnableZHTranslations(false),  // gin参数绑定&校验错误的中文翻译器，默认不启用
	).
		// 支持swagger，及swagger管理后台url前缀配置
		// 即最终的访问url为: /openapi-demo/v4/swagger/index.html
		WithSwagger(docs.SwaggerInfo, options.WithSwaggerUrlPrefix("/openapi-demo/v4")).
		// 发生panic时，recover后的处理函数(gin默认时设置http_status_code=500)
		WithRecoverFunc(MyRecoverFunc).
		// 全局的自定义middleware配置
		WithMiddleware(MyMiddleware()).
		// 路由注入函数(签名: func(*gin.Engine) )
		WithRouteRegister(MyRouteRegister).
		// 获取*gin.Engine
		Engine()

	// 通过xone.RunGin()运行gin服务，可以直接解析相应的配置文件，并运行xone的hook
	xone.RunGin(engine)
}

func MyRecoverFunc(c *gin.Context, err interface{}) {
	c.JSON(http.StatusOK, gin.H{"err_code": 900, "err_msg": fmt.Sprintf("%v", err)})
}

func MyRouteRegister(engine *gin.Engine) {
	engine.GET("/demo", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"msg": "hello"})
	})
}

func MyMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		// before do something ...
		c.Next()
		// after do something ...
	}
}

4. 中间件配置

4.1 日志中间件配置

日志中间件支持配置跳过指定路由的日志记录，适用于健康检查等高频接口：

import (
    "github.com/xiaoshicae/ginx"
    "github.com/xiaoshicae/ginx/options"
)

engine := ginx.New(
    options.LogSkipPaths("/health", "/metrics", "/ping"),      // 精确匹配
    options.LogSkipPaths("/api/internal/"),                    // 前缀匹配（以 / 结尾）
).Engine()

匹配规则：

配置	路径	是否跳过
/health	/health	✓
/health	/health/live	✗
/health/	/health/live	✓

4.2 敏感字段配置

日志中间件默认过滤常见敏感字段（password、token、secret等），支持自定义添加：

import "github.com/xiaoshicae/ginx/middleware"

// 添加自定义敏感字段（request body）
middleware.AddSensitiveFields("my_secret", "private_key")

// 添加自定义敏感头（request/response header）
middleware.AddSensitiveHeaders("X-My-Secret")

5. 其它

• gin需要关注的并发问题

  *gin.Context在Goroutine之间传递时存在并发问题，因此需要c.Copy() 进行传递，ctx建议使用c.Request.Context()

• gin mode: 如果设置 GIN_MODE，则遵循 gin 自身模式；否则读取 SERVER_ENABLE_DEBUG（true/1/t/yes/y/on -> Debug，其它 -> Release）

6. TODO

• 集成 metrics middleware

7. Change Log

• 2026-1-04 v0.0.1 初始版本
• 2026-1-04 v0.0.2 升级依赖
• 2026-1-04 v0.0.3 支持gin mode
• 2026-1-04 v0.0.4 log新增敏感字段加密
• 2026-1-24 v1.0.0 代码优化重构，补充单元测试(覆盖率89.2%)
• 2026-1-25 v1.0.1 FuncMapKey 常量迁移到 xone 包统一管理
• 2026-1-25 v1.0.2 引入xone，用xone的常量替换硬编码
• 2026-1-26 v1.0.3 优化日志中间件：response header敏感过滤、换行符处理、文件上传跳过body记录、body读取后重新包装
• 2026-1-26 v1.0.4 response header 增加x-trace-id返回
• 2026-1-26 v1.0.5 fix response header x-trace-id返回
• 2026-1-26 v1.0.6 升级xone，fix response header x-trace-id返回
• 2026-1-26 v1.0.7 日志中间件支持配置跳过指定路由