Documentation
¶
Overview ¶
Package ginx 提供基于 gin 的 Web 服务封装:配置化启动 HTTP/HTTPS 服务与集中式路由管理。
设计目标: 用户以配置(结构体/配置文件)声明服务参数, 以与 gin 用法一致的方式声明路由 (Group 提供与 gin.RouterGroup 相同的便捷方法, 一条路由可传多个 handler 依次执行), 由本包在启动时统一校验(方法/路径/处理链/重复注册)并注册进 gin 引擎, 随后启动服务 并支持优雅停机, 减少在业务代码中持续管理路由与服务器的工作。
内置常用能力: Bind 系列请求绑定辅助(绑定+校验+失败自动 400 响应)、 健康检查路由(health_check_path, 默认 /healthz)、 CORS 跨域与固定窗口限流中间件(cors / rate_limit 配置节点, 实现位于 middleware 子包)、 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 Register(rs ...Router)
- 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 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。
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, 设为 "-" 关闭)
HealthCheckPath string `yaml:"health_check_path" toml:"health_check_path" json:"health_check_path" mapstructure:"health_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"`
// 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)
// 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。
Directories
¶
| Path | Synopsis |
|---|---|
|
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。
|
Package middleware 提供 ginx 的内置中间件集合, 每个中间件独立一个文件; 各中间件均可脱离 ginx, 直接用于原生 gin。 |