refactor(router): extract route registration into helper methods

2026-10-13 18:36:37 +08:00 · 2026-06-13 16:27:08 +08:00
parent 922f764241
commit 5698169f20
6 changed files with 253 additions and 228 deletions
@@ -107,6 +107,38 @@ const docTemplate = `{
                }
            }
        },
+        "/api/health": {
+            "get": {
+                "description": "检查服务是否正常运行，可用于负载均衡存活探测",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "health"
+                ],
+                "summary": "健康检查",
+                "responses": {
+                    "200": {
+                        "description": "服务正常",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "type": "string"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    }
+                }
+            }
+        },
        "/api/v1/admin/auth-sources": {
            "get": {
                "security": [
@@ -3426,38 +3458,6 @@ const docTemplate = `{
                }
            }
        },
-        "/api/v1/health": {
-            "get": {
-                "description": "检查服务是否正常运行，可用于负载均衡存活探测",
-                "produces": [
-                    "application/json"
-                ],
-                "tags": [
-                    "health"
-                ],
-                "summary": "健康检查",
-                "responses": {
-                    "200": {
-                        "description": "服务正常",
-                        "schema": {
-                            "allOf": [
-                                {
-                                    "$ref": "#/definitions/util.ResponseAny"
-                                },
-                                {
-                                    "type": "object",
-                                    "properties": {
-                                        "data": {
-                                            "type": "string"
-                                        }
-                                    }
-                                }
-                            ]
-                        }
-                    }
-                }
-            }
-        },
        "/api/v1/oauth/callback": {
            "post": {
                "description": "接收前端传回的 state 和 code，完成 OAuth/OIDC 认证并建立会话。支持登录（login）和账号绑定（bind）两种场景。",
@@ -100,6 +100,38 @@
                }
            }
        },
+        "/api/health": {
+            "get": {
+                "description": "检查服务是否正常运行，可用于负载均衡存活探测",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "health"
+                ],
+                "summary": "健康检查",
+                "responses": {
+                    "200": {
+                        "description": "服务正常",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/util.ResponseAny"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "type": "string"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    }
+                }
+            }
+        },
        "/api/v1/admin/auth-sources": {
            "get": {
                "security": [
@@ -3419,38 +3451,6 @@
                }
            }
        },
-        "/api/v1/health": {
-            "get": {
-                "description": "检查服务是否正常运行，可用于负载均衡存活探测",
-                "produces": [
-                    "application/json"
-                ],
-                "tags": [
-                    "health"
-                ],
-                "summary": "健康检查",
-                "responses": {
-                    "200": {
-                        "description": "服务正常",
-                        "schema": {
-                            "allOf": [
-                                {
-                                    "$ref": "#/definitions/util.ResponseAny"
-                                },
-                                {
-                                    "type": "object",
-                                    "properties": {
-                                        "data": {
-                                            "type": "string"
-                                        }
-                                    }
-                                }
-                            ]
-                        }
-                    }
-                }
-            }
-        },
        "/api/v1/oauth/callback": {
            "post": {
                "description": "接收前端传回的 state 和 code，完成 OAuth/OIDC 认证并建立会话。支持登录（login）和账号绑定（bind）两种场景。",
@@ -1190,6 +1190,24 @@ paths:
      summary: 校验人机验证解答
      tags:
      - cap
+  /api/health:
+    get:
+      description: 检查服务是否正常运行，可用于负载均衡存活探测
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: 服务正常
+          schema:
+            allOf:
+            - $ref: '#/definitions/util.ResponseAny'
+            - properties:
+                data:
+                  type: string
+              type: object
+      summary: 健康检查
+      tags:
+      - health
  /api/v1/admin/auth-sources:
    get:
      description: 返回所有已配置的 OAuth/OIDC 认证源列表，包括已启用和未启用的，需要管理员权限
@@ -3193,24 +3211,6 @@ paths:
      summary: Sample Hello API
      tags:
      - custom
-  /api/v1/health:
-    get:
-      description: 检查服务是否正常运行，可用于负载均衡存活探测
-      produces:
-      - application/json
-      responses:
-        "200":
-          description: 服务正常
-          schema:
-            allOf:
-            - $ref: '#/definitions/util.ResponseAny'
-            - properties:
-                data:
-                  type: string
-              type: object
-      summary: 健康检查
-      tags:
-      - health
  /api/v1/oauth/{source}/authorize:
    get:
      description: 根据指定认证源名称发起 OAuth 授权，支持 purpose 参数用于区分登录和账号绑定场景。认证源必须已启用。
@@ -18,7 +18,7 @@ import (
 // @Tags health
 // @Produce json
 // @Success 200 {object} util.ResponseAny{data=string} "服务正常"
-// @Router /api/v1/health [get]
+// @Router /api/health [get]
 func Health(c *gin.Context) {
 	c.JSON(http.StatusOK, util.OKNil())
 }
@@ -45,7 +45,7 @@ func loggerMiddleware() gin.HandlerFunc {

 		// 打印日志
 		// 排除健康检查接口
-		healthPath := config.Config.App.APIPrefix + "/v1/health"
+		healthPath := config.Config.App.APIPrefix + "/health"
 		if c.Request.URL.Path != healthPath {
 			logger.InfoF(
 				ctx,
@@ -146,19 +146,47 @@ func registerRoutes(r *gin.Engine) {
 		}

 		// CAPTCHA
+		registerCaptchaRoutes(apiGroup)
+
+		// Health
+		apiGroup.GET("/health", health.Health)
+
+		// API V1
+		apiV1Router := apiGroup.Group("/v1")
+		{
+			// OAuth
+			registerOAuthRoutes(apiV1Router)
+
+			// User
+			registerUserRoutes(apiV1Router)
+
+			// Upload
+			registerUploadRoutes(apiV1Router)
+
+			// Config (public)
+			registerConfigRoutes(apiV1Router)
+
+			// Admin
+			registerAdminRoutes(apiV1Router)
+
+			// Register custom business routes
+			registerCustomRoutes(apiV1Router)
+		}
+	}
+
+	// 注册前端静态路由（当启用 embed_frontend 编译标签时）
+	registerFrontend(r)
+}
+
+func registerCaptchaRoutes(apiGroup *gin.RouterGroup) {
 	capGroup := apiGroup.Group("/cap")
 	{
 		capGroup.POST("/challenge", capApp.Challenge)
 		capGroup.POST("/redeem", capApp.Redeem)
 	}
+}

-		// API V1
-		apiV1Router := apiGroup.Group("/v1")
-		{
-			// Health
-			apiV1Router.GET("/health", health.Health)
-
-			// OAuth
+func registerOAuthRoutes(apiV1Router *gin.RouterGroup) {
 	apiV1Router.GET("/oauth/sources", oauth.GetLoginSources)
 	apiV1Router.GET("/oauth/login", oauth.GetLoginURL)
 	apiV1Router.GET("/oauth/:source/authorize", oauth.Authorize)
@@ -168,8 +196,9 @@ func registerRoutes(r *gin.Engine) {
 	apiV1Router.GET("/user-info", oauth.LoginRequired(), oauth.UserInfo)
 	apiV1Router.GET("/oauth/external-accounts", oauth.LoginRequired(), oauth.ListExternalAccounts)
 	apiV1Router.POST("/oauth/external-accounts/:id/delete", oauth.LoginRequired(), oauth.DeleteExternalAccount)
+}

-			// User
+func registerUserRoutes(apiV1Router *gin.RouterGroup) {
 	userRouter := apiV1Router.Group("/user")
 	{
 		userRouter.POST("/login", capApp.VerifyMiddleware(capUtil.GetDefaultManager(), "login", func() bool {
@@ -208,17 +237,29 @@ func registerRoutes(r *gin.Engine) {
 			tokenRouter.POST("/:id/rotate", user.RotateAccessToken)
 		}
 	}
+}

-			// Upload
-			registerUploadRoutes(apiV1Router)
+func registerUploadRoutes(apiV1Router *gin.RouterGroup) {
+	uploadRouter := apiV1Router.Group("/upload")
+	uploadRouter.Use(oauth.LoginRequired())
+	{
+		uploadRouter.POST("", upload.UploadFile)
+		uploadRouter.GET("/my", upload.ListMyFiles)
+		uploadRouter.DELETE("/:id", upload.DeleteMyFile)
+		uploadRouter.PUT("/:id", upload.UpdateMyFile)
+		uploadRouter.GET("/download/:id", upload.DownloadFile)
+		uploadRouter.POST("/download/batch", upload.BatchDownloadFiles)
+	}
+}

-			// Config (public)
+func registerConfigRoutes(apiV1Router *gin.RouterGroup) {
 	configRouter := apiV1Router.Group("/config")
 	{
 		configRouter.GET("/public", publicconfig.GetPublicConfig)
 	}
+}

-			// Admin
+func registerAdminRoutes(apiV1Router *gin.RouterGroup) {
 	adminRouter := apiV1Router.Group("/admin")
 	adminRouter.Use(oauth.LoginRequired(), admin.LoginAdminRequired())
 	{
@@ -251,19 +292,7 @@ func registerRoutes(r *gin.Engine) {
 		adminRouter.GET("/logs/ws", admin_logs.HandleLogWebSocket)

 		// Task dispatch
-				adminRouter.GET("/tasks/types", admin_task.ListTaskTypes)
-				adminRouter.POST("/tasks/dispatch", admin_task.DispatchTask)
-
-				// Task executions
-				adminRouter.GET("/tasks/executions", admin_task.ListTaskExecutions)
-				adminRouter.GET("/tasks/executions/:id", admin_task.GetTaskExecution)
-				adminRouter.POST("/tasks/executions/:id/retry", admin_task.RetryTask)
-
-				// Task schedules
-				adminRouter.GET("/tasks/schedules", admin_task.ListSchedules)
-				adminRouter.POST("/tasks/schedules", admin_task.CreateSchedule)
-				adminRouter.PUT("/tasks/schedules/:id", admin_task.UpdateSchedule)
-				adminRouter.DELETE("/tasks/schedules/:id", admin_task.DeleteSchedule)
+		registerAdminTaskRoutes(adminRouter)

 		// Users
 		adminRouter.GET("/users", admin_user.ListUsers)
@@ -304,27 +333,23 @@ func registerRoutes(r *gin.Engine) {
 		adminRouter.PUT("/auth-sources/:id/toggle", admin_auth_source.ToggleAuthSource)
 		adminRouter.DELETE("/auth-sources/:id", admin_auth_source.DeleteAuthSource)
 	}
-
-			// Register custom business routes
-			registerCustomRoutes(apiV1Router)
-		}
 }

-	// 注册前端静态路由（当启用 embed_frontend 编译标签时）
-	registerFrontend(r)
-}
+func registerAdminTaskRoutes(adminRouter *gin.RouterGroup) {
+	// Task dispatch
+	adminRouter.GET("/tasks/types", admin_task.ListTaskTypes)
+	adminRouter.POST("/tasks/dispatch", admin_task.DispatchTask)

-func registerUploadRoutes(apiV1Router *gin.RouterGroup) {
-	uploadRouter := apiV1Router.Group("/upload")
-	uploadRouter.Use(oauth.LoginRequired())
-	{
-		uploadRouter.POST("", upload.UploadFile)
-		uploadRouter.GET("/my", upload.ListMyFiles)
-		uploadRouter.DELETE("/:id", upload.DeleteMyFile)
-		uploadRouter.PUT("/:id", upload.UpdateMyFile)
-		uploadRouter.GET("/download/:id", upload.DownloadFile)
-		uploadRouter.POST("/download/batch", upload.BatchDownloadFiles)
-	}
+	// Task executions
+	adminRouter.GET("/tasks/executions", admin_task.ListTaskExecutions)
+	adminRouter.GET("/tasks/executions/:id", admin_task.GetTaskExecution)
+	adminRouter.POST("/tasks/executions/:id/retry", admin_task.RetryTask)
+
+	// Task schedules
+	adminRouter.GET("/tasks/schedules", admin_task.ListSchedules)
+	adminRouter.POST("/tasks/schedules", admin_task.CreateSchedule)
+	adminRouter.PUT("/tasks/schedules/:id", admin_task.UpdateSchedule)
+	adminRouter.DELETE("/tasks/schedules/:id", admin_task.DeleteSchedule)
 }

 func registerAdminUploadRoutes(adminRouter *gin.RouterGroup) {