# 1.3 项目目录结构

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

## 顶层结构

```text
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/ — 核心业务

```text
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/ — 前端工程

```text
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 声明块 |