89 lines
4.6 KiB
Markdown
89 lines
4.6 KiB
Markdown
# 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 声明块 |
|