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 ¶
- func Any(path string, handlers ...gin.HandlerFunc)
- func Bind(c *gin.Context, obj any) bool
- func BindForm(c *gin.Context, obj any) bool
- func BindJSON(c *gin.Context, obj any) bool
- func BindQuery(c *gin.Context, obj any) bool
- func BindURI(c *gin.Context, obj any) bool
- func ClearRoutes()
- func DELETE(path string, handlers ...gin.HandlerFunc)
- func Engine() *gin.Engine
- func GET(path string, handlers ...gin.HandlerFunc)
- func HEAD(path string, handlers ...gin.HandlerFunc)
- func Handle(method, path string, handlers ...gin.HandlerFunc)
- func OPTIONS(path string, handlers ...gin.HandlerFunc)
- func PATCH(path string, handlers ...gin.HandlerFunc)
- func POST(path string, handlers ...gin.HandlerFunc)
- func PUT(path string, handlers ...gin.HandlerFunc)
- func Ready() bool
- func Register(rs ...Router)
- func Render(c *gin.Context, err error, data any)
- func RenderError(c *gin.Context, err error)
- func RenderOK(c *gin.Context, data any)
- func RenderPage[T any](c *gin.Context, err error, p Page, list []T, total int64)
- func SetReadyChecker(fn func() bool)
- type Gin
- type Group
- func (g *Group) Any(path string, handlers ...gin.HandlerFunc)
- func (g *Group) DELETE(path string, handlers ...gin.HandlerFunc)
- func (g *Group) GET(path string, handlers ...gin.HandlerFunc)
- func (g *Group) Group(prefix string, handlers ...gin.HandlerFunc) *Group
- func (g *Group) HEAD(path string, handlers ...gin.HandlerFunc)
- func (g *Group) Handle(method, path string, handlers ...gin.HandlerFunc)
- func (g *Group) OPTIONS(path string, handlers ...gin.HandlerFunc)
- func (g *Group) PATCH(path string, handlers ...gin.HandlerFunc)
- func (g *Group) POST(path string, handlers ...gin.HandlerFunc)
- func (g *Group) PUT(path string, handlers ...gin.HandlerFunc)
- type Page
- type PageResult
- type Response
- type Route
- type Router
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 ¶
Bind 依据 Content-Type 自动绑定请求参数到 obj 并完成校验(binding/validator 标签), 兼容 JSON / 表单等常见格式。
绑定/校验失败时自动写入 400 响应并返回 false, 业务代码仅需在失败时直接 return, 免去每个 handler 重复编写绑定错误处理:
var req LoginRequest
if !ginx.Bind(c, &req) {
return
}
func DELETE ¶
func DELETE(path string, handlers ...gin.HandlerFunc)
DELETE 在根分组注册 DELETE 路由, 见 Group.DELETE。
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 Register ¶
func Register(rs ...Router)
Register 收集实现了 Router 的业务模块, 在 Build/Run 时统一回调展开。 各模块在自身初始化时调用即可, 无需关心注册顺序与引擎创建过程。
func Render ¶ added in v1.0.4
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
RenderError 渲染错误响应, 映射规则同 Render, 语义更显式的便捷入口。
func RenderOK ¶ added in v1.0.4
RenderOK 渲染成功响应: 200 {"code":0,"msg":"ok","data":...}。 已通过 Render(c, nil, data) 覆盖, 需要显式语义时直接使用。
func RenderPage ¶ added in v1.0.4
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) Build ¶
Build 创建 gin 引擎并注册全部已声明的路由, 不启动监听。 成功后注入全局引擎(Engine() 可获取), 适合集成测试中使用 httptest 直接调用引擎。
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。
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
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)
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 表示成功。
Directories
¶
| Path | Synopsis |
|---|---|
|
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。
|
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。 |