init

routes/rest/example_rest.go

@@ -0,0 +1,18 @@
+package rest
+
+import (
+	"skeleton/modules/example"
+
+	"github.com/gin-gonic/gin"
+)
+
+func init() {
+	RegisterPublic(registerExampleRoutes)
+}
+
+func registerExampleRoutes(r *gin.RouterGroup) {
+	ctrl := example.NewExampleController()
+
+	group := r.Group("/example")
+	group.GET("/hello", ctrl.Hello)
+}

routes/rest/health_rest.go

@@ -0,0 +1,29 @@
+package rest
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+func init() {
+	RegisterPublic(registerHealthRoutes)
+}
+
+func registerHealthRoutes(r *gin.RouterGroup) {
+	r.GET("/ping", func(ctx *gin.Context) {
+		ctx.JSON(http.StatusOK, gin.H{
+			"code":    200,
+			"message": "pong",
+			"data":    nil,
+		})
+	})
+
+	r.GET("/health", func(ctx *gin.Context) {
+		ctx.JSON(http.StatusOK, gin.H{
+			"code":    200,
+			"message": "ok",
+			"data":    nil,
+		})
+	})
+}

routes/rest/registry.go

@@ -0,0 +1,86 @@
+package rest
+
+import (
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// 子路由注册函数签名
+type Registrar func(*gin.RouterGroup)
+
+// 两类注册器：公开/私有（是否需要 JWT）
+var (
+	publicRegistrars  []Registrar
+	privateRegistrars []Registrar
+)
+
+// RegisterPublic 注册公开路由（无需认证）
+func RegisterPublic(fn Registrar) {
+	publicRegistrars = append(publicRegistrars, fn)
+	zap.L().Debug("公开路由注册器已添加",
+		zap.Int("total_public", len(publicRegistrars)),
+	)
+}
+
+// RegisterPrivate 注册私有路由（需要 JWT 认证）
+func RegisterPrivate(fn Registrar) {
+	privateRegistrars = append(privateRegistrars, fn)
+	zap.L().Debug("私有路由注册器已添加",
+		zap.Int("total_private", len(privateRegistrars)),
+	)
+}
+
+// ApplyPublic 应用所有公开路由
+func ApplyPublic(group *gin.RouterGroup) {
+	zap.L().Info("开始应用公开路由",
+		zap.Int("count", len(publicRegistrars)),
+	)
+
+	for i, fn := range publicRegistrars {
+		fn(group)
+		zap.L().Debug("公开路由已应用",
+			zap.Int("index", i+1),
+		)
+	}
+
+	zap.L().Info("公开路由应用完成",
+		zap.Int("applied_count", len(publicRegistrars)),
+	)
+}
+
+// ApplyPrivate 应用所有私有路由（带 JWT 中间件）
+func ApplyPrivate(group *gin.RouterGroup) {
+	zap.L().Info("开始应用私有路由",
+		zap.Int("count", len(privateRegistrars)),
+	)
+
+	for i, fn := range privateRegistrars {
+		fn(group)
+		zap.L().Debug("私有路由已应用",
+			zap.Int("index", i+1),
+		)
+	}
+
+	zap.L().Info("私有路由应用完成",
+		zap.Int("applied_count", len(privateRegistrars)),
+	)
+}
+
+// GetRegistrarStats 获取注册器统计信息（调试用）
+func GetRegistrarStats() map[string]int {
+	return map[string]int{
+		"public":  len(publicRegistrars),
+		"private": len(privateRegistrars),
+		"total":   len(publicRegistrars) + len(privateRegistrars),
+	}
+}
+
+// PrintStats 打印注册器统计信息
+func PrintStats() {
+	stats := GetRegistrarStats()
+	zap.L().Info("路由注册器统计",
+		zap.Int("public_count", stats["public"]),
+		zap.Int("private_count", stats["private"]),
+		zap.Int("total_count", stats["total"]),
+	)
+}

routes/routes.go

@@ -0,0 +1,55 @@
+package routes
+
+import (
+	"skeleton/config"
+	"skeleton/middlewares"
+	"skeleton/routes/rest"
+	"skeleton/routes/ws"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// SetupRoutes 设置主路由
+func SetupRoutes(cfg *config.Config) *gin.Engine {
+	// 根据配置设置 Gin 模式
+	if !cfg.App.Debug {
+		gin.SetMode(gin.ReleaseMode)
+	}
+
+	// 创建 Gin 路由器（不使用默认中间件）
+	r := gin.New()
+
+	// 设置 multipart form 内存限制为 100MB
+	r.MaxMultipartMemory = 100 << 20 // 100 MB
+
+	// 添加自定义中间件
+	r.Use(middlewares.CORS())         // CORS跨域处理（需要在其他中间件之前）
+	r.Use(middlewares.GinLogger())    // 结构化日志
+	r.Use(middlewares.GinRecovery())  // 异常恢复
+	r.Use(middlewares.ErrorLogging()) // 错误响应日志（用于记录逻辑异常）
+
+	// API 路由组
+	api := r.Group("/api")
+
+	// 公开路由组（无需认证）
+	public := api.Group("")
+	rest.ApplyPublic(public)
+
+	// 私有路由组（需要 JWT 认证）
+	private := api.Group("/private")
+	private.Use(middlewares.JWTAuth()) // 启用JWT认证中间件
+	rest.ApplyPrivate(private)
+
+	// WebSocket 路由组（无需认证）
+	ws.ApplyWebSocketRoutes(api)
+
+	// 打印路由统计信息
+	rest.PrintStats()
+
+	zap.L().Info("主路由设置完成",
+		zap.Any("rest_stats", rest.GetRegistrarStats()),
+	)
+
+	return r
+}

routes/ws/ws.go

@@ -0,0 +1,8 @@
+package ws
+
+import "github.com/gin-gonic/gin"
+
+// ApplyWebSocketRoutes WebSocket路由挂载点
+func ApplyWebSocketRoutes(r *gin.RouterGroup) {
+	_ = r
+}