ldap-1-backend/routes/a_routes.go

/*
Package routes 系统路由配置的主入口

该文件负责初始化和配置整个系统的路由结构，包括：
- Gin 引擎的基础配置
- 全局中间件的注册和配置
- 静态文件服务配置
- API 路由组的初始化
- Swagger 文档路由配置

路由架构说明：
1. 静态文件路由：服务前端 Vue 应用
2. API 路由组：所有后端 API 接口
3. Swagger 文档：API 文档和测试界面

中间件执行顺序：
1. 静态文件服务中间件
2. 限流中间件（令牌桶算法）
3. CORS 跨域中间件
4. 操作日志中间件
5. JWT 认证中间件（特定路由）
6. Casbin 权限中间件（特定路由）
*/
package routes

import (
	"fmt"
	"net/http"
	"time"

	"github.com/eryajf/go-ldap-admin/config"
	_ "github.com/eryajf/go-ldap-admin/docs"
	"github.com/eryajf/go-ldap-admin/middleware"
	"github.com/eryajf/go-ldap-admin/public/common"
	"github.com/eryajf/go-ldap-admin/public/static"
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

// InitRoutes 初始化系统路由
// 该函数是整个路由系统的入口点，负责：
// 1. 配置 Gin 引擎的运行模式
// 2. 注册全局中间件
// 3. 配置静态文件服务
// 4. 初始化 API 路由组
// 5. 配置 Swagger 文档路由
//
// 返回值：
// - *gin.Engine: 配置完成的 Gin 引擎实例
func InitRoutes() *gin.Engine {
	// ==================== Gin 引擎配置 ====================

	// 根据配置文件设置 Gin 运行模式（debug/release/test）
	gin.SetMode(config.Conf.System.Mode)

	// 创建 Gin 引擎实例，包含默认的日志和恢复中间件
	r := gin.Default()

	// 备选方案：创建不带默认中间件的引擎
	// r := gin.New()
	// r.Use(gin.Recovery())

	// ==================== 静态文件服务配置 ====================

	// 配置静态文件服务，用于提供前端 Vue 应用
	r.Use(middleware.Serve("/", middleware.EmbedFolder(static.Static, "dist")))

	// 配置 NoRoute 处理器，用于 SPA 路由支持
	// 当请求的路由不存在时，返回 index.html，让前端路由接管
	r.NoRoute(func(c *gin.Context) {
		data, err := static.Static.ReadFile("dist/index.html")
		if err != nil {
			_ = c.AbortWithError(http.StatusInternalServerError, err)
			return
		}
		c.Data(http.StatusOK, "text/html; charset=utf-8", data)
	})

	// ==================== 全局中间件配置 ====================

	// 配置限流中间件（令牌桶算法）
	// 根据配置文件设置令牌填充间隔和桶容量，防止 API 被恶意调用
	fillInterval := time.Duration(config.Conf.RateLimit.FillInterval)
	capacity := config.Conf.RateLimit.Capacity
	r.Use(middleware.RateLimitMiddleware(time.Millisecond*fillInterval, capacity))

	// 启用 CORS 跨域中间件
	// 允许前端应用跨域访问后端 API
	r.Use(middleware.CORSMiddleware())

	// 启用操作日志中间件
	// 记录所有 API 请求的详细信息，用于审计和问题排查
	r.Use(middleware.OperationLogMiddleware())

	// ==================== JWT 认证中间件初始化 ====================

	// 初始化 JWT 认证中间件
	authMiddleware, err := middleware.InitAuth()
	if err != nil {
		common.Log.Panicf("初始化 JWT 中间件失败：%v", err)
		panic(fmt.Sprintf("初始化 JWT 中间件失败：%v", err))
	}

	// ==================== Swagger 文档路由 ====================

	// 注册 Swagger API 文档路由
	// 提供交互式的 API 文档和测试界面
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	// ==================== API 路由组注册 ====================

	// 创建 API 路由组，所有业务接口都在此组下
	apiGroup := r.Group("/" + config.Conf.System.UrlPathPrefix)

	// 注册各个功能模块的路由
	// 注意：路由注册顺序会影响中间件的执行顺序

	InitBaseRoutes(apiGroup, authMiddleware)          // 基础路由（登录、登出等，无需认证）
	InitUserRoutes(apiGroup, authMiddleware)          // 用户管理路由（需要 JWT + Casbin）
	InitGroupRoutes(apiGroup, authMiddleware)         // 部门/组管理路由（需要 JWT + Casbin）
	InitRoleRoutes(apiGroup, authMiddleware)          // 角色管理路由（需要 JWT + Casbin）
	InitMenuRoutes(apiGroup, authMiddleware)          // 菜单管理路由（需要 JWT + Casbin）
	InitApiRoutes(apiGroup, authMiddleware)           // 接口管理路由（需要 JWT + Casbin）
	InitOperationLogRoutes(apiGroup, authMiddleware)  // 操作日志路由（需要 JWT + Casbin）
	InitFieldRelationRoutes(apiGroup, authMiddleware) // 字段关系路由（需要 JWT + Casbin）

	common.Log.Info("🚀 系统路由初始化完成！")
	return r
}