4.2 KiB
4.2 KiB
4.1 整体架构概览
:::tip 概述 EasyGoAdmin 是前后端分离的多层架构：Vue3 单页应用通过统一信封与 Gin 后端交互，后端按"契约 → 接口 → 业务 → 数据"四件套分层，横切能力（认证、租户、日志、限流）全部收敛在中间件与全局钩子。 :::
总体拓扑
┌─────────────────────────────────────────────┐
│ 浏览器（Vue3 + ElementPlus 单页应用） │
│ api 封装 · 动态菜单路由 · Pinia · v-permission│
└────────────────────┬────────────────────────┘
│ /api/**（统一 JSON 信封）
┌────────────────────▼────────────────────────┐
│ Gin HTTP 层 │
│ 中间件链：trace→CORS→metrics→response→ │
│ ratelimit→demo→JWT→tenant→authz→op_log │
│ │ │
│ router.Bind 反射注册（RouteSpec 表即路由） │
└────────────────────┬────────────────────────┘
│ 签名固定的方法调用
┌────────────────────▼────────────────────────┐
│ 四件套业务层 │
│ handler（极薄委托）→ service（ModuleSpec │
│ 声明 + 手写逻辑）→ repository（Ctx 入口） │
│ dto（契约与校验标签） │
└────────────────────┬────────────────────────┘
│ GORM（全局钩子盖章 + Scope 注入）
┌────────────────────▼────────────────────────┐
│ 数据层：MySQL / PostgreSQL / SQL Server / │
│ SQLite / Oracle（+ Redis 缓存，失败降级内存） │
└─────────────────────────────────────────────┘
设计原则
| 原则 | 落点 |
|---|---|
| 一处声明，多处生效 | RouteSpec 同源驱动注册/权限/日志/公开/OpenAPI；ModuleSpec 声明驱动查询/输出/写入 |
| 红线在入口执行，不靠自觉 | 软删过滤与租户隔离在 Ctx(ctx) 注入；物理删除被钩子拦截；审计字段钩子补齐 |
| 薄接口层，厚业务层 | handler 只委托；规则在 service；数据在 repository |
| 契约稳定 | dto json 标签名即 API 字段名，前后端与生成器共同依赖 |
| fail-fast + 优雅降级 | 配置非法拒绝启动；Redis 缺失降级内存；接线缺失告警降级（WireCheck） |
| 合法逃生舱 | 写不进声明的复杂逻辑手写方法，不硬塞框架 |
请求的一生（简版）
- 中间件链逐层处理（追踪、跨域、指标、响应包裹、限流、演示、认证、租户、鉴权、日志采集）
router.Bind包装函数按 path > body > query 绑定参数并校验- handler 委托 service；service 经 ModuleSpec / 手写逻辑完成业务
- repository.Ctx 在 SQL 构建前注入红线条件
- 结果回到 response 中间件统一封装信封返回；操作日志异步落库
逐层展开见 4.2 请求处理链路。
代码域划分
| 域 | 位置 | 职责边界 |
|---|---|---|
| 装配 | internal/server、cmd/api | 启动序列、优雅关闭 |
| HTTP | internal/router、internal/middleware | 路由注册与横切处理 |
| 业务 | internal/handler/service/repository/model/dto | 四件套 |
| 基础设施 | utility/* | 无业务语义的通用能力 |
| 后台任务 | internal/task | 定时任务（init 自注册） |
| 前端 | ui/* | 独立工程，经信封对接 |