ginx

package
v1.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 15 Imported by: 0

README

ginx Web 服务封装包

基于 gin 的 Web 服务封装:以配置声明服务参数(监听地址、运行模式、超时、TLS 证书、优雅停机等)一键启动 HTTP / HTTPS 服务,配合集中式路由注册管理——路由注册用法与 gin 完全一致(分组、多 handler 依次执行、嵌套分组),但统一进入 ginx 注册表,由本包在启动时校验并注册,减少在业务代码中持续管理路由与服务器的工作。

特性

  • gin 原生注册体验:Group 提供与 gin.RouterGroup 一致的便捷方法(GET / POST / Any / 嵌套 Group),一条路由可传多个 handler 依次执行,业务代码零学习成本
  • 统一响应渲染:Render 一行收尾——err 为 nil 渲染成功,errcode.BizError 按 HTTPStatus() 映射状态码与业务码,其他错误 500 且不泄露内部细节;RenderOK / RenderError 便捷入口
  • 分页助手:BindPage 绑定并归一化 page / size,RenderPage 输出 {list,total,page,size}(空页渲染 [] 而非 null),与 database.Paginate scope 一行配合
  • 请求绑定辅助:Bind / BindJSON / BindQuery / BindForm / BindURI 一行完成绑定 + validator 校验 + 失败自动 400 统一格式响应({"code":10400,"msg":"...","data":null}),免去每个 handler 重复编写绑定错误处理
  • 双探活:存活 /healthz(进程活着即 200)与就绪 /readyz(SetReadyChecker 检查通过才 200)分离,均经配置可改路径或关闭
  • 停机排空:收到退出信号后 readiness 自动 503 引导 LB 摘流,drain_delay 留出摘流窗口,OnDrain 钩子通知注册中心摘除实例,之后才断开在途连接
  • 内置 CORS:配置 cors 节点即启用跨域中间件(origins / methods / headers / credentials / max_age),allow_credentials 与 "*" 互斥在启动时校验;实现位于 middleware 子包,每个中间件独立一个文件,亦可用于原生 gin
  • 内置限流:配置 rate_limit 节点即启用固定窗口限流(按客户端 IP,limit / window,可经 KeyFunc 自定义限流键),超限返回 429 与 Retry-After
  • 链路追踪:配置 trace_id 节点即启用 TraceID 中间件——读取/生成 trace id(默认 X-Request-Id 请求头),写入 context 与响应头,TraceIDField 配合 logger 按请求聚合日志;需要分布式 tracing(span / 跨服务传递 / OTLP 导出)时改用 trace 包,其 otel trace id 桥接同一套约定
  • 可观测端点:配置 telemetry 节点按需挂载 /metrics(Prometheus 指标采集中间件 + 抓取端点)与 /debug/pprof(运行时剖析);指标名前缀(namespace)与耗时直方图分桶(buckets)可配
  • 可定制 Recovery:RecoveryWriter 注入自定义 panic 日志输出(如 logger.L,zap 核心实现了 io.Writer),默认 os.Stderr
  • 集中式注册表:所有声明统一进入 ginx 注册表,启动时统一注册;方法合法性、路径非空、处理链非空、重复注册(同方法同路径)快速失败,gin 注册期 panic(如 /:id 与 /:name 参数冲突)同样转为错误返回
  • 配置化启动:监听地址 / gin 模式 / http.Server 超时 / 优雅停机全部来自 Gin 配置,未设置自动填充默认值
  • HTTPS:cert_file / key_file 成对配置即启用 HTTPS,证书问题在启动时暴露
  • 优雅停机:SIGINT / SIGTERM 或 Stop() 触发:readiness 置否(503)→ OnDrain 钩子 → 等待 drain_delay → 按 ShutdownTimeout 等待在途请求完成后退出
  • 内置 panic 恢复:始终注入 gin.Recovery(),用户中间件在其后生效
  • 零侵入兼容:Engine() / Build() 暴露原生 gin 引擎,gin 生态中间件与 httptest 均可直用

目录结构

ginx/
├── gin.go      核心包: Gin 配置(含 TLS/CORS/双探活/停机排空)、引擎构建、HTTP/HTTPS 启动与优雅停机
├── route.go    路由管理: Group 分组注册、Router 模块收集、启动时统一校验注册
├── render.go   统一响应渲染: Response 结构、Render/RenderOK/RenderError
├── page.go     分页助手: Page/BindPage/PageResult/RenderPage
├── ready.go    就绪状态: SetReadyChecker/Ready 与停机排空联动
├── bind.go     请求绑定: Bind 系列辅助(绑定 + 校验 + 失败统一 400 响应)
├── middleware/ 内置中间件子包: 每个中间件独立一个文件, 亦可用于原生 gin
│   ├── cors.go      CORS 跨域中间件
│   ├── ratelimit.go 固定窗口限流中间件
│   ├── traceid.go   链路追踪中间件(trace id 读取/生成/回写)
│   ├── binding.go   泛型绑定 handler 工厂与校验错误提取器
│   ├── telemetry.go 可观测端点(Prometheus 指标 + pprof)
│   └── doc.go       包级文档
└── doc.go      包级文档

快速开始

package main

import (
	"net/http"

	"gitee.com/usmos/basic-go/ginx"
	"github.com/gin-gonic/gin"
)

func main() {
	// 与 gin 一致的注册方式: 分组 + 多 handler 依次执行
	api := ginx.NewGroup("api/v1")
	api.GET("/users", listUsers)
	api.GET("/users/:id", auth, getUser) // 前置中间件 + 业务处理函数

	// 根分组可直接使用包级便捷函数
	ginx.GET("/ping", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"message": "pong"}) })

	r := &ginx.Gin{
		Host: "0.0.0.0",
		Port: 8080,
		// 超时等配置不设时自动使用默认值
		// CertFile: "cert.pem", KeyFile: "key.pem", // 成对设置时启用 HTTPS
	}
	if err := r.Run(); err != nil { // 阻塞, Ctrl+C / kill 优雅停机
		panic(err)
	}
}

// 请求绑定辅助: 绑定 + 校验 + 失败自动 400 统一格式响应, 失败直接 return
func login(c *gin.Context) {
	var req LoginRequest // `json:"..." binding:"required"` 标签生效
	if !ginx.BindJSON(c, &req) {
		return
	}
	c.JSON(http.StatusOK, gin.H{"user": req.Name})
}

模块化注册:业务模块实现 Router 接口,一行收集,注册代码与 gin 用法完全一致:

type UserRouter struct{}

func (UserRouter) Register(g *ginx.Group) {
	api := g.Group("api/v1", auth) // 嵌套分组: 继承前缀与父级中间件, auth 追加其后
	api.GET("/users", listUsers)
	api.GET("/users/:id", getUser)
}

func main() {
	ginx.Register(UserRouter{}) // 可收集任意多个模块
	// ... 启动同上
}

与 config 配合,从配置文件加载:

type Root struct {
	Server ginx.Gin `yaml:"server"`
}

var c Root
cfg, _ := config.New("yaml", config.WithFile("config.yaml"))
_ = cfg.UnmarshalWithDefault(&c)
_ = c.Server.Run()

对应配置文件:

server:
  host: 0.0.0.0
  port: 8080
  mode: release             # debug/release/test(默认 release)
  cert_file: ""             # SSL 证书文件路径(PEM), 与 key_file 成对设置启用 HTTPS
  key_file: ""              # SSL 私钥文件路径(PEM)
  health_check_path: /healthz # 存活检查路由(默认 /healthz, 设为 "-" 关闭)
  ready_check_path: /readyz   # 就绪检查路由(默认 /readyz, 设为 "-" 关闭)
  drain_delay: 3s             # readiness 置否后留给 LB 摘流的等待时长(默认 0 不等待, 但仍置否)
  trace_id:                   # 配置本节点即启用 TraceID 中间件(省略则关闭)
    header: X-Request-Id      # 读取/回写 trace id 的请求头(默认 X-Request-Id)
  telemetry:                  # 可观测端点(省略则关闭)
    metrics: true             # 挂载 /metrics 并注入指标采集中间件
    metrics_path: /metrics    # 指标抓取端点(默认 /metrics)
    namespace: ""             # 指标名前缀(默认空; 多服务共用 Prometheus 时设为服务名)
    buckets: [0.005, 0.01, 0.05, 0.1, 0.5, 1, 5] # 耗时直方图分桶(秒, 默认 DefBuckets)
    pprof: true               # 挂载 /debug/pprof/* 剖析端点(生产建议置于内网或叠加鉴权)
    pprof_prefix: /debug/pprof # pprof 端点前缀(默认 /debug/pprof)
  cors:                     # 配置本节点即启用跨域支持(省略则关闭)
    allow_origins:          # 允许的源, "*" 匹配全部(默认 *)
      - "https://example.com"
    allow_credentials: true  # 允许携带凭证, 不可与 "*" 同时使用(启动时校验)
    max_age: 12h             # 预检结果缓存时长(默认 12h)
  rate_limit:               # 配置本节点即启用限流(省略则关闭)
    limit: 100              # 单个客户端每个窗口内允许的最大请求数(默认 100)
    window: 1s              # 统计时间窗口(默认 1s)
  read_header_timeout: 10s   # 读请求头超时(默认 10s, 可省略)
  read_timeout: 30s         # 读超时, 含请求体(默认 30s, 可省略)
  write_timeout: 30s        # 写超时(默认 30s, 可省略)
  idle_timeout: 60s          # keep-alive 空闲超时(默认 60s, 可省略)
  max_header_bytes: 0       # 请求头最大字节数(0 = http 默认 1MB)
  shutdown_timeout: 5s      # 优雅停机最大等待(默认 5s, 可省略)

统一响应渲染

Response 为统一响应结构:{"code":0,"msg":"ok","data":...},code 0 表示成功,错误码约定见 errcode(render.go):

方法 说明
Render(c, err, data) 业务 handler 的统一收尾,映射规则见下表
RenderOK(c, data) 成功响应便捷入口:200 {"code":0,"msg":"ok","data":...}
RenderError(c, err) 错误响应便捷入口,映射规则同 Render

Render 的错误映射:

err 响应
nil 200 {"code":0,"msg":"ok","data":...}
*errcode.BizError 按 HTTPStatus() 映射,如 errcode.ErrNotFound → 404 {"code":10404,"msg":"资源不存在","data":null}
其他错误 500 {"code":10500,"msg":"内部错误","data":null};原始错误经 c.Error 附加(供日志/追踪取用),不会泄露给客户端
func getUser(c *gin.Context) {
	user, err := repo.Get(c.Param("id"))
	ginx.Render(c, err, user) // 一行收尾: 成功 200 / ErrNotFound 404 / 其他错误 500
}

func deleteUser(c *gin.Context) {
	if !isAdmin(c) {
		ginx.RenderError(c, errcode.ErrForbidden) // 403 {"code":10403,"msg":"无权限","data":null}
		return
	}
	ginx.Render(c, doDelete(c.Param("id")), nil)
}

分页助手

Page 从查询参数绑定 page / size,BindPage 绑定并归一化(page<=0 → 1;size<=0 → 20;size>100 → 100;非数字等非法参数容错为默认页),归一化约定与 database.Paginate scope 保持一致(page.go):

方法 / 类型 说明
Page 分页请求参数(form 标签绑定 page / size)
BindPage(c) 从查询参数绑定并归一化,返回 Page
Page.Offset() 当前页的 SQL 偏移量 (page-1)*size
PageResult[T] 分页响应结构 {list,total,page,size},空列表渲染 [] 而非 null
RenderPage(c, err, p, list, total) 分页统一渲染:err 非 nil 时按 Render 的映射规则渲染错误

与 database 的 Paginate scope 配合(Count + Scopes + Find):

func listUsers(c *gin.Context) {
	page := ginx.BindPage(c) // page/size 已归一化
	var (
		total int64
		users []User
	)
	if err := database.DB().Model(&User{}).Count(&total).Error; err != nil {
		ginx.Render(c, err, nil)
		return
	}
	err := database.DB().
		Scopes(database.Paginate(page.Page, page.Size)).
		Find(&users).Error
	ginx.RenderPage(c, err, page, users, total) // {"list":[...],"total":N,"page":P,"size":S}
}

双探活与停机排空

存活(liveness)与就绪(readiness)分离(ready.go):

端点 配置 语义
GET /healthz health_check_path(默认 /healthz,- 关闭) 存活检查:进程活着即返回 200,不反映依赖健康状态
GET /readyz ready_check_path(默认 /readyz,- 关闭) 就绪检查:SetReadyChecker 检查通过返回 200,否则 503;停机排空阶段自动 503
// 业务初始化完成(数据库/缓存连通)后注入; 检查函数在每次探活时调用, 应快速返回
ginx.SetReadyChecker(func() bool {
	return database.DB() != nil
})
  • 未注入 SetReadyChecker 时实例视为始终就绪
  • ginx.Ready() 返回当前实例是否就绪:业务检查通过且未处于停机排空阶段

停机时序(Run 内部执行):

收到 SIGINT/SIGTERM 或 Stop()
  → readiness 置否(503, 引导 LB 摘流)
  → OnDrain 钩子(通知注册中心摘除本实例, panic 自动 recover)
  → 等待 drain_delay(留出 LB 摘流窗口, 默认 0 不等待, 但仍置否)
  → srv.Shutdown(按 shutdown_timeout 等待在途请求)
  → Run 返回

配置字段

连接与运行(Gin,见 gin.go):

字段 类型 说明
host string 监听地址(默认 0.0.0.0)
port int 监听端口(默认 8080)
mode string gin 运行模式 debug / release / test(默认 release)
cert_file string SSL 证书文件路径(PEM),与 key_file 成对设置时启用 HTTPS
key_file string SSL 私钥文件路径(PEM)
health_check_path string 存活检查路由路径(默认 /healthz,设为 - 关闭)
ready_check_path string 就绪检查路由路径(默认 /readyz,设为 - 关闭);经 SetReadyChecker 注入检查逻辑,停机排空阶段自动 503
cors *middleware.CORS 跨域配置,非空时启用内置 CORS 中间件(见下表)
rate_limit *middleware.RateLimit 限流配置,非空时启用内置限流中间件(见下表)
trace_id *middleware.TraceID 链路追踪配置,非空时启用内置 TraceID 中间件(见下表)
telemetry *middleware.Telemetry 可观测性端点配置,非空时按需挂载 /metrics 与 /debug/pprof(见下表)

CORS(middleware.CORS,见 middleware/cors.go):

字段 类型 说明
allow_origins []string 允许的源(协议+域名+端口),* 匹配全部(默认 *)
allow_methods []string 允许的方法(默认 GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS)
allow_headers []string 允许的请求头(默认 Origin/Content-Type/Accept/Authorization/X-Requested-With)
expose_headers []string 允许前端读取的响应头(可选)
allow_credentials bool 允许携带凭证(Cookie),不可与 * 源同时使用(启动时校验)
max_age time.Duration 预检结果缓存时长(默认 12h)

RateLimit(middleware.RateLimit,见 middleware/ratelimit.go):

字段 类型 说明
limit int 单个客户端每个时间窗口内允许的最大请求数(默认 100)
window time.Duration 统计时间窗口(默认 1s)
KeyFunc func(*gin.Context) string 限流键生成函数,返回相同键的请求共享同一配额(默认客户端 IP,可按用户 ID / API Key 限流);仅支持代码注入

TraceID(middleware.TraceID,见 middleware/traceid.go):

字段 类型 说明
header string 读取/回写 trace id 的请求头(默认 X-Request-Id)
Generator func() string trace id 生成函数(默认 crypto/rand 生成 32 位小写 hex,128 位随机);对接 uuid / OpenTelemetry 等既有体系时注入;仅支持代码注入

需要分布式 tracing 时改用 trace 包(otel span + W3C 跨服务传递 + OTLP 导出):其 trace id 同为 32 位 hex,经 SetTraceID 桥接后 TraceIDOf / TraceIDField 照常可用,trace_id 节点可省略。

Telemetry(middleware.Telemetry,见 middleware/telemetry.go):

字段 类型 说明
metrics bool 开启 Prometheus 指标:注入采集中间件并挂载抓取端点
metrics_path string 指标抓取端点路径(默认 /metrics)
namespace string 指标名前缀(默认空);多服务共用 Prometheus 时设为服务名,指标变为 <namespace>_http_request_duration_seconds;多实例并存以首个启用者为准
buckets []float64 耗时直方图分桶边界(秒,默认 prometheus.DefBuckets);按业务时延分布定制;多实例并存以首个启用者为准
pprof bool 挂载 pprof 剖析端点(heap / goroutine / mutex / cpu 等);生产环境建议置于内网或叠加鉴权
pprof_prefix string pprof 端点前缀(默认 /debug/pprof)

超时(Gin):

字段 类型 说明
read_header_timeout time.Duration 读请求头超时(默认 10s)
read_timeout time.Duration 读超时,含请求体(默认 30s)
write_timeout time.Duration 写超时(默认 30s)
idle_timeout time.Duration keep-alive 空闲超时(默认 60s)
max_header_bytes int 请求头最大字节数(0 = http 默认 1MB)
drain_delay time.Duration readiness 置否后留给 LB 摘流的等待时长(默认 0 不等待,但仍会置否)
shutdown_timeout time.Duration 优雅停机最大等待时间(默认 5s)

代码注入(Gin,不参与配置文件反序列化):

字段 类型 说明
Middlewares []gin.HandlerFunc 全局中间件,在内置中间件(Recovery / TraceID / Telemetry 采集 / CORS / 限流)之后注入
OnDrain func() 停机排空钩子:readiness 置否后、Shutdown 前同步调用,用于通知注册中心摘除本实例;panic 会被 recover
RecoveryWriter io.Writer panic 恢复日志输出,可注入 logger.L(zap 核心实现了 io.Writer),默认 os.Stderr

接口总览

服务(gin.go):

方法 说明
Gin.Addr() 生成监听地址 host:port
Gin.Build() 创建引擎并注册全部路由,不启动监听;注入全局引擎,适合配合 httptest 做集成测试
Gin.Run() 注册路由并启动 HTTP/HTTPS 服务,阻塞直至 SIGINT / SIGTERM / Stop();停机走排空时序(见双探活与停机排空),按 ShutdownTimeout 等待在途请求
Gin.Stop() 主动触发优雅停机,Run 随之返回;可重复调用
Engine() 获取全局 gin 引擎(Build / Run 之后可用)

路由(route.go):

方法 / 类型 说明
Group 路由分组:前缀 + 分组级中间件,注册方法与 gin.RouterGroup 一致
NewGroup(prefix, handlers...) 创建顶层分组挂入注册表
g.Group(prefix, handlers...) 嵌套子分组,继承父分组前缀与中间件
g.Handle / g.Any / g.GET / g.POST / g.PUT / g.DELETE / g.PATCH / g.HEAD / g.OPTIONS 分组路由注册,一条路由可传多个 handler 依次执行
Handle / Any / GET / POST / ...(包级) 根分组便捷注册,等价于 NewGroup("").XXX
Router 模块路由接口:Register(g *Group),实现后经 Register 收集
Register(routers...) 收集实现了 Router 的业务模块,Build / Run 时统一回调展开
Routes() 返回全部路由声明(平铺拷贝:Method / Path / Handlers),用于调试与文档生成
ClearRoutes() 清空路由注册表(测试用)

分组前缀与路由路径自动规范化:补全前导 /、去除尾部 /;前缀为空表示根分组。

统一响应渲染(render.go):

方法 / 类型 说明
Response 统一响应结构 {code, msg, data},code 0 表示成功
Render(c, err, data) 统一收尾:nil → 200 成功;*errcode.BizError → 按 HTTPStatus() 映射;其他错误 → 500,原始错误经 c.Error 附加不泄露给客户端
RenderOK(c, data) 成功响应便捷入口
RenderError(c, err) 错误响应便捷入口,映射规则同 Render

分页(page.go):

方法 / 类型 说明
BindPage(c) 从查询参数绑定 page / size 并归一化(page<=0→1,size<=0→20,size>100→100,非法参数容错为默认页)
Page.Offset() 当前页的 SQL 偏移量 (page-1)*size
PageResult[T] 分页响应结构 {list,total,page,size},空列表渲染 [] 而非 null
RenderPage(c, err, p, list, total) 分页统一渲染:err 非 nil 按 Render 映射渲染错误

就绪状态(ready.go):

方法 说明
SetReadyChecker(fn) 注入就绪检查函数,就绪端点据此返回 200/503;未注入视为始终就绪
Ready() 当前实例是否就绪:业务检查通过且未处于停机排空阶段

请求绑定(bind.go,绑定 + validator 校验 + 失败自动 400 响应):

方法 说明
Bind(c, obj) 依据 Content-Type 自动选择绑定器(JSON / 表单等)
BindJSON(c, obj) 绑定 JSON 请求体(json / binding 标签)
BindQuery(c, obj) 绑定 URL 查询参数(form 标签)
BindForm(c, obj) 绑定表单请求体(form 标签)
BindURI(c, obj) 绑定路径参数(uri 标签)

失败响应格式为统一格式 {"code":10400,"msg":"<提取后的校验错误>","data":null},与 errcode 及 middleware.Bind 泛型工厂共用 ExtractValidationError 提取器——默认把 validator 校验错误转为「字段 规则[=参数]」列表(如 Name required; Age min=18),可经 SetValidationErrorExtractor 替换(如对接 i18n)。

中间件(middleware 子包,每个中间件独立一个文件,亦可用于原生 gin):

类型 / 方法 说明
middleware.CORS 跨域配置结构体(带 yaml / toml / json / mapstructure 标签),经 Gin.CORS 配置启用
CORS.Handler() 构建跨域中间件(内部填充默认值并校验配置);ginx 自动注入,亦可在原生 gin 中 e.Use 使用
middleware.RateLimit 限流配置结构体(带 yaml / toml / json / mapstructure 标签),经 Gin.RateLimit 配置启用
RateLimit.Handler() 构建固定窗口限流中间件(内部填充默认值,超限返回 429 与 Retry-After);ginx 自动注入,亦可在原生 gin 中 e.Use 使用
middleware.TraceID 链路追踪配置结构体(带 yaml / toml / json / mapstructure 标签),经 Gin.TraceID 配置启用
TraceID.Handler() 构建追踪中间件:读取上游请求头(默认 X-Request-Id)携带的 trace id,缺失时经 crypto/rand 生成 32 位 hex,写入 gin context 并回写响应头
SetTraceID(c, id) 注入 trace id 到当前请求,供 trace 包等外部追踪实现桥接:写入后 TraceIDOf / TraceIDField 无感知生效
TraceIDOf(c) / TraceIDField(c) 读取当前请求的 trace id / 返回携带 trace_id 的 zap.Field,配合 logger 聚合同一请求的日志
middleware.Bind / BindJSON / BindQuery / BindURI 泛型绑定 handler 工厂:Bind[T](fn) 返回 func(c *gin.Context, req *T) gin.HandlerFunc,绑定/校验失败统一 400(响应格式与 ginx.Bind 系列一致)
ExtractValidationError / SetValidationErrorExtractor 校验错误信息提取器及替换入口,ginx.Bind 系列与 middleware.Bind 系列共用
middleware.Telemetry 可观测性端点配置结构体(带 yaml / toml / json / mapstructure 标签),经 Gin.Telemetry 配置启用
Telemetry.Handler() 指标采集中间件:记录每请求的耗时与总数(标签为 method / 路由模板 path / status);仅 metrics 开启时由 ginx 注入
Telemetry.Mount(e) 挂载 /metrics 与 /debug/pprof/* 端点,与业务路由冲突时返回错误而非 panic

ginx 内置中间件顺序:Recovery → TraceID → Telemetry 采集 → CORS → RateLimit → 用户中间件(Middlewares);trace id 尽量前置保证 429 / 5xx 等短路响应可被追踪,指标采集先于跨域/限流使预检与 429 同样计入指标。

注意事项

  • 先注册后启动:路由注册须在 Run / Build 之前完成(与 gin 一致,注册阶段非并发安全),启动后注册表不再生效
  • 快速失败:方法不合法、路径为空、处理链为空、同一方法+路径重复注册、gin 参数冲突均导致启动返回错误,问题在启动时全部暴露
  • HTTPS:cert_file / key_file 须成对配置,仅设置其一启动即报错;证书文件不可用(路径错误/格式非法)在启动监听时暴露
  • 优雅停机:SIGINT / SIGTERM 信号或 Stop() 等价触发,先 readiness 置否(503)→ OnDrain → 等待 drain_delay 再 Shutdown;等待超过 ShutdownTimeout 时 Run 返回停机错误
  • 双探活:/healthz 只反映进程存活,依赖健康状态请用 /readyz + SetReadyChecker;检查函数在每次探活时调用,应快速返回,慢检查会拖累 LB / 探活的重试节奏
  • 内部错误不外泄:Render 对非 BizError 一律 500 + 通用文案,原始错误经 c.Error 附加供日志取用
  • pprof 安全:telemetry.pprof 会暴露运行时细节,生产环境建议仅内网开启或叠加鉴权中间件
  • 限流语义:固定窗口算法在窗口边界可能出现最多 2 倍的短暂突发;默认按客户端 IP 统计(gin 的 ClientIP 受可信代理配置影响),更复杂的限流需求可经 KeyFunc 或 Middlewares 自行扩展
  • 全局 gin 模式:gin.SetMode 为 gin 包全局状态,多实例场景以最后一次 Build 为准
  • 测试:用 Build() 获取引擎后配合 httptest.PerformRequest 直接测试路由,无需真实监听端口

Documentation

Overview

Package ginx 提供基于 gin 的 Web 服务封装:配置化启动 HTTP/HTTPS 服务与集中式路由管理。

设计目标: 用户以配置(结构体/配置文件)声明服务参数, 以与 gin 用法一致的方式声明路由 (Group 提供与 gin.RouterGroup 相同的便捷方法, 一条路由可传多个 handler 依次执行), 由本包在启动时统一校验(方法/路径/处理链/重复注册)并注册进 gin 引擎, 随后启动服务 并支持优雅停机, 减少在业务代码中持续管理路由与服务器的工作。

内置常用能力: Bind 系列请求绑定辅助(绑定+校验+失败按 errcode 约定自动 400 响应)、 Render/RenderPage 统一响应渲染(配合 errcode 自动映射 4xx/5xx)、 Page/PageResult 分页助手、 存活/就绪双探活(health_check_path 默认 /healthz; ready_check_path 默认 /readyz, 就绪状态经 SetReadyChecker 注入, 停机排空阶段自动 503)、 TraceID 链路追踪与 Telemetry 可观测端点(/metrics 与 /debug/pprof, 见 middleware 子包)、 CORS 跨域与固定窗口限流中间件(cors / rate_limit 配置节点, 实现位于 middleware 子包)、 停机排空(drain_delay 等待 LB 摘流 + OnDrain 摘除钩子)、 HTTPS 证书配置(cert_file/key_file)与 panic 恢复输出定制(RecoveryWriter)。

使用示例:

// 与 gin 一致的路由注册: 分组 + 多 handler 依次执行
api := ginx.NewGroup("api/v1")
api.GET("/users", listUsers)
api.GET("/users/:id", auth, getUser) // 前置中间件 + 业务处理函数

r := &ginx.Gin{
	Host: "0.0.0.0",
	Port: 8080,
	// CertFile/KeyFile 成对设置时启用 HTTPS
}
if err := r.Run(); err != nil { // 阻塞, Ctrl+C / kill 优雅停机
	panic(err)
}

// 请求绑定辅助: 绑定 + 校验 + 失败自动 400 响应
var req LoginRequest
if !ginx.BindJSON(c, &req) {
	return
}

本包未封装的高级用法通过 Engine() 获取原生 gin 引擎完成。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Any

func Any(path string, handlers ...gin.HandlerFunc)

Any 在根分组注册路由到全部支持的 HTTP 方法, 见 Group.Any。

func Bind

func Bind(c *gin.Context, obj any) bool

Bind 依据 Content-Type 自动绑定请求参数到 obj 并完成校验(binding/validator 标签), 兼容 JSON / 表单等常见格式。

绑定/校验失败时自动写入 400 响应并返回 false, 业务代码仅需在失败时直接 return, 免去每个 handler 重复编写绑定错误处理:

var req LoginRequest
if !ginx.Bind(c, &req) {
	return
}

func BindForm

func BindForm(c *gin.Context, obj any) bool

BindForm 绑定表单请求体到 obj(form 标签)并完成校验, 见 Bind。

func BindJSON

func BindJSON(c *gin.Context, obj any) bool

BindJSON 绑定 JSON 请求体到 obj 并完成校验, 见 Bind。

func BindQuery

func BindQuery(c *gin.Context, obj any) bool

BindQuery 绑定 URL 查询参数到 obj(form 标签)并完成校验, 见 Bind。

func BindURI

func BindURI(c *gin.Context, obj any) bool

BindURI 绑定路径参数到 obj(uri 标签)并完成校验, 见 Bind。

func ClearRoutes

func ClearRoutes()

ClearRoutes 清空全局路由注册表与已收集的模块(主要用于测试)。

func DELETE

func DELETE(path string, handlers ...gin.HandlerFunc)

DELETE 在根分组注册 DELETE 路由, 见 Group.DELETE。

func Engine

func Engine() *gin.Engine

Engine 获取全局 gin 引擎, 用于本包未封装的高级用法; Build/Run 之前为 nil。

func GET

func GET(path string, handlers ...gin.HandlerFunc)

GET 在根分组注册 GET 路由, 见 Group.GET。

func HEAD(path string, handlers ...gin.HandlerFunc)

HEAD 在根分组注册 HEAD 路由, 见 Group.HEAD。

func Handle

func Handle(method, path string, handlers ...gin.HandlerFunc)

Handle 在根分组注册路由, 见 Group.Handle。

func OPTIONS

func OPTIONS(path string, handlers ...gin.HandlerFunc)

OPTIONS 在根分组注册 OPTIONS 路由, 见 Group.OPTIONS。

func PATCH

func PATCH(path string, handlers ...gin.HandlerFunc)

PATCH 在根分组注册 PATCH 路由, 见 Group.PATCH。

func POST

func POST(path string, handlers ...gin.HandlerFunc)

POST 在根分组注册 POST 路由, 见 Group.POST。

func PUT

func PUT(path string, handlers ...gin.HandlerFunc)

PUT 在根分组注册 PUT 路由, 见 Group.PUT。

func Ready added in v1.0.4

func Ready() bool

Ready 返回当前实例是否就绪: 业务检查通过且未处于停机排空阶段。

func Register

func Register(rs ...Router)

Register 收集实现了 Router 的业务模块, 在 Build/Run 时统一回调展开。 各模块在自身初始化时调用即可, 无需关心注册顺序与引擎创建过程。

func Render added in v1.0.4

func Render(c *gin.Context, err error, data any)

Render 统一响应渲染, 业务 handler 的收尾动作:

err 为 nil → 200 {"code":0,"msg":"ok","data":...}
err 为 *errcode.BizError → 按 HTTPStatus() 映射, 如 errcode.ErrNotFound
                          输出 404 {"code":10404,"msg":"资源不存在","data":null}
其他错误 → 500 {"code":10500,"msg":"内部错误","data":null},
          原始错误经 c.Error 附加, 不会泄露给客户端

func getUser(c *gin.Context) {
	user, err := repo.Get(c.Param("id"))
	ginx.Render(c, err, user)
}

func RenderError added in v1.0.4

func RenderError(c *gin.Context, err error)

RenderError 渲染错误响应, 映射规则同 Render, 语义更显式的便捷入口。

func RenderOK added in v1.0.4

func RenderOK(c *gin.Context, data any)

RenderOK 渲染成功响应: 200 {"code":0,"msg":"ok","data":...}。 已通过 Render(c, nil, data) 覆盖, 需要显式语义时直接使用。

func RenderPage added in v1.0.4

func RenderPage[T any](c *gin.Context, err error, p Page, list []T, total int64)

RenderPage 分页统一渲染: err 非 nil 时按 Render 的映射规则渲染错误; 成功时输出 {"list":[...],"total":N,"page":P,"size":S}。

func SetReadyChecker added in v1.0.4

func SetReadyChecker(fn func() bool)

SetReadyChecker 注入就绪检查函数, 就绪端点(默认 /readyz)据此返回 200/503。 通常在业务初始化完成(数据库/缓存连通)后注入; 检查函数在每次探活时调用, 应快速返回, 慢检查会拖累 LB/探活的重试节奏。

未注入时实例视为始终就绪; 停机排空阶段(收到退出信号、等待 LB 摘流) 无论检查结果如何均返回未就绪, 引导流量先于连接关闭摘除本实例。

Types

type Gin

type Gin struct {
	Host string `yaml:"host" toml:"host" json:"host" mapstructure:"host"` // 监听地址
	Port int    `yaml:"port" toml:"port" json:"port" mapstructure:"port"` // 监听端口

	Mode string `yaml:"mode" toml:"mode" json:"mode" mapstructure:"mode"` // gin 运行模式: debug/release/test(空时默认 release)

	// TLS/HTTPS 配置: cert_file 与 key_file 成对设置时启用 HTTPS
	CertFile string `yaml:"cert_file" toml:"cert_file" json:"cert_file" mapstructure:"cert_file"` // SSL 证书文件路径(PEM)
	KeyFile  string `yaml:"key_file" toml:"key_file" json:"key_file" mapstructure:"key_file"`     // SSL 私钥文件路径(PEM)

	// HealthCheckPath 存活检查路由路径(默认 /healthz, 设为 "-" 关闭):
	// 进程存活即返回 200, 不反映依赖健康状态
	HealthCheckPath string `yaml:"health_check_path" toml:"health_check_path" json:"health_check_path" mapstructure:"health_check_path"`

	// ReadyCheckPath 就绪检查路由路径(默认 /readyz, 设为 "-" 关闭):
	// 就绪(SetReadyChecker 检查通过)返回 200, 否则 503;
	// 停机排空阶段自动返回 503, 引导 LB 先摘流再停机
	ReadyCheckPath string `yaml:"ready_check_path" toml:"ready_check_path" json:"ready_check_path" mapstructure:"ready_check_path"`

	// CORS 跨域配置, 非 nil 时启用内置跨域中间件(见 middleware 子包)
	CORS *middleware.CORS `yaml:"cors" toml:"cors" json:"cors" mapstructure:"cors"`

	// RateLimit 限流配置, 非 nil 时启用内置限流中间件(见 middleware 子包)
	RateLimit *middleware.RateLimit `yaml:"rate_limit" toml:"rate_limit" json:"rate_limit" mapstructure:"rate_limit"`

	// TraceID 链路追踪配置, 非 nil 时启用内置 trace id 中间件(见 middleware 子包)
	TraceID *middleware.TraceID `yaml:"trace_id" toml:"trace_id" json:"trace_id" mapstructure:"trace_id"`

	// Telemetry 可观测性端点配置, 非 nil 时按需挂载 /metrics 与 /debug/pprof(见 middleware 子包)
	Telemetry *middleware.Telemetry `yaml:"telemetry" toml:"telemetry" json:"telemetry" mapstructure:"telemetry"`

	// RecoveryWriter panic 恢复日志输出(默认 os.Stderr),
	// 可注入日志对象(如 logger.L 的 zap 核心实现了 io.Writer); 仅支持代码注入
	RecoveryWriter io.Writer `yaml:"-" toml:"-" json:"-" mapstructure:"-"`

	// http.Server 超时配置
	ReadHeaderTimeout time.Duration `yaml:"read_header_timeout" toml:"read_header_timeout" json:"read_header_timeout" mapstructure:"read_header_timeout"` // 读请求头超时时间(<=0 时默认 10s)
	ReadTimeout       time.Duration `yaml:"read_timeout" toml:"read_timeout" json:"read_timeout" mapstructure:"read_timeout"`                             // 读超时时间, 含请求体(<=0 时默认 30s)
	WriteTimeout      time.Duration `yaml:"write_timeout" toml:"write_timeout" json:"write_timeout" mapstructure:"write_timeout"`                         // 写超时时间(<=0 时默认 30s)
	IdleTimeout       time.Duration `yaml:"idle_timeout" toml:"idle_timeout" json:"idle_timeout" mapstructure:"idle_timeout"`                             // keep-alive 空闲超时时间(<=0 时默认 60s)
	MaxHeaderBytes    int           `yaml:"max_header_bytes" toml:"max_header_bytes" json:"max_header_bytes" mapstructure:"max_header_bytes"`             // 请求头最大字节数(0 表示使用 http 默认 1MB)

	// 优雅停机
	ShutdownTimeout time.Duration `yaml:"shutdown_timeout" toml:"shutdown_timeout" json:"shutdown_timeout" mapstructure:"shutdown_timeout"` // 优雅停机最大等待时间(<=0 时默认 5s)

	// 停机排空: 收到退出信号后 readiness 先置否(503), 再执行排空动作,
	// 让 LB/探活先把流量摘到其他实例, 随后才 Shutdown 断开存量连接
	DrainDelay time.Duration `yaml:"drain_delay" toml:"drain_delay" json:"drain_delay" mapstructure:"drain_delay"` // readiness 置否后的等待时长, 留给 LB 摘流(<=0 不等待, 但仍会置否)
	OnDrain    func()        `yaml:"-" toml:"-" json:"-" mapstructure:"-"`                                         // 排空钩子: readiness 置否后、Shutdown 前同步调用, 用于通知注册中心摘除本实例; panic 会被 recover

	// Middlewares 全局中间件, 在内置中间件(Recovery/CORS/限流)之后注入
	// 仅支持代码注入, 不参与配置文件反序列化
	Middlewares []gin.HandlerFunc `yaml:"-" toml:"-" json:"-" mapstructure:"-"`
	// contains filtered or unexported fields
}

Gin gin 服务配置

func (*Gin) Addr

func (g *Gin) Addr() string

Addr 监听地址

func (*Gin) Build

func (g *Gin) Build() (*gin.Engine, error)

Build 创建 gin 引擎并注册全部已声明的路由, 不启动监听。 成功后注入全局引擎(Engine() 可获取), 适合集成测试中使用 httptest 直接调用引擎。

func (*Gin) Run

func (g *Gin) Run() error

Run 注册全部路由并启动 HTTP 服务, 阻塞直至收到 SIGINT/SIGTERM 或 Stop 被调用; 退出前按 ShutdownTimeout 等待处理中的请求完成后优雅停机。 返回 nil 表示正常停机, 否则为监听失败/停机超时等错误。

func (*Gin) Stop

func (g *Gin) Stop()

Stop 主动触发优雅停机, Run 随之返回。 可重复调用; 服务未运行时无效果。

type Group

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

Group 路由分组: 前缀与分组级中间件, 提供与 gin.RouterGroup 一致的便捷注册方法。

注册用法与 gin 完全一致(一条路由可传多个 handler, 依次执行; 支持嵌套分组), 业务代码零学习成本; 区别在于路由先集中进入 ginx 注册表, 由 Build/Run 时统一校验(方法/路径/处理链/重复注册)后注册进引擎。

路由注册须在 Build/Run 之前完成(与 gin 一致, 注册阶段非并发安全)。

func NewGroup

func NewGroup(prefix string, handlers ...gin.HandlerFunc) *Group

NewGroup 创建顶层路由分组并挂入全局注册表。 prefix 为分组前缀(如 "api/v1", 空表示根分组), handlers 为分组级中间件。

func (*Group) Any

func (g *Group) Any(path string, handlers ...gin.HandlerFunc)

Any 注册路由到全部支持的 HTTP 方法。

func (*Group) DELETE

func (g *Group) DELETE(path string, handlers ...gin.HandlerFunc)

DELETE 注册 DELETE 路由, 见 GET。

func (*Group) GET

func (g *Group) GET(path string, handlers ...gin.HandlerFunc)

GET 注册 GET 路由: handlers 依次执行, 最后一个通常为业务处理函数。

func (*Group) Group

func (g *Group) Group(prefix string, handlers ...gin.HandlerFunc) *Group

Group 创建嵌套子分组: 继承父分组的前缀与中间件, handlers 追加在父中间件之后。

func (*Group) HEAD

func (g *Group) HEAD(path string, handlers ...gin.HandlerFunc)

HEAD 注册 HEAD 路由, 见 GET。

func (*Group) Handle

func (g *Group) Handle(method, path string, handlers ...gin.HandlerFunc)

Handle 注册路由: method 为 HTTP 方法(大小写不敏感), handlers 依次执行(分组中间件在前), 最后一个通常为业务处理函数。

func (*Group) OPTIONS

func (g *Group) OPTIONS(path string, handlers ...gin.HandlerFunc)

OPTIONS 注册 OPTIONS 路由, 见 GET。

func (*Group) PATCH

func (g *Group) PATCH(path string, handlers ...gin.HandlerFunc)

PATCH 注册 PATCH 路由, 见 GET。

func (*Group) POST

func (g *Group) POST(path string, handlers ...gin.HandlerFunc)

POST 注册 POST 路由, 见 GET。

func (*Group) PUT

func (g *Group) PUT(path string, handlers ...gin.HandlerFunc)

PUT 注册 PUT 路由, 见 GET。

type Page added in v1.0.4

type Page struct {
	Page int `form:"page" json:"page"` // 页码, 从 1 开始
	Size int `form:"size" json:"size"` // 每页条数
}

Page 分页请求参数, 从 URL 查询参数绑定(page/size), 归一化约定: page 从 1 开始(<=0 按 1 计), size<=0 默认 20、超过 100 按 100 截断。

func BindPage added in v1.0.4

func BindPage(c *gin.Context) Page

BindPage 从查询参数绑定分页参数并归一化, 缺参/非法参数按默认值处理:

page := ginx.BindPage(c)
var users []User
database.DB().Model(&User{}).Count(&total)
database.DB().Scopes(database.Paginate(page.Page, page.Size)).Find(&users)
ginx.RenderPage(c, nil, page, users, total)

func (*Page) Normalize added in v1.0.4

func (p *Page) Normalize()

Normalize 归一化分页参数: page<=0 → 1; size<=0 → 20; size>100 → 100。

func (*Page) Offset added in v1.0.4

func (p *Page) Offset() int

Offset 当前页在 SQL 查询中的偏移量, 配合 database.Paginate 或手写 offset 时使用。

type PageResult added in v1.0.4

type PageResult[T any] struct {
	List  []T   `json:"list"`  // 当前页数据; 空页渲染为 [] 而非 null
	Total int64 `json:"total"` // 总条数
	Page  int   `json:"page"`  // 当前页码
	Size  int   `json:"size"`  // 每页条数
}

PageResult 分页响应结构。

type Response added in v1.0.4

type Response struct {
	Code int    `json:"code"` // 业务码: 0 成功; 错误时见 errcode 包
	Msg  string `json:"msg"`  // 提示信息: 成功 "ok"; 错误时为可展示的文案
	Data any    `json:"data"` // 业务数据: 错误时为 null
}

Response 统一响应结构 {code, msg, data}, code 0 表示成功。

type Route

type Route struct {
	Method   string            // HTTP 方法(大写)
	Path     string            // 完整路由路径(含分组前缀), 如 /api/v1/users/:id
	Handlers []gin.HandlerFunc // 处理链, 依次执行
}

Route 路由声明: 注册表存储与调试输出的载体。 Handlers 为完整的处理链(分组中间件在前), 依次执行, 最后一个通常为业务处理函数, 与 gin 原生注册 r.GET("/path", mw1, mw2, handler) 的语义一致。

func Routes

func Routes() []Route

Routes 返回已注册的全部路由声明(平铺拷贝), 用于调试输出与路由文档生成。 首次调用会触发 Router 模块展开。

type Router

type Router interface {
	// Register 注册模块路由; g 为根分组, 可直接使用 g.GET 等便捷方法,
	// 或经 g.Group 创建模块子分组(前缀与中间件)。
	Register(g *Group)
}

Router 业务模块路由注册接口; 实现后经 ginx.Register 收集, 在 Build/Run 时回调 Register 完成模块路由注册。

Directories

Path Synopsis
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL