Gin通用脚手架是面向Go开发者、整合MySQL与Redis的轻量工程化模板，含13个Go源码文件、YAML配置等25个文件，结构清晰、开箱即用，已获1353人下载使用。
直接用 gin.Default() 启动一个能跑的后台服务只要 10 行代码，但真要上线、加数据库、做权限、接 Redis，必须提前拆清结构、管住初始化顺序——否则第 3 天就会卡在 nil pointer dereference 或连接池耗尽上。
从 gin.Default() 到可维护服务：别跳过初始化分层
很多人写完 gin.Default() + r.GET() 就以为搭好了，结果加 MySQL 时把 gorm.Open() 塞进 handler，导致每次请求都建新连接；或者把 Redis 客户端声明成全局变量却没设超时，压测时连接堆积到 2000+。
- 必须把配置加载、DB/Redis 初始化、路由注册三件事严格分离，推荐目录：
cmd/server/main.go（只启动）、internal/config/（解析 YAML/.env）、internal/setup/（返回 *gorm.DB 和 *redis.Client） -
gin.Default()自带日志和 panic 恢复中间件，开发期够用；生产环境建议用gin.New()+ 手动挂载，避免日志中间件吃掉大量 I/O - 路由注册不能全塞在
main()里——按业务域拆成userRouter(r.Group("/api/v1"))、orderRouter(r.Group("/api/v1"))，否则 50 个接口后main.go超过 800 行且无法单测
go-admin 不是 Gin 插件：强行“整合”等于自建陷阱
搜“Gin 整合 GoAdmin”会看到一堆误导性教程，实际 go-admin-team/go-admin 是基于 Gin 的完整项目框架，不是你 go get 后调个函数就能接入的库。它自带 CLI、migrate、RBAC 模块和固定配置路径，硬塞进已有 Gin 项目只会触发一连串静默失败。
- 典型报错：
panic: runtime error: invalid memory address or nil pointer dereference，根源是app.Initialize()没执行，Casbin 策略为空，JWT 密钥未加载 - 数据库必须先跑：
./go-admin migrate -c config/settings.yml，否则sys_user表不存在，登录接口直接 500 -
config/settings.yml中的database.dsn必须是标准格式：root:password@tcp(127.0.0.1:3306)/go_admin?charset=utf8mb4&parseTime=True&loc=Local，漏掉&或写成&会导致连接失败且无明确提示
新增业务接口：绕过 GoAdmin 模块机制就等于裸奔
想加个 /city 接口？别在 main() 里写 r.POST("/city", handler)。GoAdmin 的 JWT 校验、角色权限检查、菜单缓存全部依赖其预设的路由注册切片（如 routerCheckRole），裸注册的路由中间件不会生效。
- 错误写法：
r.POST("/city", apis.City{}.Create)→ 接口无鉴权，任何人均可调用 - 正确位置：在
app/adm/router/router.go中追加到routerCheckRole切片，并确保绑定到v1.Group("/admin")下 - 如果只是临时调试，可用
routerNoCheck，但上线前必须移回routerCheckRole并补全 Casbin 规则，否则权限模型形同虚设
最常被忽略的点：Redis 配置项 redis.addr 没填时部分功能降级不报错，但一旦 cache.enabled: true 而 Redis 不可达，服务会 panic 退出——这个逻辑不在文档首页，藏在 pkg/cache/redis.go 的初始化分支里。
