103 lines
7.2 KiB
Markdown
103 lines
7.2 KiB
Markdown
# 4.1 整体架构概览
|
||
|
||
:::tip 概述
|
||
系统采用分层架构 + 声明式基座 + 全局钩子横切 + gmeta 反射注解的组合。本节给出总架构图、模块依赖方向（允许/禁止）与启动编排，是理解全部机制的地图。
|
||
:::
|
||
|
||
## 系统总架构图
|
||
|
||
```text
|
||
┌───────────────────────────── 客户端 ─────────────────────────────┐
|
||
│ ui/（Vue3 + Element Plus，baseURL=/api） 其他 API 消费方 │
|
||
└──────────────────────────────────┬─────────────────────────────────┘
|
||
│ HTTP（Bearer JWT）
|
||
╔══════════════════════════════════▼═════════════════════════════════╗
|
||
║ ghttp Server(:8000) ║
|
||
║ ┌────────────────── 中间件链（顺序执行）──────────────────┐ ║
|
||
║ │ CORS → Response → RateLimit → Demo → JWT → Tenant │ ║
|
||
║ │ → OperationLog │ ║
|
||
║ └──────────────────────────┬──────────────────────────────┘ ║
|
||
║ ┌──────────────────────────▼──────────────────────────────┐ ║
|
||
║ │ Bind 反射包装层（gmeta）：权限校验 → 参数解析 → 分发 │ ║
|
||
║ │ 路由元数据表 meta（权限/日志 注解即事实，补注册 goai） │ ║
|
||
║ └──────────────────────────┬──────────────────────────────┘ ║
|
||
║ controller（薄）→ service 接口（手维护）→ logic（ModuleSpec 基座） ║
|
||
║ │ 侧路：utility/{jwt,captcha,cache,upload,excel,ip2region…} ║
|
||
║ │ 侧路：gcron 调度器（job daemon + CleanTemp） ║
|
||
║ ┌────▼─────────────────────────────────────────────────────┐ ║
|
||
║ │ dao.Xxx.Ctx(ctx) —— 唯一查询入口 │ ║
|
||
║ │ hooks.ApplyCtx：del_flag=0 + 租户级表 tenant_id IN(0,x) │ ║
|
||
║ │ hooks.Handler：Insert 盖章 / Update 盖章 / Delete→软删 │ ║
|
||
║ └────┬─────────────────────────────────────────────────────┘ ║
|
||
╚══════╪══════════════════════════════════════════════════════════════╝
|
||
│ gdb（五驱动运行时切换）
|
||
┌──────▼────────┐ ┌──────────────┐ ┌─────────────────────────────┐
|
||
│ MySQL/PgSQL/… │ │ Redis（缓存） │ │ 磁盘 resource/upload + xdb │
|
||
└───────────────┘ └──────────────┘ └─────────────────────────────┘
|
||
```
|
||
|
||
## 模块依赖方向图（允许 / 禁止）
|
||
|
||
```text
|
||
api/v1 ◀── controller ◀── logic ──▶ service（接口注册）
|
||
│
|
||
├──▶ dao ──▶ model/entity · model/hooks ──▶ gdb
|
||
├──▶ utility/*（无业务依赖）
|
||
└──▶ consts
|
||
|
||
internal/task ──▶ internal/logic ✅ 允许（任务复用 base 能力）
|
||
internal/logic ──▶ internal/task ❌ 禁止（反向依赖）
|
||
internal/middleware ──▶ 业务包 ❌ 禁止（经 wire.go 函数变量接线）
|
||
internal/migrate ──▶ dao/logic ❌ 禁止（gdb 裸连，隔离钩子）
|
||
base.go ──▶ 模块文件 ❌ 禁止（只依赖 dao/utility/consts）
|
||
```
|
||
|
||
## 启动编排（internal/cmd）
|
||
|
||
```text
|
||
main.go（注册五数据库驱动 + Redis 适配器 + blank import internal/logic）
|
||
└─ internal/cmd.Run(ctx)
|
||
├─ 1) utility/cache.Init Redis 探测，失败降级进程内存
|
||
├─ 2) wireDependencies 校验中间件依赖是否已由业务包 init 接线
|
||
├─ 3) g.Server("easygoadmin") + router.Register(s)
|
||
│ 中间件链注册 + 404/500 状态处理器 + SetServerRoot("resource")
|
||
│ + /api/health + /swagger → 逐个 Bind 全部控制器
|
||
├─ 4) go DaemonInit（延时 2s） 定时任务调度器加载 status=1 任务
|
||
├─ 5) gcron 注册 CleanTemp 每日 03:30 清理上传临时目录
|
||
└─ 6) s.Run() 阻塞运行 HTTP 服务
|
||
```
|
||
|
||
延时 2s 的原因：等 HTTP 监听就绪（任务可能是 HTTP 调自身接口）。
|
||
|
||
## 业务调用链（标准 CRUD）
|
||
|
||
```text
|
||
Bind 包装（gmeta 权限/日志元数据）
|
||
→ controller.CXxx（薄层，仅转发 service.Xxx()）
|
||
→ service.IXxx 接口（internal/service/{模块}.go，手维护）
|
||
→ logic.sXxx 实现（internal/logic/{模块}.go，ModuleSpec 基座或手写）
|
||
→ dao.Xxx.Ctx(ctx)（唯一查询入口：挂全局钩子 + 注入 del_flag/租户条件）
|
||
→ gdb → 数据库
|
||
```
|
||
|
||
## 五个关键设计决策
|
||
|
||
| 决策 | 理由 |
|
||
|------|------|
|
||
| **目录平铺**：api/controller/logic/service 均单包，每模块一文件 | 跨模块直接同包调用（如 user 调 ResolveCityNames 无需 import）；生成器目标路径唯一 |
|
||
| **service 接口手维护** | 接口即文档；禁止 gf gen service 整体覆盖 |
|
||
| **logic 同包 init() 注册** | 无需 blank import，包内全量加载 |
|
||
| **中间件不依赖业务层** | IdentityLoader/TenantLoader/LogSink 以函数变量接线（wire.go），cmd 启动期检查告警 |
|
||
| **dao.Ctx 唯一查询入口** | 软删/租户/审计三条红线在钩子层强制执行，业务零感知 |
|
||
|
||
## 分层职责速查
|
||
|
||
| 层 | 位置 | 职责 | 禁止 |
|
||
|----|------|------|------|
|
||
| api/v1 | api/v1/{模块}.go | 请求响应结构体 + gmeta 注解 | 业务逻辑 |
|
||
| controller | internal/controller/{模块}.go | 薄层透传 | 业务/dao/手写响应 |
|
||
| service | internal/service/{模块}.go | 接口契约（手维护） | 实现 |
|
||
| logic | internal/logic/{模块}.go | 业务实现（基座+钩子+手写） | 反向依赖 task |
|
||
| dao | internal/dao/ | 查询入口（钩子+红线条件） | 绕过直连 DB |
|
||
| hooks | internal/model/hooks/ | 审计盖章/软删/租户 | 业务判断 |
|