easygoadmin-wiki/EasyGoAdmin_Gin_NaiveVue/zh/directory.md

1.3 项目目录结构

:::tip 概述 本页给出项目顶层与关键子目录的结构说明。目录划分遵循"一个模块固定四个文件"的契约，基础设施统一收敛在 utility/。 :::

顶层结构

EasyGoAdmin_Gin_EleVue/
├── cmd/                    # 可执行入口（api 服务、gen 生成器、migrator 迁移器）
├── config/                 # 配置文件（config.yaml 为基）
├── deploy/                 # 部署物料（Dockerfile、docker-compose.yaml、nginx.conf）
├── document/               # 项目文档与数据库脚本（module-conventions.md、各方言 SQL）
├── internal/               # 核心业务代码（对外不可见的内部包）
├── resource/               # 运行期资源（ip2region 等数据文件）
├── templates/              # 代码生成器模板（后端四件套 + 前端 ui/ui2）
├── ui/                     # 前端工程（Vue3 + ElementPlus）
├── utility/                # 基础设施包（config、logger、cache、jwt、upload...）
├── Makefile / make.bat     # 构建与开发命令（两套目标一致）
├── go.mod / go.sum         # Go 模块定义（module easygoadmin）
└── log/ upload/            # 运行期产生的日志与上传文件目录

internal/ — 核心业务

internal/
├── consts/                 # 业务常量（错误码哨兵、缓存键、上下文键、日志类型）
├── handler/                # 接口层：极薄委托，方法签名与 dto 一一对应
├── middleware/             # 中间件（trace/cors/response/jwt/tenant/authz/operation_log...）
├── migrate/                # 跨库迁移引擎（内省、DDL 生成、分批搬运、序列修复）
├── model/
│   ├── db/                 # 数据库连接与多方言驱动装配
│   ├── dto/                # 契约层：请求/响应结构与校验标签
│   ├── hooks/              # 全局 GORM 钩子（审计字段补齐、软删除拦截）
│   └── dbtest/             # 数据库相关测试辅助
├── repository/             # 数据访问层：XxxRepo + Base，统一 Ctx(ctx) 入口
├── router/                 # 路由注册（router.go 声明表、bind.go 反射引擎、meta 元数据）
├── server/                 # 服务装配与启动、优雅关闭
├── service/                # 业务层：sXxx + ModuleSpec 声明 + 手写复杂逻辑
└── task/                   # 定时任务（init 自注册 + 调度器）

utility/ — 基础设施

包	职责
apperr	业务错误类型（New/Newf，携带错误码上抛）
cache	缓存抽象（Redis 探测失败自动降级内存）
captcha	图形验证码生成与校验
config	配置加载（config.yaml + APP_* 环境变量覆盖）
crypto	加解密与哈希工具
excel	Excel 导入导出封装（excelize）
ip2region	IP 归属地查询
jwt	Token 签发与解析
logger	zap 结构化日志（支持 ctx 追踪字段）
response	统一响应信封构造
ua	User-Agent 解析
upload	文件上传与转正（temp → 模块目录）
validator	binding 标签校验与错误消息映射

ui/ — 前端工程

ui/src/
├── api/                    # 接口模块（按业务域分组，与后端路由一一对应）
├── components/             # 公共组件（Table、Page、Form、Upload、Editor、Excel...）
├── directives/             # 自定义指令（permission 等）
├── enums/                  # 前端枚举常量
├── hooks/                  # 组合式函数
├── layout/                 # 布局系统（侧边栏、顶栏、标签页）
├── router/                 # 路由（静态路由 + 动态菜单路由生成器 + 守卫）
├── store/                  # Pinia 状态（user、asyncRoute、tabsView...）
├── styles/                 # 全局样式与主题变量
├── utils/                  # 工具函数（http 封装、auth、校验、格式化）
└── views/                  # 页面（按业务域分目录）

约定回顾

约定	说明
表名	gin_ 前缀 + 小写下划线
模块文件	dto / repository / service / handler 四件套同名
服务单例	type sXxx struct{} + init() 注册 + var Xxx *sXxx
仓储入口	统一 repository.NewXxxRepo().Ctx(ctx)，禁止裸用 *gorm.DB
代码生成产物	菜单行幂等创建，router.go 自动追加 Bind 声明块