Documentation
¶
Index ¶
- Constants
- Variables
- func Apply()
- func Group(engine *gin.Engine, path string, middlewares ...gin.HandlerFunc) *gin.RouterGroup
- func GroupWithMiddlewareGroup(engine *gin.Engine, path string, groupName string) *gin.RouterGroup
- func RegisterDefaultRoutes(r *gin.Engine, checks ...HealthCheck)
- func RegisterHealthRoute(r *gin.Engine, checks ...HealthCheck)
- func RegisterLivenessRoute(r *gin.Engine)
- func RegisterMetricsRoute(r *gin.Engine, path ...string)
- func RegisterReadinessRoute(r *gin.Engine, checks ...HealthCheck)
- func RegisterSwaggerRoutes(r *gin.Engine)
- type HealthCheck
- type MiddlewareGroup
- type Module
- type ModuleFunc
- type RESTfulRoute
- func (r *RESTfulRoute) CRUD(list, detail, create, update, delete gin.HandlerFunc)
- func (r *RESTfulRoute) DELETE(handlers ...gin.HandlerFunc)
- func (r *RESTfulRoute) GET(handlers ...gin.HandlerFunc)
- func (r *RESTfulRoute) PATCH(handlers ...gin.HandlerFunc)
- func (r *RESTfulRoute) POST(handlers ...gin.HandlerFunc)
- func (r *RESTfulRoute) PUT(handlers ...gin.HandlerFunc)
- type Registry
- func GetRegistry() *Registry
- func Init(engine *gin.Engine) *Registry
- func NewRegistry(engine *gin.Engine) *Registry
- func RegisterModule(module Module) *Registry
- func RegisterModuleFunc(name string, fn func(r *gin.RouterGroup)) *Registry
- func RegisterVersion(version *VersionedAPI) *Registry
- func Use(middlewares ...gin.HandlerFunc) *Registry
- func (r *Registry) Apply()
- func (r *Registry) GetMiddlewareGroup(name string) []gin.HandlerFunc
- func (r *Registry) GroupWithMiddlewareGroup(engine *gin.Engine, path string, groupName string) *gin.RouterGroup
- func (r *Registry) RegisterMiddlewareGroup(group *MiddlewareGroup) *Registry
- func (r *Registry) RegisterModule(module Module) *Registry
- func (r *Registry) RegisterModuleFunc(name string, fn func(r *gin.RouterGroup)) *Registry
- func (r *Registry) RegisterVersion(version *VersionedAPI) *Registry
- func (r *Registry) SetMetricsMiddleware(mw gin.HandlerFunc)
- func (r *Registry) Use(middlewares ...gin.HandlerFunc) *Registry
- type VersionedAPI
Constants ¶
const DefaultHealthCheckTimeout = 2 * time.Second
DefaultHealthCheckTimeout bounds each dependency check so /health and /readyz do not hang behind a stuck database/client call.
Variables ¶
var DefaultModule = &defaultModule{}
DefaultModule 默认路由模块（可用于 WithModules）
Functions ¶
func Group ¶
func Group(engine *gin.Engine, path string, middlewares ...gin.HandlerFunc) *gin.RouterGroup
Group 创建路由组（带中间件分组）
func GroupWithMiddlewareGroup ¶
GroupWithMiddlewareGroup 使用中间件分组创建路由组（全局方式，代理到默认 Registry）。
func RegisterDefaultRoutes ¶
func RegisterDefaultRoutes(r *gin.Engine, checks ...HealthCheck)
RegisterDefaultRoutes 注册框架默认路由（健康检查、Swagger） 用户可以选择使用或不使用这些默认路由
func RegisterHealthRoute ¶
func RegisterHealthRoute(r *gin.Engine, checks ...HealthCheck)
RegisterHealthRoute 注册健康检查路由（兼容端点，等价于 readiness）。 幂等：若 /health 已注册则跳过（首次注册胜出），避免与 defaultModule 等并存时重复路由 panic。
func RegisterLivenessRoute ¶ added in v1.1.0
RegisterLivenessRoute 注册存活性探针（#17）。 GET /livez 永不依赖外部，仅表示进程存活，始终返回 200。 供 K8s livenessProbe 使用：失败由进程崩溃体现，而非端点返回 503。 幂等：重复注册跳过。
func RegisterMetricsRoute ¶ added in v1.1.0
RegisterMetricsRoute 注册 Prometheus 指标暴露端点（#18，H8c 修正）。
默认路径 /metrics。传入 path 可自定义。本函数仅注册暴露端点，不再用 r.Use 挂采集中间件——采集中间件改由 Registry.SetMetricsMiddleware 在 Apply 内作为 首个全局中间件装入，使所有经注册中心注册的业务路由都被采集，且不依赖本函数 相对其他路由注册的调用顺序。/metrics 端点自身与 /health 等基础路由不经采集中间件。
用法：
router.RegisterMetricsRoute(r) // /metrics router.RegisterMetricsRoute(r, "/metrics") // 等价
func RegisterReadinessRoute ¶ added in v1.1.0
func RegisterReadinessRoute(r *gin.Engine, checks ...HealthCheck)
RegisterReadinessRoute 注册就绪性探针（#17）。 GET /readyz 复用 HealthCheck 检查依赖（mysql/redis...），任一失败返回 503。 供 K8s readinessProbe 使用：未就绪时不接流量。 幂等：重复注册跳过。
func RegisterSwaggerRoutes ¶
RegisterSwaggerRoutes 注册 Swagger 文档路由。幂等：重复注册跳过。
Types ¶
type HealthCheck ¶
type HealthCheck struct {
Name string
Check func(context.Context) error
Disabled bool
Timeout time.Duration
}
HealthCheck 健康检查项
type MiddlewareGroup ¶
type MiddlewareGroup struct {
Name string
Middlewares []gin.HandlerFunc
}
MiddlewareGroup 中间件分组
func NewMiddlewareGroup ¶
func NewMiddlewareGroup(name string, middlewares ...gin.HandlerFunc) *MiddlewareGroup
NewMiddlewareGroup 创建中间件分组
type Module ¶
type Module interface {
// Name 模块名称（用于日志和调试）
Name() string
// Register 注册路由到指定组
Register(r *gin.RouterGroup)
}
Module 路由模块接口 用户实现此接口来注册业务路由
type RESTfulRoute ¶
type RESTfulRoute struct {
Group *gin.RouterGroup
Path string
}
RESTfulRoute RESTful 路由快捷注册
func NewRESTful ¶
func NewRESTful(group *gin.RouterGroup, path string) *RESTfulRoute
NewRESTful 创建 RESTful 路由
func (*RESTfulRoute) CRUD ¶
func (r *RESTfulRoute) CRUD(list, detail, create, update, delete gin.HandlerFunc)
CRUD 注册标准 CRUD 路由 GET /path - 列表 GET /path/:id - 详情 POST /path - 创建 PUT /path/:id - 更新 DELETE /path/:id - 删除
func (*RESTfulRoute) DELETE ¶
func (r *RESTfulRoute) DELETE(handlers ...gin.HandlerFunc)
DELETE 注册 DELETE 路由
func (*RESTfulRoute) PATCH ¶
func (r *RESTfulRoute) PATCH(handlers ...gin.HandlerFunc)
PATCH 注册 PATCH 路由
func (*RESTfulRoute) POST ¶
func (r *RESTfulRoute) POST(handlers ...gin.HandlerFunc)
POST 注册 POST 路由
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry 路由注册中心
func RegisterModuleFunc ¶
func RegisterModuleFunc(name string, fn func(r *gin.RouterGroup)) *Registry
RegisterModuleFunc 注册函数式模块（全局方式）
func RegisterVersion ¶
func RegisterVersion(version *VersionedAPI) *Registry
RegisterVersion 注册版本化 API（全局方式）
func (*Registry) Apply ¶
func (r *Registry) Apply()
Apply 应用所有路由注册。
幂等（H8b）：二次调用直接返回，避免重复 engine.Use 与 Gin 重复路由 panic。 装入顺序：metrics 中间件（若有）→ 用户全局中间件 → 模块/版本路由。 metrics 置于首位保证全量业务路由被采集，且不依赖 RegisterMetricsRoute 调用顺序。
func (*Registry) GetMiddlewareGroup ¶
func (r *Registry) GetMiddlewareGroup(name string) []gin.HandlerFunc
GetMiddlewareGroup 获取中间件分组
func (*Registry) GroupWithMiddlewareGroup ¶ added in v1.3.0
func (r *Registry) GroupWithMiddlewareGroup(engine *gin.Engine, path string, groupName string) *gin.RouterGroup
GroupWithMiddlewareGroup 使用中间件分组创建路由组。
H-B 修复：改走 ensureRegistry()（与 Use/RegisterModule/Apply 等所有全局 helper 一致）， 把"未初始化"从 nil 解引用 panic 转成可定位的明确 panic（H8a 目标）。原实现用 GetRegistry() 可返回 nil，nil.GetMiddlewareGroup 即 panic，错误信息晦涩。
func (*Registry) RegisterMiddlewareGroup ¶
func (r *Registry) RegisterMiddlewareGroup(group *MiddlewareGroup) *Registry
RegisterMiddlewareGroup 注册中间件分组
func (*Registry) RegisterModule ¶
RegisterModule 注册模块（无版本）
func (*Registry) RegisterModuleFunc ¶
func (r *Registry) RegisterModuleFunc(name string, fn func(r *gin.RouterGroup)) *Registry
RegisterModuleFunc 注册函数式模块
func (*Registry) RegisterVersion ¶
func (r *Registry) RegisterVersion(version *VersionedAPI) *Registry
RegisterVersion 注册版本化 API
func (*Registry) SetMetricsMiddleware ¶ added in v1.2.0
func (r *Registry) SetMetricsMiddleware(mw gin.HandlerFunc)
SetMetricsMiddleware 设置指标采集中间件（H8c）。Apply 时它会作为首个全局中间件 装入 engine，使所有经注册中心注册的路由都被采集，不再依赖注册顺序。 传入 nil 清除。须在 Apply 之前调用。
type VersionedAPI ¶
type VersionedAPI struct {
Version string // 版本标识，如 "v1", "v2"
BasePath string // 基础路径，如 "/api/v1"
Modules []Module // 该版本的模块列表
Middlewares []gin.HandlerFunc // 该版本的公共中间件
}
VersionedAPI 版本化 API 配置
func NewVersion ¶
func NewVersion(version, basePath string, middlewares ...gin.HandlerFunc) *VersionedAPI
NewVersion 创建版本化 API
func (*VersionedAPI) AddModule ¶
func (v *VersionedAPI) AddModule(module Module) *VersionedAPI
AddModule 为版本添加模块
func (*VersionedAPI) AddModuleFunc ¶
func (v *VersionedAPI) AddModuleFunc(name string, fn func(r *gin.RouterGroup)) *VersionedAPI
AddModuleFunc 为版本添加函数式模块
Source Files